출시 노트

현재 및 계획된 기능 지원 중단의 최신 목록은 기능 지원 중단을 참고하세요.

v24 주 버전 및 부 버전

Google Ads API v24에는 다음과 같은 새로운 기능, 업데이트, 주요 변경사항이 포함되어 있습니다.

v24.2 (2026-06-24)

Google Ads API v24.2에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v24.2와 같은 부 버전에는 브레이킹 체인지가 포함되지 않습니다.

기능 및 업데이트 유형 설명
광고
AssetAutomationType.GENERATE_LANDING_PAGE_TEXT 새 enum 값 이 API 버전부터 기본적으로 선택되는 DemandGenVideoResponsiveAd 인스턴스의 참여 패널에 표시할 방문 페이지의 텍스트 정보를 생성합니다.
애셋
AssetGroup.google_local_services_info 새로운 필드 실적 최대화 캠페인에서 지역 서비스 광고 정보 (카테고리 ID 및 콜아웃)를 지원하도록 추가되었습니다.
AssetGroupSignal.local_services_id 새로운 필드 실적 최대화 캠페인에서 지역 서비스 광고 서비스 ID 신호를 지원하기 위해 추가되었습니다.
AssetGroupSignal.vertical_ads_item_group_rule_list 새로운 필드 실적 최대화 캠페인에서 연결된 업종 피드에서 상품을 선택하기 위한 업종 광고 상품 그룹 규칙을 지원하기 위해 추가되었습니다. 이 기능은 허용 목록에 있는 계정에서만 사용할 수 있습니다.
AssetGroupErrorEnum.CANNOT_REMOVE_ALL_ASSET_GROUPS_FROM_CAMPAIGN 새 enum 값 / 오류 캠페인에서 모든 애셋 그룹을 삭제하려고 할 때 반환됩니다.
AssetGroupSignalErrorEnum.CANNOT_REMOVE_ALL_SIGNALS 새 enum 값 / 오류 애셋 그룹에서 모든 신호를 삭제하려고 할 때 반환됩니다.
캠페인
Campaign.PmaxCampaignSettings.local_services_pmax_campaign_settings
Campaign.PmaxCampaignSettings.local_services_enabled		 새 필드 지역 서비스 실적 최대화 캠페인 식별 지원
AdGroup.DemandGenAdGroupSettings.DemandGenChannelControls.DemandGenSelectedChannels.maps 새로운 필드 디맨드젠 광고 그룹의 선택 가능한 채널에 Google 지도가 포함됩니다.
CampaignCriterionErrorEnum.CANNOT_REMOVE_ALL_LOCATIONS_FROM_LOCAL_SERVICES_PMAX_CAMPAIGN 새 enum 값 / 오류 지역 서비스 실적 최대화 캠페인에서 모든 위치를 삭제하려고 할 때 반환됩니다.
SmartCampaignErrorEnum.CREATION_FAILED 새 enum 값 / 오류 새 스마트 캠페인을 만들려고 할 때 반환됩니다.
전환수
ConversionOrigin.LOCAL_SERVICES_ADS
ConversionActionType.LOCAL_SERVICES_ADS		 새 enum 값 사용자가 지역 서비스 광고를 클릭하고 광고주에게 전화, 메시지를 보내거나 예약할 때 발생하는 전환을 나타냅니다.
실험
COMPARE_CAMPAIGNS
PMAX_TEXT_CUSTOMIZATION_FINAL_URL_EXPANSION		 새 enum 값 새 ExperimentType 유형 지원 추가:
  • COMPARE_CAMPAIGNS: 단일 실험에서 동일하거나 다른 유형의 여러 캠페인을 비교하는 캠페인 믹스 실험 및 맞춤 실적 최대화 캠페인 실험
  • PMAX_TEXT_CUSTOMIZATION_FINAL_URL_EXPANSION: 텍스트 맞춤설정 및 최종 URL 확장을 위한 실적 최대화 캠페인 최적화 실험
일반
Asset.synthetic_content_info
Ad.synthetic_content_info		 새 필드 합성/AI 생성 콘텐츠에 대한 증명을 포함하며, advertiser_input (광고주가 직접 제공한 선언)과 system_input (시스템에서 자동으로 감지하거나 제공한 증명)으로 구분됩니다.

이 기능은 v23 및 v22로 백포트되었습니다.

v25의 향후 통합 작업을 계획할 수 있도록 광고주 증명 필드를 변경하는 인터페이스가 v22 이상에 조기에 도입됩니다. 이러한 버전에서는 인터페이스가 표시되지만 synthetic_content_info.advertiser_attestation.status 및 synthetic_content_info.advertiser_attestation.source은 이러한 버전에서 변경되지 않습니다.

이러한 필드 중 하나에 대해 변이 요청을 시도하면 다음 오류 중 하나가 반환됩니다.

'변경하려는 필드가 변경할 수 없음' 또는 '필드를 설정할 수 없음'

이러한 필드는 v25부터 완전히 변경 가능해집니다. 지금 인터페이스를 사용하여 내부 로직을 빌드하고 테스트하여 v25가 출시될 때 시스템이 전체 쓰기 기능을 지원할 수 있도록 하는 것이 좋습니다.
다자간 승인 새로운 기능 복수 사용자 승인 (MPA) 검토 지원이 추가되었습니다.
이 기능은 v23.3, v22.2, v21.2로 백포트되었습니다.
IncentiveService.FetchIncentive 동작 변경 이제 요청에 잘못된 이메일 주소가 제공되면 이 메서드는 AuthenticationError.INVALID_EMAIL_ADDRESS 오류를 발생시키는 대신 기본 인센티브 혜택을 반환하도록 정상적으로 대체됩니다.
계획
GenerateCreatorInsightsRequest.search_topics 새로운 필드 ContentCreatorInsightsService.GenerateCreatorInsights 서비스에 추가되었습니다. 이 옵션은 country_locations에 지정된 국가에서 특정 주제에 대해 이야기하는 크리에이터를 검색합니다 (한 국가만 검색 지원).
CREATOR_TOPIC_INSIGHTS 새 enum 값 주제에 대해 이야기하는 크리에이터를 검색하기 위한 항목을 나타내기 위해 InsightsKnowledgeGraphEntityCapabilities에 추가되었습니다. 이러한 항목은 search_topics 필드에서 사용해야 합니다. AudienceInsightsService.ListAudienceInsightsAttributes을 사용하여 가져왔습니다.
KnowledgeGraphEntitySearchOptions 새 유형 / 옵션 크리에이터 속성으로 지원되는 모든 주제를 가져오고 기능별로 필터링하는 옵션을 비롯해 ListAudienceInsightsAttributes의 주제에 관한 추가 검색 옵션이 포함되어 있습니다.
GenerateCreatorInsightsRequest.supplemental_data
GenerateTrendingInsightsRequest.supplemental_data		 새 필드 ContentCreatorInsightsService 메서드의 선택적 입력입니다. 이 필드를 제공하면 응답에 추가 위치 또는 크리에이터 속성이 채워집니다.
local_creator_insights
related_local_creators		 새 필드 supplemental_data에 LOCAL_CREATOR_DATA enum이 포함된 경우 채워집니다. 위치 데이터 공유에 동의한 선택한 국가의 현지 크리에이터를 표시합니다.
GenerateTrendingInsightsRequest.sub_country_locations 새로운 필드 ContentCreatorInsightsService.GenerateTrendingInsights에 추가되어 국가 위치와 하위 국가 위치를 사용하여 인기 급상승 통계를 검색할 수 있습니다.
보고서
PerformanceMaxPlacementView 세그먼트 확장 프로그램 ad_network_type에 의해 세그먼트화할 수 있습니다.
쇼핑
Campaign.ShoppingSetting.ignore_brand_exclusion_in_shopping_ads 새로운 필드 true인 경우 쇼핑 광고에서 브랜드 제외가 무시됩니다. 쇼핑 캠페인에서만 지원됩니다.
타겟팅
CriterionErrorEnum.CANNOT_TARGET_LANGUAGE 새 enum 값 / 오류 허용되지 않는 언어를 타겟팅하려고 하면 반환됩니다.
동영상
DataLink.youtube_link_metadata 새로운 필드 연결된 YouTube 브랜드 채널의 ID를 지정하는 brand_channel_id를 포함합니다.

v24.1 (2026-05-13)

Google Ads API v24.1에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v24.1과 같은 부 버전에는 브레이킹 체인지가 포함되지 않습니다.

기능 및 업데이트 유형 설명
광고
DemandGenMultiAssetAdInfo.classic_display_images 새로운 필드 추가 반응형 애셋이 필요 없이 게재되는 맞춤 업로드 디스플레이 이미지
실험
ADOPT_AI_MAX
ADOPT_BROAD_MATCH_KEYWORDS
OPTIMIZE_ASSETS
PMAX_REPLACEMENT_SHOPPING		 새 enum 값 새 ExperimentType 유형 지원 추가:
  • ADOPT_AI_MAX: AI Max를 이용하면 Google AI와 확장검색 키워드를 통해 얼마나 효과적으로 더 많은 고객의 참여를 유도할 수 있는지를 테스트하는 실험
  • ADOPT_BROAD_MATCH_KEYWORDS: 확장검색 키워드가 광고가 게재되는 검색 수에 미치는 영향을 테스트하는 실험
  • OPTIMIZE_ASSETS: 애셋 최적화를 위한 맞춤 실험
  • PMAX_REPLACEMENT_SHOPPING: 쇼핑 캠페인의 실적을 실적 최대화 캠페인과 비교하여 테스트하는 실험
Experiment.video_experiment 새로운 필드 동영상 캠페인으로 구성된 기존 YOUTUBE_CUSTOM 실험의 구성 지원
ExperimentArm.asset_testing_info
ExperimentArm.asset_groups
ExperimentArm.performance_max_experiment_arm_info		 새 필드 실험 부문에서 애셋 테스트, 애셋 그룹, 실적 최대화 캠페인 설정을 지원하는 필드를 노출합니다.
  • asset_testing_info: 광고의 실험용 사본과 연결된 애셋의 세부정보입니다.
  • asset_groups: 애셋 최적화 실험의 실험 부문에 있는 애셋 그룹 목록입니다.
  • performance_max_experiment_arm_info: PMAX_REPLACEMENT_SHOPPING 실험의 실적 최대화 캠페인 설정
일반
CustomerUserAccess.passkey_enabled 새로운 필드 사용자가 패스키를 사용 설정했는지 여부를 나타내는 읽기 전용 필드입니다.
보고서
mobile_device_platform 새 세그먼트 사용자 기기의 플랫폼 (예: iOS 또는 Android)별로 보고서를 분류할 수 있습니다.
REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED 새 enum 값 / 오류 요청된 일별, 시간별 또는 주별 시간 세분성이 쿼리 기간에 지원되지 않는 경우 반환됩니다 (지난 37개월 동안만 사용 가능).
vertical_ads_listing_user_rating
vertical_ads_listing_venue		 새 세그먼트 카테고리 광고에 사용할 새 세그먼트입니다.
user_rating, venue, event_participant_display_name 새 필터 기준 SharedCriterion 리소스의 VerticalAdsItemGroupRuleInfo에서 필터링이 지원됩니다.
대조군/처리군 실험 측정항목 새 필드 7가지 핵심 측정항목 계열 (클릭수, 노출수, 비용, 전환수, 전환당비용, 전환 가치, 비용당 전환 가치)에 걸쳐 관리 값 (control_clicks 등), 처리 값 (clicks 등), 점 추정치 (clicks_point_estimate 등), 오차 범위 (clicks_margin_of_error 등), p값 (clicks_p_value 등)이 추가되었습니다.
전환 절대 변경 측정항목 새 필드 점 추정치, 오차 범위, p값 필드를 사용하여 Conversions 절대 차이 추정 지원
타겟팅
CriterionErrorEnum.CANNOT_EXCLUDE_ALL_TARGETS 새 enum 값 / 오류 모든 인구통계 타겟을 제외하려고 할 때 반환됩니다.
동영상
ThirdPartyViewabilityIntegrationPartnerEnum.ZEFR 새 enum 값 ZEFR을 서드 파티 조회가능성 통합 파트너로 게시했습니다.
DataLink.youtube_video.channel_id 새로운 필드 데이터 링크와 연결된 YouTube 채널 ID를 노출합니다.

v24 (2026-04-22)

메이저 버전인 Google Ads API v24에는 다음과 같은 새로운 기능, 업데이트, 호환성이 깨지는 변경사항이 추가되었습니다.

최신 버전으로 업그레이드에서 안내를 확인하세요.

브레이킹 체인지

초기 상태 새 상태 변경 유형 구현 안내
광고
DemandGenVideoResponsiveAdInfo의 선택사항 videos 및 logo_images 필수 입력란 행동 변화 반응형 디맨드젠 동영상 광고를 만들거나 변경할 때 videos 및 logo_images을 제공합니다.
VideoResponsiveAdInfo의 선택사항 videos, business_name, logo_images 필수 입력란 행동 변화 동영상 반응형 광고를 만들거나 변경할 때 videos, business_name, logo_images를 제공합니다. 이제 VideoResponsiveAdInfo이 변경 가능합니다.
캠페인
Campaign.video_brand_safety_suitability 없음 삭제 캠페인 수준의 적합성 관리가 삭제됩니다. 브랜드 안전성 적합성은 고객 수준에서 계속 사용할 수 있습니다. 대신 Customer.video_brand_safety_suitability를 사용하세요.
전환수
UserListCustomerTypeCategoryEnum.LOYALTY_SIGN_UPS 없음 삭제 충성도 가입 사용자 카테고리가 삭제되었습니다. 코드 참조를 삭제합니다.
계획
topic_audience_combinations의 InsightsAudienceAttributeGroup 유형 common.InsightsAudienceAttributeGroup 유형 행동 변화 / 유형 변경 입력된 클라이언트 라이브러리 통합은 새 리소스 네임스페이스를 사용하도록 업데이트해야 합니다.
ReachPlanService.ListPlannableProducts의 youtube_select_lineups 필드 없음 삭제 youtube_select_lineup_targeting에서 경기 일정 사용으로 전환
ContentCreatorInsightsService.GenerateCreatorInsights 및 GenerateTrendingInsights의 is_brand_connect_creator 필드 없음 삭제 대신 크리에이터가 partnership_opportunities에서 CREATOR_PARTNERSHIPS을 사용할 수 있는지 확인합니다.
KeywordPlanIdeaService.GenerateKeywordForecastMetrics의 geo_modifiers 및 biddable_keywords geo_target_constants 및 keywords 이름 변경 / 삭제 CampaignToForecast.geo_target_constants[] 및 ForecastAdGroup.keywords[]로 대체되었습니다.
GenerateKeywordForecastMetrics에서 키워드 계획 / 예측 필드가 지원 중단됨 없음 삭제 다음 계획 / 예측 필드와 유형이 삭제되었습니다. 이에 따라 통합을 업데이트합니다.
보고서
campaign_budget의 ad_sub_network_type 세그먼트 없음 삭제 campaign_budget 리소스의 ad_sub_network_type 세그먼트가 삭제되었습니다.
애셋 뷰의 click_type 세그먼트 없음 삭제 AdGroupAsset, CampaignAsset, CustomerAsset 뷰에서 세그먼트가 삭제되었습니다.
동영상
ShareablePreviewService.GenerateShareablePreviews에서 부분 실패 허용 부분 실패 없음 행동 변화 요청에 포함된 ID 중 하나라도 유효성 검사에 실패하면 요청이 실패하고 오류가 발생합니다.
ShareablePreviewError 기존 코드: MutateErrorEnum.RESOURCE_NOT_FOUND
ShareablePreviewError.TOO_MANY_RESOURCES_IN_REQUEST		 이름 바꾸기 / 행동 변화 애셋 그룹에 대해 반환되는 오류 코드가 광고 그룹 광고 오류와 일치하도록 수정됩니다. 유효성 검사 포착 로직 업데이트

기능 및 업데이트 (호환성 유지)

기능 및 업데이트 유형 설명
광고
VideoResponsiveAdInfo의 변경 가능 여부 동작 변경 이제 반응형 동영상 광고 정보 객체를 변경할 수 있습니다.
애셋
AssetSet의 travel_feed_data 새로운 필드 여행 피드 확장 소재 속성 (hotel_center_account_id, merchant_center_id, partner_center_id, subset_id, travel_feed_vertical_type)을 가져오기 위해 추가되었습니다.
캠페인
Campaign.view_through_conversion_optimization_enabled 새로운 필드 디맨드젠 캠페인 및 앱 캠페인에서 조회 후 전환 (VTC) 최적화 (기본값 false)를 사용 설정할 수 있습니다.
CampaignCriterion.gender 새로운 기능 모든 Google Ads API 버전에서 실적 최대화 캠페인의 성별 제외가 사용 설정되었습니다.
전환수
리드 생성 전환 유형 새 enum 값 ConversionActionType에 새로운 GA4/Firebase 전환 액션 유형 enum이 추가되었습니다.
  • GOOGLE_ANALYTICS_4_GENERATE_LEAD
  • GOOGLE_ANALYTICS_4_QUALIFY_LEAD
  • GOOGLE_ANALYTICS_4_CLOSE_CONVERT_LEAD
  • FIREBASE_ANDROID_GENERATE_LEAD
  • FIREBASE_ANDROID_QUALIFY_LEAD
  • FIREBASE_ANDROID_CLOSE_CONVERT_LEAD
  • FIREBASE_IOS_GENERATE_LEAD
  • FIREBASE_IOS_QUALIFY_LEAD
  • FIREBASE_IOS_CLOSE_CONVERT_LEAD
일반
UserListErrorEnum.DUPLICATE_LOOKALIKE 새 enum 값 / 오류 동일한 유사 사용자 목록을 여러 개 만들려고 할 때 반환됩니다.
계획
ListPlannableProductsResponse의 ProductCoreAttributes 필드 새 필드 ListPlannableProductsResponse 아래 ProductCoreAttributes에 계획 가능한 제품 설명, 마케팅 목표, 비용 모델, 구매 방법을 추가했습니다.
보고서
CartDataSalesView 새 보고 리소스 클릭한 제품 외에도 판매된 특정 제품 (브랜드 등)별로 전환 측정항목을 분류하는 보고서를 표시합니다.
입찰에 사용되지 않는 측정항목 새 필드 일치하는 모든 리소스에 입찰에 사용되지 않는 측정항목 (캠페인에서 최적화하지 않는 전환을 보여주는 측정항목)이 추가되었습니다.
conversion_attribution_event_type 새 세그먼트 ShoppingPerformanceView에 추가되었습니다.
쇼핑
ShoppingProduct의 앱 캠페인 새로운 기능 ShoppingProduct 리소스 내에서 지원되는 앱 캠페인 메모 상태 및 문제는 지원되지 않습니다.
태그 기반 제품 필터링 새로운 기능 논리 집합 표현식을 사용하여 동적으로 필터링 도입: 이 기능은 허용 목록에 있는 계정에서만 사용할 수 있습니다.

v23 메이저 버전 및 마이너 버전

Google Ads API v23에는 다음과 같은 새로운 기능, 업데이트, 주요 변경사항이 포함되어 있습니다.

v23.3 (2026-06-24)

Google Ads API v23.3에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v23.3과 같은 부 버전에는 이전 버전과 호환되지 않는 변경사항이 포함되지 않습니다.

기능 및 업데이트 유형 설명
일반
Asset.synthetic_content_info
Ad.synthetic_content_info		 새 필드 합성/AI 생성 콘텐츠에 대한 증명을 포함하며, advertiser_attestation (광고주가 직접 제공한 선언) 및 system_attestation (Google 시스템에서 자동으로 감지하거나 제공한 증명)으로 구분됩니다.

v25의 향후 통합 작업을 계획할 수 있도록 광고주 증명 필드를 변경하는 인터페이스가 v22 이상에 조기에 도입됩니다. 이러한 버전에서는 인터페이스가 표시되지만 synthetic_content_info.advertiser_attestation.status 및 synthetic_content_info.advertiser_attestation.source은 이러한 버전에서 변경되지 않습니다.

이러한 필드 중 하나에 대해 변이 요청을 시도하면 다음 오류 중 하나가 반환됩니다.

'변경하려는 필드가 변경할 수 없음' 또는 '필드를 설정할 수 없음'

이러한 필드는 v25부터 완전히 변경 가능해집니다. 지금 인터페이스를 사용하여 내부 로직을 빌드하고 테스트하여 v25가 출시될 때 시스템이 전체 쓰기 기능을 지원할 수 있도록 하는 것이 좋습니다.
복수 사용자 승인 체계 새로운 기능 복수 사용자 승인 (MPA) 검토 지원이 추가되었습니다.

v23.2 (2026-03-25)

Google Ads API v23.2에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v23.2와 같은 부 버전에는 브레이킹 체인지가 포함되지 않습니다.

기능 및 업데이트 유형 설명
애셋
VideoEnhancement 새 리소스 Google에서 생성했는지 광고주가 제공했는지 등 개선사항 관련 동영상 광고 정보가 포함됩니다. 자세한 내용은 동영상 자동 개선 기능에 대한 정보를 참고하세요.
AppTopCombinationView 새 리소스 앱 캠페인에서 실적이 우수한 애셋 조합에 대한 통계를 제공하는 읽기 전용 리소스입니다.
CustomerAsset 새로운 기능 field_type이 BUSINESS_LOGO로 설정된 CustomerAsset를 가져오는 지원이 추가되었습니다.
캠페인
AdGroupAd.start_date_time
AdGroupAd.end_date_time		 새 필드 캠페인 날짜에 대해 더 세부적인 일정 제약 조건을 제공합니다. 일부 광고 그룹 유형에만 지원됩니다.
HotelSettingInfo.disable_hotel_setting 새로운 필드 디맨드젠 캠페인에서 호텔 피드를 사용 중지할 수 있습니다.
일반
CustomerClientLinkError 새 enum 값 / 오류 MAX_CUSTOMER_LIMIT_REACHED 및 ACCOUNT_CREATION_POLICY_VIOLATION이라는 두 개의 새로운 오류 코드가 추가되었습니다.
UserListCustomerTypeCategoryEnum.LOYALTY_SIGN_UPS 동작 변경 이제 지원이 종료된 사용자 목록 고객 유형 카테고리를 사용하려고 하면 오류가 발생합니다.
계획
GenerateTrendingInsights
GenerateCreatorInsights		 새로운 기능 엔티티, 주제, 잠재고객의 맞춤 AND/OR 조합에 대한 지원이 추가되었습니다.
ReachPlanService.GenerateReachForecast 새 enum 값 AGE_RANGE_21_44 또는 AGE_RANGE_21_49과 같이 타겟팅 가능한 새로운 연령대가 추가되었습니다.
youtube_select_lineup_targeting 새로운 필드 youtube_select_lineups을 대체할 ReachPlanService.ListPlannableProducts에 추가되었습니다. 현재 두 필드가 모두 채워져 있습니다.
ReachPlanSurface 새 enum 값 IN_STREAM_NON_SKIPPABLE_THIRTY_SECONDS이 표시 경로 옵션으로 추가되었습니다.
Forecast 새로운 필드 ReachPlanService.GenerateReachForecast에 디맨드젠 캠페인 최대 클릭수 (CPC)에 대한 clicks가 추가되었습니다.
partnership_opportunities 새로운 필드 ContentCreatorInsightsService.GenerateCreatorInsights 및 ContentCreatorInsightsService.GenerateTrendingInsights에 추가되었습니다.
보고서
biddable_indirect_install_first_in_app_conversion_micros 새로운 필드 Campaign, Customer, AdGroup 리소스에 추가되었습니다.
동영상
ShareablePreviewService 새로운 기능 preview_type을 YOUTUBE_LIVE_PREVIEW로 설정하여 YouTube 라이브 스트리밍 미리보기를 지원하도록 확장되었습니다. ShareablePreviewError에 UNSUPPORTED_AD_TYPE 및 TOO_MANY_RESOURCES_IN_REQUEST가 추가되었습니다. 일부 광고 유형에서만 지원됩니다.

v23.1 (2026-02-25)

Google Ads API v23.1에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v23.1과 같은 부 버전에는 이전 버전과 호환되지 않는 변경사항이 포함되지 않습니다.

기능 및 업데이트 유형 설명
계정 관리
advertising_partner_properties.allowed_domain 새로운 필드 ProductLinkInvitation 및 ProductLink 리소스에 추가되었습니다. 광고 파트너는 이 도메인에서만 광고할 수 있습니다.
Customer.contains_eu_political_advertising 새로운 필드 EU를 타겟팅하는 정치 광고가 포함되어 있는지 여부에 관한 계정 수준 선언 상태를 가져오고 EuPoliticalAdvertisingStatus을 반환합니다.
캠페인
Campaign.text_guidelines 새로운 필드 실적 최대화 캠페인 및 검색 캠페인에서 사용하여 AI 생성 텍스트 애셋을 프로그래매틱 방식으로 제어할 수 있는 광고 문구 가이드라인 지원이 추가되었습니다. text_guidelines 내에서 term_exclusions 및 messaging_restrictions를 정의할 수 있습니다.
CampaignPrimaryStatusReason 새 enum 값 FIXED_CPM 입찰 전략을 사용하는 캠페인의 기본 상태 이유를 제공하기 위해 CAMPAIGN_NOT_BOOKED, BOOKING_HOLD_EXPIRING, BOOKING_HOLD_EXPIRED, BOOKING_CANCELLED가 추가되었습니다.
Campaign.VideoCampaignSettings.reservation_ad_category_self_disclosure
Campaign.VideoCampaignSettings.booking_details		 새 필드 예약 광고 카테고리 직접 공개 및 읽기 전용 예약 세부정보에 대한 지원이 추가되었습니다.
Campaign.missing_eu_political_advertising_declaration 새로운 필드 EU를 타겟팅하는 정치 광고가 포함되어 있는지 여부에 관한 선언이 누락된 캠페인을 쿼리하고 필터링하는 기능을 지원합니다.
전환수
ConversionActionCategory.YOUTUBE_FOLLOW_ON_VIEWS 새 enum 값 광고를 시청한 후 동일한 채널의 동영상을 시청하는 사용자를 추적할 수 있습니다.
일반
CriterionErrorEnum.CANNOT_TARGET_ONLY_UNDETERMINED 새 enum 값 / 오류 인구통계 측정기준에서 미확정 카테고리만 타겟팅하려고 할 때 반환됩니다.
인센티브
IncentiveErrorEnum 새 enum 값 / 오류 MAX_INCENTIVES_REDEEMED 및 ACCOUNT_TOO_OLD이라는 두 개의 새로운 오류 코드가 추가되었습니다. 이러한 오류는 2026년 3월 11일 이후에 이루어진 요청에 대해 반환될 수 있습니다.
계획
GenerateBenchmarksMetrics 새로운 기능 BreakdownDefinition를 사용한 날짜 분류 지원이 추가되었습니다.
ReachPlanService.GenerateReachForecast 새 enum 값 GOOGLE_DISPLAY_NETWORK이 디맨드젠 캠페인 전환수 극대화의 타겟팅 가능한 표시 경로로 추가되었습니다.
GenerateTrendingInsights 새 필드 주제로 검색할 때 TrendInsightDataPoint에서 TrendInsights까지의 이전 추세선 정보가 추가되었습니다.
보고서
순 사용자 게재빈도 측정항목 새 필드 광고를 2회, 3회, 4회, 5회 또는 10회 이상 본 사용자 수를 보고하는 새로운 측정항목이 추가되었습니다(unique_users_two_plus, unique_users_three_plus, unique_users_four_plus, unique_users_five_plus, unique_users_ten_plus).
SearchTermMatchSource 새 enum 값 여행 광고 엔티티 타겟팅과 같은 업종별 광고 데이터 피드를 지원하기 위해 VERTICAL_ADS_DATA_FEED가 추가되었습니다.
YouTubeVideoUpload
YouTubeVideoUpload 새 서비스 / 리소스 YouTube에서 동영상을 업로드하고 관리하는 기능을 지원하는 YouTubeVideoUpload 서비스와 업로드 상태 및 메타데이터 가져오기를 지원하는 YouTubeVideoUpload 리소스가 추가되었습니다. 이 기능은 REST 및 Python 클라이언트 라이브러리에서만 지원됩니다.

v23 (2026-01-28)

주요 버전인 Google Ads API v23에는 다음과 같은 새로운 기능, 업데이트, 호환성이 깨지는 변경사항이 추가되었습니다.

최신 버전으로 업그레이드에서 안내를 확인하세요.

브레이킹 체인지

초기 상태 새 상태 변경 유형 구현 안내
광고
광고 공유 허용됨 AdGroupAdError.AD_SHARING_NOT_ALLOWED 행동 변화 여러 광고 그룹 간의 광고 공유는 더 이상 허용되지 않습니다. 광고를 공유하려고 시도하는 요청은 AD_SHARING_NOT_ALLOWED 오류를 반환합니다.
CallAd 및 CallAdInfo 지원 없음 삭제 전화 유도 광고 지원이 삭제되었습니다. 통화 광고 정보 고객센터 도움말을 참고하세요.
캠페인
Campaign.start_date
Campaign.end_date		 Campaign.start_date_time
Campaign.end_date_time		 이름 바꾸기 / 교체 새 날짜-시간 필드를 사용하여 캠페인의 시간 구성요소를 지정합니다. 원본 날짜 전용 필드가 삭제됩니다.
디맨드젠 캠페인
DemandGenMultiAssetAdInfo.lead_form_only 없음 삭제 lead_form_only 필드가 삭제되었습니다. 코드에서 참조를 업데이트합니다.
보고서
애셋 실적 라벨 측정항목 및 enum 집계 없음 삭제 집계된 애셋 실적 라벨 측정항목이 삭제되었습니다. 실적 라벨 enum이 더 이상 검색 및 디스플레이에 반환되지 않습니다.

기능 및 업데이트 (호환성 유지)

기능 및 업데이트 유형 설명
광고
AdFormatType 새 enum 값 새로운 형식 유형이 추가되었습니다(TEXT, VERTICAL_ADS_BOOKING_LINK, VERTICAL_ADS_PROMOTION).
애셋
asset_group회 조회 새 필드 metrics.engagements, metrics.engagement_rate, metrics.average_cpe 측정항목이 추가되었습니다.
asset_group_asset회 조회 새 필드 metrics.average_cpe, metrics.average_cpm, metrics.trueview_average_cpv, metrics.video_trueview_view_rate, metrics.video_trueview_views, metrics.interaction_event_types 측정항목이 추가되었습니다.
Asset.orientation 새로운 필드 이미지 및 동영상 애셋에 읽기 전용 방향 필드가 추가되었습니다.
CampaignAsset 새로운 기능 field_type이 HEADLINE 및 DESCRIPTION로 설정된 캠페인 확장 소재를 가져오는 지원이 추가되었습니다.
ServedAssetFieldType 새 enum 값 사이트링크로 게재되는 애셋에 HEADLINE_AS_SITELINK_POSITION_ONE, HEADLINE_AS_SITELINK_POSITION_TWO, DESCRIPTION_LINE_HEADLINE_AS_SITELINK_POSITION_ONE, DESCRIPTION_LINE_HEADLINE_AS_SITELINK_POSITION_TWO이 추가되었습니다.
BusinessMessageAsset 새로운 기능 / 지원 업데이트된 비즈니스 메시지 확장 소재:
결제
InvoiceService.ListInvoices 새 옵션 이제 ListInvoicesRequest에서 include_granular_level_invoice_details를 설정하여 캠페인 수준 비용 분류, 항목별 규제 비용, 조정 정보를 비롯한 더 상세한 세부정보를 Invoice에서 반환할 수 있습니다.
RegulatoryFeeType
UnitOfMeasure		 새 enum 규제 수수료 및 측정 단위에 대한 도우미 enum이 추가되었습니다.
캠페인
CampaignError 새 enum 값 / 오류 DURATION_TOO_LONG_FOR_TOTAL_BUDGET 및 END_DATE_TIME_REQUIRED_FOR_TOTAL_BUDGET 오류 코드가 추가되었습니다.
전환수
ConversionActionCategory 새 enum 값 광고를 시청한 후 동일한 채널의 동영상을 시청하는 사용자를 추적할 수 있도록 YOUTUBE_FOLLOW_ON_VIEWS가 추가되었습니다.
디맨드젠 캠페인
DemandGenVideoResponsiveAdInfo.companion_banner 새로운 필드 디맨드젠 캠페인 반응형 동영상 광고에 컴패니언 배너 지원이 추가되었습니다.
인센티브
내 선택 인센티브 지원 추가:

실패를 더 세부적으로 프로그래매틱 방식으로 처리할 수 있도록 향후 버전에서 IncentivesService에 오류 코드가 추가될 예정입니다. 애플리케이션에서 이러한 새로운 오류 모드를 관리할 수 있도록 예정된 공지사항과 출시 노트를 통해 이러한 새로운 오류 코드를 모니터링하는 것이 좋습니다.
계획
AudienceInsightsDimension.LIFE_EVENT_USER_INTEREST 새 enum 값 GenerateAudienceCompositionInsights, GenerateSuggestedTargetingInsights, GenerateInsightsFinderReport, GenerateCreatorInsights에서 생애 주요 이벤트를 사용하여 잠재고객을 구성할 수 있습니다.

AudienceInsightsService.GenerateAudienceOverlap, AudienceInsightsService.GenerateTargetingSuggestionMetrics과 같은 다른 AudienceInsightsService 메서드에는 생애 주요 이벤트가 지원되지 않습니다.
ReachPlanService.GenerateConversionRates 새 필드 / 옵션 이제 응답에 표시 제어 (예: Gmail, Shorts)에 기반한 전환율 추천을 지원하는 표시 경로가 포함됩니다. 디맨드젠 캠페인에서만 지원됩니다.
LanguageDistribution 새 필드 / 유형 YouTube 채널 콘텐츠의 언어 분포 세부정보를 제공하기 위해 YouTubeChannelInsights에 추가되었습니다.
BenchmarksService 새 서비스 YouTube 광고 데이터를 업계 기준치와 비교합니다.
AudienceInsightsService.GenerateAudienceDefinition 새로운 방법 생성형 AI를 사용하여 타겟 고객의 자유 텍스트 설명을 일치하는 잠재고객 속성으로 변환합니다.
YouTubeChannelInsights.relevance_score 새로운 필드 조회수로 가중치를 부여한 주제와 크리에이터의 관련성을 평가합니다.
TrendInsightMetrics.trend_change_percent 새로운 필드 비교 기간 동안의 트렌드 값의 변화율을 나타냅니다.
권장사항
GenerateRecommendationsRequest 새로운 필드 is_new_customer을 추가했습니다. CAMPAIGN_BUDGET 추천에 대해 true로 설정하면 신규 고객에 최적화된 모델을 사용합니다 (캠페인이 없는 고객에게만 추천).
보고서
AdGroupAdAssetView 새로운 기능 / 측정항목 지원 이제 RESPONSIVE_DISPLAY_AD의 노출수, 실적, 전환 측정항목을 지원합니다.
ad_sub_network_type 세그먼트 새 세그먼트 광고 네트워크 내의 세부적인 실적 분석을 제공합니다. 처음에는 YouTube의 디맨드젠 캠페인 (인스트림 광고, 인피드 광고, Shorts)에서 사용할 수 있습니다. ad_network_type와 함께 선택해야 합니다.
실적 최대화 캠페인 보고 새로운 기능 실적 최대화 캠페인에 대해 광고 네트워크 유형 분석이 사용 설정되었습니다.
UserLocationView
GeographicView		 새 세그먼트 지원 전환 날짜별로 분류된 측정항목 지원: conversions_by_conversion_date, all_conversions_by_conversion_date, conversions_value_by_conversion_date, all_conversions_value_by_conversion_date, value_per_conversions_by_conversion_date, value_per_all_conversions_by_conversion_date, cross_device_conversions_by_conversion_date, cross_device_conversions_value_by_conversion_date
카테고리 광고 세그먼트 새 세그먼트 vertical_ads_event_participant_display_names, vertical_ads_hotel_class, vertical_ads_listing, vertical_ads_listing_brand, vertical_ads_listing_city, vertical_ads_listing_country, vertical_ads_listing_region, vertical_ads_partner_account, vertical_ads_vertical 세그먼트가 추가되었습니다.
PerStoreView
MatchedLocationInterestView		 새 보고 리소스 PerStoreView를 추가하여 매장 위치 세부정보를 쿼리하고 MatchedLocationInterestView (AI Max 캠페인용)를 추가하여 관심 있는 지리적 위치별로 실적 측정항목을 제공했습니다.
쇼핑
ShoppingPerformanceView 새 측정항목 지원 이제 전환 날짜별로 분류된 conversions_by_conversion_date, all_conversions_by_conversion_date, conversions_value_by_conversion_date, value_per_conversions_by_conversion_date, value_per_all_conversions_by_conversion_date 측정항목이 지원됩니다.
ShoppingPerformanceView 새 측정항목 지원 search_budget_lost_impression_share, search_rank_lost_impression_share, search_budget_lost_absolute_top_impression_share, search_rank_lost_absolute_top_impression_share 지원 추가
ShoppingProduct.product_image_uri 새로운 필드 ShoppingProduct에 추가되었습니다.
세로형 광고
AdGroup.vertical_ads_format_setting 새로운 필드 여행 피드를 사용하는 검색 캠페인에서 게재할 수 있는 광고 형식을 관리할 수 있습니다.
AdGroupCriterion
SharedCriterion		 새 필드 / 기준 여행 피드가 있는 검색 캠페인에서 항목 그룹을 타겟팅할 수 있도록 AdGroupCriterion 및 vertical_ads_item_group_rule에 vertical_ads_item_group_rule_list 기준 유형을 추가했습니다.SharedCriterion
카테고리 광고 데이터 피드 통합 새로운 기능 이제 AI Max를 실행하는 검색 캠페인에 업종 광고 데이터 피드를 연결하여 텍스트 광고와 함께 숙박 시설 프로모션 및 예약 링크 여행 광고를 게재할 수 있습니다. vertical_ads_format_setting로 형식을 제어하고 vertical_ads_item_group_rule를 사용하여 규칙을 정의합니다. AdFormatType 및 업종 광고 데이터 피드 측정기준별로 보고서를 분류합니다.
동영상
AdVideoAssetInfo.ad_video_asset_feature_control 새로운 필드 동영상 광고 애셋에 기능 제어 옵션이 추가되었습니다.
CampaignCriterionError 새 enum 값 / 오류 INVALID_VIDEO_LINEUP_ID 오류 코드가 추가되었습니다.
YouTube 청취 가능성 측정항목 새 측정항목 YouTube의 오디오 광고에 대한 청취 가능성 측정항목이 추가되어 광고의 청취 가능 여부와 청취 가능성을 측정할 수 있는 노출수가 보고됩니다.

v22 메이저 버전 및 마이너 버전

Google Ads API v22에는 다음과 같은 새로운 기능, 업데이트, 주요 변경사항이 포함되어 있습니다.

v22.2 (2026-06-24)

Google Ads API v22.2에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v22.2와 같은 부 버전에는 브레이킹 체인지가 포함되지 않습니다.

기능 및 업데이트 유형 설명
일반
Asset.synthetic_content_info
Ad.synthetic_content_info		 새 필드 합성/AI 생성 콘텐츠에 대한 증명을 포함하며, advertiser_attestation (광고주가 직접 제공한 선언) 및 system_attestation (Google 시스템에서 자동으로 감지하거나 제공한 증명)으로 구분됩니다.

v25의 향후 통합 작업을 계획할 수 있도록 광고주 증명 필드를 변경하는 인터페이스가 v22 이상에 조기에 도입됩니다. 이러한 버전에서는 인터페이스가 표시되지만 synthetic_content_info.advertiser_attestation.status 및 synthetic_content_info.advertiser_attestation.source은 이러한 버전에서 변경되지 않습니다.

이러한 필드 중 하나에 대해 변이 요청을 시도하면 다음 오류 중 하나가 반환됩니다.

'변경하려는 필드가 변경할 수 없음' 또는 '필드를 설정할 수 없음'

이러한 필드는 v25부터 완전히 변경 가능해집니다. 지금 인터페이스를 사용하여 내부 로직을 빌드하고 테스트하여 v25가 출시될 때 시스템이 전체 쓰기 기능을 지원할 수 있도록 하는 것이 좋습니다.
복수 사용자 승인 체계 새로운 기능 복수 사용자 승인 (MPA) 검토 지원이 추가되었습니다.

v22.1 (2026년 2월 25일)

Google Ads API v22.1에 다음 새로운 기능이 추가되었습니다. v22.1과 같은 부 버전에는 브레이킹 체인지가 포함되지 않습니다.

기능 및 업데이트 유형 설명
계정 관리
Customer.contains_eu_political_advertising 새로운 필드 EU를 타겟팅하는 정치 광고가 포함되어 있는지 여부에 관한 계정 수준 선언 상태를 가져오고 EuPoliticalAdvertisingStatus을 반환합니다.
캠페인
Campaign.missing_eu_political_advertising_declaration 새로운 필드 EU를 타겟팅하는 정치 광고가 포함되어 있는지 여부에 관한 선언이 누락된 캠페인을 쿼리하고 필터링하는 기능을 지원합니다.

v22 (2025년 10월 15일)

다음 새로운 기능, 업데이트, 주요 변경사항이 주요 버전인 Google Ads API v22에 추가되었습니다.

최신 버전으로 업그레이드에서 안내를 확인하세요.

브레이킹 체인지

초기 상태 새 상태 변경 유형 구현 안내
디맨드젠 캠페인
BudgetPerDayMinimumErrorDetails.minimum_bugdet_amount_micros minimum_budget_amount_micros 이름 바꾸기 / 맞춤법 수정 수정된 필드 이름을 사용하도록 참조 이름을 바꿉니다.
일반
AddBatchJobOperations에는 작업 제한이 없습니다. 요청당 작업 수 제한 10,000개 행동 변화 단일 AddBatchJobOperations 요청에 10,000개가 넘는 작업이 포함되지 않도록 합니다.
ListBatchJobResultsRequest에서 페이지 크기를 1,000으로 자동 제한 INVALID_PAGE_SIZE 오류 반환 행동 변화 이제 더 큰 페이지 크기를 요청하면 오류가 발생하므로 ListBatchJobResultsRequest.page_size이 1,000 이하로 설정되어 있는지 확인하세요.
실적 최대화 캠페인
애셋 실적 라벨 없음 삭제 실적 최대화 캠페인에서 애셋 실적 라벨 지원 및 관련 실적 라벨 enum이 삭제되었습니다. 이에 따라 통합을 업데이트합니다.
Campaign.url_expansion_opt_out AssetAutomationSetting의 FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION 플래그 삭제 / 교체 최종 URL 확장 텍스트 애셋 자동화 설정을 사용합니다. 캠페인 수준 URL 확장 선택 해제 필드가 삭제됩니다.
계획
views trueview_views 삭제 / 교체 ReachPlanService에서 views에 대한 참조를 새 trueview_views 필드로 바꿉니다.
동영상
average_cpv
video_view_rate
video_views
video_view_rate_in_feed
video_view_rate_in_stream
video_view_rate_shorts		 trueview_average_cpv
video_trueview_view_rate
video_trueview_views
video_trueview_view_rate_in_feed
video_trueview_view_rate_in_stream
video_trueview_view_rate_shorts		 이름 변경 TrueView 동영상 조회수를 나타내는 새 측정항목 이름을 사용하도록 쿼리 문자열과 통합을 업데이트합니다.

기능 및 업데이트 (호환성 유지)

기능 및 업데이트 유형 설명
애셋
AssetFieldType.LANDING_PAGE_PREVIEW 새 enum 값 새 이미지 확장 소재 필드 유형으로 추가되었습니다.
AssetGenerationService 새 서비스 (베타) 생성형 AI를 사용하여 텍스트 및 이미지 확장 소재를 생성할 수 있습니다.
  • GenerateText: 최종 URL, 프롬프트, 키워드 등을 기반으로 텍스트를 생성합니다.
  • GenerateImages: 최종 URL, 프롬프트 또는 제품 이미지의 재맥락화에 따라 이미지를 생성합니다.
  • 오류는 AssetGenerationError의 코드로 반환됩니다.
처음에는 제한된 수의 비공개 베타 참여자에게만 제공됩니다.
캠페인
AppCampaignBiddingStrategyGoalType 새 enum 값 타겟을 지정하지 않고 최적화할 수 있도록 설치 유도 앱 캠페인 (ACi)에 새로운 목표가 추가되었습니다.
  • OPTIMIZE_IN_APP_CONVERSIONS_WITHOUT_TARGET_CPA: 표준 전환수 최대화와 함께 사용합니다.
  • OPTIMIZE_TOTAL_VALUE_WITHOUT_TARGET_ROAS: 표준 전환 가치 극대화와 함께 사용합니다.
BiddingStrategyType 새로운 기능 고정 광고 점유율 입찰 전략 유형에 대한 지원이 추가되었습니다.
Campaign.feed_types 새로운 필드 캠페인에 연결된 피드의 유형을 표시합니다. 실적 최대화 캠페인의 경우 비즈니스 업종(예: 소매업의 경우 MERCHANT_CENTER_FEED)을 나타낼 수 있습니다.
공유 조합 타겟팅 새로운 기능 제외 키워드 공유 세트를 멀티 채널 (앱 캠페인용) 및 지역 캠페인에 연결할 수 있습니다.
디맨드젠 캠페인
타겟 CPC 입찰 새로운 기능 타겟 CPC에서 클릭수를 최대화하는 입찰 전략 추가: Campaign.target_cpc을 사용하여 캠페인 수준 타겟 CPC를 설정하고 AdGroup.target_cpc_micros을 사용하여 광고 그룹 수준에서 재정의합니다.
AssetAutomationType.GENERATE_DESIGN_VERSIONS_FOR_IMAGES 새 enum 값 DemandGenMultiAssetAdInfo에 사용 설정된 경우 디자인 요소를 추가하고 텍스트 애셋을 이미지 애셋에 삽입하여 가로세로 비율이 다른 새 이미지 애셋을 만듭니다 (기본적으로 사용 설정됨).
AssetAutomationType.GENERATE_VIDEOS_FROM_OTHER_ASSETS 새 enum 값 DemandGenMultiAssetAdInfo에 사용 설정된 경우 이미지, 텍스트와 같은 다른 애셋을 사용하여 동영상을 생성하며, 이 동영상을 사용하여 새로운 DemandGenVideoResponsiveAdInfo 인스턴스를 만들 수 있습니다 (기본적으로 사용 설정됨).
일반
ListBatchJobResultsRequest 페이지 크기 대체 동작 변경 이제 page_size가 설정되지 않았거나 0인 경우 기본값은 최대 1,000입니다 (이전에는 INVALID_PAGE_SIZE이 반환됨).
QuotaError 새 enum 값 / 오류 지급 프로필 활성화 비율 한도가 초과된 시점을 나타내는 PAYMENTS_PROFILE_ACTIVATION_RATE_LIMIT_EXCEEDED가 추가되었습니다.
실적 최대화 캠페인
애셋 자동화 설정 새 enum 값 새로운 실적 최대화 캠페인 애셋 자동화 옵션이 추가되었습니다.
  • GENERATE_IMAGE_ENHANCEMENT: 향상된 이미지 (자동 자르기)의 자동 생성을 사용 설정합니다. 기본적으로 사용 설정됩니다.
  • GENERATE_IMAGE_EXTRACTION: 최종 도착 URL에서 가져온 이미지입니다. 기본값은 계정 동적 이미지 확장 프로그램 설정입니다.
실적 최대화 캠페인 보고 세그먼트 새 세그먼트 실적 최대화 캠페인에만 해당하는 새로운 세그먼트가 추가되었습니다.
  • ad_using_product_data: 광고에서 Google 판매자 센터 제품 데이터를 사용하는지 여부를 나타냅니다.
  • ad_using_video: 광고에서 동영상 애셋을 사용하는지 여부를 나타냅니다.
계획
CRM 파트너 데이터 목록 새 기능 / 열거형 값 파트너 잠재고객 유효성 검사 오류 코드 (예: 서비스 약관 수락, 링크 누락 등)와 함께 CRM 데이터 소스에 THIRD_PARTY_PARTNER_DATA이 추가되었습니다.
라이브 스트림 크리에이터 측정항목 새로운 필드 크리에이터 통계에서 반환되며 크리에이터가 지난 90일 동안 라이브 스트림을 게시했는지 여부를 나타내는 YouTubeMetrics.is_active_live_stream_creator이 추가되었습니다.
계획 가능한 CRM 소스 메타데이터 새 메시지 CRM 데이터 소스 유형을 표시하기 위해 ReachPlanService.ListPlannableUserLists에서 반환된 PlannableUserList 내에 PlannableUserListMetadata를 추가했습니다.
TrendInsight의 관련 동영상 및 크리에이터 지원 새 필드 TrendInsight에서 related_videos 및 related_creators 지원이 추가되었으며, video_properties 및 publish_date에서 속성을 감시합니다.
InsightsFinder 개선사항 새로운 기능 이제 GenerateInsightsFinderReport에서 parental_status, income_ranges, 더 복잡한 AND/OR 타겟팅 조합을 지원합니다.
보고서
새 클릭 유형 새 enum 값 CLICK_TO_MESSAGE_THIRD_PARTY_CLICK 및 CLICK_TO_MESSAGE_LANDING_PAGE_CLICK를 추가했습니다.
AssetGroupAsset 세분화 새 세그먼트 지원 이제 AssetGroupAsset을 device, conversion_action, conversion_action_name, conversion_action_category로 분류할 수 있습니다.
AdGroupAdAssetView의 RSA 새로운 기능 / 측정항목 지원 이제 AdGroupAdAssetView에서 RESPONSIVE_SEARCH_AD의 실적 및 전환 측정항목을 완전히 지원합니다 (이전에는 노출수만 반환됨).
탐색 분석 쿼리 클러스터 측정항목 세분화 새 세그먼트 지원 이제 clicks_unique_query_clusters, conversions_unique_query_clusters, impressions_unique_query_clusters 측정항목을 날짜 필드로 분류할 수 있습니다.
TargetingExpansionView 새 보고 리소스 TargetingExpansionView를 추가하여 AI Max 검색 캠페인의 키워드 없는 확장검색과 같은 수동 타겟팅을 통한 확장의 측정항목을 보고합니다.
쇼핑
쇼핑 범위 수정 버그 수정 ShoppingProduct 리소스의 측정항목 캠페인 및 광고 그룹 범위가 수정되었습니다.
통합 목표
이탈 고객 확보 목표 새로운 기능 기존 고객의 재참여를 유도하기 위해 최적화하는 고객 유지 목표 지원이 추가되었습니다 (예: TARGET_SPECIFIC 또는 TARGET_ALL와 함께 target_option 사용).
동영상
동영상 시청 시간 측정항목 새 필드 시청 시간 측정항목(video_watch_time_duration_millis(총 지속 시간) 및 average_video_watch_time_duration_millis(노출당 평균 지속 시간))을 추가했습니다.

v21 주 버전 및 부 버전

Google Ads API v21에는 다음과 같은 새로운 기능, 업데이트, 주요 변경사항이 포함되어 있습니다.

v21.2 (2026-06-24)

Google Ads API v21.2에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v21.2와 같은 부 버전에는 이전 버전과 호환되지 않는 변경사항이 포함되지 않습니다.

기능 및 업데이트 유형 설명
일반
복수 사용자 승인 체계 새로운 기능 복수 사용자 승인 (MPA) 검토 지원이 추가되었습니다.

v21.1 (2026년 2월 25일)

Google Ads API v21.1에 다음과 같은 새로운 기능과 업데이트가 추가되었습니다. v21.1과 같은 부 버전에는 이전 버전과 호환되지 않는 변경사항이 포함되지 않습니다.

기능 및 업데이트 유형 설명
계정 관리
Customer.contains_eu_political_advertising 새로운 필드 EU를 타겟팅하는 정치 광고가 포함되어 있는지 여부에 관한 계정 수준 선언 상태를 가져오고 EuPoliticalAdvertisingStatusEnum을 반환합니다.
캠페인
Campaign.missing_eu_political_advertising_declaration 새로운 필드 EU를 타겟팅하는 정치 광고가 포함되어 있는지 여부에 관한 선언이 누락된 캠페인을 쿼리하고 필터링하는 기능을 지원합니다.

v21 (2025년 8월 6일)

메이저 버전인 Google Ads API v21에는 다음과 같은 새로운 기능, 업데이트, 호환성이 깨지는 변경사항이 추가되었습니다.

최신 버전으로 업그레이드에서 안내를 확인하세요.

브레이킹 체인지

초기 상태 새 상태 변경 유형 구현 안내
캠페인
CriterionError.INVALID_LISTING_GROUP_HIERARCHY를 반환합니다. CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION를 반환합니다. 오류 코드 변경 부분 실패가 사용 설정된 요청의 경우 원래 계층 구조 오류 코드 대신 새 오류 코드를 처리합니다.
전환수
ConversionUploadService의 debug_enabled 모드 액세스 없음 삭제 debug_enabled 필드가 삭제됩니다. 이 매개변수를 설정하거나 쿼리하지 않도록 참조하는 코드를 업데이트합니다.
EU 정치 광고 변경사항
EU 정치 광고에 대한 선택적 캠페인 자체 선언 새 캠페인에 필요한 contains_eu_political_advertising 필드 유효성 검사 규칙 / 행동 변화 이 필드가 설정되지 않으면 새 캠페인을 만들기 위한 API 호출이 FieldError.REQUIRED 오류와 함께 실패합니다. 2025년 9월 22일부터 CONTAINS_EU_POLITICAL_ADVERTISING로 선언된 캠페인은 EU에서 더 이상 게재되지 않습니다.
직접 신고 없이 수정 가능한 기준 CriterionError.MISSING_EU_POLITICAL_ADVERTISING_SELF_DECLARATION을 사용하여 업데이트가 실패함 유효성 검사 규칙 / 행동 변화 기존 캠페인의 캠페인 또는 광고 그룹 수준 근접성, 위치 또는 위치 그룹 타겟팅 기준을 만들거나 업데이트하기 전에 자체 선언 상태를 설정하세요.
직접 신고 요건이 없는 실험 ExperimentError.MISSING_EU_POLITICAL_ADVERTISING_SELF_DECLARATION을 사용하여 업데이트가 실패함 유효성 검사 규칙 / 행동 변화 실험의 캠페인에서 자체 선언이 완료되었는지 확인합니다.
실적 최대화 캠페인
brand_guidelines_enabled 기본값은 false입니다. 기본값은 true입니다. 행동 변화 새로운 실적 최대화 캠페인의 경우 브랜드 가이드라인이 기본적으로 사용 설정됩니다. 사용 중지해야 하는 경우 필드를 false로 명시적으로 설정합니다.
계획
AudienceInsightsService.GenerateTargetingSuggestionMetrics의 원래 입력 인수 유형 InsightsAudience 유형의 입력 유형 변경 사용자 관심분야의 AND-of-OR 조합을 지원하는 새 입력 유형을 전달하도록 구현을 업데이트하여 맞춤 잠재고객 정의의 잠재 도달범위 측정항목을 허용합니다.

기능 및 업데이트 (호환성 유지)

기능 및 업데이트 유형 설명
AI Max 검색 캠페인
Campaign의 ai_max_setting.enable_ai_max 새로운 필드 AI Max가 검색어 일치를 확장할 수 있도록 지원합니다 (사용 중지로 전환될 때까지 이전 텍스트 애셋 자동화 및 브랜드 목록을 준수). Campaign.ai_max_setting.bundling_required 필드는 이러한 설정을 준수/수정하기 위해 AI Max를 사용 설정해야 하는지 여부를 나타내며, AdGroup.ai_max_ad_group_setting.disable_search_term_matching은 광고 그룹 수준에서 일치를 사용 중지할 수 있습니다. AI Max 검색 캠페인으로 한 단계 높은 실적 달성하기를 참고하세요.
CampaignError.AI_MAX_MUST_BE_ENABLED 새 enum 값 / 오류 AI Max를 사용 설정하지 않고 검색 캠페인에서 URL 확장 텍스트 애셋 자동화를 선택할 때 발생합니다.
광고 그룹 수준 타겟팅 새로운 기능 AI Max 검색 캠페인에서 광고 그룹 수준의 브랜드 목록, 위치, 웹페이지 (URL 규칙)에 대한 지원이 추가되었습니다.
ai_max_search_term_ad_combination_view 새 보고 리소스 검색어, 광고 제목, 방문 페이지의 조합에 대한 실적을 보고합니다.
search_term_match_type 세그먼트 새 enum 값 AI_MAX이 검색어 검색 유형 옵션으로 추가되었습니다.
애셋
PromotionAsset 새 필드 terms_and_conditions_text, terms_and_conditions_uri, promotion_trigger 옵션 중 하나 (promotion_barcode_info, promotion_qr_code_info)가 추가되었습니다. 프로모션 확장 소재에 대한 정보를 참고하세요.
AssetAutomationType.FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION 새 enum 값 검색 캠페인의 최종 URL에서 자동 텍스트 및 방문 페이지 생성을 제어하기 위해 AssetAutomationType에 추가되었습니다.
AutomaticallyCreatedAssetRemovalService.RemoveCampaignAutomaticallyCreatedAsset 새 서비스 / 메서드 캠페인에서 자동으로 생성된 최종 URL 확장 애셋을 삭제할 수 있습니다.
ServedAssetFieldType.DESCRIPTION_PREFIX 새 enum 값 ad_group_ad_asset_combination_view에서 유형이 UNKNOWN로 반환되는 보고 문제를 수정하기 위해 추가되었습니다.
캠페인
CampaignPrimaryStatusReason.MISSING_LOCATION_TARGETING 새 enum 값 위치 제한 캠페인에 위치 타겟팅이 없는 경우 반환됩니다 (이제 허용된 지역 외부를 타겟팅하면 LOCATION_TARGETING_NOT_ELIGIBLE_FOR_RESTRICTED_CAMPAIGN이 발생함).
서드 파티 앱 분석 통합 새 필드 VideoCustomer.third_party_integration_partners 및 Campaign.third_party_integration_partners 지원이 추가되었습니다. 서드 파티 앱 분석을 활용한 앱 전환 추적을 참고하세요.
Campaign.advertising_partner_ids 새 필드 지원 이제 기존 캠페인에 이 필드를 설정할 수 있습니다 (설정 후에는 변경할 수 없음).
관리자 수준 제외 게재위치 새로운 기능 CustomerNegativeCriterion를 사용하여 개별 광고주 계정에서 게재위치 목록을 제외할 수 있습니다.
타겟 ROAS 전략의 허용 범위 구성 새 필드 MaximizeConversionValue 및 TargetRoas에 TargetRoas.target_roas_tolerance_percent_millis (검색 캠페인 포트폴리오 전략용) 지원이 추가되었습니다.
LocationInterestView 새 보고 리소스 광고 그룹 위치 관심분야 기준의 실적을 요약합니다.
전환수
conversion_attribution_event_type 세그먼트 새 enum 값 전환 기여 분석 유형 옵션에 ENGAGED_VIEW이 추가되었습니다.
디맨드젠 캠페인
CampaignBudgetError.BUDGET_BELOW_DAILY_MINIMUM 새 enum 값 / 오류 디맨드젠 캠페인의 최소 일일 예산 적용을 준비하기 위해 추가되었습니다. 세부정보는 budgetDailyMinimumErrorDetails을 사용하여 노출됩니다.
실적 최대화 캠페인
campaign_search_term_view 새 보고 리소스 캠페인 수준에서 검색어 측정항목을 집계하여 실적 최대화 캠페인의 검색어 분석 및 보고를 지원합니다.
계획
ReachPlanService.ListPlannableUserInterests 새로운 방법 generateReachForecast의 계획 가능한 관심분야와 구매 의도 관심분야를 검색할 수 있습니다.
AdditionalApplicationInfo 새로운 필드 ReachPlanService.ListPlannableUserLists에 선택사항 입력으로 추가되었습니다.
AudienceInsights 속성 목록 새로운 기능 이제 AudienceInsightsService.ListAudienceInsightsAttributes에서 사용 가능한 퍼스트 파티 사용자 목록을 가져옵니다.
잠재고객 구성 통계에서 CRM 목록을 타겟팅 새로운 기능 이제 AudienceInsightsService.GenerateAudienceCompositionInsights에서 AudienceInsightsDimension 측정기준(AGE_RANGE, GENDER, AFFINITY_USER_INTEREST, IN_MARKET_USER_INTEREST)의 사용자 목록 색인 세부정보를 반환합니다.
TrendInsightMetrics 잠재고객 점유율 새로운 필드 트렌드의 잠재고객 점유율을 나타냅니다.
KnowledgeGraphAttributeMetadata 카테고리 새 필드 일치하는 카테고리로 지식 그래프 속성을 필터링합니다.
보고서
애셋 조회수 측정항목 새로운 기능 / 측정항목 AssetGroupAsset, ChannelAggregateAssetView, CampaignAggregateAssetView에 여러 새 측정항목이 추가되었습니다. 이제 실적 최대화 캠페인에서 impressions의 실제 값도 보고합니다.
선택기 확장 프로그램 새로운 기능 ChangeStatus 내에서 AssetSet 및 CampaignAssetSet을 함께 쿼리할 수 있도록 했습니다.
search_term_targeting_status 새 세그먼트 캠페인 검색어 보기에서 선택 가능한 세그먼트입니다.
final_url_expansion_asset_view 새 보고 리소스 최종 URL 확장 확장 소재 실적 세부정보를 보고합니다.
AssetGroup 가치 조정 새 필드 AssetGroup 보고서에 value_adjustment 및 all_value_adjustment 측정항목 지원이 추가되었습니다.
landing_page_source 새 세그먼트 landing_page_view에 방문 페이지 소스 세그먼트를 제공합니다.
search_term_match_source 새 세그먼트 검색어 및 캠페인 검색어 보기에서 선택할 수 있는 세그먼트입니다.
match_type 새 세그먼트 키워드 보기에서 선택 가능한 세그먼트 키입니다.
고유한 검색어 의도 클러스터 보고 새 필드 고유한 쿼리 의도 클러스터를 보고하기 위해 clicks_unique_query_clusters, conversions_unique_query_clusters, impressions_unique_query_clusters을 추가했습니다.
ClickType.VEHICLE_ASSETS 새 enum 값 click_view 보고서에서 차량 광고 형식과 관련된 클릭수를 추적하고 보고합니다.
스마트 자동 입찰 탐색
검색 전략의 허용 범위 구성 새 필드 / 설정 target_roas_tolerance_percent_millis을 10,000 (10%)~30,000 (30%) 사이로 설정하여 검색 캠페인에서 스마트 자동 입찰 탐색을 사용 설정할 수 있습니다 (전환수 최대화에는 target_roas 설정이 필요함). 스마트 자동 입찰 탐색 분석에 관한 블로그 게시물과 고객센터 도움말을 참고하세요.
다양성 보고 호환성 새로운 기능 이제 순 검색어 의도 클러스터의 다음 측정항목에 집계된 다양성 보고가 지원됩니다. Google Ads UI에서 시간 세그먼트 보기를 사용할 수 있습니다.
  • clicks_unique_query_clusters
  • conversions_unique_query_clusters
  • impressions_unique_query_clusters
동영상
YouTubeVideoListAsset 새 리소스 / 필드 Asset.youtube_video_list_asset를 사용하여 캠페인과 동영상 목록 애셋 간의 연결을 설정할 수 있습니다. 관련 동영상 사용하기를 참고하세요.
인사이트 메타데이터 확장 프로그램 새 필드 YouTubeChannelInsights 및 YouTubeVideoAttributeMetadata에 새 메타데이터가 추가되었습니다.
대화형 클릭 유형 새 enum 값 클릭 유형 VIDEO_RELATED_VIDEOS_CLICK, VIDEO_CHANNEL_CLICK, PRODUCT_ASSETS이 추가되었습니다.
VideoAdInventoryControl.allow_non_skippable_in_stream 새로운 필드 건너뛸 수 있는 형식과 건너뛸 수 없는 형식을 혼합하는 캠페인에서 동영상 반응형 광고가 건너뛸 수 없는 인스트림 광고로 게재되도록 합니다.
동영상 순서 지정 설정 새 필드 읽기 전용 시퀀싱 구성 Campaign.VideoCampaignSettings.video_ad_sequence 및 VideoAdSequenceStepSetting이 추가되었습니다. 동영상 광고 시퀀스 정보를 참고하세요.
동영상 라인업 타겟팅 새 기준 유형 / 필드 CampaignCriterion 및 AdGroupCriterion에 VIDEO_LINEUP 기준 유형과 해당 필드를 추가했습니다. 이 기능은 허용 목록에 있는 계정에서만 사용할 수 있습니다.
콘텐츠 적합성 게재위치 조회수 새 보고 리소스 세부정보 (detail_content_suitability_placement_view) 및 그룹 (group_content_suitability_placement_view) 수준 모두에 콘텐츠 적합성 보고서가 추가되었습니다. '콘텐츠 적합성' 보고서에 대한 정보를 참고하세요.

보관처리된 출시 노트

보관된 출시 노트는 지원 종료된 버전을 참고하세요.