انتقال از Display & Video 360 API نسخه ۴ به نسخه ۵

آخرین به‌روزرسانی: ۲۰۲۶-۱۰-۲۲

هشدار: نسخه ۵ در مرحله بتای باز است. ممکن است تغییرات اساسی در نسخه ۵ درحالی‌که در نسخه بتا است ایجاد شود و این تغییرات در یادداشت‌های انتشار Display & Video 360 API فهرست خواهد شد. این سند درصورت نیاز به‌روزرسانی خواهد شد تا نسخه بتای فعال را منعکس کند.

انتقال برنامه

برای انتقال از نسخه ۴ به نسخه ۵، باید نشانی‌های وب نقطه پایانی‌تان را برای فراخوانی نسخه ۵ به‌روز کنید، برنامه‌تان را برای درنظر گرفتن تغییرات اساسی به‌روز کنید، و هرگونه ویژگی جدیدی را که ممکن است برای ادغام شما مفید باشد مرور کنید.

فراخوانی‌های میانای برنامه‌سازی کاربردی خود را از نسخه ۴ به نسخه ۵ به‌روز کنید

برای استفاده از نسخه ۵ به‌جای نسخه ۴، باید درخواست‌هایتان را به‌روز کنید تا از نقاط پایانی جدید نسخه ۵ استفاده کنند.

برای مثال، برای فراخوانی روش advertisers.get با v4، از نشانی وب زیر استفاده کنید:

GET https://displayvideo.googleapis.com/v4/advertisers/advertiserId

برای نسخه ۵، نشانی وب را به نشانی زیر به‌روز کنید:

GET https://displayvideo.googleapis.com/v5/advertisers/advertiserId

اگر از کتابخانه کارخواه برای درخواست به API استفاده می‌کنید، از جدیدترین نسخه کتابخانه کارخواه استفاده کنید و پیکربندی‌تان را برای استفاده از نسخه ۵ به‌روز کنید.

تغییرات لازم را اعمال کنید

Display & Video 360 API v5 introduces a number of breaking changes. دستورالعمل‌های زیر را مرور کنید و تغییرات لازم را در رابطه با استفاده فعلی‌تان از Display & Video 360 API اعمال کنید.

برای مشاهده فهرست کامل تفاوت‌های Display & Video 360 API نسخه ۴ و ۵، به یادداشت‌های انتشار مراجعه کنید.

به‌روزرسانی بازیابی و هدف‌یابی منبع فهرست موجودی برای استفاده از شناسه‌ها و انواع جدید

Display & Video 360 API v5 نحوه بازیابی و هدف‌یابی بسته‌های مزایده و معامله‌های منبع موجودی را تغییر می‌دهد.

در نسخه ۴، منابع InventorySource بازیابی‌شده بااستفاده از سرویس inventorySources هم نشان‌دهنده معامله‌های منبع موجودی و هم بسته‌های مزایده است. هم معامله‌ها و هم بسته‌های مزایده بااستفاده از TARGETING_TYPE_INVENTORY_SOURCE هدف‌یابی می‌شوند.

در نسخه ۵، بسته‌های مزایده و معامله‌های منبع موجودی به‌طور جداگانه مدیریت می‌شوند:

• معاملات منبع فهرست موجودی بااستفاده از TARGETING_TYPE_INVENTORY_SOURCE_DEAL هدف‌یابی می‌شوند، بااستفاده از سرویس‌های advertisers.inventorySources و partners.inventorySources بازیابی می‌شوند، و بااستفاده از فیلد AssignedTargetingOption inventorySourceDetails هدف‌یابی می‌شوند.
• بسته‌های مزایده بااستفاده از TARGETING_TYPE_AUCTION_PACKAGE هدف‌یابی می‌شوند، بااستفاده از سرویس targetingTypes.targetingOptions بازیابی می‌شوند، و بااستفاده از فیلد AssignedTargetingOption auctionPackageDetails هدف‌یابی می‌شوند.

این به‌روزرسانی شناسه‌های مورداستفاده برای بسته‌های مزایده و معامله‌های موجود را تغییر می‌دهد، بنابراین نمی‌توانید پس‌از انتقال از شناسه‌های منبع InventorySource که قبلاً ذخیره شده‌اند استفاده کنید.

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

به‌روزرسانی منطق هدف‌یابی مخاطب برای منابع «تولید تقاضا» و YouTube

نسخه ۵ «میانای برنامه‌سازی کاربردی Display & Video 360» منطق هدف‌یابی مخاطب را برای منابع «تولید تقاضا» و YouTube به‌روز می‌کند تا از گزینه‌های اختصاص‌یافته جداگانه برای هر فهرست مخاطب هدف‌یابی‌شده استفاده کند.

در نسخه ۴، همه هدف‌یابی مخاطبان بااستفاده از TARGETING_TYPE_AUDIENCE_GROUP مدیریت می‌شود.

در نسخه ۵، هدف‌یابی مخاطب اختصاص‌داده‌شده به گروه‌های آگهی «تولید تقاضا» و YouTube بااستفاده از یکی از انواع هدف‌یابی زیر و فیلدهای منبع AssignedTargetingOption بسته به نوع مخاطب مدیریت می‌شود:

• TARGETING_TYPE_COMBINED_AUDIENCE بااستفاده از combinedAudienceDetails
• TARGETING_TYPE_CUSTOM_LIST بااستفاده از customListDetails
• TARGETING_TYPE_FIRST_PARTY_AND_PARTNER_AUDIENCE بااستفاده از firstPartyAndPartnerAudienceDetails
• TARGETING_TYPE_GOOGLE_AUDIENCE بااستفاده از googleAudienceDetails
• TARGETING_TYPE_LOOKALIKE_AUDIENCE بااستفاده از lookalikeAudienceDetails

اقلام ردیفی همچنان از یک TARGETING_TYPE_AUDIENCE_GROUP AssignedTargetingOption برای مدیریت هدف‌یابی مخاطب برای همه انواع استفاده خواهند کرد.

ارتقا دادن به Data Manager API برای مدیریت مخاطبان «مطابقت مشتری»

Display & Video 360 API v5 امکان ایجاد و مدیریت عضویت مخاطبان «مطابقت مشتری» را با برداشتن روش‌های زیر حذف می‌کند:

• firstPartyAndPartnerAudiences.create
• firstPartyAndPartnerAudiences.editCustomerMatchMembers
• firstPartyAndPartnerAudiences.patch

برای ادامه مدیریت مخاطبان «مطابقت مشتری»، گردش کارتان را ارتقا دهید تا از Data Manager API استفاده کنید.

افزودن پشتیبانی برای بازیابی سفارش‌های درج «دیجیتال خارج از خانه»

Display & Video 360 API v5 پشتیبانی از بازیابی سفارش‌های درج «دیجیتال خارج از خانه» را اضافه می‌کند.

اگر تبلیغ‌کنندگان شما از تبلیغات «دیجیتال خارج از خانه» استفاده می‌کنند، هرگونه ادغامی را که advertisers.insertionOrders.list را فراخوانی می‌کند ارتقا دهید تا برای گنجاندن منابع InsertionOrder با مقدار فیلد insertionOrderType برابر با OUT_OF_HOME آماده شوید.

در نسخه ۵، اقلام ردیفی تحت سفارش‌های درج «دیجیتال خارج از خانه» همچنان مانند نسخه ۴ قابل‌بازیابی خواهند بود.

به‌روزرسانی ارجاع‌ها به Adloox به Peer39

در نسخه ۵، فیلدها و مقادیر enum که به ادغام مناسب بودن نمانام شخص ثالث Display & Video 360 با Adloox (که Scope3 نیز نامیده می‌شود) ارجاع می‌دهند به Peer39 به‌روزرسانی شده‌اند:

• ThirdPartyVerifierAssignedTargetingOptionDetails فیلد adloox با peer39 جایگزین شده است.
• مقادیر شمارشی PartnerCostType PARTNER_COST_TYPE_ADLOOX و PARTNER_COST_TYPE_ADLOOX_PREBID با PARTNER_COST_TYPE_PEER39 و PARTNER_COST_TYPE_PEER39_PREBID جایگزین شده‌اند.

فیلدهای به‌روزرسانی برای موردهای سطری، گروه‌های آگهی، و آگهی‌های YouTube

در نسخه ۵، فیلدهای مختلفی در منابع LineItem، AdGroup، و AdGroupAd برداشته یا به‌روز شده‌اند. منطق بازیابی منابعتان را به‌روز کنید تا این تغییرات را درنظر بگیرید.

در منبع LineItem:

• فیلد YoutubeAndPartnersSettings relatedVideoIds با relatedVideos جایگزین شده است.

در منابع LineItem و AdGroup:

• فیلدهای TargetingExpansionConfig audienceExpansionSeedListExcluded و audienceExpansionLevel برداشته شده‌اند.

در منبع AdGroupAd:

• فیلد containsSyntheticMedia اضافه شده است.
• فیلد trackingUrl در اشیاء AudioAd، CommonInStreamAttribute، و VideoPerformanceAd به دو فیلد trackingUrl و userSpecifiedTrackingUrl تقسیم شده است تا بین نشانی وب استفاده‌شده برای ردیابی و نشانی وب ردیابی مشخص‌شده توسط کاربر تمایز قائل شود.

برداشتن ارجاع به مقادیر enum منسوخ‌شده

در نسخه ۵، مقادیر enum که قبلاً منسوخ شده بودند به‌طور کامل برداشته شده‌اند. درحالی‌که استفاده از این مقادیر در درخواست‌های ارسال‌شده به API در نسخه ۴ منجر به خطا می‌شود، این تغییر هرگونه ارجاع به آن‌ها را از کتابخانه‌های کارخواه نسخه ۵ حذف می‌کند. هرگونه ارجاع به این مقادیر منسوخ‌شده در کد شما ممکن است هنگام ارتقا به نسخه ۵ باعث بروز خطا شود.

انواع Enum که مقادیر تحت‌تأثیر قرارگرفته دارند شامل ContentRatingTier، GoogleAudienceType، SdfVersion، و SensitiveCategory است. برای مشاهده فهرست کامل همه مقادیر enum برداشته‌شده، یادداشت‌های انتشار ما را ببینید.

مرور ویژگی‌های جدید

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

• مدیریت کامل هدف‌یابی حذفی کانال و ویدیو YouTube در سطح آگهی‌دهنده تحت انواع هدف‌یابی TARGETING_TYPE_YOUTUBE_VIDEO و TARGETING_TYPE_YOUTUBE_CHANNEL. در نسخه ۴، این هدف‌یابی فقط خواندنی بود.
• توانایی ایجاد منابع «دیجیتال خارج از خانه» InsertionOrder.
• پشتیبانی از گروه‌های آگهی بااستفاده از طرح‌آگهی‌های واگذارشده برای تولید آگهی ازطریق افزودن فیلدهای AdGroup adSource و creativeAssignments و فیلد AdGroupAd parentCreativeId.
• توانایی ایجاد و بازیابی منابع LookalikeAudience.
• فیلد containsSyntheticMedia جدید در منبع AdGroupAd.