برنامه پخش کننده ویدیوی مشتری برای جریان های 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

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

{network_code} کد شبکه Google Ad Manager 360 شما

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

targeting_parameters یک شی JSON حاوی پارامترهای هدف‌یابی آگهی. مورد نیاز

پاسخ JSON

media_verification_url نشانی وب پایه رویدادهای ردیابی پخش پینگ. یک URL تأیید رسانه کامل با افزودن شناسه رویداد تبلیغاتی به این URL پایه تشکیل می‌شود.
metadata_url نشانی اینترنتی درخواست فراداده غلاف آگهی .
stream_id رشته ای که برای شناسایی جلسه جریان فعلی استفاده می شود.
valid_for مقدار زمان باقی مانده تا پایان جلسه جاری جاری، در قالب dhms (روز، ساعت، دقیقه، ثانیه). برای مثال، 2h0m0.000s نشان دهنده مدت زمان 2 ساعت است.
valid_until زمانی که جلسه جاری جاری منقضی می‌شود، به‌عنوان یک رشته تاریخ تاریخ ISO 8601 در قالب yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .

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

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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 حاوی پارامترهای زیر دریافت می کنید:

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 نشانی اینترنتی که باید هنگام تعامل کاربر با این تبلیغ باز شود، در صورت پشتیبانی.
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 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

منابع اضافی