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

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تطبيق مشغّل الفيديو التابع للعميل لبث الفيديوهات عند الطلب

تتيح لك واجهة برمجة التطبيقات Google DAI Pod Inventory API تنفيذ ميزة إدراج الإعلانات من جهة الخادم. من خلال "إعلانات Google" مع الحفاظ على التحكّم في تركيب الفيديوهات بنفسك.

يوضِّح لك هذا الدليل كيفية التفاعل مع واجهة برمجة تطبيقات عرض الإعلانات Pod وتحقيق بوظائف مشابهة باستخدام حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية. إذا كانت لديك أسئلة محددة حول وظائف متوافقة، اتصل بمدير حسابك في Google.

تتيح واجهة برمجة تطبيقات عرض Pod Inventory عرض مجموعات البث بتنسيق HLS أو MPEG-DASH وبروتوكولات البث. يركِّز هذا الدليل على أحداث بث HLS، ويسلّط الضوء على أهم الاختلافات بين بروتوكول HLS وMPEG-DASH في خطوات محدّدة.

لدمج واجهة برمجة تطبيقات عرض الفيديوهات Pod في تطبيقك لبثّ الفيديوهات عند الطلب، أكمِل الخطوات التالية:

تقديم طلب تسجيل البث إلى "مدير إعلانات Google"

تقديم طلب POST إلى نقطة نهاية تسجيل البث تتلقى بالدور استجابة JSON تحتوي على رقم تعريف مصدر البيانات لإرسالها إلى التلاعب بالبيان ونقاط نهاية واجهة برمجة التطبيقات Pod Inventory API المرتبطة بها.

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

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

مَعلمات المسار

{network_code} رمز شبكة "مدير إعلانات Google 360"

مَعلمات نص JSON

targeting_parameters كائن JSON يحتوي على معرّف مصدر المحتوى (cmsid) ومعرّف الفيديو (vid) استهداف الإعلانات المَعلمات. مطلوب

استجابة 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 \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

مثال على إجابة

{
  "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، رقم تعريف حدث الإعلان الكامل.

كلّ قيمة هي عنصر يحتوي على المَعلمات التالية:

ad رقم تعريف إعلان يتطابق مع مفتاح في عنصر ads.

ad_break_id رقم تعريف فاصل إعلاني يتطابق مع مفتاح في ad_breaks الخاص بك.

type

نوع حدث الإعلان. أنواع أحداث الإعلانات هي:

`start`	يتم إطلاقه في بداية الإعلان.
`firstquartile`	تم إطلاقها في نهاية الربع الأول.
`midpoint`	يتم إطلاقه في منتصف الإعلان.
`thirdquartile`	تم إطلاقها في نهاية الربع الثالث.
`complete`	يتم إطلاقه في نهاية الإعلان.
`progress`	يتم إطلاقها بشكل دوري في أنحاء الإعلان لإعلام التطبيق بأن الإعلان الاستراحة.

ads

مجموعة من أزواج المفتاح/القيمة تصف جميع الإعلانات التي تظهر في ساحة المشاركات. تشير رسالة الأشكال البيانية المفاتيح هي أرقام تعريف إعلانات تتطابق مع القيم المتوفّرة في عنصر tags. الواردة أعلاه. كلّ قيمة هي عنصر يحتوي على المَعلمات التالية:

`ad_break_id`	رقم تعريف فاصل إعلاني يتطابق مع مفتاح في `ad_breaks` الخاص بك.
`position`	الموضع الذي يظهر فيه هذا الإعلان ضمن مجموعة الإعلانات في الإعلان ينكسر في ثانية النقطة العائمة.
`duration`	مدة الإعلان بالثواني العائم.
`clickthrough_url`	تمثّل هذه السمة عنوان URL الذي يجب فتحه عندما يتفاعل المستخدِم مع هذا الإعلان، إذا كان متاحًا.

ad_breaks

مجموعة من أزواج المفتاح/القيمة تصف كل الفواصل الإعلانية التي تظهر في البث المباشر. المفاتيح هي أرقام تعريف الفواصل الإعلانية التي تتطابق مع القيم الواردة في tags. وads كائنًا أعلاه. كل قيمة هي كائن تحتوي على المَعلمات التالية:

`type`	نوع الفاصل الإعلاني. أنواع الفواصل الإعلانية هي `pre` (إعلانات ما قبل التشغيل). `mid` (إعلان أثناء التشغيل) و`post` (إعلان ما بعد التشغيل)
`duration`	مدة الفاصل الإعلاني بالثواني العائم.
`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 للإصدار 2.3 ضمن النطاق. على كل تحتوي علامة البيانات الوصفية على رقم التعريف TXXX، وتبدأ القيمة بالسلسلة google_ متبوعة بسلسلة من الأحرف. هذه القيمة هي رقم تعريف حدث الإعلان.

إنّ العنصر XXX في السمة TXXX ليس عنصرًا نائبًا. السلسلة "TXXX" هي رقم تعريف العلامة ID3. محجوزة لـ "النص الذي يحدده المستخدم".

مثال على علامة ID3

TXXXgoogle_1234567890123456789

بالنسبة إلى أحداث البث بتنسيق MP4، يتم إرسالها كأحداث رسائل إلكترونية ضمن النطاق تحاكي الإصدار 2.3 من المعرّف 3 (ID3). . يحتوي كل مربع رسالة إلكترونية ذي صلة على قيمة 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",
  ...
}

تعرض بعض مكتبات مشغّلات الوسائط تلقائيًا أحداث الرسائل الإلكترونية التي تحاكي رقم التعريف 3. كعلامات 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"
  },
  ...
}

إرسال إشعارات للتحقق من الوسائط

يجب إرسال إشعار التحقّق من الوسائط إلى "مدير إعلانات Google" في كل مرة يحدث فيها إعلان. من أي نوع آخر غير progress يتم استلامها.

لإنشاء عنوان URL الكامل للتحقق من الوسائط لحدث إعلان، ألحق العنوان الكامل رقم تعريف حدث الإعلان إلى القيمة media_verification_url من تسجيل البث الاستجابة.

يمكنك تقديم طلب GET باستخدام عنوان URL الكامل. إذا كان طلب التحقق هو بنجاح، ستتلقى استجابة HTTP برمز الحالة 202. وإذا لم يكن كذلك، سيظهر لك رمز خطأ HTTP 404.

ملاحظة: يجب عدم إرسال أحداث الإعلانات من النوع progress إلى "مدير إعلانات Google". هذه الأحداث لإعلام تطبيق مشغّل الفيديو للعميل بأنّ الفاصل الإعلاني في الحالات التي لا يمكن فيها استلام حدث البداية. على سبيل المثال، إذا كان المستخدم يسعى إلى مكان معيّن أو يبدأ التشغيل في موضع معيّن الطابع الزمني الذي يظهر في منتصف الإعلان، لن يتلقّى حدث بدء. يتم تجاهل أحداث مستوى التقدّم التي تم إرسالها إلى "مدير إعلانات Google"، ما قد يؤثر سلبًا في أداء الحملة. من أداء التطبيق

مثال على الطلب (cURL)

curl https://{...}/media/google_5555555555123456789

مثال على الرد الناجح

HTTP/1.1 202 Accepted

تطبيق مشغّل الفيديو التابع للعميل لبث الفيديوهات عند الطلب

تقديم طلب تسجيل البث إلى "مدير إعلانات Google"

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

مَعلمات المسار

مَعلمات نص JSON

استجابة JSON

مثال على الطلب (cURL)

مثال على إجابة

طلب بيان البث من أداة معالجة البيان

مثال على الطلب (cURL)

مثال على الردّ (HLS)

تشغيل البث

طلب البيانات الوصفية لمجموعة الإعلانات من "مدير إعلانات Google"

مثال على الطلب (cURL)

مثال على إجابة

الاطّلاع على أحداث الإعلانات

مثال على علامة ID3

مثال على مربّع رسالة إلكترونية

تحديث واجهة المستخدم لتطبيق مشغّل الفيديو العميل

أمثلة على أرقام تعريف أحداث الإعلانات

مثال على عنصر العلامات

إرسال إشعارات للتحقق من الوسائط

مثال على الطلب (cURL)

مثال على الرد الناجح

مراجع إضافية