Early ad break notification v1

استخدام Early Ad Break Notification API

  • معرّف البث المباشر المقابل الذي يتم إنشاء الفاصل الإعلاني له. يمكن أن يكون هذا المعرّف أحد العناصر التالية:
  • "مفتاح مادة العرض" للبث المباشر
  • "مفتاح مادة العرض المخصّص" للبث المباشر، والذي يتيح لك إدارة مساحة المفاتيح الخاصة بك من خلال تحديد سلسلة المعرّف الخاصة بك.
  • "رقم تعريف مصدر المحتوى" و"رقم تعريف المحتوى" للبث المباشر

ملاحظة: يجب أن تكون مفعّلاً لاستخدام نوع المعرّف هذا. لمزيد من المعلومات، يُرجى التواصل مع مدير حسابك.

  • المدة المتوقّعة للفاصل الإعلاني التالي. يجب أن تكون المدة قريبة من مدة الفاصل الإعلاني الفعلية قدر الإمكان.

بالإضافة إلى هذه الحقول المطلوبة، يمكنك أيضًا إرسال مَعلمات استهداف مخصّصة أو اسم نموذج مجموعة إعلانية متسلسلة لتطبيقه أو بيانات وقت الانتهاء وفقًا لمعيار SCTE35، إذا كانت متاحة.

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

لاستخدام واجهة برمجة التطبيقات EABN API، عليك إنشاء حساب خدمة وإضافته إلى شبكتك على "مدير إعلانات Google".

إنشاء حساب خدمة

لإنشاء حساب خدمة لاستدعاء واجهة برمجة التطبيقات EABN API، أكمِل الخطوات التالية: - إذا كان لديك حساب على Google Cloud، استخدِم وحدة إدارة الهوية وإمكانية الوصول (IAM) لإنشاء حساب خدمة. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء حسابات الخدمة وإدارتها. - إذا لم يكن لديك حساب على Google Cloud، أكمِل الخطوات التالية لإنشاء حساب من Google API Console:

  1. أنشئ مشروعًا جديدًا أو اختَر مشروعًا حاليًا.
  2. في صفحة بيانات الاعتماد، انقر على إدارة حسابات الخدمة.
  3. في صفحة حسابات الخدمة، انقر على إنشاء حساب خدمة.
  4. في صفحة إنشاء حساب خدمة، أدخِل تفاصيل الحساب. بعد ذلك، انقر على إنشاء.

بعد إنشاء حساب خدمة، انسخ مفتاح JSON للحساب الذي يُستخدَم للمصادقة.

إضافة حساب الخدمة إلى شبكة "مدير إعلانات Google"

لإضافة حساب الخدمة إلى شبكتك، أكمِل الخطوات الواردة في مقالة إضافة مستخدم حساب خدمة للوصول إلى واجهة برمجة التطبيقات.

تفعيل واجهة برمجة التطبيقات

بعد إنشاء حساب الخدمة، قدِّم المعلومات التالية إلى مدير حسابك لتفعيل واجهة برمجة التطبيقات لحسابك:

  • عنوان البريد الإلكتروني لحسابك على Google Cloud
  • حساب الخدمة
  • رمز الشبكة لشبكة "مدير إعلانات Google".

بعد أن يفعّل مدير حسابك واجهة برمجة التطبيقات، يُرجى إكمال الخطوات التالية لتفعيلها:

  1. في مكتبة Google API، ابحث عن "Google Ad Manager Video API".
  2. انقر على تفعيل.

ملاحظة: إذا لم تظهر واجهة برمجة التطبيقات في نتائج البحث، يُرجى التواصل مع مدير حسابك للتأكّد من أنّه تم تفعيل واجهة برمجة التطبيقات DAI API في حسابك.

استخدام واجهة برمجة التطبيقات

يمكنك طلب بيانات من واجهة برمجة التطبيقات EABN API باستخدام طلبات JSON/REST.

التفويض

لإجراء طلبات مفوَّضة إلى واجهة برمجة التطبيقات EABN API، عليك إنشاء بيانات اعتماد حساب الخدمة OAuth2 باستخدام مفتاح JSON من حساب الخدمة والنطاق https://www.googleapis.com/auth/video-ads. لمزيد من المعلومات، يُرجى الاطّلاع على استخدام OAuth 2.0 لتطبيقات الخادم إلى الخادم.

يجب تضمين رمز الموافقة الناتج كعنوان Auth لكل طلب إلى EABN API.

إرسال إشعار بفاصل إعلاني مبكر

لإرسال إشعار ببدء الفاصل الإعلاني مبكرًا، أرسِل طلب POST إلى أحد عناوين URL الثلاثة الصالحة لنظام EABN، استنادًا إلى الطريقة التي تفضّل بها تحديد البث المباشر. توضِّح الأقسام التالية الاختلافات بين عناوين URL وتوفّر أمثلة على الطلبات والردود.

عناوين URL

هناك ثلاثة عناوين URL صالحة لإشعارات الفواصل الإعلانية المبكرة. يمكنك استخدام الأنواع الثلاثة لإنشاء فاصل إعلاني (POST) أو الحصول على قائمة الفواصل الإعلانية المحدّدة (GET).

لاستخدام مفتاح مادة العرض لبث مباشر، استخدِم:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

لاستخدام مفتاح مادة العرض المخصّصة لبث مباشر، استخدِم:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

لاستخدام رقم تعريف مصدر المحتوى ونهج Content ID، استخدِم:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

بالنسبة إلى جميع المَعلمات:

  • يمثّل network_code رمز الشبكة لشبكة "مدير إعلانات Google".
  • يمثّل الرمز asset_key مفتاح مادة العرض المعروض في صفحة تفاصيل البث المباشر.
  • يمثّل custom_asset_key مفتاح مادة العرض المخصّصة لبثك المباشر.
  • يمثّل content_source_id رقم تعريف مصدر محتوى في "مدير إعلانات Google".
  • يمثّل content_id رقم تعريف قطعة محتوى في "مدير إعلانات Google".

ملاحظة: يجب أن يكون الزوج content_source_id/content_id المحدّد مرتبطًا ببث مباشر في "مدير إعلانات Google".

محتوى الطلب: يُستخدَم فقط لإنشاء فاصل إعلاني (POST)

عنصر

expectedDuration

 مطلوب مدة هذا الفاصل الإعلاني، باستخدام تنسيق المدة العادي من Google (xx.xxx ثانية حيث xx.xxx هو عدد الثواني)

customParams

 اختياري أزواج المفتاح/القيمة التي سيتم تضمينها في طلبات الإعلانات لهذا الفاصل لاستهداف المعايير المخصّصة في "مدير إعلانات شبكة البحث 360"، مفصولة بـ

=

انضم إليهم

&


مثال:

key=value&key2=value2,value3


لمزيد من المعلومات عن الاستهداف، اطّلِع على مقالة إرسال مَعلمات الاستهداف إلى البث.

podTemplateName

 اختياري اسم نموذج مجموعة الإعلانات

scte35CueOut

 اختياري بيانات بترميز Base-64 من إشارة الخروج scte35 يمكن أن يشمل ذلك

splice_insert()

أو

time_signal()

الأمر.
أمثلة:

  • time_signal():

    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

أمثلة على الطلبات

إنشاء فاصل إعلاني
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}
نص الاستجابة

يحتوي نص الاستجابة على جميع المَعلمات المُرسَلة في عنصر adBreak، بالإضافة إلى حقل name إضافي يحتوي على المعرّف العادي على مستوى Google للمَوقف الإعلاني الذي تم إنشاؤه. يتم عرض هذا الحقل بالتنسيق التالي:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
مثال على إجابة
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}
إدراج الفواصل الإعلانية المخصّصة
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
نص الاستجابة

يحتوي نص الاستجابة على الفواصل الإعلانية مع حقل breakState إضافي لكل فاصل إعلاني تم تعيينه إلى البث. يقبل الحقل breakState القيم التالية:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
مثال على إجابة
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}