در تاریخ ۲۴ سپتامبر، ساعت ۱۰:۰۰ صبح به وقت شرق آمریکا، به صورت زنده در Discord روی سرور Google Advertising and Measurement Community و در YouTube به ما بپیوندید! ما در مورد ویژگی‌های جدید اضافه شده در نسخه ۲۵.۲ از API تبلیغات گوگل صحبت خواهیم کرد.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

کنترل‌ها و فیلتر کردن موجودی برای تبلیغات عمودی

تبلیغات عمودی ویژگی‌های تخصصی را برای کمپین‌های جستجوی مبتنی بر AI Max for Search ارائه می‌دهند که به یک فید عمودی مانند هتل‌ها مرتبط هستند. شما می‌توانید کنترل کنید که کدام قالب‌های تبلیغات عمودی در سطح گروه تبلیغاتی ارائه شوند و می‌توانید با استفاده از قوانین گروه آیتم‌های تبلیغات عمودی، کنترل کنید که کدام موجودیت‌های فید هدف قرار گیرند.

نمای کلی

این راهنما دو ویژگی اصلی برای مدیریت تبلیغات عمودی را پوشش می‌دهد:

کنترل‌های قالب: در سطح گروه تبلیغاتی، قالب‌های تبلیغاتی خاص (تبلیغات متنی، لینک‌های رزرو و تبلیغات تبلیغاتی عمودی) را انتخاب یا از آنها انصراف دهید.
مدیریت آیتم‌های تبلیغات عمودی: با استفاده از یک سیستم مبتنی بر قانون که شامل SharedSet و SharedCriterion می‌شود، موجودی خاصی را از فید عمودی (که قبلاً سفر نامیده می‌شد) مرتبط خود فیلتر و هدف قرار دهید.

پیش‌نیازها

قبل از پیاده‌سازی این ویژگی‌ها، مطمئن شوید که کمپین شما الزامات زیر را برآورده می‌کند:

نوع کمپین: باید یک کمپین جستجو باشد.
فید عمودی: یک فید داده عمودی فعال باید در سطح مشتری یا کمپین لینک شود. فیدهای داده عمودی Reference Link در سطح کمپین، فیدی را در سطح کمپین لینک می‌کنند. لینک کردن یک فید داده عمودی ، فیدهای مسافرتی در تبلیغات جستجو (TFSA) را فعال می‌کند و کنترل‌های تبلیغات عمودی را برای کمپین فعال می‌کند.
حداکثر هوش مصنوعی برای کمپین‌های جستجو: تنظیمات حداکثر هوش مصنوعی برای کمپین‌های جستجو باید در کمپین فعال شود.

فیدهای داده عمودی را در سطح کمپین پیوند دهید

برای فعال کردن فیدهای مسافرتی در تبلیغات جستجو (TFSA) و فعال کردن کنترل‌های تبلیغات عمودی در کمپین خود، می‌توانید مجموعه دارایی فید داده‌های عمودی خود را در سطح کمپین با استفاده از مراحل زیر پیوند دهید. از طرف دیگر، برای فعال کردن این ویژگی‌ها برای همه کمپین‌های حساب خود، می‌توانید با دنبال کردن دستورالعمل‌های پیوند سطح مشتری در راهنمای فیدهای مسافرتی در تبلیغات جستجو، فید را در سطح مشتری پیوند دهید.

یک شیء CampaignAssetSet ایجاد کنید، asset_set را روی نام منبع مجموعه دارایی‌های فید عمودی خود و campaign را روی نام منبع کمپین خود تنظیم کنید.
یک CampaignAssetSetOperation با create set برای CampaignAssetSet ایجاد کنید.
عملیات را با استفاده از CampaignAssetSetService.MutateCampaignAssetSets ارسال کنید.

برای جزئیات بیشتر در مورد مدیریت فیدهای مسافرتی در مقیاس بزرگ، به مستندات فیدهای مسافرتی در تبلیغات جستجو مراجعه کنید.

کنترل‌های قالب گروه‌های تبلیغاتی

شما می‌توانید پیکربندی کنید که کدام قالب‌های تبلیغات عمودی برای یک گروه تبلیغاتی خاص فعال باشند. این کار از طریق فیلد vertical_ads_format_setting ( VerticalAdsFormatSetting ) در منبع AdGroup مدیریت می‌شود.

فرمت‌های موجود

تبلیغات متنی ( disable_text_ads ): به طور پیش‌فرض فعال است. می‌توان آن را غیرفعال کرد.
لینک‌های رزرو ( enable_booking_links ): ثبت نام الزامی است.
تبلیغات عمودی ( enable_vertical_promotion_ads ): لازم است ثبت نام کنید.

قوانین اعتبارسنجی

شما نمی‌توانید همزمان از هر سه قالب برای یک گروه تبلیغاتی واحد صرف نظر کنید.
این تنظیمات فقط برای انواع گروه‌های تبلیغاتی SEARCH_STANDARD و SEARCH_DYNAMIC_ADS اعمال می‌شود.

مثال: به‌روزرسانی تنظیمات قالب

مثال جاوای زیر نحوه غیرفعال کردن تبلیغات متنی و فعال کردن تبلیغات عمودی برای یک گروه تبلیغاتی موجود را نشان می‌دهد:

// Assuming 'adGroup' is an existing AdGroup object.
// Example resource name: "customers/{customer_id}/adGroups/{ad_group_id}"
AdGroup adGroupToUpdate = AdGroup.newBuilder()
    .setResourceName(adGroup.getResourceName())
    .setVerticalAdsFormatSetting(
        VerticalAdsFormatSetting.newBuilder()
            .setDisableTextAds(true)
            .setEnableBookingLinks(false)
            .setEnableVerticalPromotionAds(true)
    )
    .build();

AdGroupOperation operation = AdGroupOperation.newBuilder()
    .setUpdate(adGroupToUpdate)
    .setUpdateMask(FieldMasks.allSetFieldsOf(adGroupToUpdate))
    .build();

// Submit the operation using AdGroupService...

مدیریت آیتم‌های تبلیغات عمودی

برای هدف قرار دادن زیرمجموعه خاصی از موجودی فید خود، مانند «هتل‌های بوستون» یا «هتل‌های ۱ ستاره را حذف کنید»، باید از قوانین گروه آیتم‌های تبلیغات عمودی استفاده کنید.

نحوه عملکرد مدل داده

مدل داده از رویکرد معیارهای مشترک استفاده می‌کند:

SharedSet : یک SharedSet با نوع VERTICAL_ADS_ITEM_GROUP_RULE_LIST ایجاد کنید.
SharedCriterion : قوانین (معیارها) را به این مجموعه اضافه کنید. هر قانون یک بُعد، مانند شهر یا کلاس هتل، و یک مقدار را مشخص می‌کند. همچنین می‌توانید معیارهای منفی برای حذف موارد ایجاد کنید.
AdGroupCriterion : با استفاده از AdGroupCriterion ( vertical_ads_item_group_rule_list )، SharedSet به AdGroup خود لینک دهید.

ابعاد پشتیبانی شده

شما می‌توانید موجودیت‌ها را بر اساس ابعاد زیر در SharedCriterion ( VerticalAdsItemGroupRuleInfo ) فیلتر کنید:

item_code : شناسه‌ی خاص فهرست.
city_criterion_id ، region_criterion_id ، country_criterion_id : نام منابع ثابت Geo Target ( geoTargetConstants/{id} ).
hotel_class : رتبه‌بندی ستاره (۱-۵).
user_rating ، venue ، event_participant_display_name (شروع از v24 ): فیلترهای رتبه‌بندی رویداد و فهرست عمودی، محل برگزاری و نام شرکت‌کننده.

مثال کد: ایجاد و پیوند قوانین

این مثال پایتون قانونی ایجاد می‌کند که اقلام موجود در «بوستون» یا «سانفرانسیسکو» را شامل شود و هتل‌های «یک ستاره» و «دو ستاره» را شامل نشود:

# 1. Create the SharedSet
shared_set_operation = client.get_type("SharedSetOperation")
shared_set = shared_set_operation.create
shared_set.name = "Boston/SF Premium Hotels"
shared_set.type_ = (
    client.enums.SharedSetTypeEnum.VERTICAL_ADS_ITEM_GROUP_RULE_LIST
)
shared_set.vertical_ads_item_vertical_type = (
    client.enums.VerticalAdsItemVerticalTypeEnum.HOTELS
)
shared_set_service = client.get_service("SharedSetService")
shared_set_response = shared_set_service.mutate_shared_sets(
    customer_id=customer_id, operations=[shared_set_operation]
)
shared_set_resource_name = shared_set_response.results[0].resource_name

# 2. Add Criteria (Rules) to the SharedSet
shared_criteria_operations = []

# Rule A: Include Boston and SF
geo_target_constant_service = client.get_service("GeoTargetConstantService")
included_city_ids = [1006543, 1014221]  # Geo Target Constant IDs
for city_id in included_city_ids:
  op = client.get_type("SharedCriterionOperation")
  criterion = op.create
  criterion.shared_set = shared_set_resource_name
  criterion.vertical_ads_item_group_rule.city_criterion_id = (
      geo_target_constant_service.geo_target_constant_path(city_id)
  )
  shared_criteria_operations.append(op)

# Rule B: Exclude 1 and 2 Star Hotels
excluded_stars = [1, 2]
for star_rating in excluded_stars:
  op = client.get_type("SharedCriterionOperation")
  criterion = op.create
  criterion.shared_set = shared_set_resource_name
  criterion.vertical_ads_item_group_rule.hotel_class = star_rating
  criterion.negative = True  # Mark as exclusion
  shared_criteria_operations.append(op)

# Submit SharedCriterionOperations...

# 3. Link to AdGroup
ad_group_service = client.get_service("AdGroupService")
ad_group_resource_name = ad_group_service.ad_group_path(
    customer_id, ad_group_id
)
agc_operation = client.get_type("AdGroupCriterionOperation")
agc = agc_operation.create
agc.ad_group = ad_group_resource_name
agc.status = client.enums.AdGroupCriterionStatusEnum.ENABLED
agc.vertical_ads_item_group_rule_list.shared_set = shared_set_resource_name

# Submit AdGroupCriterionOperation...

گزارش‌های عملکرد

شما می‌توانید معیارهای عملکرد را برای تبلیغات عمودی با استفاده از متدهای GoogleAdsService.SearchStream یا GoogleAdsService.Search بازیابی کنید.

بخش‌های تبلیغات عمودی

segments.vertical_ads_hotel_class : مقدار صحیح (۱ تا ۵ ستاره) که رتبه‌بندی کلاس را برای فهرست هتل مشخص می‌کند.
segments.vertical_ads_listing : شناسه‌ای برای یک فهرست آگهی عمودی خاص.
segments.vertical_ads_listing_brand : برند مرتبط با یک فهرست تبلیغات عمودی.
segments.vertical_ads_listing_city : شهری که با آگهی مرتبط است.
segments.vertical_ads_listing_country : کشوری که با فهرست مرتبط است.
segments.vertical_ads_listing_region : ناحیه مرتبط با فهرست.
segments.vertical_ads_partner_account : حساب همکار در یک مرکز همکار (به عنوان مثال، مرکز هتل) که داده‌های فید موجودی را تأمین می‌کند.
segments.vertical_ads_vertical : نوع عمودی، مانند هتل یا ماشین کرایه‌ای.
segments.vertical_ads_event_participant_display_names (شروع از v24 ): نام‌های نمایشی شرکت‌کنندگان در یک فهرست رویداد، مانند اجراکنندگان، سخنرانان یا تیم‌ها.
segments.vertical_ads_listing_user_rating (شروع از v24 ): مقدار صحیح (۱ تا ۵) که امتیاز کاربر به فهرست تبلیغات عمودی را مشخص می‌کند.
segments.vertical_ads_listing_venue (شروع از v24 ): نام محل نمایش تبلیغات عمودی (مثلاً محل برگزاری کنسرت).
segments.vertical_ads_price_tier (شروع از v25 ): معیار رقابت‌پذیری نسبی قیمت برای فهرست هتل‌ها.
segments.vertical_ads_rate_rule_id (شروع از v25 ): شناسه رشته‌ای مربوط به قوانین نرخ خصوصی یا مشروط اعمال شده بر پیشنهاد یا نمایش.
segments.vertical_ads_rate_type (شروع از v25 ): دسته‌بندی نوع نرخ عمومی، خصوصی یا مشروط.

بخش‌های ابعاد مسیر

از v25 به بعد، برای تبلیغات عمودی مرتبط با فیدهای سفر و اقامت، می‌توانید گزارش‌های عملکرد را با استفاده از ابعاد برنامه سفر بخش‌بندی کنید:

segments.advance_booking_window : بازه زمانی رزرو قبلی برای برنامه سفر بر حسب روز.
segments.length_of_booking : مدت زمان رزرو برای برنامه سفر به روز.
segments.start_date : تاریخ شروع رزرو که به صورت yyyy-MM-dd قالب‌بندی شده است.
segments.start_day_of_week : روز شروع هفته رزرو.
segments.user_set_dates : نشان می‌دهد که آیا تاریخ‌های مشخص‌شده توسط کاربر انتخاب شده‌اند یا خیر ( USER_SELECTED یا DEFAULT_SELECTION ).

معیارهای تبلیغات عمودی

از v25 به بعد، می‌توانید معیارهای تبلیغات عمودی زیر را بازیابی کنید:

metrics.vertical_ads_potential_impressions : تعداد نمایش‌های بالقوه که نشان‌دهنده‌ی کل نمایش‌های واجد شرایطِ دارای محدودیت نمایشِ موجود در سراسر متن جستجو است.
metrics.vertical_ads_average_booking_value_micros : میانگین نرخ روزانه کلیک-وزنی بر حسب میکرو، شامل مالیات و هزینه‌ها، در کل مدت اقامت.
metrics.vertical_ads_price_difference_percentage : درصد دلتا که قیمت پیشنهادی تبلیغ‌کننده را در مقابل پایین‌ترین قیمت رقابتی برای همان ملک مقایسه می‌کند.

نمونه پرس و جو GAQL

SELECT
  campaign.id,
  ad_group.id,
  segments.vertical_ads_listing_city,
  segments.advance_booking_window,
  segments.length_of_booking,
  segments.start_date,
  metrics.impressions,
  metrics.vertical_ads_potential_impressions,
  metrics.clicks,
  metrics.all_conversions_value,
  metrics.vertical_ads_average_booking_value_micros,
  metrics.vertical_ads_price_difference_percentage
FROM
  ad_group
WHERE
  segments.date DURING LAST_30_DAYS

مدیریت خطا

اینها خطاهای رایجی هستند که ممکن است هنگام پیکربندی تبلیغات عمودی با آنها مواجه شوید:

کد خطا	علت	اقدام توصیه شده
`AdGroupError.INVALID_VERTICAL_ADS_FORMAT_SETTING`	هر سه قالب تبلیغ (متن، لینک رزرو، تبلیغات ویژه) به طور همزمان غیرفعال شدند.	مطمئن شوید که حداقل یک فرمت در `VerticalAdsFormatSetting` فعال باشد.
`AdGroupError.VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED_FOR_CAMPAIGNS_WITHOUT_AI_MAX`	این کمپین، کمپین‌های AI Max for Search را فعال نکرده است.	فعال کردن AI Max برای کمپین‌های جستجو در تنظیمات کمپین.
`AdGroupError.VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED_FOR_CAMPAIGNS_WITHOUT_ENABLED_TRAVEL_FEED`	این کمپین فاقد فید داده عمودی فعال است.	اطمینان حاصل کنید که یک فید عمودی معتبر در سطح مشتری یا کمپین مرتبط است.
`CriterionError.VERTICAL_ADS_ITEM_GROUP_RULE_LIST_DOES_NOT_EXIST`	نام منبع `SharedSet` ارائه شده در `AdGroupCriterion` وجود ندارد.	تأیید کنید که نام منبع `shared_set` با یک مجموعه ایجاد شده مطابقت دارد.
`CriterionError.VERTICAL_ADS_ITEM_GROUP_RULE_NOT_SUPPORTED_FOR_THE_VERTICAL_TYPE`	بُعد معیار مورد استفاده برای یک سطح عمودی خاص، مانند کلاس هتل برای اجاره خودرو، پشتیبانی نمی‌شود.	بررسی کنید که بُعد `vertical_ads_item_group_rule` با نوع عمودی شما مطابقت داشته باشد.

نمای کلی

این راهنما دو ویژگی اصلی برای مدیریت تبلیغات عمودی را پوشش می‌دهد:

کنترل‌های قالب: در سطح گروه تبلیغاتی، قالب‌های تبلیغاتی خاص (تبلیغات متنی، لینک‌های رزرو و تبلیغات تبلیغاتی عمودی) را انتخاب یا از آنها انصراف دهید.
مدیریت آیتم‌های تبلیغات عمودی: با استفاده از یک سیستم مبتنی بر قانون که شامل SharedSet و SharedCriterion می‌شود، موجودی خاصی را از فید عمودی (که قبلاً سفر نامیده می‌شد) مرتبط خود فیلتر و هدف قرار دهید.

پیش‌نیازها

قبل از پیاده‌سازی این ویژگی‌ها، مطمئن شوید که کمپین شما الزامات زیر را برآورده می‌کند:

نوع کمپین: باید یک کمپین جستجو باشد.
فید عمودی: یک فید داده عمودی فعال باید در سطح مشتری یا کمپین لینک شود. فیدهای داده عمودی Reference Link در سطح کمپین، فیدی را در سطح کمپین لینک می‌کنند. لینک کردن یک فید داده عمودی ، فیدهای مسافرتی در تبلیغات جستجو (TFSA) را فعال می‌کند و کنترل‌های تبلیغات عمودی را برای کمپین فعال می‌کند.
حداکثر هوش مصنوعی برای کمپین‌های جستجو: تنظیمات حداکثر هوش مصنوعی برای کمپین‌های جستجو باید در کمپین فعال شود.

فیدهای داده عمودی را در سطح کمپین پیوند دهید

یک شیء CampaignAssetSet ایجاد کنید، asset_set را روی نام منبع مجموعه دارایی‌های فید عمودی خود و campaign را روی نام منبع کمپین خود تنظیم کنید.
یک CampaignAssetSetOperation با create set برای CampaignAssetSet ایجاد کنید.
عملیات را با استفاده از CampaignAssetSetService.MutateCampaignAssetSets ارسال کنید.

کنترل‌های قالب گروه‌های تبلیغاتی

فرمت‌های موجود

تبلیغات متنی ( disable_text_ads ): به طور پیش‌فرض فعال است. می‌توان آن را غیرفعال کرد.
لینک‌های رزرو ( enable_booking_links ): ثبت نام الزامی است.
تبلیغات عمودی ( enable_vertical_promotion_ads ): لازم است ثبت نام کنید.

قوانین اعتبارسنجی

شما نمی‌توانید همزمان از هر سه قالب برای یک گروه تبلیغاتی واحد صرف نظر کنید.
این تنظیمات فقط برای انواع گروه‌های تبلیغاتی SEARCH_STANDARD و SEARCH_DYNAMIC_ADS اعمال می‌شود.

مثال: به‌روزرسانی تنظیمات قالب

// Assuming 'adGroup' is an existing AdGroup object.
// Example resource name: "customers/{customer_id}/adGroups/{ad_group_id}"
AdGroup adGroupToUpdate = AdGroup.newBuilder()
    .setResourceName(adGroup.getResourceName())
    .setVerticalAdsFormatSetting(
        VerticalAdsFormatSetting.newBuilder()
            .setDisableTextAds(true)
            .setEnableBookingLinks(false)
            .setEnableVerticalPromotionAds(true)
    )
    .build();

AdGroupOperation operation = AdGroupOperation.newBuilder()
    .setUpdate(adGroupToUpdate)
    .setUpdateMask(FieldMasks.allSetFieldsOf(adGroupToUpdate))
    .build();

// Submit the operation using AdGroupService...

مدیریت آیتم‌های تبلیغات عمودی

نحوه عملکرد مدل داده

مدل داده از رویکرد معیارهای مشترک استفاده می‌کند:

SharedSet : یک SharedSet با نوع VERTICAL_ADS_ITEM_GROUP_RULE_LIST ایجاد کنید.
SharedCriterion : قوانین (معیارها) را به این مجموعه اضافه کنید. هر قانون یک بُعد، مانند شهر یا کلاس هتل، و یک مقدار را مشخص می‌کند. همچنین می‌توانید معیارهای منفی برای حذف موارد ایجاد کنید.
AdGroupCriterion : با استفاده از AdGroupCriterion ( vertical_ads_item_group_rule_list )، SharedSet به AdGroup خود لینک دهید.

ابعاد پشتیبانی شده

شما می‌توانید موجودیت‌ها را بر اساس ابعاد زیر در SharedCriterion ( VerticalAdsItemGroupRuleInfo ) فیلتر کنید:

item_code : شناسه‌ی خاص فهرست.
city_criterion_id ، region_criterion_id ، country_criterion_id : نام منابع ثابت Geo Target ( geoTargetConstants/{id} ).
hotel_class : رتبه‌بندی ستاره (۱-۵).
user_rating ، venue ، event_participant_display_name (شروع از v24 ): فیلترهای رتبه‌بندی رویداد و فهرست عمودی، محل برگزاری و نام شرکت‌کننده.

مثال کد: ایجاد و پیوند قوانین

# 1. Create the SharedSet
shared_set_operation = client.get_type("SharedSetOperation")
shared_set = shared_set_operation.create
shared_set.name = "Boston/SF Premium Hotels"
shared_set.type_ = (
    client.enums.SharedSetTypeEnum.VERTICAL_ADS_ITEM_GROUP_RULE_LIST
)
shared_set.vertical_ads_item_vertical_type = (
    client.enums.VerticalAdsItemVerticalTypeEnum.HOTELS
)
shared_set_service = client.get_service("SharedSetService")
shared_set_response = shared_set_service.mutate_shared_sets(
    customer_id=customer_id, operations=[shared_set_operation]
)
shared_set_resource_name = shared_set_response.results[0].resource_name

# 2. Add Criteria (Rules) to the SharedSet
shared_criteria_operations = []

# Rule A: Include Boston and SF
geo_target_constant_service = client.get_service("GeoTargetConstantService")
included_city_ids = [1006543, 1014221]  # Geo Target Constant IDs
for city_id in included_city_ids:
  op = client.get_type("SharedCriterionOperation")
  criterion = op.create
  criterion.shared_set = shared_set_resource_name
  criterion.vertical_ads_item_group_rule.city_criterion_id = (
      geo_target_constant_service.geo_target_constant_path(city_id)
  )
  shared_criteria_operations.append(op)

# Rule B: Exclude 1 and 2 Star Hotels
excluded_stars = [1, 2]
for star_rating in excluded_stars:
  op = client.get_type("SharedCriterionOperation")
  criterion = op.create
  criterion.shared_set = shared_set_resource_name
  criterion.vertical_ads_item_group_rule.hotel_class = star_rating
  criterion.negative = True  # Mark as exclusion
  shared_criteria_operations.append(op)

# Submit SharedCriterionOperations...

# 3. Link to AdGroup
ad_group_service = client.get_service("AdGroupService")
ad_group_resource_name = ad_group_service.ad_group_path(
    customer_id, ad_group_id
)
agc_operation = client.get_type("AdGroupCriterionOperation")
agc = agc_operation.create
agc.ad_group = ad_group_resource_name
agc.status = client.enums.AdGroupCriterionStatusEnum.ENABLED
agc.vertical_ads_item_group_rule_list.shared_set = shared_set_resource_name

# Submit AdGroupCriterionOperation...

گزارش‌های عملکرد

بخش‌های تبلیغات عمودی

segments.vertical_ads_hotel_class : مقدار صحیح (۱ تا ۵ ستاره) که رتبه‌بندی کلاس را برای فهرست هتل مشخص می‌کند.
segments.vertical_ads_listing : شناسه‌ای برای یک فهرست آگهی عمودی خاص.
segments.vertical_ads_listing_brand : برند مرتبط با یک فهرست تبلیغات عمودی.
segments.vertical_ads_listing_city : شهری که با آگهی مرتبط است.
segments.vertical_ads_listing_country : کشوری که با فهرست مرتبط است.
segments.vertical_ads_listing_region : ناحیه مرتبط با فهرست.
segments.vertical_ads_partner_account : حساب همکار در یک مرکز همکار (به عنوان مثال، مرکز هتل) که داده‌های فید موجودی را تأمین می‌کند.
segments.vertical_ads_vertical : نوع عمودی، مانند هتل یا ماشین کرایه‌ای.
segments.vertical_ads_event_participant_display_names (شروع از v24 ): نام‌های نمایشی شرکت‌کنندگان در یک فهرست رویداد، مانند اجراکنندگان، سخنرانان یا تیم‌ها.
segments.vertical_ads_listing_user_rating (شروع از v24 ): مقدار صحیح (۱ تا ۵) که امتیاز کاربر به فهرست تبلیغات عمودی را مشخص می‌کند.
segments.vertical_ads_listing_venue (شروع از v24 ): نام محل نمایش تبلیغات عمودی (مثلاً محل برگزاری کنسرت).
segments.vertical_ads_price_tier (شروع از v25 ): معیار رقابت‌پذیری نسبی قیمت برای فهرست هتل‌ها.
segments.vertical_ads_rate_rule_id (شروع از v25 ): شناسه رشته‌ای مربوط به قوانین نرخ خصوصی یا مشروط اعمال شده بر پیشنهاد یا نمایش.
segments.vertical_ads_rate_type (شروع از v25 ): دسته‌بندی نوع نرخ عمومی، خصوصی یا مشروط.

بخش‌های ابعاد مسیر

segments.advance_booking_window : بازه زمانی رزرو قبلی برای برنامه سفر بر حسب روز.
segments.length_of_booking : مدت زمان رزرو برای برنامه سفر به روز.
segments.start_date : تاریخ شروع رزرو که به صورت yyyy-MM-dd قالب‌بندی شده است.
segments.start_day_of_week : روز شروع هفته رزرو.
segments.user_set_dates : نشان می‌دهد که آیا تاریخ‌های مشخص‌شده توسط کاربر انتخاب شده‌اند یا خیر ( USER_SELECTED یا DEFAULT_SELECTION ).

معیارهای تبلیغات عمودی

از v25 به بعد، می‌توانید معیارهای تبلیغات عمودی زیر را بازیابی کنید:

metrics.vertical_ads_potential_impressions : تعداد نمایش‌های بالقوه که نشان‌دهنده‌ی کل نمایش‌های واجد شرایطِ دارای محدودیت نمایشِ موجود در سراسر متن جستجو است.
metrics.vertical_ads_average_booking_value_micros : میانگین نرخ روزانه کلیک-وزنی بر حسب میکرو، شامل مالیات و هزینه‌ها، در کل مدت اقامت.
metrics.vertical_ads_price_difference_percentage : درصد دلتا که قیمت پیشنهادی تبلیغ‌کننده را در مقابل پایین‌ترین قیمت رقابتی برای همان ملک مقایسه می‌کند.

نمونه پرس و جو GAQL

SELECT
  campaign.id,
  ad_group.id,
  segments.vertical_ads_listing_city,
  segments.advance_booking_window,
  segments.length_of_booking,
  segments.start_date,
  metrics.impressions,
  metrics.vertical_ads_potential_impressions,
  metrics.clicks,
  metrics.all_conversions_value,
  metrics.vertical_ads_average_booking_value_micros,
  metrics.vertical_ads_price_difference_percentage
FROM
  ad_group
WHERE
  segments.date DURING LAST_30_DAYS

مدیریت خطا

اینها خطاهای رایجی هستند که ممکن است هنگام پیکربندی تبلیغات عمودی با آنها مواجه شوید:

کد خطا	علت	اقدام توصیه شده
`AdGroupError.INVALID_VERTICAL_ADS_FORMAT_SETTING`	هر سه قالب تبلیغ (متن، لینک رزرو، تبلیغات ویژه) به طور همزمان غیرفعال شدند.	مطمئن شوید که حداقل یک فرمت در `VerticalAdsFormatSetting` فعال باشد.
`AdGroupError.VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED_FOR_CAMPAIGNS_WITHOUT_AI_MAX`	این کمپین، کمپین‌های AI Max for Search را فعال نکرده است.	فعال کردن AI Max برای کمپین‌های جستجو در تنظیمات کمپین.
`AdGroupError.VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED_FOR_CAMPAIGNS_WITHOUT_ENABLED_TRAVEL_FEED`	این کمپین فاقد فید داده عمودی فعال است.	اطمینان حاصل کنید که یک فید عمودی معتبر در سطح مشتری یا کمپین مرتبط است.
`CriterionError.VERTICAL_ADS_ITEM_GROUP_RULE_LIST_DOES_NOT_EXIST`	نام منبع `SharedSet` ارائه شده در `AdGroupCriterion` وجود ندارد.	تأیید کنید که نام منبع `shared_set` با یک مجموعه ایجاد شده مطابقت دارد.
`CriterionError.VERTICAL_ADS_ITEM_GROUP_RULE_NOT_SUPPORTED_FOR_THE_VERTICAL_TYPE`	بُعد معیار مورد استفاده برای یک سطح عمودی خاص، مانند کلاس هتل برای اجاره خودرو، پشتیبانی نمی‌شود.	بررسی کنید که بُعد `vertical_ads_item_group_rule` با نوع عمودی شما مطابقت داشته باشد.

نمای کلی

این راهنما دو ویژگی اصلی برای مدیریت تبلیغات عمودی را پوشش می‌دهد:

کنترل‌های قالب: در سطح گروه تبلیغاتی، قالب‌های تبلیغاتی خاص (تبلیغات متنی، لینک‌های رزرو و تبلیغات تبلیغاتی عمودی) را انتخاب یا از آنها انصراف دهید.
مدیریت آیتم‌های تبلیغات عمودی: با استفاده از یک سیستم مبتنی بر قانون که شامل SharedSet و SharedCriterion می‌شود، موجودی خاصی را از فید عمودی (که قبلاً سفر نامیده می‌شد) مرتبط خود فیلتر و هدف قرار دهید.

پیش‌نیازها

قبل از پیاده‌سازی این ویژگی‌ها، مطمئن شوید که کمپین شما الزامات زیر را برآورده می‌کند:

نوع کمپین: باید یک کمپین جستجو باشد.
فید عمودی: یک فید داده عمودی فعال باید در سطح مشتری یا کمپین لینک شود. فیدهای داده عمودی Reference Link در سطح کمپین، فیدی را در سطح کمپین لینک می‌کنند. لینک کردن یک فید داده عمودی ، فیدهای مسافرتی در تبلیغات جستجو (TFSA) را فعال می‌کند و کنترل‌های تبلیغات عمودی را برای کمپین فعال می‌کند.
حداکثر هوش مصنوعی برای کمپین‌های جستجو: تنظیمات حداکثر هوش مصنوعی برای کمپین‌های جستجو باید در کمپین فعال شود.

فیدهای داده عمودی را در سطح کمپین پیوند دهید

یک شیء CampaignAssetSet ایجاد کنید، asset_set را روی نام منبع مجموعه دارایی‌های فید عمودی خود و campaign را روی نام منبع کمپین خود تنظیم کنید.
یک CampaignAssetSetOperation با create set برای CampaignAssetSet ایجاد کنید.
عملیات را با استفاده از CampaignAssetSetService.MutateCampaignAssetSets ارسال کنید.

کنترل‌های قالب گروه‌های تبلیغاتی

فرمت‌های موجود

تبلیغات متنی ( disable_text_ads ): به طور پیش‌فرض فعال است. می‌توان آن را غیرفعال کرد.
لینک‌های رزرو ( enable_booking_links ): ثبت نام الزامی است.
تبلیغات عمودی ( enable_vertical_promotion_ads ): لازم است ثبت نام کنید.

قوانین اعتبارسنجی

شما نمی‌توانید همزمان از هر سه قالب برای یک گروه تبلیغاتی واحد صرف نظر کنید.
این تنظیمات فقط برای انواع گروه‌های تبلیغاتی SEARCH_STANDARD و SEARCH_DYNAMIC_ADS اعمال می‌شود.

مثال: به‌روزرسانی تنظیمات قالب

// Assuming 'adGroup' is an existing AdGroup object.
// Example resource name: "customers/{customer_id}/adGroups/{ad_group_id}"
AdGroup adGroupToUpdate = AdGroup.newBuilder()
    .setResourceName(adGroup.getResourceName())
    .setVerticalAdsFormatSetting(
        VerticalAdsFormatSetting.newBuilder()
            .setDisableTextAds(true)
            .setEnableBookingLinks(false)
            .setEnableVerticalPromotionAds(true)
    )
    .build();

AdGroupOperation operation = AdGroupOperation.newBuilder()
    .setUpdate(adGroupToUpdate)
    .setUpdateMask(FieldMasks.allSetFieldsOf(adGroupToUpdate))
    .build();

// Submit the operation using AdGroupService...

مدیریت آیتم‌های تبلیغات عمودی

نحوه عملکرد مدل داده

مدل داده از رویکرد معیارهای مشترک استفاده می‌کند:

SharedSet : یک SharedSet با نوع VERTICAL_ADS_ITEM_GROUP_RULE_LIST ایجاد کنید.
SharedCriterion : قوانین (معیارها) را به این مجموعه اضافه کنید. هر قانون یک بُعد، مانند شهر یا کلاس هتل، و یک مقدار را مشخص می‌کند. همچنین می‌توانید معیارهای منفی برای حذف موارد ایجاد کنید.
AdGroupCriterion : با استفاده از AdGroupCriterion ( vertical_ads_item_group_rule_list )، SharedSet به AdGroup خود لینک دهید.

ابعاد پشتیبانی شده

شما می‌توانید موجودیت‌ها را بر اساس ابعاد زیر در SharedCriterion ( VerticalAdsItemGroupRuleInfo ) فیلتر کنید:

item_code : شناسه‌ی خاص فهرست.
city_criterion_id ، region_criterion_id ، country_criterion_id : نام منابع ثابت Geo Target ( geoTargetConstants/{id} ).
hotel_class : رتبه‌بندی ستاره (۱-۵).
user_rating ، venue ، event_participant_display_name (شروع از v24 ): فیلترهای رتبه‌بندی رویداد و فهرست عمودی، محل برگزاری و نام شرکت‌کننده.

مثال کد: ایجاد و پیوند قوانین

# 1. Create the SharedSet
shared_set_operation = client.get_type("SharedSetOperation")
shared_set = shared_set_operation.create
shared_set.name = "Boston/SF Premium Hotels"
shared_set.type_ = (
    client.enums.SharedSetTypeEnum.VERTICAL_ADS_ITEM_GROUP_RULE_LIST
)
shared_set.vertical_ads_item_vertical_type = (
    client.enums.VerticalAdsItemVerticalTypeEnum.HOTELS
)
shared_set_service = client.get_service("SharedSetService")
shared_set_response = shared_set_service.mutate_shared_sets(
    customer_id=customer_id, operations=[shared_set_operation]
)
shared_set_resource_name = shared_set_response.results[0].resource_name

# 2. Add Criteria (Rules) to the SharedSet
shared_criteria_operations = []

# Rule A: Include Boston and SF
geo_target_constant_service = client.get_service("GeoTargetConstantService")
included_city_ids = [1006543, 1014221]  # Geo Target Constant IDs
for city_id in included_city_ids:
  op = client.get_type("SharedCriterionOperation")
  criterion = op.create
  criterion.shared_set = shared_set_resource_name
  criterion.vertical_ads_item_group_rule.city_criterion_id = (
      geo_target_constant_service.geo_target_constant_path(city_id)
  )
  shared_criteria_operations.append(op)

# Rule B: Exclude 1 and 2 Star Hotels
excluded_stars = [1, 2]
for star_rating in excluded_stars:
  op = client.get_type("SharedCriterionOperation")
  criterion = op.create
  criterion.shared_set = shared_set_resource_name
  criterion.vertical_ads_item_group_rule.hotel_class = star_rating
  criterion.negative = True  # Mark as exclusion
  shared_criteria_operations.append(op)

# Submit SharedCriterionOperations...

# 3. Link to AdGroup
ad_group_service = client.get_service("AdGroupService")
ad_group_resource_name = ad_group_service.ad_group_path(
    customer_id, ad_group_id
)
agc_operation = client.get_type("AdGroupCriterionOperation")
agc = agc_operation.create
agc.ad_group = ad_group_resource_name
agc.status = client.enums.AdGroupCriterionStatusEnum.ENABLED
agc.vertical_ads_item_group_rule_list.shared_set = shared_set_resource_name

# Submit AdGroupCriterionOperation...

گزارش‌های عملکرد

بخش‌های تبلیغات عمودی

segments.vertical_ads_hotel_class : مقدار صحیح (۱ تا ۵ ستاره) که رتبه‌بندی کلاس را برای فهرست هتل مشخص می‌کند.
segments.vertical_ads_listing : شناسه‌ای برای یک فهرست آگهی عمودی خاص.
segments.vertical_ads_listing_brand : برند مرتبط با یک فهرست تبلیغات عمودی.
segments.vertical_ads_listing_city : شهری که با آگهی مرتبط است.
segments.vertical_ads_listing_country : کشوری که با فهرست مرتبط است.
segments.vertical_ads_listing_region : ناحیه مرتبط با فهرست.
segments.vertical_ads_partner_account : حساب همکار در یک مرکز همکار (به عنوان مثال، مرکز هتل) که داده‌های فید موجودی را تأمین می‌کند.
segments.vertical_ads_vertical : نوع عمودی، مانند هتل یا ماشین کرایه‌ای.
segments.vertical_ads_event_participant_display_names (شروع از v24 ): نام‌های نمایشی شرکت‌کنندگان در یک فهرست رویداد، مانند اجراکنندگان، سخنرانان یا تیم‌ها.
segments.vertical_ads_listing_user_rating (شروع از v24 ): مقدار صحیح (۱ تا ۵) که امتیاز کاربر به فهرست تبلیغات عمودی را مشخص می‌کند.
segments.vertical_ads_listing_venue (شروع از v24 ): نام محل نمایش تبلیغات عمودی (مثلاً محل برگزاری کنسرت).
segments.vertical_ads_price_tier (شروع از v25 ): معیار رقابت‌پذیری نسبی قیمت برای فهرست هتل‌ها.
segments.vertical_ads_rate_rule_id (شروع از v25 ): شناسه رشته‌ای مربوط به قوانین نرخ خصوصی یا مشروط اعمال شده بر پیشنهاد یا نمایش.
segments.vertical_ads_rate_type (شروع از v25 ): دسته‌بندی نوع نرخ عمومی، خصوصی یا مشروط.

بخش‌های ابعاد مسیر

segments.advance_booking_window : بازه زمانی رزرو قبلی برای برنامه سفر بر حسب روز.
segments.length_of_booking : مدت زمان رزرو برای برنامه سفر به روز.
segments.start_date : تاریخ شروع رزرو که به صورت yyyy-MM-dd قالب‌بندی شده است.
segments.start_day_of_week : روز شروع هفته رزرو.
segments.user_set_dates : نشان می‌دهد که آیا تاریخ‌های مشخص‌شده توسط کاربر انتخاب شده‌اند یا خیر ( USER_SELECTED یا DEFAULT_SELECTION ).

معیارهای تبلیغات عمودی

از v25 به بعد، می‌توانید معیارهای تبلیغات عمودی زیر را بازیابی کنید:

metrics.vertical_ads_potential_impressions : تعداد نمایش‌های بالقوه که نشان‌دهنده‌ی کل نمایش‌های واجد شرایطِ دارای محدودیت نمایشِ موجود در سراسر متن جستجو است.
metrics.vertical_ads_average_booking_value_micros : میانگین نرخ روزانه کلیک-وزنی بر حسب میکرو، شامل مالیات و هزینه‌ها، در کل مدت اقامت.
metrics.vertical_ads_price_difference_percentage : درصد دلتا که قیمت پیشنهادی تبلیغ‌کننده را در مقابل پایین‌ترین قیمت رقابتی برای همان ملک مقایسه می‌کند.

نمونه پرس و جو GAQL

SELECT
  campaign.id,
  ad_group.id,
  segments.vertical_ads_listing_city,
  segments.advance_booking_window,
  segments.length_of_booking,
  segments.start_date,
  metrics.impressions,
  metrics.vertical_ads_potential_impressions,
  metrics.clicks,
  metrics.all_conversions_value,
  metrics.vertical_ads_average_booking_value_micros,
  metrics.vertical_ads_price_difference_percentage
FROM
  ad_group
WHERE
  segments.date DURING LAST_30_DAYS

مدیریت خطا

اینها خطاهای رایجی هستند که ممکن است هنگام پیکربندی تبلیغات عمودی با آنها مواجه شوید:

کد خطا	علت	اقدام توصیه شده
`AdGroupError.INVALID_VERTICAL_ADS_FORMAT_SETTING`	هر سه قالب تبلیغ (متن، لینک رزرو، تبلیغات ویژه) به طور همزمان غیرفعال شدند.	مطمئن شوید که حداقل یک فرمت در `VerticalAdsFormatSetting` فعال باشد.
`AdGroupError.VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED_FOR_CAMPAIGNS_WITHOUT_AI_MAX`	این کمپین، کمپین‌های AI Max for Search را فعال نکرده است.	فعال کردن AI Max برای کمپین‌های جستجو در تنظیمات کمپین.
`AdGroupError.VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED_FOR_CAMPAIGNS_WITHOUT_ENABLED_TRAVEL_FEED`	این کمپین فاقد فید داده عمودی فعال است.	اطمینان حاصل کنید که یک فید عمودی معتبر در سطح مشتری یا کمپین مرتبط است.
`CriterionError.VERTICAL_ADS_ITEM_GROUP_RULE_LIST_DOES_NOT_EXIST`	نام منبع `SharedSet` ارائه شده در `AdGroupCriterion` وجود ندارد.	تأیید کنید که نام منبع `shared_set` با یک مجموعه ایجاد شده مطابقت دارد.
`CriterionError.VERTICAL_ADS_ITEM_GROUP_RULE_NOT_SUPPORTED_FOR_THE_VERTICAL_TYPE`	بُعد معیار مورد استفاده برای یک سطح عمودی خاص، مانند کلاس هتل برای اجاره خودرو، پشتیبانی نمی‌شود.	بررسی کنید که بُعد `vertical_ads_item_group_rule` با نوع عمودی شما مطابقت داشته باشد.

کنترل‌ها و فیلتر کردن موجودی برای تبلیغات عمودی با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

نمای کلی

پیش‌نیازها

فیدهای داده عمودی را در سطح کمپین پیوند دهید

کنترل‌های قالب گروه‌های تبلیغاتی

فرمت‌های موجود

قوانین اعتبارسنجی

مثال: به‌روزرسانی تنظیمات قالب

مدیریت آیتم‌های تبلیغات عمودی

نحوه عملکرد مدل داده

ابعاد پشتیبانی شده

مثال کد: ایجاد و پیوند قوانین

گزارش‌های عملکرد

بخش‌های تبلیغات عمودی

بخش‌های ابعاد مسیر

معیارهای تبلیغات عمودی

نمونه پرس و جو GAQL

مدیریت خطا

نمای کلی

پیش‌نیازها

فیدهای داده عمودی را در سطح کمپین پیوند دهید

کنترل‌های قالب گروه‌های تبلیغاتی

فرمت‌های موجود

قوانین اعتبارسنجی

مثال: به‌روزرسانی تنظیمات قالب

مدیریت آیتم‌های تبلیغات عمودی

نحوه عملکرد مدل داده

ابعاد پشتیبانی شده

مثال کد: ایجاد و پیوند قوانین

گزارش‌های عملکرد

بخش‌های تبلیغات عمودی

بخش‌های ابعاد مسیر

معیارهای تبلیغات عمودی

نمونه پرس و جو GAQL

مدیریت خطا

نمای کلی

پیش‌نیازها

فیدهای داده عمودی را در سطح کمپین پیوند دهید

کنترل‌های قالب گروه‌های تبلیغاتی

فرمت‌های موجود

قوانین اعتبارسنجی

مثال: به‌روزرسانی تنظیمات قالب

مدیریت آیتم‌های تبلیغات عمودی

نحوه عملکرد مدل داده

ابعاد پشتیبانی شده

مثال کد: ایجاد و پیوند قوانین

گزارش‌های عملکرد

بخش‌های تبلیغات عمودی

بخش‌های ابعاد مسیر

معیارهای تبلیغات عمودی

نمونه پرس و جو GAQL

مدیریت خطا

کنترل‌ها و فیلتر کردن موجودی برای تبلیغات عمودی