برنامه پخش کننده ویدیوی مشتری برای جریان های VOD

Google DAI Pod Serving API به شما امکان می‌دهد درج آگهی در سمت سرور را که توسط Google Ads پشتیبانی می‌شود، انجام دهید و در عین حال کنترل دوخت ویدیوی خود را حفظ کنید.

این راهنما به شما نشان می‌دهد که چگونه با Pod Serving API تعامل کنید و با IMA DAI SDK به عملکردی مشابه دست پیدا کنید. برای سؤالات خاص در مورد عملکرد پشتیبانی شده، با مدیر حساب Google خود تماس بگیرید.

Pod Serving API از جریان های سرویس دهی در پروتکل های پخش HLS یا MPEG-DASH پشتیبانی می کند. این راهنما بر جریان های HLS تمرکز دارد و تفاوت های کلیدی بین HLS و MPEG-DASH را در مراحل خاص برجسته می کند.

برای ادغام Pod Serving API در برنامه خود برای جریان های VOD، مراحل زیر را کامل کنید:

یک درخواست ثبت جریان به Ad Manager ارائه دهید

یک درخواست POST به نقطه پایانی ثبت جریان ارسال کنید. شما به نوبه خود یک پاسخ JSON حاوی شناسه جریان برای ارسال به سرور دستکاری مانیفست و نقاط پایانی Pod Serving API دریافت می کنید.

نقطه پایانی API

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

پارامترهای مسیر

پارامترهای بدنه JSON

پاسخ JSON

درخواست نمونه (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

پخش جریانی

مانیفست دریافتی از سرور دستکاری مانیفست را در یک پخش کننده ویدیو بارگیری کنید و پخش را شروع کنید.

فراداده غلاف آگهی را از Ad Manager درخواست کنید

یک درخواست GET به metadata_url که در مرحله یک دریافت کردید، ارسال کنید. این مرحله باید بعد از اینکه مانیفست دوخته شده را از دستکاری کننده مانیفست خود دریافت کردید انجام شود. شما به نوبه خود یک شی JSON حاوی پارامترهای زیر دریافت می کنید:

این مقادیر را ذخیره کنید تا با رویدادهای فراداده زمان‌بندی شده در جریان ویدیوی خود مرتبط شوند.

درخواست نمونه (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 v2.3 ظاهر می شوند. هر تگ فراداده دارای شناسه TXXX است و مقدار آن با رشته google_ و سپس یک سری کاراکتر شروع می شود. این مقدار شناسه رویداد تبلیغاتی است.

XXX در TXXX یک مکان نگهدار نیست. رشته TXXX شناسه تگ ID3 است که برای "متن تعریف شده توسط کاربر" رزرو شده است.

تگ ID3 مثال

TXXXgoogle_1234567890123456789

برای جریان‌های MP4، اینها به‌عنوان رویدادهای emsg درون باند ارسال می‌شوند که برچسب‌های ID3 v2.3 را شبیه‌سازی می‌کنند. هر جعبه emsg مربوطه دارای مقدار scheme_id_uri https://aomedia.org/emsg/ID3 یا https://developer.apple.com/streaming/emsg-id3 و مقدار message_data با ID3TXXXgoogle_ است. این مقدار message_data ، بدون پیشوند ID3TXXX ، شناسه رویداد تبلیغاتی است.

جعبه emsg مثال

بسته به کتابخانه پخش کننده رسانه شما، ساختار داده ممکن است متفاوت باشد.

اگر شناسه رویداد تبلیغاتی google_1234567890123456789 باشد، پاسخ به این شکل است:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

برخی از کتابخانه های پخش کننده رسانه به طور خودکار رویدادهای emsg را ارائه می کنند که برچسب های ID3 را به عنوان برچسب های ID3 بومی تقلید می کنند. در این مورد، جریان های MP4 برچسب های ID3 یکسانی را به عنوان MPEG_TS ارائه می دهند.

رابط کاربری برنامه پخش‌کننده ویدیوی مشتری را به‌روزرسانی کنید

هر شناسه رویداد تبلیغاتی را می‌توان با کلیدی در شی tags از مرحله 4 مطابقت داد. تطبیق این مقادیر یک فرآیند دو مرحله‌ای است:

1. شی tags برای داشتن کلیدی که با شناسه کامل رویداد تبلیغاتی مطابقت دارد بررسی کنید. اگر مطابقت یافت شد، نوع رویداد و اشیاء ad و ad_break مرتبط با آن را بازیابی کنید. این رویدادها باید نوع progress داشته باشند.

   اگر مطابق با شناسه کامل رویداد تبلیغاتی یافت نشد، شیء tags برای کلیدی که با 17 نویسه اول شناسه رویداد تبلیغاتی مطابقت دارد بررسی کنید. نوع رویداد و اشیاء ad و ad_break مرتبط را بازیابی کنید. این باید همه رویدادها را با انواعی غیر از progress بازیابی کند.

2. از این اطلاعات بازیابی شده برای به روز رسانی رابط کاربری پخش کننده خود استفاده کنید. به عنوان مثال، هنگامی که یک 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 دریافت می‌شود، یک پینگ تأیید رسانه باید به Ad Manager ارسال شود.

برای ایجاد URL تأیید رسانه کامل یک رویداد تبلیغاتی، شناسه کامل رویداد آگهی را به مقدار media_verification_url از پاسخ ثبت جریانی اضافه کنید.

با URL کامل یک درخواست GET داشته باشید. اگر درخواست تأیید موفقیت آمیز باشد، به نوبه خود یک پاسخ HTTP با کد وضعیت 202 دریافت می کنید. در غیر این صورت، کد خطای HTTP 404 را دریافت می کنید.

درخواست نمونه (cURL)

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

نمونه پاسخ موفق

HTTP/1.1 202 Accepted

منابع اضافی

• اسناد IMA SDK
• مقایسه انواع اجرای پخش کننده DAI