إنّ واجهة برمجة تطبيقات DAI في مرحلة تجريبية وقد لا تكون متاحة في شبكتك. اتصل بمدير حسابك للحصول على مزيد من المعلومات. ويُنصَح باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية للأنظمة الأساسية التي تتوفّر فيها.
إدارة أحداث البث المباشر التي تتضمّن إعلانات ديناميكية
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
من خلال Google DAI API، يمكنك الاستفادة من ميزة "إدراج إعلان ديناميكي" من Google في مختلف البيئات.
حيث لا يكون تنفيذ حزمة تطوير البرامج لإعلانات الوسائط التفاعلية متاحًا ننصحك بمواصلة استخدام
إعلانات الوسائط التفاعلية على الأنظمة الأساسية التي تتيح استخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية
ننصحك باستخدام DAI API على المنصّات التالية:
تلفزيون Samsung الذكي (Tizen)
تلفزيون LG
HbbTV
Xbox (تطبيقات JavaScript)
KaiOS
تتوافق واجهة برمجة التطبيقات مع الإمكانات الأساسية التي توفرها حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية. بالنسبة
أسئلة محددة حول التوافق أو الميزات المتاحة، يُرجى التواصل مع
مدير حسابك في Google.
تنفيذ DAI API لأحداث البث المباشر
تتيح واجهة برمجة التطبيقات DAI عمليات البث المباشر غير القابلة للتقديم أو الإيقاف باستخدام بروتوكولَي HLS وDASH.
تنطبق الخطوات الموضّحة في هذا الدليل على كلا البروتوكولَين.
لدمج واجهة برمجة التطبيقات في تطبيقك لأحداث البث المباشر، يجب إكمال الخطوات التالية:
الخطوات:
1. طلب بث
لطلب بث مباشر من واجهة DAI API، يجب طلب البث المباشر من خلال POST.
النهائية. تحتوي استجابة JSON على بيان ساحة المشاركات بالإضافة إلى
نقاط نهاية وقيم DAI API
في حال حدوث أخطاء، يتم عرض رموز خطأ HTTP العادية بدون استجابة JSON.
جسم.
حلِّل استجابة JSON واحتفِظ بالقيم التالية:
stream_id
يمكن استخدام هذه القيمة لتحديد مصدر البيانات الذي تم عرضه.
stream_manifest
يتم إرسال عنوان URL هذا إلى مشغّل الوسائط لتشغيل البث.
media_verification_url
يمثّل عنوان URL هذا نقطة النهاية الأساسية لتتبُّع أحداث التشغيل.
metadata_url
يتم استخدام عنوان URL هذا لإنشاء استطلاع للحصول على معلومات دورية حول البث القادم.
فعالية.
session_update_url
يُستخدَم عنوان URL هذا لتعديل مَعلمات طلب البث التي تم إرسالها خلال العملية.
طلب البث. تجدر الإشارة إلى أن معلمات هذا الطلب تحل محل جميع المعلمات
التي تم ضبطها للبث السابق
polling_frequency
معدل التكرار، بالثواني، عند طلب البيانات الوصفية المُعدَّلة من AdBreak من
DAI API.
2. استطلاع للحصول على البيانات الوصفية الجديدة لـ AdBreak
اضبط موقّتًا لاستطلاع آراء البيانات الوصفية الجديدة لـ AdBreak بمعدّل تكرار الاستطلاعات، وذلك باستخدام
للبيانات الوصفية. إذا لم يتم تحديده في استجابة ساحة المشاركات، يُنصَح باستخدام الإعداد التلقائي.
الفاصل الزمني هو 10 ثوانٍ.
للتحقّق من وقوع أحداث معيّنة في الفيديو المضمّن، يُرجى اتّباع الخطوات التالية:
خطوات التعامل مع أحداث ID3:
يمكنك تخزين أحداث الوسائط في قائمة انتظار، وحفظ كل معرف وسائط مع
الطابع الزمني (في حال عرضه مشغّل الفيديو)
عند التحديث في كل مرة من المشغّل أو بمعدّل تكرار محدّد (يُنصح به)
500 ملي ثانية)، فتحقق من قائمة انتظار أحداث الوسائط للأحداث التي تم تشغيلها مؤخرًا عن طريق
مقارنة الطوابع الزمنية للأحداث برأس التشغيل.
بالنسبة إلى أحداث الوسائط التي تأكّدت من تشغيلها، تحقّق من نوعها من خلال البحث عن
رقم تعريف الوسائط في علامات الفواصل الإعلانية المخزّنة. ضع في اعتبارك أن العلامات المخزنة
تحتوي على بادئة من معرف الوسائط فقط ولذلك لا يمكن إجراء مطابقة تامة.
استخدام كلمة "التقدم" الأحداث لتتبُّع ما إذا كان المستخدم ضمن فاصل إعلاني.
لا ترسل هذه الأحداث إلى نقطة نهاية التحقق من الوسائط. للأحداث الأخرى
وإلحاق معرف الوسائط بنقطة نهاية التحقق من الوسائط وإجراء طلب GET
طلب تتبع التشغيل.
Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict
Successful response would be to look for - HTTP/1.1 200
القيود
في حال استخدام واجهة برمجة التطبيقات في مكتبات WebView، تنطبق القيود التالية في ما يتعلق
إلى الاستهداف:
UserAgent: يتم ضبط معلَمة وكيل المستخدم كقيمة خاصة بالمتصفّح.
بدلاً من المنصة الأساسية
rdid،
idtype,
is_lat:
لا يتم تمرير رقم تعريف الجهاز بشكل صحيح، ما يحد من إمكانات
الميزات التالية:
تحديد عدد مرات الظهور
العرض المتسلسل للإعلانات بالتناوب
تقسيم الجمهور واستهدافه
أفضل الممارسات
تجدر الإشارة إلى أنّ نقطة نهاية البيانات الوصفية لفهرس البث المباشر تستند إلى
لعلامة ID3 المقابلة. ويتم هذا عمدًا لمنع استخدام
نقطة نهاية البيانات الوصفية لاختبار فحص جميع عُقد التحقق على الفور.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Google DAI API enables dynamic ad insertion in environments where the IMA SDK isn't feasible, offering an alternative for platforms like Samsung Smart TV, LG TV, and others.\u003c/p\u003e\n"],["\u003cp\u003eFor live streams, the API involves requesting a stream, polling for ad metadata, tracking playback events using ID3 cues and media verification URLs, and optionally updating stream session parameters.\u003c/p\u003e\n"],["\u003cp\u003eWhile supporting core IMA DAI functionalities, there are limitations regarding user agent and device ID targeting within webviews, potentially affecting frequency capping and audience segmentation.\u003c/p\u003e\n"],["\u003cp\u003eAd metadata retrieval is optimized using ID3 tag prefixes for indexing, and detailed API documentation, samples, and resources are available for further implementation guidance.\u003c/p\u003e\n"]]],[],null,["# Manage DAI livestreams\n\nThe Google DAI API lets you implement Google DAI-enabled streams in environments\nwhere implementing the IMA SDK is not supported. We recommend that you still use\nIMA on platforms where the IMA SDK is supported.\n\nWe recommend using the DAI API on the following platforms:\n\n- Samsung Smart TV (Tizen)\n- LG TV\n- HbbTV\n- Xbox (JavaScript apps)\n- KaiOS\n\nThe API supports the basic capabilities provided by the IMA DAI SDK. For\nspecific questions about compatibility or supported features, reach out to\nyour Google account manager.\n\nImplement the DAI API for LIVE streams\n--------------------------------------\n\nThe DAI API supports linear (LIVE) streams using both HLS and DASH protocols.\nThe steps described in this guide apply to both protocols.\n\nTo integrate the API into your app for LIVE streams, complete the following\nsteps:\n\n### 1. Request a stream\n\nTo request a livestream from the DAI API, make a POST call to the stream\nendpoint. The JSON response contains the stream manifest as well as associated\nDAI API endpoints and values.\n\n#### Example request body\n\n https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream\n\n {\n key1 : \"value1\",\n stream_parameter1 : \"value2\"\n }\n\n| **Note:** `api_key` can be supplied using the `Authorization` HTTP header.\n\n#### Example response body\n\n {\n \"stream_id\":\"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL\",\n \"stream_manifest\":\"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd\",\n \"media_verification_url\":\"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/\",\n \"metadata_url\":\"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata\",\n \"session_update_url\":\"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session\",\n \"polling_frequency\":10\n }\n\n#### Error response\n\nIn case of errors, standard HTTP error codes are returned with no JSON response\nbody.\n\nParse the JSON response and store the following values:\n\nstream_id\n: This value can be used to identify the returned stream.\n\nstream_manifest\n: This URL is passed to your media player for stream playback.\n\nmedia_verification_url\n: This URL is the base endpoint for tracking playback events.\n\nmetadata_url\n: This URL is used to poll for periodic information about upcoming stream\n events.\n\nsession_update_url\n: This URL is used to update stream request parameters sent during the initial\n stream request. Note that the parameters of this request replace all parameters\n set for the earlier stream.\n\npolling_frequency\n: The frequency, in seconds, when requesting updated AdBreak Metadata from the\n DAI API.\n\n### 2. Poll for new AdBreak Metadata\n\nSet a timer to poll for new AdBreak Metadata at the polling frequency, using the\nmetadata URL. If not specified in the stream response, the default recommended\ninterval is 10 seconds.\n\n#### Example request body\n\n https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata\n\n#### Example response body\n\n {\n \"tags\":{\n \"google_0492266569\":{\n \"ad\":\"0000229836_ad1\",\n \"ad_break_id\":\"0000229836\",\n \"type\":\"firstquartile\"\n },\n \"google_1560331148\":{\n \"ad\":\"0000229836_ad1\",\n \"ad_break_id\":\"0000229836\",\n \"type\":\"thirdquartile\"\n },\n \"google_1877686714378797835\":{\n \"ad\":\"0000229836_slate\",\n \"ad_break_id\":\"0000229836\",\n \"type\":\"progress\"\n },\n \"google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU\":{\n \"ad\":\"0000229835_ad1\",\n \"ad_break_id\":\"0000229835\",\n \"type\":\"progress\"\n },\n \"google_2032765498\":{\n \"ad\":\"0000229835_ad1\",\n \"ad_break_id\":\"0000229835\",\n \"type\":\"midpoint\"\n },......\n \"google_5646900623\":{\n \"ad\":\"0000229837_ad1\",\n \"ad_break_id\":\"0000229837\",\n \"type\":\"complete\"\n }\n },\n \"ads\":{\n \"0000229834_ad1\":{\n \"ad_break_id\":\"0000229834\",\n \"position\":1,\n \"duration\":15.01,\n \"title\":\"truman-e2e-creativeset4\",\n \"description\":\"truman-e2e-creativeset4 ad\",\n \"ad_system\":\"GDFP\",\n \"ad_id\":\"39066884\",\n \"creative_id\":\"58092079124\",\n \"clickthrough_url\":\"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\\u0026adurl=http://google.com\",\n \"universal_ad_id\":{\n \"id_value\":\"58092079124\",\n \"id_registry\":\"GDFP\"\n }\n },\n \"0000229834_slate\":{\n \"ad_break_id\":\"0000229834\",\n \"position\":-1,\n \"duration\":14.974977777,\n \"slate\":true\n },...\n },\n \"ad_breaks\":{\n \"0000229834\":{\n \"type\":\"mid\",\n \"duration\":15.01,\n \"expected_duration\":29.984977776999997,\n \"ads\":1\n },....\n }\n }\n\n### 3. Listen to ID3 events and track playback events\n\nTo verify that specific events have occurred in a video stream, follow these\nsteps to handle ID3 events:\n\n1. Store the media events in a queue, saving each media ID along with its timestamp (if surfaced by the player).\n2. On each time update from the player, or at a set frequency (recommended 500 ms), check the media events queue for recently played events by comparing the event timestamps to the playhead.\n3. For media events that you confirm have played, check the type by looking up the media ID in the stored ad break tags. Keep in mind that the stored tags only contain a prefix of the media ID so an exact match isn't possible.\n4. Use \"progress\" events to keep track of whether a user is inside an ad break. Don't send these events to the media verification endpoint. For other event types, append the media ID to the media verification endpoint and make a GET request to track playback.\n5. Remove the media event from the queue.\n\n#### Example request body\n\n https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/\n\n#### Example responses\n\n Accepted for asynchronous verification - HTTP/1.1 202 Accepted\n Successful empty response - HTTP/1.1 204 No Content\n Media verification not found - HTTP/1.1 404 Not Found\n Media verification sent by someone else - HTTP/1.1 409 Conflict\n\nYou can verify tracking events in [Stream Activity\nMonitor](//support.google.com/admanager/answer/7009058).\n\n### 4. Update livestream session parameters\n\nYou might want to adjust your session parameters after a stream has been\ncreated. To do so, make a request to the session update URL.\n| **Warning:** This call overwrites all the existing stream parameters, so your request body must contain all relevant key-value pairs, not just those which have changed.\n\n#### Example request body\n\n https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session\n\n {\n key1 : \"value1\",\n stream_parameter1 : \"value2\"\n }\n\n#### Example response body\n\n Successful response would be to look for - HTTP/1.1 200\n\nLimitations\n-----------\n\nIf using the API within webviews, the following limitations apply with respect\nto targeting:\n\n- UserAgent: The user agent parameter is passed as browser specific value instead of the underlying platform.\n- [`rdid`](//support.google.com/admanager/answer/7320899), [`idtype`](//support.google.com/admanager/answer/7320899), [`is_lat`](//support.google.com/admanager/answer/7320899): The device ID is not properly passed, which limits the capabilities of the following features:\n - Frequency capping\n - Sequential ad rotation\n - Audience segmentation and targeting\n\nBest practices\n--------------\n\nKeep in mind that the metadata endpoint for livestream indexes is based on the\nprefix of the corresponding ID3 tag. This is by design to prevent the use of the\nmetadata endpoint for immediately pinging all of the verification nodes.\n\nAdditional resources\n--------------------\n\n- [API reference\n documentation](/ad-manager/dynamic-ad-insertion/api/full-service/reference/live)\n- [Simple\n sample](//github.com/googleads/googleads-dynamic-ad-insertion/tree/master/simple/Live)\n- [IMA SDK documentation](/interactive-media-ads)\n- [DAI layer implementation types\n comparison](//support.google.com/admanager/answer/9840889)"]]
