یادداشت های انتشار

برای مشاهده‌ی فهرست به‌روز شده‌ی ویژگی‌های منسوخ‌شده‌ی فعلی و برنامه‌ریزی‌شده، به بخش منسوخ‌شده‌ها مراجعه کنید.

نسخه‌های اصلی و فرعی v25

نسخه ۲۵ رابط برنامه‌نویسی کاربردی گوگل ادز (Google Ads API) شامل ویژگی‌ها، به‌روزرسانی‌ها و تغییرات اساسی زیر است.

نسخه ۲۵.۲ (۲۰۲۶-۰۹-۲۳)

ویژگی‌ها و به‌روزرسانی‌های جدید زیر در Google Ads API نسخه ۲۵.۲ اضافه شده‌اند. نسخه‌های فرعی مانند نسخه ۲۵.۲ شامل تغییرات اساسی نیستند.

ویژگی‌ها و به‌روزرسانی‌ها نوع توضیحات
دارایی‌ها
گزینه‌های URL برای AssetGroup فیلدهای جدید پشتیبانی از گزینه‌های URL در AssetGroup اضافه شد که به تبلیغ‌کنندگان اجازه می‌دهد الگوهای ردیابی، پارامترهای سفارشی و پسوندهای نهایی URL را در سطح گروه دارایی مشخص کنند:
  • AssetGroup.tracking_url_template : الگوی URL برای ساخت یک URL ردیابی.
  • AssetGroup.url_custom_parameters : فهرستی از نگاشت‌هایی که برای جایگزینی تگ‌های پارامتر سفارشی URL در tracking_url_template ، final_urls یا final_mobile_urls استفاده می‌شوند.
  • AssetGroup.final_url_suffix : الگوی URL برای افزودن پارامترها به URLهای صفحات فرود که با ردیابی موازی ارائه می‌شوند.
کمپین‌ها
اطلاعات خزش خودکار ویدیو فیلدها و enumهای جدید AutomatedVideoCrawlSetting به Campaign.AssetAutomationSetting به همراه AssetAutomationType.AUTOMATED_VIDEO_CRAWL اضافه شد که به شما امکان می‌دهد تنظیمات خزش خودکار ویدیو را برای یک کمپین Performance Max مشخص کنید. AutomatedVideoCrawlSetting.automated_video_crawl_infos شامل لیستی از ورودی‌های AutomatedVideoCrawlInfo است که هر کدام یک url خزش، source_platform ( VideoCrawlSourcePlatform : LANDING_PAGE ، SOCIAL یا YOUTUBE ) و وضعیت انتخاب enabled پیکربندی می‌کنند.
خطاهای ضریب ارزش بهینه سازی چرخه عمر مشتری مقادیر و خطاهای جدید enum دلایل خطای اعتبارسنجی جدیدی هنگام پیکربندی ضرب‌کننده‌های ارزش ( value_multiplier و high_lifetime_value_multiplier ) برای بهینه‌سازی چرخه عمر مشتری اضافه شد:
SmartCampaignSettingService.GeneratePMaxDraftCampaign ویژگی جدید SmartCampaignSettingService.GeneratePMaxDraftCampaign برای پشتیبانی از تولید یک کمپین پیش‌نویس Performance Max از یک کمپین هوشمند موجود، که با وضعیت CampaignStatus.PAUSED و وضعیت ایجاد CampaignCreationStatus.INCOMPLETE مقداردهی اولیه شده است، اضافه شد ( به تبدیل کمپین‌های هوشمند به کمپین‌های PMax مراجعه کنید):
تبدیل‌ها
نمایش تبلیغات فایربیس انواع و دسته بندی جدید اقدامات تبدیل انواع اقدامات تبدیل FIREBASE_ANDROID_APP_AD_IMPRESSION و FIREBASE_IOS_APP_AD_IMPRESSION در معرض نمایش قرار گرفته‌اند که به شما امکان بازیابی و تغییر این اقدامات تبدیل را می‌دهد. همچنین دسته IN_APP_AD_REVENUE در دسته ConversionActionCategory برای ردیابی درآمد حاصل از تبلیغات درون برنامه‌ای در معرض نمایش قرار گرفته است.
عمومی
BusinessProfileLocationSyncError شمارش جدید و خطاها دلایل خطاهای همگام‌سازی مکان پروفایل تجاری هنگام همگام‌سازی مکان‌ها در یک AssetSet با نوع LOCATION_SYNC اضافه شد. به جای بازگرداندن یک خطای عمومی UNKNOWN ، API اکنون BusinessProfileLocationSyncError را با دلایل خاص ( EMAIL_INVALID ، OAUTH_TOKEN_INVALID ، ACCOUNT_REMOVED و NO_PERMISSION_TO_ACCESS_LOCATION_ACCOUNT ) برمی‌گرداند.
برنامه‌ریزی
معیارهای درصدی BenchmarksService.GenerateBenchmarksMetrics ویژگی‌های جدید

BenchmarksService.GenerateBenchmarksMetrics به‌روزرسانی شد تا معیارهایی را ارائه دهد که نشان‌دهنده جایگاه رقابتی مشتری در میان سایر تبلیغ‌کنندگان در قالب ردیف درصدی است. معیارها در PercentileMetrics در فیلد جدید CustomerMetrics.percentile_metrics (در هر دو GenerateBenchmarksMetricsResponse.customer_metrics و BreakdownMetrics.customer_metrics ) بازگردانده می‌شوند و با استفاده BenchmarksCustomerPercentileTier نمایش داده می‌شوند.

CustomerMetrics.percentile_metrics فقط زمانی پر می‌شود که هر دو شرط زیر در GenerateBenchmarksMetricsRequest رعایت شده باشد:

پشتیبانی از معیارهای درصدی برای تاریخ‌های سه‌ماهه‌های باز در ListBenchmarksAvailableDatesResponse.supported_dates (برگردانده شده توسط BenchmarksService.ListBenchmarksAvailableDates ) اضافه شد. در حالی که معیارهای تجمیع مشتری ( CustomerMetrics.aggregate_metrics )، معیارهای نرخ مشتری ( CustomerMetrics.average_rate_metrics ) و معیارهای درصدی مشتری ( CustomerMetrics.percentile_metrics ) در تمام تاریخ‌های موجود در supported_dates (از جمله سه‌ماهه‌های باز) پشتیبانی می‌شوند، معیارهای سهم مشتری ( CustomerMetrics.share_metrics ) و معیارهای نرخ منبع معیارها ( average_benchmarks_metrics ، مانند average_cpm تبلیغات "/Apparel/Clothing") برای سه‌ماهه‌های باز پشتیبانی نمی‌شوند و از پاسخ حذف می‌شوند، مگر اینکه date_range درخواستی در محدوده محدودتر ListBenchmarksAvailableDatesResponse.supported_dates_for_all_metrics قرار گیرد.

یک خطای BenchmarksError.NO_METRICS_FOUND سفارشی اضافه شد که نشان می‌دهد هیچ معیاری برای ترکیب انتخاب‌شده از ورودی‌ها یافت نشده است تا قابلیت استفاده را بهبود بخشد.

دسته بندی کانال های یوتیوب برای بینش خالقان ویژگی جدید ContentCreatorInsightsService.GenerateCreatorInsights به‌روزرسانی شد تا از جستجو بر اساس شناسه‌های کانال یوتیوب با استفاده از YouTubeChannels.youtube_channel_handles پشتیبانی کند (شناسه‌های کانال معتبر باید با @ شروع شوند، مانند @channel_handle ). این گزینه مشابه جستجو بر اساس شناسه‌های کانال یوتیوب است. پاسخ شامل اطلاعاتی در مورد سازندگان یوتیوب درخواستی است.
توصیه‌ها
توصیه‌های قیمت‌گذاری CPA و ROAS توصیه‌های جدید اضافه شدن Recommendation.raise_target_cpa_performance_bid_too_low_recommendation ( RAISE_TARGET_CPA_PERFORMANCE_BID_TOO_LOW ) و Recommendation.lower_target_roas_performance_bid_too_low_recommendation ( LOWER_TARGET_ROAS_PERFORMANCE_BID_TOO_LOW ) به همراه ApplyRecommendationOperation.raise_target_cpa_performance_bid_too_low و ApplyRecommendationOperation.lower_target_roas_performance_bid_too_low برای پشتیبانی از افزایش CPA هدف یا کاهش ROAS هدف، زمانی که پیشنهادات برای کمپین‌های جستجو برای ورود به مزایده‌ها بسیار پایین هستند:
گزارش‌ها
بخش‌های ابعاد برنامه سفر هتل بخش‌های جدید بخش‌های زیر مربوط به رزرو هتل و برنامه سفر با ابعاد زیر به Segments ) اضافه شد (که با campaign ، ad_group و customer قابل انتخاب هستند):
معیارهای تبلیغات عمودی معیارهای جدید معیارهای زیر برای گزارش تبلیغات عمودی هتل و سفر به Metrics اضافه شد (با استفاده از campaign ، ad_group و customer قابل انتخاب است):
بخش‌های تبلیغات عمودی بخش‌های جدید بخش‌های زیر برای گزارش تبلیغات عمودی هتل و سفر به Segments اضافه شد (قابل انتخاب با campaign ، ad_group و customer ):

نسخه ۲۵.۱ (۲۰۲۶-۰۸-۱۹)

ویژگی‌ها و به‌روزرسانی‌های جدید زیر در Google Ads API نسخه ۲۵.۱ اضافه شده‌اند. نسخه‌های فرعی مانند نسخه ۲۵.۱ شامل تغییرات اساسی نیستند.

ویژگی‌ها و به‌روزرسانی‌ها نوع توضیحات
دارایی‌ها
AssetFieldType.TEXT_DISCLAIMER
ServedAssetFieldType.TEXT_DISCLAIMER		 مقادیر شمارشی جدید پشتیبانی از فایل‌های سلب مسئولیت متنی اضافه شد.
کمپین‌ها
Campaign.aca_migration_date_time
Campaign.broad_match_migration_date_time		 فیلدهای جدید مهاجرت خودکار آتی به AI Max را پیگیری کنید.
تبدیل‌ها
اندازه گیری های برند لیفت ویژگی‌های جدید پشتیبانی از اندازه‌گیری‌های Brand Lift با به‌روزرسانی‌های زیر اضافه شد:
اندازه‌گیری‌های لیفت تبدیلی ویژگی‌های جدید پشتیبانی از اندازه‌گیری‌های Conversion Lift با به‌روزرسانی‌های زیر اضافه شد:
  • یک منبع فقط خواندنی جدید LiftMeasurementConfig اضافه شد که نشان‌دهنده‌ی مطالعه‌ی لیفت است.
  • بخش‌های قابل انتخاب جدیدی به بخش‌بندی و فیلتر کردن نتایج لیفت اضافه شد.
  • ۲۴ معیار جدید Conversion Lift و معیارهای امتیاز برنده اضافه شده است که از تجزیه و تحلیل آماری دقیق عملکرد Lift پشتیبانی می‌کنند.
  • پشتیبانی برای بازیابی جزئیات کمپین و اهداف تبدیل اضافه شد.
  • یک فیلد اختیاری جدید به نام Experiment.lift_measurement_config اضافه شد.
  • شمارشگر ConversionLiftIncludedConversionActionTypes اضافه شد.
LiftMeasurementFlight منبع جدید یک منبع فقط خواندنی جدید که جزئیات پرواز را برای پیکربندی اندازه‌گیری لیفت، از جمله تاریخ‌های شروع و پایان اندازه‌گیری شده پرواز ( start_date و end_date ) نشان می‌دهد.
عمومی
SmartCampaignError مقادیر شمارشی جدید کدهای خطای خاص جدیدی برای محدودیت‌های تولید Performance Max اضافه شد:
AuthorizationErrorEnum.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION مقدار / خطای شمارشی جدید زمانی برمی‌گردد که یک پروژه Google Cloud با سطح دسترسی TEST تلاش می‌کند درخواست‌هایی را علیه یک حساب کاربری غیرتست ارسال کند.
برنامه‌ریزی
بینش‌های مربوط به احساسات برند ویژگی‌های جدید پشتیبانی از بینش‌های مربوط به احساسات برند در ContentCreatorInsightsService اضافه شد:
بهبودهای BenchmarksService ویژگی‌های جدید پشتیبانی از دسته‌ها به عنوان فیلتر برای تعیین محدوده تحلیل معیارها اضافه شد. همچنین از معیارهای حیاتی تجاری بیشتری پشتیبانی می‌شود:
  • گزینه‌ای برای مقایسه با تمام تبلیغ‌کنندگانی که تبلیغات را در یک یا چند دسته محصول و خدمات اجرا می‌کنند، با استفاده BenchmarksService.GenerateBenchmarksMetrics و category_filter اضافه شد.
  • معیارهای بیشتری از تبلیغات مشتری، مانند هزینه و بازدیدهای کلی مشتری، و معیارهای اشتراک‌گذاری مانند share_of_voice نمایش داده شد. معیارها با استفاده از AggregateMetrics و ShareMetrics بازگردانده می‌شوند.
  • فهرست دسته‌بندی‌های پشتیبانی‌شده را می‌توان با استفاده از BenchmarksService.ListBenchmarksSources با نوع منبع CATEGORY بازیابی کرد.
هدف‌گیری وضعیت والدین ویژگی جدید پشتیبانی از هدف‌گیری وضعیت والدین در برنامه‌ریزی دسترسی اضافه شد. فیلد جدید parental_statuses به Targeting برای سرویس ReachPlanService.GenerateReachForecast و parental_statuses به PlannableTargeting برای سرویس ReachPlanService.ListPlannableProducts اضافه شد.
توصیه‌ها
Recommendation.campaign_specific_app_goal_recommendation توصیه جدید پیشنهاد می‌کند یک هدف تبدیل مختص کمپین به اپلیکیشن اضافه شود. منبع جدید EffectiveAutomaticGoal برای نمایش اهداف فعلی در این پیشنهاد استفاده می‌شود.
گزارش‌ها
Metrics.original_conversion_value میدان جدید مقدار تبدیل اصلی را از تبدیل‌های قابل پیشنهاد نشان می‌دهد. این مقدار، مقدار تعدیل نشده تبدیل‌ها قبل از اعمال هرگونه تنظیم قانون مقدار، مانند قوانین مقدار تبدیل یا تنظیمات اهداف چرخه عمر، است.
آمار عضویت وفاداری ویژگی‌های جدید پشتیبانی از بخش‌بندی آمار بر اساس وضعیت برنامه عضویت وفاداری کاربر اضافه شد و بُعد اصلی عضویت وفاداری برای قوانین ارزش تبدیل اضافه شد:
  • بخش Segments.loyalty_membership برای پشتیبانی از تقسیم‌بندی معیارهای گزارش بر اساس سطح برنامه وفاداری کاربر در حال تبدیل، اضافه شد.
  • بُعد اصلی LOYALTY_MEMBERSHIP برای شناسایی زمان برآورده شدن شرط عضویت وفاداری برای یک قانون ارزش تبدیل اضافه شد.
هدف‌گیری
vertical_ads_item_bid نوع معیار جدید نوع معیار جدید vertical_ads_item_bid به AdGroupCriterion.criterion اضافه شد.

نسخه ۲۵ (۲۰۲۶-۰۷-۲۲)

ویژگی‌های جدید، به‌روزرسانی‌ها و تغییرات اساسی زیر در Google Ads API v25 اضافه شده‌اند که یک نسخه اصلی محسوب می‌شود.

برای راهنمایی به بخش ارتقا به آخرین نسخه مراجعه کنید.

شکستن تغییرات

حالت اولیه ایالت جدید نوع تغییر راهنمای پیاده‌سازی
کمپین‌ها
فیلدهای مستقل additional_value و additional_high_lifetime_value در CustomerLifecycleOptimizationValueSettings به ترتیب بخشی از value_adjustment و high_lifetime_value_adjustment ، در کنار فیلدهای جدید value_multiplier و high_lifetime_value_multiplier تغییر ساختاری ارجاعات به این فیلدها را به‌روزرسانی کنید، زیرا اکنون بخشی از oneofs هستند.
منابع قدیمی CustomerLifecycleGoal و CampaignLifecycleGoal ، سرویس‌های متناظر آنها CustomerLifecycleGoalService و CampaignLifecycleGoalService ، و تنظیمات/enumهای قدیمی ( CustomerAcquisitionGoalSettings ، CustomerAcquisitionOptimizationModeEnum ، LifecycleGoalValueSettings ) هیچکدام حذف از طرحواره اهداف یکپارچه اصلاح‌شده استفاده کنید:
عمومی
فیلدهای شمارشی تو در تو در پیام‌های درخواست و پاسخ سرویس تشویقی:
  • FetchIncentiveRequest.type
  • Incentive.type
  • IncentiveOffer.type
 فیلدهای شمارشی مستقل: تغییر نام / حذف به جای فیلدهای type قدیمی، از فیلدهای enum مستقل جدید استفاده کنید.
فیلدهای selected_incentive_id و customer_id اختیاری در ApplyIncentiveRequest فیلدهای مورد نیاز تغییر رفتاری هنگام فراخوانی ApplyIncentive مطمئن شوید که هر دو فیلد را ارائه می‌دهید.
فیلد آدرس ایمیل مصرف‌کننده ContactDetails.email در منبع LocalServicesLead هیچکدام حذف ارجاعات به این فیلد را حذف کنید زیرا دیگر پشتیبانی نمی‌شود.
فیلد اختیاری allowed_domain در AdvertisingPartnerLinkInvitationProperties فیلدهای ضروری هنگام فراخوانی CreateProductLinkInvitation برای یک شریک تبلیغاتی تغییر رفتاری هنگام ایجاد دعوتنامه لینک محصول برای یک شریک تبلیغاتی، مطمئن شوید که allowed_domain را ارائه می‌دهید.
برنامه‌ریزی
فیلد search_brand در GenerateCreatorInsightsRequest هیچکدام حذف به جای آن search_topics استفاده کنید.
فیلد plannable_location_id در Targeting و فیلد cookie_frequency_cap در GenerateReachForecastRequest هیچکدام حذف به استفاده از plannable_location_ids و cookie_frequency_cap_setting تغییر دهید.
گزارش‌ها
فیلد customer_metrics در GenerateBenchmarksMetricsResponse و BreakdownMetrics از نوع Metrics فیلد از نوع CustomerMetrics تغییر نوع / تغییر رفتاری ادغام‌های خود را به‌روزرسانی کنید تا از نوع جدید CustomerMetrics استفاده کنید، که فقط شامل معیارهایی است که عملکرد تبلیغ مشتری را نشان می‌دهند.

ویژگی‌ها و به‌روزرسانی‌ها (غیر قابل شکستن)

ویژگی‌ها و به‌روزرسانی‌ها نوع توضیحات
تبلیغات
AssetAutomationType.GENERATE_ANIMATED_IMAGES_FROM_OTHER_ASSETS مقدار/رفتار جدید enum برای DemandGenMultiAssetAds موجود است. در صورت فعال بودن، با استفاده از تصاویر غیرمتحرک به عنوان ورودی، تصاویر متحرک تولید می‌کند. DemandGenMultiAssetAds جدید به طور پیش‌فرض از این نسخه API انتخاب می‌شوند.
تغییرپذیری اطلاعات محتوای مصنوعی تغییر رفتار Asset.synthetic_content_info و Ad.synthetic_content_info اکنون در نسخه‌های ۲۵، ۲۴ و ۲۳ کاملاً قابل تغییر هستند.
کمپین‌ها
هدف حفظ وفاداری ویژگی‌ها/تنظیمات جدید پشتیبانی از هدف حفظ وفاداری اضافه شد، که به تبلیغ‌کنندگان اجازه می‌دهد کمپین‌ها را برای حفظ اعضای برنامه وفاداری بهینه کنند.
هدف جذب مشتری جدید ویژگی‌ها/تنظیمات جدید پشتیبانی از هدف جذب مشتری جدید در API گوگل ادز به‌روزرسانی شد تا طرحواره اهداف یکپارچه اصلاح‌شده را منعکس کند:
تبدیل‌ها
انتساب تبدیل شخص ثالث یوتیوب فیلدهای جدید پشتیبانی از تأیید انتساب تبدیل YouTube با استفاده از شرکای شخص ثالث اضافه شد: برای کسب اطلاعات بیشتر به مقاله مرکز راهنمایی مراجعه کنید.
عمومی
ContactDetails.phone_number_extension میدان جدید به منبع LocalServicesLead اضافه شد.
IncentiveError مقادیر و خطاهای جدید enum کدهای خطای خاص جدیدی برای شکست‌های بازخرید تشویقی اضافه شد:
  • BILLING_COUNTRY_NOT_ELIGIBLE (کشوری که مشتری از آن صورتحساب صادر می‌کند واجد شرایط دریافت این طرح تشویقی نیست)
  • USER_IS_MCC_MANAGER (کاربر یک حساب مدیر است و نمی‌تواند از طرح تشویقی استفاده کند)
  • USER_SUSPENDED (حساب مشتری به حالت تعلیق درآمده است)
  • MAX_PENDING_INCENTIVES (مشتری به حداکثر تعداد مشوق‌های در انتظار رسیده است)
  • ACCOUNT_HAD_RECENT_SPEND (حساب اخیراً خرج شده و واجد شرایط نیست)
  • MAX_INCENTIVES_REDEEMED_FROM_OFFER (مشتری قبلاً حداکثر تعداد مشوق‌های این پیشنهاد را استفاده کرده است)
  • MISMATCHING_BILLING_COUNTRY_CODE (کد کشور صورتحساب ارائه شده در درخواست با کشور حساب مشتری مطابقت ندارد)
برنامه‌ریزی
جزئیات کانال یوتیوب در بخش بینش‌های پرطرفدار فیلدهای جدید پشتیبانی از جزئیات بیشتر کانال یوتیوب مربوط به ویدیوهای مرتبط هنگام جستجوی اطلاعات مربوط به ترندها اضافه شد. فیلدهای جدید channel_id ، channel_name و channel_url به YouTubeVideoAttributeMetadata اضافه شد.
YouTubeChannelInsights.data_sharing_consent_given میدان جدید به YouTubeChannelInsights اضافه شد. این در صورتی صادق است که سازنده به اشتراک‌گذاری داده‌های غیرعمومی رضایت داده باشد. در این صورت، فیلدهای زیر پر می‌شوند:
گزارش‌ها
ad_sub_format_type بخش جدید تفکیکی از تبلیغات غیرقابل رد شدن در پخش زنده یوتیوب بر اساس مدت زمان ارائه می‌دهد: این بخش همیشه باید همراه با ad_format_type انتخاب شود. این بخش با AdGroup ، AdGroupAd ، Campaign ، Customer ، Video و VideoEnhancement قابل انتخاب است.
معیارهای اجتماعی مختص ویدیو فیلدها/معیارهای جدید معیارهای اجتماعی مختص ویدیو اضافه شده است تا به تبلیغ‌کنندگان کمک کند تا میزان مشارکت کاربران (نظرات، لایک‌ها و اشتراک‌گذاری‌ها) را برای تبلیغات Shorts در یوتیوب ردیابی کنند: آنها در AdGroup ، AdGroupAd ، Asset ، Campaign ، Customer و Video در دسترس هستند.

نسخه‌های اصلی و فرعی v24

نسخه ۲۴ رابط برنامه‌نویسی کاربردی گوگل ادز (Google Ads API) شامل ویژگی‌ها، به‌روزرسانی‌ها و تغییرات اساسی زیر است.

نسخه ۲۴.۲ (۲۴-۰۶-۲۰۲۶)

ویژگی‌ها و به‌روزرسانی‌های جدید زیر در Google Ads API نسخه ۲۴.۲ اضافه شده‌اند. نسخه‌های فرعی مانند نسخه ۲۴.۲ شامل تغییرات اساسی نیستند.

ویژگی‌ها و به‌روزرسانی‌ها نوع توضیحات
تبلیغات
AssetAutomationType.GENERATE_LANDING_PAGE_TEXT مقدار شمارشی جدید اطلاعات متنی را از صفحه فرود تولید می‌کند تا در پنل تعامل برای نمونه‌های DemandGenVideoResponsiveAd (که به طور پیش‌فرض از این نسخه API انتخاب شده‌اند) نمایش داده شود.
دارایی‌ها
AssetGroup.google_local_services_info میدان جدید برای پشتیبانی از اطلاعات تبلیغات خدمات محلی (شناسه دسته و توضیحات) در کمپین‌های Performance Max اضافه شد.
AssetGroupSignal.local_services_id میدان جدید برای پشتیبانی از سیگنال‌های شناسه سرویس تبلیغات خدمات محلی در کمپین‌های Performance Max اضافه شد.
AssetGroupSignal.vertical_ads_item_group_rule_list میدان جدید برای پشتیبانی از قوانین گروه آیتم‌های تبلیغات عمودی برای انتخاب آیتم‌ها از فیدهای عمودی پیوست‌شده در کمپین‌های Performance Max اضافه شده است. این ویژگی فقط برای حساب‌های موجود در لیست مجاز در دسترس است.
AssetGroupErrorEnum.CANNOT_REMOVE_ALL_ASSET_GROUPS_FROM_CAMPAIGN مقدار / خطای شمارشی جدید هنگام تلاش برای حذف همه گروه‌های دارایی از یک کمپین، بازگردانده می‌شود.
AssetGroupSignalErrorEnum.CANNOT_REMOVE_ALL_SIGNALS مقدار / خطای شمارشی جدید هنگام تلاش برای حذف همه سیگنال‌ها از یک گروه دارایی، بازگردانده می‌شود.
کمپین‌ها
Campaign.PmaxCampaignSettings.local_services_pmax_campaign_settings
Campaign.PmaxCampaignSettings.local_services_enabled		 فیلدهای جدید از شناسایی کمپین‌های «حداکثر عملکرد خدمات محلی» پشتیبانی کنید.
AdGroup.DemandGenAdGroupSettings.DemandGenChannelControls.DemandGenSelectedChannels.maps میدان جدید نقشه‌های گوگل را در کانال‌های قابل انتخاب برای گروه‌های تبلیغاتی Demand Gen قرار می‌دهد.
CampaignCriterionErrorEnum.CANNOT_REMOVE_ALL_LOCATIONS_FROM_LOCAL_SERVICES_PMAX_CAMPAIGN مقدار / خطای شمارشی جدید هنگام تلاش برای حذف همه مکان‌ها از یک کمپین خدمات محلی با حداکثر عملکرد، این خطا بازگردانده شد.
SmartCampaignErrorEnum.CREATION_FAILED مقدار / خطای شمارشی جدید هنگام تلاش برای ایجاد کمپین‌های هوشمند جدید، این خطا برمی‌گشت.
تبدیل‌ها
ConversionOrigin.LOCAL_SERVICES_ADS
ConversionActionType.LOCAL_SERVICES_ADS		 مقادیر شمارشی جدید تبدیل‌هایی را نشان می‌دهد که وقتی کاربر روی یک تبلیغ خدمات محلی کلیک می‌کند و با تبلیغ‌کننده تماس می‌گیرد، پیام می‌دهد یا رزرو می‌کند، رخ می‌دهد.
آزمایش‌ها
COMPARE_CAMPAIGNS
PMAX_TEXT_CUSTOMIZATION_FINAL_URL_EXPANSION		 مقادیر شمارشی جدید پشتیبانی از انواع جدید ExperimentType اضافه شد:
  • COMPARE_CAMPAIGNS : برای آزمایش‌های ترکیبی کمپین و آزمایش‌های سفارشی حداکثر عملکرد که چندین کمپین از انواع یکسان یا متفاوت را در یک آزمایش واحد مقایسه می‌کنند.
  • PMAX_TEXT_CUSTOMIZATION_FINAL_URL_EXPANSION : برای آزمایش‌های بهینه‌سازی Performance Max برای سفارشی‌سازی متن و بسط نهایی URL.
عمومی
Asset.synthetic_content_info
Ad.synthetic_content_info		 فیلدهای جدید شامل گواهی‌هایی برای محتوای مصنوعی/تولید شده توسط هوش مصنوعی است که به دو بخش advertiser_attestation (اعلان‌هایی که مستقیماً توسط تبلیغ‌کننده ارائه می‌شوند) و system_attestation (گواهی‌هایی که به‌طور خودکار توسط سیستم شناسایی یا ارائه می‌شوند) تقسیم می‌شوند.

این ویژگی به نسخه‌های ۲۳ و ۲۲ بک‌پورت شده است.

برای کمک به شما در برنامه‌ریزی کارهای ادغام آینده‌تان برای نسخه ۲۵، رابط کاربری برای تغییر فیلدهای گواهی تبلیغ‌کننده برای نسخه ۲۲ و بالاتر، زودتر معرفی می‌شود. این رابط کاربری در این نسخه‌ها قابل مشاهده است، اما synthetic_content_info.advertiser_attestation.status و synthetic_content_info.advertiser_attestation.source برای این نسخه‌ها تغییرناپذیر باقی خواهند ماند.

اگر درخواست تغییر (mutate) را در هر یک از این فیلدها امتحان کنید، یکی از این خطاها برگردانده خواهد شد:

«فیلدی که تلاش برای تغییر آن شده است، تغییرناپذیر است» یا «فیلد قابل تنظیم نیست».

این فیلدها از نسخه ۲۵ به بعد کاملاً قابل تغییر خواهند بود. توصیه می‌کنیم همین حالا از رابط کاربری برای ساخت و آزمایش منطق داخلی خود استفاده کنید تا سیستم شما هنگام راه‌اندازی نسخه ۲۵ برای قابلیت‌های کامل نوشتن آماده باشد.

مجوز چندجانبه ویژگی‌های جدید پشتیبانی از بررسی‌های مجوز چندجانبه (MPA) اضافه شد:
این ویژگی به نسخه‌های ۲۳.۳ ، ۲۲.۲ و ۲۱.۲ بک‌پورت شده است.
IncentiveService.FetchIncentive تغییر رفتاری وقتی یک آدرس ایمیل نامعتبر در درخواست ارائه می‌شود، این متد اکنون به جای نمایش خطای AuthenticationError.INVALID_EMAIL_ADDRESS ، پیشنهادات تشویقی پیش‌فرض را برمی‌گرداند.
برنامه‌ریزی
GenerateCreatorInsightsRequest.search_topics میدان جدید به سرویس ContentCreatorInsightsService.GenerateCreatorInsights اضافه شد. این گزینه به دنبال سازندگانی می‌گردد که در مورد موضوعی در کشور مشخص شده در country_locations صحبت می‌کنند (فقط از جستجوی یک کشور پشتیبانی می‌کند).
CREATOR_TOPIC_INSIGHTS مقدار شمارشی جدید به 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 باشد، پر می‌شود. سازندگان محلی را که در کشور انتخاب شده مشاهده شده‌اند یا در آن مستقر هستند و به اشتراک‌گذاری داده‌های موقعیت مکانی رضایت داده‌اند، نمایش می‌دهد.
GenerateTrendingInsightsRequest.sub_country_locations میدان جدید به ContentCreatorInsightsService.GenerateTrendingInsights اضافه شد و امکان جستجو برای بینش‌های پرطرفدار با استفاده از موقعیت مکانی کشور و موقعیت‌های مکانی زیرکشور را فراهم می‌کند.
گزارش‌ها
PerformanceMaxPlacementView گسترش بخش‌ها توسط ad_network_type قابل تقسیم‌بندی شده است.
خرید
Campaign.ShoppingSetting.ignore_brand_exclusion_in_shopping_ads میدان جدید اگر درست باشد، استثنائات برند برای تبلیغات خرید نادیده گرفته می‌شوند. فقط برای کمپین‌های خرید پشتیبانی می‌شوند.
هدف‌گیری
CriterionErrorEnum.CANNOT_TARGET_LANGUAGE مقدار / خطای شمارشی جدید هنگام تلاش برای هدف قرار دادن زبانی که مجاز نیست، برگردانده می‌شود.
ویدیوها
DataLink.youtube_link_metadata میدان جدید شامل brand_channel_id برای مشخص کردن شناسه کانال برند یوتیوب لینک‌شده است.

نسخه ۲۴.۱ (۲۰۲۶-۰۵-۱۳)

ویژگی‌ها و به‌روزرسانی‌های جدید زیر در Google Ads API نسخه ۲۴.۱ اضافه شده‌اند. نسخه‌های فرعی مانند نسخه ۲۴.۱ شامل تغییرات اساسی نیستند.

ویژگی‌ها و به‌روزرسانی‌ها نوع توضیحات
تبلیغات
DemandGenMultiAssetAdInfo.classic_display_images میدان جدید تصاویر نمایشی آپلود شده سفارشی بدون نیاز به فایل‌های واکنش‌گرای اضافی ارائه می‌شوند.
آزمایش‌ها
ADOPT_AI_MAX
ADOPT_BROAD_MATCH_KEYWORDS
OPTIMIZE_ASSETS
PMAX_REPLACEMENT_SHOPPING		 مقادیر شمارشی جدید پشتیبانی از انواع جدید ExperimentType اضافه شد:
  • ADOPT_AI_MAX : برای آزمایش‌هایی که بررسی می‌کنند چگونه AI Max می‌تواند به شما در جذب مشتریان بیشتر با استفاده از هوش مصنوعی گوگل و کلمات کلیدی با تطابق گسترده کمک کند.
  • ADOPT_BROAD_MATCH_KEYWORDS : برای آزمایش‌هایی که بررسی می‌کنند کلمات کلیدی با تطابق گسترده چگونه می‌توانند بر تعداد جستجوهایی که تبلیغات شما در آنها ظاهر می‌شود تأثیر بگذارند.
  • OPTIMIZE_ASSETS : برای آزمایش‌های سفارشی جهت بهینه‌سازی دارایی‌ها.
  • PMAX_REPLACEMENT_SHOPPING : برای آزمایش‌هایی که عملکرد کمپین‌های خرید شما را در مقایسه با Performance Max بررسی می‌کنند.
Experiment.video_experiment میدان جدید پشتیبانی از پیکربندی برای آزمایش‌های موجود YOUTUBE_CUSTOM شامل کمپین‌های ویدیویی.
ExperimentArm.asset_testing_info
ExperimentArm.asset_groups
ExperimentArm.performance_max_experiment_arm_info		 فیلدهای جدید فیلدهایی را برای پشتیبانی از آزمایش دارایی‌ها، گروه‌های دارایی و تنظیمات حداکثر عملکرد در بازوهای آزمایش در معرض نمایش قرار می‌دهد:
  • asset_testing_info : جزئیات دارایی‌های مرتبط با نسخه‌های آزمایشی تبلیغات.
  • asset_groups : فهرست گروه‌های دارایی در بازوی آزمایش برای آزمایش‌های Optimize Assets.
  • performance_max_experiment_arm_info : تنظیمات مربوط به کمپین‌های Performance Max در آزمایش‌های PMAX_REPLACEMENT_SHOPPING .
عمومی
CustomerUserAccess.passkey_enabled میدان جدید فیلد فقط خواندنی که نشان می‌دهد آیا کاربر رمز عبور را فعال کرده است یا خیر.
گزارش‌ها
mobile_device_platform بخش جدید امکان تقسیم‌بندی گزارش‌ها بر اساس پلتفرم دستگاه کاربر (مانند iOS یا اندروید) را فراهم می‌کند.
REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED مقدار / خطای شمارشی جدید زمانی برگردانده می‌شود که جزئیات زمانی روزانه، ساعتی یا هفتگی درخواستی برای محدوده‌های تاریخ پرس‌وجو پشتیبانی نمی‌شود (فقط برای ۳۷ ماه گذشته در دسترس است).
vertical_ads_listing_user_rating
vertical_ads_listing_venue		 بخش‌های جدید بخش‌های جدیدی که برای تبلیغات عمودی استفاده خواهند شد.
user_rating ، venue ، event_participant_display_name معیارهای فیلتر جدید فیلترینگ پشتیبانی شده در VerticalAdsItemGroupRuleInfo برای منبع SharedCriterion .
معیارهای آزمایش کنترل/درمان فیلدهای جدید مقادیر کنترل ( control_clicks و غیره)، مقادیر درمان ( clicks و غیره)، تخمین‌های نقطه‌ای ( clicks_point_estimate و غیره)، حاشیه‌های خطا ( clicks_margin_of_error و غیره) و مقادیر p ( clicks_p_value و غیره) در هفت خانواده اصلی معیار (کلیک‌ها، نمایش‌ها، هزینه، تبدیل‌ها، هزینه به ازای هر تبدیل، مقدار تبدیل، مقدار تبدیل به ازای هر هزینه) اضافه شد.
معیارهای تغییر مطلق تبدیل‌ها فیلدهای جدید پشتیبانی از Conversions برای تخمین تفاضل مطلق با استفاده از تخمین نقطه‌ای، حاشیه خطا و فیلدهای مقدار p.
هدف‌گیری
CriterionErrorEnum.CANNOT_EXCLUDE_ALL_TARGETS مقدار / خطای شمارشی جدید هنگام تلاش برای حذف همه اهداف جمعیتی، بازگردانده شد.
ویدیوها
ThirdPartyViewabilityIntegrationPartnerEnum.ZEFR مقدار شمارشی جدید ZEFR را به عنوان شریک شخص ثالث برای ادغام قابلیت مشاهده منتشر کرد.
DataLink.youtube_video.channel_id میدان جدید شناسه کانال یوتیوب مرتبط با لینک داده را افشا می‌کند.

نسخه ۲۴ (۲۰۲۶-۰۴-۲۲)

ویژگی‌های جدید، به‌روزرسانی‌ها و تغییرات اساسی زیر در Google Ads API v24 اضافه شده‌اند که یک نسخه اصلی است.

برای راهنمایی به بخش ارتقا به آخرین نسخه مراجعه کنید.

شکستن تغییرات

حالت اولیه ایالت جدید نوع تغییر راهنمای پیاده‌سازی
تبلیغات
videos و logo_images اختیاری در DemandGenVideoResponsiveAdInfo فیلدهای مورد نیاز تغییر رفتاری هنگام ایجاد یا تغییر تبلیغات ویدیویی واکنش‌گرای Demand Gen، videos و logo_images را ارائه دهید.
videos ، business_name و logo_images اختیاری در VideoResponsiveAdInfo فیلدهای مورد نیاز تغییر رفتاری هنگام ایجاد یا تغییر تبلیغات ویدیویی واکنش‌گرا، videos ، business_name و logo_images را ارائه دهید. توجه داشته باشید که VideoResponsiveAdInfo اکنون قابل تغییر است.
کمپین‌ها
Campaign.video_brand_safety_suitability هیچکدام حذف کنترل مناسب بودن در سطح کمپین حذف شده است. مناسب بودن برای ایمنی برند هنوز در سطح مشتری موجود است. به جای آن Customer.video_brand_safety_suitability استفاده کنید.
تبدیل‌ها
UserListCustomerTypeCategoryEnum.LOYALTY_SIGN_UPS هیچکدام حذف دسته بندی کاربران ثبت نام شده در طرح وفاداری حذف شده است. ارجاعات کد به آن را حذف کنید.
برنامه‌ریزی
InsightsAudienceAttributeGroup نوع گروه برای topic_audience_combinations common. InsightsAudienceAttributeGroup گروه تغییر رفتار / تغییر نوع ادغام‌های کتابخانه‌های کلاینت تایپ‌شده باید برای استفاده از فضاهای نام منابع جدید به‌روزرسانی شوند.
فیلد youtube_select_lineups در ReachPlanService.ListPlannableProducts هیچکدام حذف به استفاده از ترکیب‌های بازی از youtube_select_lineup_targeting تغییر دهید.
فیلد is_brand_connect_creator در ContentCreatorInsightsService.GenerateCreatorInsights و GenerateTrendingInsights هیچکدام حذف در عوض، بررسی کنید که آیا سازنده، CREATOR_PARTNERSHIPS را در partnership_opportunities در دسترس دارد یا خیر.
geo_modifiers و biddable_keywords در KeywordPlanIdeaService.GenerateKeywordForecastMetrics geo_target_constants و keywords تغییر نام / حذف با CampaignToForecast.geo_target_constants[] و ForecastAdGroup.keywords[] جایگزین شده است.
فیلدهای برنامه‌ریزی/پیش‌بینی کلمات کلیدی منسوخ‌شده در GenerateKeywordForecastMetrics هیچکدام حذف فیلدها و انواع طرح/پیش‌بینی زیر حذف شدند: بر این اساس، ادغام‌ها را به‌روزرسانی کنید.
گزارش‌ها
بخش ad_sub_network_type در campaign_budget هیچکدام حذف بخش ad_sub_network_type برای منبع campaign_budget حذف شد.
بخش click_type در نماهای دارایی هیچکدام حذف بخش از نماهای AdGroupAsset ، CampaignAsset و CustomerAsset حذف شد.
ویدیوها
خطای جزئی در ShareablePreviewService.GenerateShareablePreviews مجاز است. بدون خرابی جزئی تغییر رفتاری اگر اعتبارسنجی هر یک از شناسه‌های درون درخواست با شکست مواجه شود، درخواست‌ها با شکست مواجه شده و خطا می‌دهند.
کدهای خطای قدیمی ShareablePreviewError : MutateErrorEnum.RESOURCE_NOT_FOUND
ShareablePreviewError.TOO_MANY_RESOURCES_IN_REQUEST		 تغییر نام / تغییر رفتار کدهای خطایی که برای گروه‌های دارایی برگردانده می‌شوند، برای هم‌ترازی با خطاهای تبلیغات گروه‌های تبلیغاتی اصلاح می‌شوند. منطق اعتبارسنجی به‌روزرسانی می‌شود.

ویژگی‌ها و به‌روزرسانی‌ها (غیر قابل شکستن)

ویژگی‌ها و به‌روزرسانی‌ها نوع توضیحات
تبلیغات
تغییرپذیری VideoResponsiveAdInfo تغییر رفتاری اشیاء اطلاعاتی تبلیغات ویدیویی واکنش‌گرا اکنون قابل تغییر هستند.
دارایی‌ها
travel_feed_data در AssetSet میدان جدید برای بازیابی ویژگی‌های دارایی‌های فید مسافرتی ( hotel_center_account_id ، merchant_center_id ، partner_center_id ، subset_id ، travel_feed_vertical_type ) اضافه شد.
کمپین‌ها
Campaign.view_through_conversion_optimization_enabled میدان جدید امکان فعال‌سازی بهینه‌سازی تبدیل از طریق نمایش (VTC) (پیش‌فرض false ) را در کمپین‌های Demand Gen و App فراهم می‌کند.
CampaignCriterion.gender ویژگی جدید امکان حذف جنسیت برای کمپین‌های Performance Max در تمام نسخه‌های API گوگل ادز.
تبدیل‌ها
انواع تبدیل سرنخ (لید جنریشن) مقادیر شمارشی جدید enum های نوع عمل تبدیل GA4/Firebase جدید در ConversionActionType اضافه شد:
  • 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 مقدار / خطای شمارشی جدید هنگام تلاش برای ایجاد چندین لیست مشابه، بازگردانده می‌شود.
برنامه‌ریزی
فیلدهای ProductCoreAttributes در ListPlannableProductsResponse فیلدهای جدید Added plannable product description, marketing objective, cost model, and buying method to ProductCoreAttributes under ListPlannableProductsResponse .
گزارش‌ها
CartDataSalesView New reporting resource Exposes reports segmenting conversions metrics by the specific product sold (brand, etc.) in addition to the clicked product.
Non-biddable metrics New fields Added non-biddable metrics (metrics showing conversions that campaigns are not optimizing for) to all matching resources:
conversion_attribution_event_type New segment Added to ShoppingPerformanceView .
خرید
App campaigns in ShoppingProduct ویژگی جدید Supported App campaigns inside the ShoppingProduct resource. Note status and issues are not supported.
Tag-based product filtering ویژگی جدید Introduced filtering using logical set expressions dynamically: This feature is only available to accounts on the allowlist.

v23 major and minor versions

Google Ads API v23 includes the following new features, updates, and breaking changes.

v23.3 (2026-06-24)

The following new features and updates were added in Google Ads API v23.3. Minor versions like v23.3 don't contain breaking changes.

Features and updates نوع توضیحات
عمومی
Asset.synthetic_content_info
Ad.synthetic_content_info		 New fields Contain attestations for synthetic/AI-generated content, split into advertiser_attestation (declarations provided directly by the advertiser) and system_attestation (attestations automatically detected or provided by Google's systems).

To help you plan your upcoming integration work for v25, the interface for mutating advertiser attestation fields is being introduced early for v22 and higher. The interface is visible in these versions, but synthetic_content_info.advertiser_attestation.status and synthetic_content_info.advertiser_attestation.source will remain immutable for these versions.

If you attempt a mutate request on either of these fields, one of these errors will be returned:

"The field attempted to be mutated is immutable" or "Field cannot be set".

These fields will become fully mutable starting in v25. We recommend using the interface now to build and test your internal logic so your system is ready for full write capabilities when v25 is launched.

Multi-party approvals ویژگی‌های جدید Added support for multi-party approvals (MPA) reviews:

v23.2 (2026-03-25)

The following new features and updates were added in Google Ads API v23.2. Minor versions like v23.2 don't contain breaking changes.

Features and updates نوع توضیحات
دارایی‌ها
VideoEnhancement New resource Contains enhancement-specific video ad information, such as whether it's Google-generated or advertiser-provided. See the About video enhancements to learn more.
AppTopCombinationView New resource Read-only resource to provide insights into top-performing asset combinations in App campaigns.
CustomerAsset ویژگی جدید Added support to retrieve CustomerAsset with field_type set to BUSINESS_LOGO .
کمپین‌ها
AdGroupAd.start_date_time
AdGroupAd.end_date_time		 New fields Provide more granular scheduling constraints over the campaign's dates. This is only supported for some ad group types.
HotelSettingInfo.disable_hotel_setting New field Allows disabling the hotel feed in Demand Gen campaigns.
عمومی
CustomerClientLinkError New enum values / errors Added two new error codes: MAX_CUSTOMER_LIMIT_REACHED and ACCOUNT_CREATION_POLICY_VIOLATION .
UserListCustomerTypeCategoryEnum.LOYALTY_SIGN_UPS Behavioral change An error is now thrown when attempting to use this sunsetted user list customer type category.
Planning
GenerateTrendingInsights
GenerateCreatorInsights		 ویژگی‌های جدید Added support for custom AND/OR combinations of entities, topics, and audiences.
ReachPlanService.GenerateReachForecast New enum values Added new targetable age ranges, such as AGE_RANGE_21_44 or AGE_RANGE_21_49 .
youtube_select_lineup_targeting New field Added to ReachPlanService.ListPlannableProducts , which will replace youtube_select_lineups . Both fields are currently populated.
ReachPlanSurface New enum value Added IN_STREAM_NON_SKIPPABLE_THIRTY_SECONDS as a surface option.
Forecast New field Added clicks for Demand Gen Max Clicks (CPC) in ReachPlanService.GenerateReachForecast .
partnership_opportunities New field Added to ContentCreatorInsightsService.GenerateCreatorInsights and ContentCreatorInsightsService.GenerateTrendingInsights .
گزارش‌ها
biddable_indirect_install_first_in_app_conversion_micros New field Added to Campaign , Customer , and AdGroup resources.
ویدیوها
ShareablePreviewService ویژگی جدید Extended to support YouTube Live previews by setting preview_type to YOUTUBE_LIVE_PREVIEW . Added UNSUPPORTED_AD_TYPE and TOO_MANY_RESOURCES_IN_REQUEST to ShareablePreviewError . This is only supported for some ad types.

v23.1 (2026-02-25)

The following new features and updates were added in Google Ads API v23.1. Minor versions like v23.1 don't contain breaking changes.

Features and updates نوع توضیحات
مدیریت حساب
advertising_partner_properties.allowed_domain New field Added to ProductLinkInvitation and ProductLink resources. The advertising partner will only be able to advertise on this domain.
Customer.contains_eu_political_advertising New field Retrieves the account-level declaration status of whether it contains political advertising targeted towards the EU, and returns an EuPoliticalAdvertisingStatus .
کمپین‌ها
Campaign.text_guidelines New field Added support for text guidelines, which can be used with Performance Max and Search campaigns to programmatically control AI-generated text assets. Within text_guidelines , you can define term_exclusions and messaging_restrictions .
CampaignPrimaryStatusReason New enum values Added CAMPAIGN_NOT_BOOKED , BOOKING_HOLD_EXPIRING , BOOKING_HOLD_EXPIRED , and BOOKING_CANCELLED to provide primary status reasons for campaigns with the FIXED_CPM bidding strategy.
Campaign.VideoCampaignSettings.reservation_ad_category_self_disclosure
Campaign.VideoCampaignSettings.booking_details		 New fields Added support for reservation ad category self disclosure and read-only booking details.
Campaign.missing_eu_political_advertising_declaration New field Supports querying and filtering campaigns that are missing declarations about whether they contain political advertising targeted towards the EU.
Conversions
ConversionActionCategory.YOUTUBE_FOLLOW_ON_VIEWS New enum value Supports tracking users who watch an ad and later watch a video from the same channel.
عمومی
CriterionErrorEnum.CANNOT_TARGET_ONLY_UNDETERMINED New enum value / error Returned when attempting to target only the undetermined category in demographics dimensions.
مشوق‌ها
IncentiveErrorEnum New enum values / errors Added two new error codes: MAX_INCENTIVES_REDEEMED and ACCOUNT_TOO_OLD . These errors can be returned for requests made on or after March 11, 2026.
Planning
GenerateBenchmarksMetrics ویژگی جدید Added support for date breakdowns using a BreakdownDefinition .
ReachPlanService.GenerateReachForecast New enum value Added GOOGLE_DISPLAY_NETWORK as a targetable surface for Demand Gen Max Conversions.
GenerateTrendingInsights New fields Added historical trend line information in TrendInsightDataPoint to TrendInsights when searching by topic.
گزارش‌ها
Unique user frequency metrics New fields Added new metrics that report how many users saw your ad at least two, three, four, five or ten times: unique_users_two_plus , unique_users_three_plus , unique_users_four_plus , unique_users_five_plus , and unique_users_ten_plus .
SearchTermMatchSource New enum value Added VERTICAL_ADS_DATA_FEED to support vertical ad data feeds, such as Travel Ads entity targeting.
YouTubeVideoUpload
YouTubeVideoUpload New service / resource Added the YouTubeVideoUpload service to support uploading and managing videos on YouTube, and the YouTubeVideoUpload resource to support fetching upload status and metadata. This feature is only supported for REST and the Python client library.

v23 (2026-01-28)

The following new features, updates, and breaking changes were added in Google Ads API v23, which is a major release.

See Upgrade to the latest version for guidance.

Breaking changes

Initial state New state Change type Implementation guidance
تبلیغات
Ad sharing permitted AdGroupAdError.AD_SHARING_NOT_ALLOWED Behavioral shift Ad sharing among multiple ad groups is no longer permitted. Requests attempting to share ads will return an AD_SHARING_NOT_ALLOWED error.
Support for CallAd and CallAdInfo هیچکدام Removal Support for call ads has been removed. Refer to the About call ads help center article.
کمپین‌ها
Campaign.start_date
Campaign.end_date		 Campaign.start_date_time
Campaign.end_date_time		 Rename / replacement Use the new date-time fields to specify time components for campaigns. The original date-only fields are removed.
Demand Gen
DemandGenMultiAssetAdInfo.lead_form_only هیچکدام Removal The lead_form_only field has been removed. Update references in your code.
گزارش‌ها
Aggregate asset performance label metrics and enum هیچکدام Removal Removed aggregate asset performance label metrics. The performance label enum is no longer returned for Search and Display.

Features and updates (non-breaking)

Features and updates نوع توضیحات
تبلیغات
AdFormatType New enum values Added new format types: TEXT , VERTICAL_ADS_BOOKING_LINK , and VERTICAL_ADS_PROMOTION .
دارایی‌ها
asset_group view New fields Added the following metrics: metrics.engagements , metrics.engagement_rate , and metrics.average_cpe .
asset_group_asset view New fields Added the following metrics: metrics.average_cpe , metrics.average_cpm , metrics.trueview_average_cpv , metrics.video_trueview_view_rate , metrics.video_trueview_views , and metrics.interaction_event_types .
Asset.orientation New field Read-only orientation field added to image and video assets.
CampaignAsset ویژگی جدید Added support to retrieve campaign assets with field_type set to HEADLINE and DESCRIPTION .
ServedAssetFieldType New enum values Added HEADLINE_AS_SITELINK_POSITION_ONE , HEADLINE_AS_SITELINK_POSITION_TWO , DESCRIPTION_LINE_HEADLINE_AS_SITELINK_POSITION_ONE , and DESCRIPTION_LINE_HEADLINE_AS_SITELINK_POSITION_TWO for assets served as sitelinks.
BusinessMessageAsset New features / support Updated Business Message assets:
صورتحساب
InvoiceService.ListInvoices New options Can now return more granular details in Invoice , including campaign-level cost breakdown, itemized regulatory costs, and adjustment information, by setting include_granular_level_invoice_details in ListInvoicesRequest .
RegulatoryFeeType
UnitOfMeasure		 New enums Added helper enums for regulatory fees and units of measure.
کمپین‌ها
CampaignError New enum values / errors Added DURATION_TOO_LONG_FOR_TOTAL_BUDGET and END_DATE_TIME_REQUIRED_FOR_TOTAL_BUDGET error codes.
Conversions
ConversionActionCategory New enum value Added YOUTUBE_FOLLOW_ON_VIEWS to support tracking users who watch an ad and later watch a video from the same channel.
Demand Gen
DemandGenVideoResponsiveAdInfo.companion_banner New field Added support for companion banners in Demand Gen responsive video ads.
مشوق‌ها
Added Choose Your Own (CYO) incentives support:

To facilitate more granular programmatic handling of failures, we will add additional error codes to IncentivesService in future releases. We recommend that you monitor upcoming announcements and release notes for these new error codes to make sure your applications can manage these new failure modes.

Planning
AudienceInsightsDimension.LIFE_EVENT_USER_INTEREST New enum value Allows building audiences using Life Events in GenerateAudienceCompositionInsights , GenerateSuggestedTargetingInsights , GenerateInsightsFinderReport , and GenerateCreatorInsights .

Life Events are not supported for other AudienceInsightsService methods such as AudienceInsightsService.GenerateAudienceOverlap and AudienceInsightsService.GenerateTargetingSuggestionMetrics .

ReachPlanService.GenerateConversionRates New fields / options The response now includes surfaces to support conversion rate suggestions based on surface controls (eg, Gmail, Shorts). Only supported for Demand Gen campaigns.
LanguageDistribution New field / type Added to YouTubeChannelInsights to provide language distribution details in YouTube channel content.
BenchmarksService سرویس جدید Compares YouTube advertisement data against industry benchmarks.
AudienceInsightsService.GenerateAudienceDefinition New method Translates a free text description of a target audience into matching audience attributes using generative AI.
YouTubeChannelInsights.relevance_score New field Evaluates how relevant a creator is for a topic weighted by views.
TrendInsightMetrics.trend_change_percent New field Represents the percentage change in a trend's value over the comparison period.
توصیه‌ها
GenerateRecommendationsRequest New field Added is_new_customer . When set to true for CAMPAIGN_BUDGET recommendations, it uses a model optimized for new customers (only recommended for customers with no campaigns).
گزارش‌ها
AdGroupAdAssetView New feature / metrics support Now supports impression, performance, and conversion metrics for RESPONSIVE_DISPLAY_AD .
ad_sub_network_type segment New segment Provides granular performance breakdown within an ad network. Initially available for Demand Gen campaigns on YouTube (In-stream, In-feed, Shorts). Must be selected along with ad_network_type .
Performance Max reporting ویژگی جدید Enabled ad network type breakdown for Performance Max campaigns.
UserLocationView
GeographicView		 New segments support Support metrics segmented by conversion date: 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 , and cross_device_conversions_value_by_conversion_date .
بخش‌های تبلیغات عمودی New segments Added the following segments: 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 , and vertical_ads_vertical .
PerStoreView
MatchedLocationInterestView		 New reporting resources Added PerStoreView to query store location details, and MatchedLocationInterestView (for AI Max campaigns) to provide performance metrics by geographic locations of interest.
خرید
ShoppingPerformanceView New metrics support Now supports the following metrics segmented by conversion date: conversions_by_conversion_date , all_conversions_by_conversion_date , conversions_value_by_conversion_date , and value_per_conversions_by_conversion_date , value_per_all_conversions_by_conversion_date .
ShoppingPerformanceView New metrics support Added support for: search_budget_lost_impression_share , search_rank_lost_impression_share , search_budget_lost_absolute_top_impression_share , and search_rank_lost_absolute_top_impression_share .
ShoppingProduct.product_image_uri New field Added to ShoppingProduct .
Vertical ads
AdGroup.vertical_ads_format_setting New field Allows control over which ad formats can serve in Search campaigns using travel feeds.
AdGroupCriterion
SharedCriterion		 New fields / criteria Added vertical_ads_item_group_rule_list criterion type to AdGroupCriterion and vertical_ads_item_group_rule to SharedCriterion to permit targeting item groups in Search campaigns with travel feeds.
Vertical ads data feed integration ویژگی جدید Can now connect a vertical ads data feed to a search campaign running AI Max to show property promotion and booking link travel ads alongside text ads. Control formats with vertical_ads_format_setting and define rules using vertical_ads_item_group_rule . Segment reporting by AdFormatType and vertical ads data feed dimensions.
ویدیوها
AdVideoAssetInfo.ad_video_asset_feature_control New field Added feature control options for video ad assets.
CampaignCriterionError New enum value / error Added the INVALID_VIDEO_LINEUP_ID error code.
YouTube audibility metrics New metrics Added audibility metrics for audio ads on YouTube, reporting whether an ad was audible and on how many impressions audibility could be measured.

v22 major and minor versions

Google Ads API v22 includes the following new features, updates, and breaking changes.

v22.2 (2026-06-24)

The following new features and updates were added in Google Ads API v22.2. Minor versions like v22.2 don't contain breaking changes.

Features and updates نوع توضیحات
عمومی
Asset.synthetic_content_info
Ad.synthetic_content_info		 New fields Contain attestations for synthetic/AI-generated content, split into advertiser_attestation (declarations provided directly by the advertiser) and system_attestation (attestations automatically detected or provided by Google's systems).

To help you plan your upcoming integration work for v25, the interface for mutating advertiser attestation fields is being introduced early for v22 and higher. The interface is visible in these versions, but synthetic_content_info.advertiser_attestation.status and synthetic_content_info.advertiser_attestation.source will remain immutable for these versions.

If you attempt a mutate request on either of these fields, one of these errors will be returned:

"The field attempted to be mutated is immutable" or "Field cannot be set".

These fields will become fully mutable starting in v25. We recommend using the interface now to build and test your internal logic so your system is ready for full write capabilities when v25 is launched.

Multi-party approvals ویژگی‌های جدید Added support for multi-party approvals (MPA) reviews:

v22.1 (2026-02-25)

The following new feature was added in Google Ads API v22.1. Minor versions like v22.1 don't contain breaking changes.

Features and updates نوع توضیحات
مدیریت حساب
Customer.contains_eu_political_advertising New field Retrieves the account-level declaration status of whether it contains political advertising targeted towards the EU, and returns an EuPoliticalAdvertisingStatus .
کمپین‌ها
Campaign.missing_eu_political_advertising_declaration New field Supports querying and filtering campaigns that are missing declarations about whether they contain political advertising targeted towards the EU.

v22 (2025-10-15)

The following new features, updates, and breaking changes were added in Google Ads API v22, which is a major release.

See Upgrade to the latest version for guidance.

Breaking changes

Initial state New state Change type Implementation guidance
Demand Gen
BudgetPerDayMinimumErrorDetails.minimum_bugdet_amount_micros minimum_budget_amount_micros Rename / spelling fix Rename references to use the corrected field name.
عمومی
No operations limit in AddBatchJobOperations 10,000 operations limit per request Behavioral shift Ensure that no single AddBatchJobOperations request contains more than 10,000 operations.
Silently capped page size at 1,000 in ListBatchJobResultsRequest Returns INVALID_PAGE_SIZE error Behavioral shift Ensure ListBatchJobResultsRequest.page_size is set to 1,000 or less, as requesting a larger page size will now result in an error.
Performance Max
Asset performance labels هیچکدام Removal Asset performance labels support and the associated performance label enum have been removed for Performance Max campaigns. Update integrations accordingly.
Campaign.url_expansion_opt_out FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION flag in AssetAutomationSetting Removal / replacement Use the final URL expansion text asset automation setting. The Campaign-level URL expansion opt-out field is removed.
Planning
views trueview_views Removal / replacement Replace references to views with the new trueview_views field in ReachPlanService .
ویدیوها
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		 Renames Update query strings and integrations to use the new metric names representing TrueView video views.

Features and updates (non-breaking)

Features and updates نوع توضیحات
دارایی‌ها
AssetFieldType.LANDING_PAGE_PREVIEW New enum value Added as a new image asset field type.
AssetGenerationService New service (Beta) Allows generating text and image assets using generative AI:
  • GenerateText : Generates text based on final URL, prompts, keywords, etc.
  • GenerateImages : Generates images based on final URL, prompts, or recontextualizing product images.
  • Errors are returned with codes from AssetGenerationError .
Initially available only to a limited set of closed beta participants.
کمپین‌ها
AppCampaignBiddingStrategyGoalType New enum values Added new goals for App campaigns for installs (ACi) to optimize without specifying a target:
  • OPTIMIZE_IN_APP_CONVERSIONS_WITHOUT_TARGET_CPA : Use with standard Maximize Conversions.
  • OPTIMIZE_TOTAL_VALUE_WITHOUT_TARGET_ROAS : Use with standard Maximize Conversion Value.
BiddingStrategyType ویژگی جدید Added support for the fixed share of voice bidding strategy type.
Campaign.feed_types New field Shows the types of feeds attached to a campaign. For Performance Max campaigns, this can indicate the business vertical, such as MERCHANT_CENTER_FEED for retail.
Shared set targeting ویژگی جدید Allowed attaching negative keywords shared sets to multi-channel (for App campaigns) and local campaigns.
Demand Gen
TargetCPC bidding ویژگی جدید Added bidding strategy to maximize clicks at target CPC: set campaign-level target CPC using Campaign.target_cpc and override at ad group level using AdGroup.target_cpc_micros .
AssetAutomationType.GENERATE_DESIGN_VERSIONS_FOR_IMAGES New enum value If enabled for DemandGenMultiAssetAdInfo , this adds design elements and embeds text assets into image assets to create new image assets with different aspect ratios (enabled by default).
AssetAutomationType.GENERATE_VIDEOS_FROM_OTHER_ASSETS New enum value If enabled for DemandGenMultiAssetAdInfo , it generates videos using other assets like images and text, which can then be used to create new DemandGenVideoResponsiveAdInfo instances (enabled by default).
عمومی
ListBatchJobResultsRequest page size fallback Behavioral change If page_size is not set or is 0, it now defaults to the maximum of 1,000 (previously returned INVALID_PAGE_SIZE ).
QuotaError New enum value / error Added PAYMENTS_PROFILE_ACTIVATION_RATE_LIMIT_EXCEEDED to indicate when payment profile activation rate limit is exceeded.
Performance Max
Asset automation settings New enum values Added new PMax asset automation options:
  • GENERATE_IMAGE_ENHANCEMENT : Enables automatic creation of enhanced images (auto-cropping). Enabled by default.
  • GENERATE_IMAGE_EXTRACTION : Sourced images from final URLs. Defaults to account Dynamic Image Extension setting.
PMax reporting segments New segments Added new segments unique to Performance Max campaigns:
Planning
CRM partner data lists New feature / enum value Added THIRD_PARTY_PARTNER_DATA to CRM data sources, along with partner audience validation error codes (such as tos acceptance, Link missing, etc.).
Livestream creator metrics New field Added YouTubeMetrics.is_active_live_stream_creator , returned by creator insights to indicate if a creator published a livestream in the past 90 days.
Plannable CRM source metadata پیام جدید Added PlannableUserListMetadata inside PlannableUserList , returned by ReachPlanService.ListPlannableUserLists , to show CRM data source types.
Support for related videos and creators in TrendInsight New fields Added support for related_videos and related_creators on TrendInsight , and watch properties in video_properties and publish_date .
InsightsFinder improvements ویژگی جدید GenerateInsightsFinderReport now supports parental_status , income_ranges , and more complex AND/OR targeting combinations.
گزارش‌ها
New click types New enum values Added CLICK_TO_MESSAGE_THIRD_PARTY_CLICK and CLICK_TO_MESSAGE_LANDING_PAGE_CLICK .
AssetGroupAsset segmentation New segments support AssetGroupAsset is now segmentable by device , conversion_action , conversion_action_name , and conversion_action_category .
RSAs in AdGroupAdAssetView New feature / metrics support AdGroupAdAssetView now fully supports performance and conversion metrics for RESPONSIVE_SEARCH_AD (previously only impressions were returned).
Exploration query cluster metric segmentations New segments support Metrics clicks_unique_query_clusters , conversions_unique_query_clusters , and impressions_unique_query_clusters are now segmentable by date fields.
TargetingExpansionView New reporting resource Added TargetingExpansionView to report metrics for expansions over manual targeting, such as keywordless expansion for AI Max for Search Campaigns.
خرید
Shopping scope fix Bug fix Fixed the campaign and ad group scoping of metrics in the ShoppingProduct resource.
Unified goals
Retention goals ویژگی جدید Added support for customer retention goals to optimize for re-engaging existing customers (eg, using target_option with TARGET_SPECIFIC or TARGET_ALL ).
ویدیوها
Video watch time metrics New fields Added watch time duration metrics: video_watch_time_duration_millis (total duration) and average_video_watch_time_duration_millis (average duration per impression).

Archived release notes

See Sunsetted versions for archived release notes.