Pod Serving API در حال حاضر در نسخه بتا بسته است. اگر علاقه مند به کسب اطلاعات بیشتر در مورد Pod Serving هستید یا می خواهید Pod Serving API را پیاده سازی کنید، لطفاً با مدیر حساب Google خود تماس بگیرید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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، مراحل زیر را کامل کنید:

یک درخواست ثبت جریان به DAI Pod Serving API ارائه دهید

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

نقطه پایانی 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 Ad Manager 360 شما
`{custom_asset}`	شناسه سفارشی مربوط به این رویداد در Google AdManager است.

پارامترهای بدنه کدگذاری شده با فرم

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

پاسخ 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 \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

پاسخ نمونه

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

در صورت بروز خطا، کدهای خطای استاندارد 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

پخش جریانی

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

نظرسنجی برای ابرداده جدید AdBreak

این برنامه مسئول بازیابی ابرداده برای هر وقفه تبلیغاتی است، بنابراین می‌داند چه نمایش‌هایی باید فعال شوند. برای انجام این کار، یک تایمر تنظیم می‌کنید تا مرتباً APIهای DAI را برای اطلاعات آگهی جدید metadata_url کند. فاصله نظرسنجی در قسمت polling_frequency در پاسخ ثبت جریان مشخص شده است.

در عوض، یک شی 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 مطابقت داد. تطبیق این مقادیر یک فرآیند دو مرحله‌ای است:

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

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

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

نکته: رویدادهای تبلیغاتی از نوع progress نباید به Ad Manager ارسال شوند. هدف از این رویدادها اطلاع رسانی به برنامه پخش کننده ویدیوی مشتری است که در شرایطی که رویداد شروع ممکن است دریافت نشده باشد، یک وقفه تبلیغاتی در حال پخش است. به عنوان مثال، اگر کاربر به دنبال موقعیتی باشد یا پخش را در یک مُهر زمانی مشخص که در وسط تبلیغ است شروع کند، رویداد شروعی را دریافت نخواهد کرد. رویدادهای پیشرفت ارسال شده به Ad Manager نادیده گرفته می شوند که می تواند بر عملکرد برنامه تأثیر منفی بگذارد.

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

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

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

HTTP/1.1 202 Accepted

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

یک درخواست ثبت جریان به DAI Pod Serving API ارائه دهید

نقطه پایانی API

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

پارامترهای بدنه کدگذاری شده با فرم

پاسخ JSON

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

پاسخ نمونه

مانیفست جریان را از دستکاری کننده مانیفست درخواست کنید

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

پاسخ نمونه (HLS)

پخش جریانی

نظرسنجی برای ابرداده جدید AdBreak

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

پاسخ نمونه

به رویدادهای تبلیغاتی گوش دهید

تگ ID3 مثال

جعبه emsg مثال

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

نمونه شناسه‌های رویداد تبلیغاتی

مثال تگ شی

پینگ های تایید رسانه را ارسال کنید

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

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

منابع اضافی