تتيح لك واجهة برمجة التطبيقات DAI Pod عرض الإعلانات من Google تنفيذ ميزة إدراج الإعلانات من جهة الخادم بدعم من "إعلانات Google" مع الحفاظ على إمكانية التحكّم في تركيب الفيديوهات.
يوضّح لك هذا الدليل كيفية التفاعل مع واجهة برمجة تطبيقات عرض الإعلانات على Pod وتحقيق وظائف مشابهة باستخدام حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية. إذا كانت لديك أسئلة محدّدة حول الوظائف المتوافقة، يُرجى التواصل مع مدير حسابك على Google.
تتوافق واجهة برمجة التطبيقات Pod Present API مع مجموعات بث عرض الإعلانات المتسلسلة في بروتوكولات البث HLS أو MPEG-DASH. يركّز هذا الدليل على بث HLS ويسلط الضوء على الاختلافات الرئيسية بين HLS وMPEG-DASH في خطوات محدّدة.
لدمج واجهة برمجة تطبيقات Pod VIEW API في تطبيقك لأحداث البث المباشر عند الطلب، أكمِل الخطوات التالية:
تقديم طلب تسجيل بث إلى "مدير إعلانات Google"
يمكنك تقديم طلب POST إلى نقطة نهاية تسجيل البث. ستتلقى بدورها استجابة JSON تحتوي على معرّف البث لإرساله إلى خادم معالجة البيان ونقاط نهاية واجهة برمجة تطبيقات Pod Present API المرتبطة بها.
نقطة النهاية لواجهة برمجة التطبيقات
POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
معلمات المسار
{network_code} |
رمز شبكة "مدير إعلانات Google 360" |
{custom_asset} |
المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google" |
مَعلمات النص بترميز النموذج
مجموعة اختيارية من معلمات الاستهداف بترميز النموذج.
استجابة JSON
media_verification_url |
عنوان URL الأساسي الذي يُستخدم لاختبار أحداث تتبُّع التشغيل. يتم إنشاء عنوان URL كامل للتحقق من الوسائط من خلال إلحاق رقم تعريف حدث إعلان بعنوان URL الأساسي هذا. |
metadata_url |
عنوان URL لطلب البيانات الوصفية لمجموعة الإعلانات المتسلسلة. |
stream_id |
السلسلة المستخدَمة لتحديد جلسة البث الحالية. |
valid_for |
تمثّل هذه السمة الفترة الزمنية المتبقية لانتهاء صلاحية جلسة البث الحالية بالتنسيق dhms (أيام، ساعات، دقائق، ثوانٍ). على سبيل المثال، تشير السمة 2h0m0.000s إلى مدة ساعتَين.
|
valid_until |
تمثّل هذه السمة الوقت الذي تنتهي فيه صلاحية جلسة البث الحالية، كسلسلة تاريخ ووقت ISO 8601 بتنسيق yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
مثال على طلب (cURL)
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded"
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\""
https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
مثال على إجابة
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
في حال حدوث أخطاء، يتم عرض رموز خطأ HTTP العادية بدون نص استجابة JSON.
تحليل استجابة JSON وتخزين القيم ذات الصلة.
طلب بيان البث من معالج البيانات
لكل معالج بيانات تنسيقات الطلبات والاستجابة المختلفة. تواصَل مع مزوّد المعالجة لفهم متطلباته الخاصة. إذا كنت تنفّذ أداة معالجة البيانت الخاصة بك، فاقرأ دليل مناولة البيانات لفهم متطلبات هذا المكوّن.
بشكل عام، يجب تمرير معرّف مصدر البيانات الذي تم عرضه من خلال نقطة نهاية التسجيل أعلاه إلى معالج البيان من أجل إنشاء بيانات خاصة بالجلسة. ما لم يُذكَر في معالج البيان صراحةً أن الرد على طلب البيان هو بث فيديو يضم كلاً من المحتوى والإعلانات.
مثال على طلب (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
مثال على الرد (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
تشغيل البث
حمِّل البيان الذي تلقّيته من خادم معالجة البيان إلى مشغّل فيديو وابدأ التشغيل.
طلب البيانات الوصفية لمجموعة الإعلانات المتسلسلة من "مدير إعلانات Google"
يمكنك تقديم طلب GET
إلى metadata_url
الذي تلقّيته في الخطوة الأولى. يجب أن تحدث هذه
الخطوة بعد أن تتلقى البيان الذي تم دمجه من معالج البيانات. وفي المقابل، تتلقى كائن JSON يحتوي على المعلمات التالية:
tags |
مجموعة من أزواج المفتاح/القيمة تحتوي على جميع أحداث الإعلانات التي تظهر في
البث. تكون المفاتيح إما أول 17 حرفًا من رقم تعريف
حدث الإعلان الذي يظهر في البيانات الوصفية المحدّدة زمنيًا للبث، أو في حالة الأحداث
من النوع progress ، الرقم التعريفي الكامل لحدث الإعلان.
كل قيمة هي كائن يحتوي على المعلمات التالية:
|
||||||||||||||||||
ads |
مجموعة من أزواج المفتاح/القيمة تصف جميع الإعلانات التي تظهر في مجموعة البث. والمفاتيح هي أرقام تعريف إعلانات تتطابق مع القيم المتوفّرة في عنصر tags
المذكور أعلاه. كل قيمة هي كائن يحتوي على المعلمات التالية:
|
||||||||||||||||||
ad_breaks |
مجموعة من أزواج المفتاح/القيمة تصف جميع الفواصل الإعلانية التي تظهر في البث.
المفاتيح هي أرقام تعريف الفواصل الإعلانية التي تطابق القيم الواردة في العنصرَين tags وads المذكورَين أعلاه. كل قيمة هي كائن
يحتوي على المَعلمات التالية:
|
ويمكنك تخزين هذه القيم لربطها بأحداث البيانات الوصفية المحدّدة زمنيًا ضمن بث الفيديو.
مثال على طلب (cURL)
curl https://dai.google.com/.../metadata
مثال على إجابة
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
الاستماع إلى أحداث الإعلانات
استمع إلى البيانات الوصفية المحدّدة زمنيًا من خلال أحداث الإعلانات المعروضة في بث الصوت/الفيديو على مشغّل الفيديو.
بالنسبة إلى مجموعات بث MPEG-TS، تظهر البيانات الوصفية كعلامات ID3.3 ضمن النطاق. لكل علامة بيانات وصفية رقم التعريف TXXX
، وتبدأ القيمة بالسلسلة google_
متبوعة بسلسلة من الأحرف. هذه القيمة هي رقم تعريف حدث الإعلان.
إنّ XXX
في TXXX
ليس عنصرًا نائبًا. السلسلة TXXX
هي رقم تعريف علامة ID3
المحجوز له لـ "نص من تحديد المستخدم".
مثال على علامة رقم التعريف 3
TXXXgoogle_1234567890123456789
بالنسبة إلى مجموعات بث MP4، يتم إرسالها كأحداث رسائل ضمن النطاق تحاكي علامات ID3 v2.3. يحتوي كل مربع رسائل ذي صلة على قيمة scheme_id_uri
إما https://aomedia.org/emsg/ID3
أو https://developer.apple.com/streaming/emsg-id3
وقيمة message_data
تبدأ بـ ID3TXXXgoogle_
. إنّ قيمة message_data
هذه، بدون
البادئة ID3TXXX
، هي رقم تعريف حدث الإعلان.
مثال على صندوق الرسائل الإلكترونية
قد تختلف بنية البيانات بناءً على مكتبة مشغّل الوسائط.
إذا كان رقم تعريف حدث الإعلان هو google_1234567890123456789
، سيبدو الرد كما يلي:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
تعرض بعض مكتبات مشغّلات الوسائط تلقائيًا أحداث رسائل قصيرة تحاكي علامات ID3 كعلامات ID3 أصلية. في هذه الحالة، تقدم مجموعات بث MP4 علامات ID3 متطابقة مثل MPEG_TS.
تحديث واجهة المستخدم لتطبيق مشغّل الفيديو الخاص بالعميل
يمكن مطابقة كل رقم تعريف حدث إعلاني بمفتاح في عنصر tags
من الخطوة 4.
مطابقة هذه القيم هي عملية مؤلفة من خطوتين:
تحقَّق من العنصر
tags
بحثًا عن مفتاح يتطابق مع رقم تعريف حدث الإعلان الكامل. إذا تم العثور على تطابق، يمكنك استرداد نوع الحدث وكائناتad
وad_break
المرتبطة به. يجب أن تكون هذه الأحداث من النوعprogress
.في حال لم يتم العثور على مطابقة للرقم التعريفي الكامل للحدث الإعلاني، تحقَّق من الكائن
tags
عن مفتاح يتطابق مع أول 17 حرفًا من رقم تعريف الحدث الإعلاني. استرِد نوع الحدث وعنصرَيad
وad_break
المرتبطَين. من المفترض أن يؤدي ذلك إلى استرداد جميع الأحداث التي لها أنواع بخلافprogress
.استخدم هذه المعلومات التي تم استردادها لتحديث واجهة مستخدم المشغل. على سبيل المثال، عندما تتلقى
start
أو حدثprogress
الأول، يمكنك إخفاء عناصر التحكم في شريط التمرير للّاعبين وعرض طبقة تصف موضع الإعلان الحالي في الفاصل الإعلاني، على سبيل المثال: "الإعلان 1 من 3".
أمثلة على أرقام تعريف أحداث الإعلانات
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
مثال على كائن العلامات
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
إرسال إشعارات لإثبات ملكية الوسائط
يجب إرسال إشعار التحقّق من الوسائط إلى "مدير الإعلانات" في كل مرة يتم فيها تلقّي حدث إعلاني من نوع غير progress
.
لإنشاء عنوان URL الكامل للتحقق من الوسائط لحدث إعلان، ألحِق رقم تعريف حدث الإعلان بالكامل بالقيمة media_verification_url
من استجابة تسجيل البث.
يمكنك تقديم طلب GET باستخدام عنوان URL الكامل. إذا كان طلب التحقق ناجحًا،
ستتلقّى استجابة HTTP برمز الحالة 202
.
وفي حال عدم تنفيذ هذا الإجراء، سيظهر رمز خطأ HTTP 404
.
مثال على طلب (cURL)
curl https://{...}/media/google_5555555555123456789
مثال على ردّ ناجح
HTTP/1.1 202 Accepted