بدء استخدام SGAI

توفّر ميزة "إدراج الإعلانات الإجرائية من الخادم" (SGAI) بيانًا عن مجموعة الإعلانات الجاهزة للدمج على أجهزة العميل. إذا فعّلت ميزة "العرض الإعلاني في مجموعات الإعلانات المتسلسلة" في شبكة "مدير إعلانات Google"، يمكنك استخدام ميزة "الحملات الإعلانية الذكية على شبكة البحث". إذا لم تكن ميزة "عرض مجموعات الإعلانات" DAI مفعّلة، يُرجى التواصل مع مدير حسابك.

باستخدام SGAI، يمكنك استخدام نقاط نهاية واجهة برمجة التطبيقات Pod serving API لإنشاء بث استرداد البيانات الوصفية للإعلانات وملفات بيان مجموعات الإعلانات.

إذا كان لديك خادم لتعديل البيان، يمكنك إنشاء عناوين URL لبيان مجموعات الإعلانات المتسلسلة وإدراج علامات الإعلانات التي تحمل معلومات بيان مجموعة الإعلانات المتسلسلة في بث المحتوى وفقًا للمواصفات المفضّلة لديك.

بدلاً من ذلك، يمكنك جدولة فاصل إعلاني باستخدام آلية مختلفة عن علامات الإعلانات في بيان البث. وفي هذه الحالات، يمكن لتطبيقك الاستماع إلى أحداث أخرى، مثل تفاعل المستخدم مع البث أو التطبيق نفسه أو إشعار فوري. بعد هذه الأحداث، يمكن للتطبيق إنشاء عناوين URL لبيان مجموعة الإعلانات المتسلسلة وإبلاغ المشغّل ببدء تحميل بيان مجموعة الإعلانات المتسلسلة.

المتطلبات الأساسية

قبل المتابعة، تأكَّد من توفّر ما يلي:

• تفعيل عرض مجموعات الإعلانات المتسلسلة في "الحملات الإعلانية الديناميكية على شبكة البحث" على شبكة "مدير إعلانات Google"
• حدث بث مباشر من النوع بيان عرض مجموعة أحداث لإنشاء الحدث، اطّلِع على إعداد بث مباشر لميزة "الإعلان أثناء التشغيل".

اتّباع الاقتراحات

قبل إنشاء عنوان URL لبيان مجموعة الإعلانات، ننصحك بطلب واجهة برمجة التطبيقات لميزة "إشعار بوقت بدء الفواصل الإعلانية" (EABN) لتحديد المدة المتوقّعة ومعلومات الاستهداف وغيرها من المَعلمات لكل فاصل إعلاني.

بالنسبة إلى أحداث البث المباشر للإصدار العلني والإصدار التجريبي، استخدِم واجهة برمجة التطبيقات EABN API، خاصةً إذا كانت شبكة الإعلانات تضم أيّ حملات آلية. لمزيد من المعلومات، يُرجى الاطّلاع على الميزات والإرشادات المتعلّقة بالإعلانات المباشرة الآلية.

تقديم طلب تسجيل بث

عندما يبدأ مستخدم بث محتوى في تطبيق مشغّل الفيديو، يمكنك إنشاء طلب تسجيل بث مع مَعلمات الاستهداف لإنشاء جلسة بث في "مدير إعلانات Google". لمعرفة تفاصيل عن تقديم طلب تسجيل بث، يُرجى الاطّلاع على Method:stream. بعد ذلك، ستتلقّى بيانات الاستجابة من الطلب.

تقدّم الأمثلة التالية طلب تسجيل بث:

HTTP بتنسيق نص عادي محارة JavaScript

• الطلب:

authority: dai.google.com
method: POST
path: /ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream
scheme: https
content-type: application/x-www-form-urlencoded

cust_params=customID%253D1543216789%2526anotherKey%253Dvalue1%252Cvalue2

• الردّ:

{
    "manifest_format": "hls",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "polling_frequency": 10,
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL"
}

• سطر الأوامر:

curl \
-H "Host: dai.google.com" \
-H "content-type: application/x-www-form-urlencoded" \
  --data-binary "cust_params=channelID%253D1543216789%2526anotherKey%253Dvalue1%252Cvalue2" \
  --compressed "https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream"

• إخراج:

{
    "manifest_format": "hls",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "pod_manifest_url": "https://dai.google.com/linear/pods/v1/hls/event/TFyZF0IoSpqvCLtLv8JdCw/pod/$pod-id$.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db%3ATUL",
    "polling_frequency": 10,
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL"
}

• باستخدام Fetch API:

const response = await fetch("https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream", {
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
  },
  "body": "cust_params=channelID%3D1543216789%26anotherKey%3Dvalue1%2Cvalue2",
  "method": "POST",
});

  const stream = await response.json();
  console.log(stream);

• سجلّ وحدة التحكّم:

{
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "polling_frequency": 10,
    "pod_manifest_url": "https://dai.google.com/linear/pods/v1/hls/event/TFyZF0IoSpqvCLtLv8JdCw/pod/$pod-id$.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db%3ATUL",
    "manifest_format": "hls"
}

الاستطلاع عن البيانات الوصفية للفاصل الإعلاني

بعد تقديم طلب تسجيل مصدر بيانات، يمكنك إجراء استطلاع للاطّلاع على البيانات الوصفية للإعلان. للتحقّق من الإعلانات، يمكنك ضبط موقّت باستخدام polling_frequence في استجابة البث في مرحلة التسجيل للاتّصالmetadata للإعلان. في كل استطلاع، قد تتلقّى قائمة جزئية بالإعلانات التي تتضمّن بيانات وصفية عند توفّرها.

إنشاء عنوان URL لملف بيان مجموعة الإعلانات

أنشئ عنوان URL لملف موارد Pod في Pod Serving API. بعد ذلك، عليك إرسال عنوان URL إلى مشغّل فيديو لبدءتحميل مجموعة الإعلانات المتسلسلة.

يوضّح المثال التالي بنية عنوان URL لبيان مجموعة الإعلانات:

https://dai.google.com/linear/pods/v1/hls/network/51636543/custom_asset/pod_serving_hls_manifest_mp4/ad_break_id/ab101.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db:TUL&pd=120000

ملاحظة: يجب أن تكون مَعلمات الفواصل الإعلانية، مثل ad_break_id وduration وcust_params وscte35، متطابقة لجميع العملاء الذين يشاهدون البث المباشر نفسه، بينما يكون معرّف البث فريدًا لكل عميل. إذا اخترت إنشاء عنوان URL لبيان مجموعة الإعلانات على جانب الخادم وإدراج عناوين URL التي تم إنشاؤها في بيان البث، اتّبِع مستندات خادم أداة التحكّم في البيان بشأن إرسال معرّف البث من العملاء وإنشاء مَعلمات الفواصل الإعلانية الأخرى.

يمكنك احتساب مَعلمات عنوان URL لبيان مجموعة الإعلانات استنادًا إلى معلومات الفاصل الإعلاني التي يتم استرجاعها من مشغّل الفيديو أو إشعار الخادم. للاطّلاع على متطلبات هذه المَعلمات، اطّلِع على الطريقة: بيان pod.

تشغيل ملف بيان مجموعة الإعلانات

في تطبيق مشغّل الفيديو لدى العميل، ابدأ تشغيل بث المحتوى باستخدام مشغّل فيديو أساسي، واتّبِع مستندات مشغّل الفيديو بشأن اتّباع جدول التشغيل والإعلانات، إذا كان ذلك منطبقًا.

في حال إنشاء عناوين URL لبيان مجموعة الإعلانات المتسلسلة وإدراجها في البيان على جانب الخادم، عليك مراقبة أحداث الفواصل الإعلانية القادمة لمشغّل الفيديو والتأكّد من الاشتراك في أحداث id3 أثناء تشغيل كل فاصل إعلاني. في حال جدولة أحداث الفاصل الإعلاني من جهة العميل، اشترِك في أحداث id3 عند الإنشاء.

الإبلاغ عن مرّات الظهور وأحداث الإعلانات

عندما يشغّل مشغّل الفيديو مجموعة الإعلانات المتسلسلة ويصادف بيانات وصفية موقّتة بتنسيق id3، فإنه يستمع إلى أحداث الإعلانات التي يشغّلها مشغّل الفيديو ويعالجها لإرسال إشعارات التحقّق من الوسائط.

ملاحظة مهمة: لا تؤخّر إرسال طلب فحص الاتصال إلى عنوان URL الخاص بإثبات ملكية الوسائط. ننصحك بالتوقف عن التصوير على الفور وبأسرع وقت ممكن، ولكن ليس لأكثر من دقيقة واحدة.