مشتری را برای تغییر مسیر سرویس غلاف آماده کنید

این راهنما، توسعه یک برنامه کلاینت برای بارگذاری پخش زنده HLS یا DASH با API سرویس‌دهی Pod و کنترل‌کننده مانیفست شما را پوشش می‌دهد.

پیش‌نیازها

قبل از ادامه، باید موارد زیر را داشته باشید:

  • یک کلید دارایی سفارشی برای یک رویداد پخش زنده که با نوع DAI Pod serving redirect پیکربندی شده است. برای دریافت این کلید، مراحل زیر را دنبال کنید:

  • بررسی کنید که آیا SDK تبلیغات رسانه‌ای تعاملی (IMA) برای پلتفرم شما در دسترس است یا خیر. ما استفاده از IMA SDK را برای افزایش درآمد توصیه می‌کنیم. برای جزئیات بیشتر، به تنظیم IMA SDK برای DAI مراجعه کنید.

درخواست پخش جریانی بدهید

وقتی کاربر شما یک جریان را انتخاب می‌کند، موارد زیر را انجام دهید:

  1. یک درخواست POST به متد سرویس پخش زنده ارسال کنید. برای جزئیات بیشتر، به Method: stream مراجعه کنید.

  2. پارامترهای هدف‌گیری تبلیغات را در قالب‌های application/x-www-form-urlencoded یا application/json ارسال کنید. این درخواست یک جلسه پخش جریانی را در Google DAI ثبت می‌کند.

    مثال زیر یک درخواست جریان ایجاد می‌کند:

    کدگذاری فرم 

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

    رمزگذاری JSON 

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

    در صورت موفقیت، خروجی مشابه زیر را مشاهده خواهید کرد:

    {
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

  3. در پاسخ JSON، شناسه جلسه جریان را پیدا کنید و سایر داده‌ها را برای مراحل بعدی ذخیره کنید.

فراداده‌های تبلیغات نظرسنجی

برای نظرسنجی در مورد متادیتای تبلیغات، موارد زیر را انجام دهید:

  1. مقدار metadata_url را از پاسخ ثبت جریان (stream registration response) بخوانید.

  2. یک درخواست اولیه GET به نقطه پایانی metadata_url ارسال کنید.

    • پارامتر کوئری delta_token حذف کنید. این فرآیند به سرور اجازه می‌دهد تا فراداده کامل مربوط به پنجره ضبط‌کننده ویدیوی دیجیتال (DVR) مربوط به پخش زنده را برگرداند. پنجره DVR شامل بازه زمانی پخش موجود برای بیننده جهت عقب و جلو بردن و پخش مجدد است. پاسخ شامل یک فیلد next_delta_token است.

  3. برای بهینه‌سازی پهنای باند، مقدار next_delta_token را از جدیدترین پاسخ ذخیره کنید.

  4. در درخواست بعدی خود، آن مقدار را به عنوان پارامتر کوئری delta_token ارسال کنید. سرور فقط فراداده‌هایی را که از زمان تولید آن توکن تغییر کرده‌اند، برمی‌گرداند. همیشه آخرین توکنی را که دریافت کرده‌اید ارسال کنید. سعی نکنید توکن را تجزیه، اصلاح یا بسازید. برای جزئیات بیشتر، به Method: metadata مراجعه کنید.

    مثال زیر متادیتای تبلیغات را دریافت می‌کند:

    // Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

    در صورت موفقیت، پاسخ PodMetadata را دریافت می‌کنید. اگر پارامتر delta_token را وارد کنید، پاسخ فقط شامل تبلیغات، وقفه‌های تبلیغاتی و برچسب‌هایی است که سرور از زمان تولید توکن توسط سرور اضافه یا به‌روزرسانی کرده است. پاسخ همچنین حاوی مقدار جدید next_delta_token است. اگر هرگونه وقفه تبلیغاتی قدیمی باشد، پاسخ شامل لیست obsolete_ad_break_ids از وقفه‌های تبلیغاتی برای حذف از حافظه پنهان شما نیز می‌شود.

    {
  "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
  "obsolete_ad_break_ids": ["0003069407"],
  "tags":{
    "google_1022389921":{
      "ad":"0003069408_ad1",
      "ad_break_id":"0003069408",
      "type":"start"
    },
    ...
  },
  "ads":{
    "0003069408_ad1":{
      "ad_break_id":"0003069408",
      "position":1,
      "duration":10.01,
      "title":"External - Pod Midroll 1",
      "clickthrough_url":"https://.../",
      ...
    },
    ...
  },
  "ad_breaks":{
    "0003069408":{
      "type":"mid",
      "duration":30,
      "ads":3
    },
    ...
  }
}

  5. شیء tags را ذخیره کنید و به‌روزرسانی‌ها را در حافظه پنهان محلی خود ادغام کنید. اگر پارامتر obsolete_ad_break_ids وجود دارد، آن وقفه‌های تبلیغاتی و تبلیغات و برچسب‌های مرتبط را از حافظه پنهان خود حذف کنید.

  6. با استفاده از مقدار polling_frequency یک تایمر تنظیم کنید تا مرتباً فراداده درخواست شود. در هر نظرسنجی، مقدار next_delta_token برگردانده شده در جدیدترین پاسخ فراداده را به عنوان پارامتر پرس و جوی delta_token ارسال کنید.

پخش جریانی را در پخش‌کننده ویدیوی خود بارگذاری کنید

بعد از اینکه شناسه جلسه را از پاسخ ثبت نام دریافت کردید، شناسه را به کنترل‌کننده مانیفست خود منتقل کنید، یا یک URL مانیفست برای بارگذاری جریان در یک پخش‌کننده ویدیو بسازید.

برای ارسال شناسه جلسه، به مستندات دستکاری‌کننده مانیفست خود مراجعه کنید. اگر یک دستکاری‌کننده مانیفست ایجاد می‌کنید، برای پخش زنده به Manifest manipulator مراجعه کنید.

مثال زیر یک URL مانیفست را مونتاژ می‌کند:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

وقتی پخش‌کننده شما آماده شد، پخش را شروع کنید.

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

قالب کانتینر جریان خود را برای ابرداده زمان‌بندی‌شده بررسی کنید:

  • جریان‌های HLS با کانتینرهای Transport Stream (TS) از برچسب‌های ID3 زمان‌بندی‌شده برای حمل فراداده‌های زمان‌بندی‌شده استفاده می‌کنند. برای جزئیات بیشتر، به «درباره قالب برنامه رسانه‌ای مشترک با HTTP Live Streaming (HLS)» مراجعه کنید.

  • جریان‌های DASH از عناصر EventStream برای مشخص کردن رویدادها در مانیفست استفاده می‌کنند.

  • جریان‌های DASH از عناصر InbandEventStream استفاده می‌کنند، زمانی که بخش‌ها حاوی کادرهای پیام رویداد ( emsg ) برای داده‌های بار داده، از جمله برچسب‌های ID3، باشند. برای جزئیات بیشتر، به InbandEventStream مراجعه کنید.

  • جریان‌های CMAF، شامل DASH و HLS، از جعبه‌های emsg حاوی برچسب‌های ID3 استفاده می‌کنند.

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

برای بازیابی شناسه رویداد تبلیغ از برچسب‌های ID3، موارد زیر را انجام دهید:

  1. رویدادها را بر اساس scheme_id_uri با urn:google:dai:2018 یا https://aomedia.org/emsg/ID3 فیلتر کنید.

  2. آرایه بایت را از فیلد message_data استخراج کن.

    مثال زیر داده‌های emsg را به JSON رمزگشایی می‌کند:

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

  3. تگ‌های ID3 را با فرمت TXXXgoogle_{ad_event_ID} فیلتر کنید:

    TXXXgoogle_1022389921

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

برای یافتن شیء TagSegment ، مراحل زیر را انجام دهید:

  1. شیء tags مربوط به متادیتای تبلیغات را از متادیتای تبلیغات Poll بازیابی کنید. شیء tags آرایه‌ای از اشیاء TagSegment است.

  2. از شناسه کامل رویداد تبلیغ برای یافتن یک شیء TagSegment با نوع progress استفاده کنید.

  3. از ۱۷ کاراکتر اول شناسه رویداد تبلیغ برای یافتن یک شیء TagSegment از انواع دیگر استفاده کنید.

    از آنجا که برنامه‌ی کلاینت شما به صورت دوره‌ای فراداده‌های تبلیغاتی را جمع‌آوری می‌کند، ممکن است بین زمانی که پخش‌کننده‌ی ویدیوی شما با یک برچسب ID3 در جریان مواجه می‌شود و زمانی که فراداده‌ی مرتبط در دسترس قرار می‌گیرد، تأخیری رخ دهد. اگر برنامه‌ی کلاینت شما برچسب ID3 را در برچسب‌های ذخیره‌شده پیدا نکرد، برچسب را در صف نگه دارید و پس از جمع‌آوری فراداده‌ی بعدی، برچسب را دوباره پردازش کنید. برچسب را تا زمان اتمام پردازش در صف نگه دارید.

  4. بعد از اینکه TagSegment ایجاد کردید، از ویژگی ad_break_id به عنوان کلید برای یافتن شیء AdBreak در متادیتای تبلیغ ad_breaks استفاده کنید.

    مثال زیر یک شیء AdBreak را پیدا می‌کند:

    {
  "type":"mid",
  "duration":15,
  "ads":1
}

  5. از داده‌های TagSegment و AdBreak برای نمایش اطلاعات مربوط به موقعیت تبلیغ در متن تبلیغ استفاده کنید. برای مثال، Ad 1 of 3 .

ارسال پینگ‌های تأیید رسانه

برای هر رویداد تبلیغاتی، به جز نوع progress ، یک پینگ تأیید رسانه ارسال کنید. Google DAI رویدادهای progress نادیده می‌گیرد و ارسال مکرر این رویدادها ممکن است بر عملکرد برنامه شما تأثیر بگذارد.

برای تولید URL تأیید رسانه کامل یک رویداد تبلیغاتی، موارد زیر را انجام دهید:

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

  2. یک درخواست GET با URL کامل ارسال کنید: 

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

    در صورت موفقیت، کد وضعیت 202 دریافت می‌کنید. در غیر این صورت، کد خطای 404 دریافت خواهید کرد.

شما می‌توانید از ابزار نظارت بر فعالیت پخش زنده (SAM) برای بررسی گزارش تاریخچه‌ی تمام رویدادهای تبلیغاتی استفاده کنید. برای جزئیات بیشتر، به بخش نظارت و عیب‌یابی پخش زنده مراجعه کنید.

،

این راهنما، توسعه یک برنامه کلاینت برای بارگذاری پخش زنده HLS یا DASH با API سرویس‌دهی Pod و کنترل‌کننده مانیفست شما را پوشش می‌دهد.

پیش‌نیازها

قبل از ادامه، باید موارد زیر را داشته باشید:

  • یک کلید دارایی سفارشی برای یک رویداد پخش زنده که با نوع DAI Pod serving redirect پیکربندی شده است. برای دریافت این کلید، مراحل زیر را دنبال کنید:

  • بررسی کنید که آیا SDK تبلیغات رسانه‌ای تعاملی (IMA) برای پلتفرم شما در دسترس است یا خیر. ما استفاده از IMA SDK را برای افزایش درآمد توصیه می‌کنیم. برای جزئیات بیشتر، به تنظیم IMA SDK برای DAI مراجعه کنید.

درخواست پخش جریانی بدهید

وقتی کاربر شما یک جریان را انتخاب می‌کند، موارد زیر را انجام دهید:

  1. یک درخواست POST به متد سرویس پخش زنده ارسال کنید. برای جزئیات بیشتر، به Method: stream مراجعه کنید.

  2. پارامترهای هدف‌گیری تبلیغات را در قالب‌های application/x-www-form-urlencoded یا application/json ارسال کنید. این درخواست یک جلسه پخش جریانی را در Google DAI ثبت می‌کند.

    مثال زیر یک درخواست جریان ایجاد می‌کند:

    کدگذاری فرم 

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

    رمزگذاری JSON 

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

    در صورت موفقیت، خروجی مشابه زیر را مشاهده خواهید کرد:

    {
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

  3. در پاسخ JSON، شناسه جلسه جریان را پیدا کنید و سایر داده‌ها را برای مراحل بعدی ذخیره کنید.

فراداده‌های تبلیغات نظرسنجی

برای نظرسنجی در مورد متادیتای تبلیغات، موارد زیر را انجام دهید:

  1. مقدار metadata_url را از پاسخ ثبت جریان (stream registration response) بخوانید.

  2. یک درخواست اولیه GET به نقطه پایانی metadata_url ارسال کنید.

    • پارامتر کوئری delta_token حذف کنید. این فرآیند به سرور اجازه می‌دهد تا فراداده کامل مربوط به پنجره ضبط‌کننده ویدیوی دیجیتال (DVR) مربوط به پخش زنده را برگرداند. پنجره DVR شامل بازه زمانی پخش موجود برای بیننده جهت عقب و جلو بردن و پخش مجدد است. پاسخ شامل یک فیلد next_delta_token است.

  3. برای بهینه‌سازی پهنای باند، مقدار next_delta_token را از جدیدترین پاسخ ذخیره کنید.

  4. در درخواست بعدی خود، آن مقدار را به عنوان پارامتر کوئری delta_token ارسال کنید. سرور فقط فراداده‌هایی را که از زمان تولید آن توکن تغییر کرده‌اند، برمی‌گرداند. همیشه آخرین توکنی را که دریافت کرده‌اید ارسال کنید. سعی نکنید توکن را تجزیه، اصلاح یا بسازید. برای جزئیات بیشتر، به Method: metadata مراجعه کنید.

    مثال زیر متادیتای تبلیغات را دریافت می‌کند:

    // Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

    در صورت موفقیت، پاسخ PodMetadata را دریافت می‌کنید. اگر پارامتر delta_token را وارد کنید، پاسخ فقط شامل تبلیغات، وقفه‌های تبلیغاتی و برچسب‌هایی است که سرور از زمان تولید توکن توسط سرور اضافه یا به‌روزرسانی کرده است. پاسخ همچنین حاوی مقدار جدید next_delta_token است. اگر هرگونه وقفه تبلیغاتی قدیمی باشد، پاسخ شامل لیست obsolete_ad_break_ids از وقفه‌های تبلیغاتی برای حذف از حافظه پنهان شما نیز می‌شود.

    {
  "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
  "obsolete_ad_break_ids": ["0003069407"],
  "tags":{
    "google_1022389921":{
      "ad":"0003069408_ad1",
      "ad_break_id":"0003069408",
      "type":"start"
    },
    ...
  },
  "ads":{
    "0003069408_ad1":{
      "ad_break_id":"0003069408",
      "position":1,
      "duration":10.01,
      "title":"External - Pod Midroll 1",
      "clickthrough_url":"https://.../",
      ...
    },
    ...
  },
  "ad_breaks":{
    "0003069408":{
      "type":"mid",
      "duration":30,
      "ads":3
    },
    ...
  }
}

  5. شیء tags را ذخیره کنید و به‌روزرسانی‌ها را در حافظه پنهان محلی خود ادغام کنید. اگر پارامتر obsolete_ad_break_ids وجود دارد، آن وقفه‌های تبلیغاتی و تبلیغات و برچسب‌های مرتبط را از حافظه پنهان خود حذف کنید.

  6. با استفاده از مقدار polling_frequency یک تایمر تنظیم کنید تا مرتباً فراداده درخواست شود. در هر نظرسنجی، مقدار next_delta_token برگردانده شده در جدیدترین پاسخ فراداده را به عنوان پارامتر پرس و جوی delta_token ارسال کنید.

پخش جریانی را در پخش‌کننده ویدیوی خود بارگذاری کنید

بعد از اینکه شناسه جلسه را از پاسخ ثبت نام دریافت کردید، شناسه را به کنترل‌کننده مانیفست خود منتقل کنید، یا یک URL مانیفست برای بارگذاری جریان در یک پخش‌کننده ویدیو بسازید.

برای ارسال شناسه جلسه، به مستندات دستکاری‌کننده مانیفست خود مراجعه کنید. اگر یک دستکاری‌کننده مانیفست ایجاد می‌کنید، برای پخش زنده به Manifest manipulator مراجعه کنید.

مثال زیر یک URL مانیفست را مونتاژ می‌کند:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

وقتی پخش‌کننده شما آماده شد، پخش را شروع کنید.

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

قالب کانتینر جریان خود را برای ابرداده زمان‌بندی‌شده بررسی کنید:

  • جریان‌های HLS با کانتینرهای Transport Stream (TS) از برچسب‌های ID3 زمان‌بندی‌شده برای حمل فراداده‌های زمان‌بندی‌شده استفاده می‌کنند. برای جزئیات بیشتر، به «درباره قالب برنامه رسانه‌ای مشترک با HTTP Live Streaming (HLS)» مراجعه کنید.

  • جریان‌های DASH از عناصر EventStream برای مشخص کردن رویدادها در مانیفست استفاده می‌کنند.

  • جریان‌های DASH از عناصر InbandEventStream استفاده می‌کنند، زمانی که بخش‌ها حاوی کادرهای پیام رویداد ( emsg ) برای داده‌های بار داده، از جمله برچسب‌های ID3، باشند. برای جزئیات بیشتر، به InbandEventStream مراجعه کنید.

  • جریان‌های CMAF، شامل DASH و HLS، از جعبه‌های emsg حاوی برچسب‌های ID3 استفاده می‌کنند.

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

برای بازیابی شناسه رویداد تبلیغ از برچسب‌های ID3، موارد زیر را انجام دهید:

  1. رویدادها را بر اساس scheme_id_uri با urn:google:dai:2018 یا https://aomedia.org/emsg/ID3 فیلتر کنید.

  2. آرایه بایت را از فیلد message_data استخراج کن.

    مثال زیر داده‌های emsg را به JSON رمزگشایی می‌کند:

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

  3. تگ‌های ID3 را با فرمت TXXXgoogle_{ad_event_ID} فیلتر کنید:

    TXXXgoogle_1022389921

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

برای یافتن شیء TagSegment ، مراحل زیر را انجام دهید:

  1. شیء tags مربوط به متادیتای تبلیغات را از متادیتای تبلیغات Poll بازیابی کنید. شیء tags آرایه‌ای از اشیاء TagSegment است.

  2. از شناسه کامل رویداد تبلیغ برای یافتن یک شیء TagSegment با نوع progress استفاده کنید.

  3. از ۱۷ کاراکتر اول شناسه رویداد تبلیغ برای یافتن یک شیء TagSegment از انواع دیگر استفاده کنید.

    از آنجا که برنامه‌ی کلاینت شما به صورت دوره‌ای فراداده‌های تبلیغاتی را جمع‌آوری می‌کند، ممکن است بین زمانی که پخش‌کننده‌ی ویدیوی شما با یک برچسب ID3 در جریان مواجه می‌شود و زمانی که فراداده‌ی مرتبط در دسترس قرار می‌گیرد، تأخیری رخ دهد. اگر برنامه‌ی کلاینت شما برچسب ID3 را در برچسب‌های ذخیره‌شده پیدا نکرد، برچسب را در صف نگه دارید و پس از جمع‌آوری فراداده‌ی بعدی، برچسب را دوباره پردازش کنید. برچسب را تا زمان اتمام پردازش در صف نگه دارید.

  4. بعد از اینکه TagSegment ایجاد کردید، از ویژگی ad_break_id به عنوان کلید برای یافتن شیء AdBreak در متادیتای تبلیغ ad_breaks استفاده کنید.

    مثال زیر یک شیء AdBreak را پیدا می‌کند:

    {
  "type":"mid",
  "duration":15,
  "ads":1
}

  5. از داده‌های TagSegment و AdBreak برای نمایش اطلاعات مربوط به موقعیت تبلیغ در متن تبلیغ استفاده کنید. برای مثال، Ad 1 of 3 .

ارسال پینگ‌های تأیید رسانه

برای هر رویداد تبلیغاتی، به جز نوع progress ، یک پینگ تأیید رسانه ارسال کنید. Google DAI رویدادهای progress نادیده می‌گیرد و ارسال مکرر این رویدادها ممکن است بر عملکرد برنامه شما تأثیر بگذارد.

برای تولید URL تأیید رسانه کامل یک رویداد تبلیغاتی، موارد زیر را انجام دهید:

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

  2. یک درخواست GET با URL کامل ارسال کنید: 

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

    در صورت موفقیت، کد وضعیت 202 دریافت می‌کنید. در غیر این صورت، کد خطای 404 دریافت خواهید کرد.

شما می‌توانید از ابزار نظارت بر فعالیت پخش زنده (SAM) برای بررسی گزارش تاریخچه‌ی تمام رویدادهای تبلیغاتی استفاده کنید. برای جزئیات بیشتر، به بخش نظارت و عیب‌یابی پخش زنده مراجعه کنید.

،

این راهنما، توسعه یک برنامه کلاینت برای بارگذاری پخش زنده HLS یا DASH با API سرویس‌دهی Pod و کنترل‌کننده مانیفست شما را پوشش می‌دهد.

پیش‌نیازها

قبل از ادامه، باید موارد زیر را داشته باشید:

  • یک کلید دارایی سفارشی برای یک رویداد پخش زنده که با نوع DAI Pod serving redirect پیکربندی شده است. برای دریافت این کلید، مراحل زیر را دنبال کنید:

  • بررسی کنید که آیا SDK تبلیغات رسانه‌ای تعاملی (IMA) برای پلتفرم شما در دسترس است یا خیر. ما استفاده از IMA SDK را برای افزایش درآمد توصیه می‌کنیم. برای جزئیات بیشتر، به تنظیم IMA SDK برای DAI مراجعه کنید.

درخواست پخش جریانی بدهید

وقتی کاربر شما یک جریان را انتخاب می‌کند، موارد زیر را انجام دهید:

  1. یک درخواست POST به متد سرویس پخش زنده ارسال کنید. برای جزئیات بیشتر، به Method: stream مراجعه کنید.

  2. پارامترهای هدف‌گیری تبلیغات را در قالب‌های application/x-www-form-urlencoded یا application/json ارسال کنید. این درخواست یک جلسه پخش جریانی را در Google DAI ثبت می‌کند.

    مثال زیر یک درخواست جریان ایجاد می‌کند:

    کدگذاری فرم 

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

    رمزگذاری JSON 

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

    در صورت موفقیت، خروجی مشابه زیر را مشاهده خواهید کرد:

    {
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

  3. در پاسخ JSON، شناسه جلسه جریان را پیدا کنید و سایر داده‌ها را برای مراحل بعدی ذخیره کنید.

فراداده‌های تبلیغات نظرسنجی

برای نظرسنجی در مورد متادیتای تبلیغات، موارد زیر را انجام دهید:

  1. مقدار metadata_url را از پاسخ ثبت جریان (stream registration response) بخوانید.

  2. یک درخواست اولیه GET به نقطه پایانی metadata_url ارسال کنید.

    • پارامتر کوئری delta_token حذف کنید. این فرآیند به سرور اجازه می‌دهد تا فراداده کامل مربوط به پنجره ضبط‌کننده ویدیوی دیجیتال (DVR) مربوط به پخش زنده را برگرداند. پنجره DVR شامل بازه زمانی پخش موجود برای بیننده جهت عقب و جلو بردن و پخش مجدد است. پاسخ شامل یک فیلد next_delta_token است.

  3. برای بهینه‌سازی پهنای باند، مقدار next_delta_token را از جدیدترین پاسخ ذخیره کنید.

  4. در درخواست بعدی خود، آن مقدار را به عنوان پارامتر کوئری delta_token ارسال کنید. سرور فقط فراداده‌هایی را که از زمان تولید آن توکن تغییر کرده‌اند، برمی‌گرداند. همیشه آخرین توکنی را که دریافت کرده‌اید ارسال کنید. سعی نکنید توکن را تجزیه، اصلاح یا بسازید. برای جزئیات بیشتر، به Method: metadata مراجعه کنید.

    مثال زیر متادیتای تبلیغات را دریافت می‌کند:

    // Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

    در صورت موفقیت، پاسخ PodMetadata را دریافت می‌کنید. اگر پارامتر delta_token را وارد کنید، پاسخ فقط شامل تبلیغات، وقفه‌های تبلیغاتی و برچسب‌هایی است که سرور از زمان تولید توکن توسط سرور اضافه یا به‌روزرسانی کرده است. پاسخ همچنین حاوی مقدار جدید next_delta_token است. اگر هرگونه وقفه تبلیغاتی قدیمی باشد، پاسخ شامل لیست obsolete_ad_break_ids از وقفه‌های تبلیغاتی برای حذف از حافظه پنهان شما نیز می‌شود.

    {
  "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
  "obsolete_ad_break_ids": ["0003069407"],
  "tags":{
    "google_1022389921":{
      "ad":"0003069408_ad1",
      "ad_break_id":"0003069408",
      "type":"start"
    },
    ...
  },
  "ads":{
    "0003069408_ad1":{
      "ad_break_id":"0003069408",
      "position":1,
      "duration":10.01,
      "title":"External - Pod Midroll 1",
      "clickthrough_url":"https://.../",
      ...
    },
    ...
  },
  "ad_breaks":{
    "0003069408":{
      "type":"mid",
      "duration":30,
      "ads":3
    },
    ...
  }
}

  5. شیء tags را ذخیره کنید و به‌روزرسانی‌ها را در حافظه پنهان محلی خود ادغام کنید. اگر پارامتر obsolete_ad_break_ids وجود دارد، آن وقفه‌های تبلیغاتی و تبلیغات و برچسب‌های مرتبط را از حافظه پنهان خود حذف کنید.

  6. با استفاده از مقدار polling_frequency یک تایمر تنظیم کنید تا مرتباً فراداده درخواست شود. در هر نظرسنجی، مقدار next_delta_token برگردانده شده در جدیدترین پاسخ فراداده را به عنوان پارامتر پرس و جوی delta_token ارسال کنید.

پخش جریانی را در پخش‌کننده ویدیوی خود بارگذاری کنید

بعد از اینکه شناسه جلسه را از پاسخ ثبت نام دریافت کردید، شناسه را به کنترل‌کننده مانیفست خود منتقل کنید، یا یک URL مانیفست برای بارگذاری جریان در یک پخش‌کننده ویدیو بسازید.

برای ارسال شناسه جلسه، به مستندات دستکاری‌کننده مانیفست خود مراجعه کنید. اگر یک دستکاری‌کننده مانیفست ایجاد می‌کنید، برای پخش زنده به Manifest manipulator مراجعه کنید.

مثال زیر یک URL مانیفست را مونتاژ می‌کند:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

وقتی پخش‌کننده شما آماده شد، پخش را شروع کنید.

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

قالب کانتینر جریان خود را برای ابرداده زمان‌بندی‌شده بررسی کنید:

  • جریان‌های HLS با کانتینرهای Transport Stream (TS) از برچسب‌های ID3 زمان‌بندی‌شده برای حمل فراداده‌های زمان‌بندی‌شده استفاده می‌کنند. برای جزئیات بیشتر، به «درباره قالب برنامه رسانه‌ای مشترک با HTTP Live Streaming (HLS)» مراجعه کنید.

  • جریان‌های DASH از عناصر EventStream برای مشخص کردن رویدادها در مانیفست استفاده می‌کنند.

  • جریان‌های DASH از عناصر InbandEventStream استفاده می‌کنند، زمانی که بخش‌ها حاوی کادرهای پیام رویداد ( emsg ) برای داده‌های بار داده، از جمله برچسب‌های ID3، باشند. برای جزئیات بیشتر، به InbandEventStream مراجعه کنید.

  • جریان‌های CMAF، شامل DASH و HLS، از جعبه‌های emsg حاوی برچسب‌های ID3 استفاده می‌کنند.

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

برای بازیابی شناسه رویداد تبلیغ از برچسب‌های ID3، موارد زیر را انجام دهید:

  1. رویدادها را بر اساس scheme_id_uri با urn:google:dai:2018 یا https://aomedia.org/emsg/ID3 فیلتر کنید.

  2. آرایه بایت را از فیلد message_data استخراج کن.

    مثال زیر داده‌های emsg را به JSON رمزگشایی می‌کند:

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

  3. تگ‌های ID3 را با فرمت TXXXgoogle_{ad_event_ID} فیلتر کنید:

    TXXXgoogle_1022389921

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

برای یافتن شیء TagSegment ، مراحل زیر را انجام دهید:

  1. شیء tags مربوط به متادیتای تبلیغات را از متادیتای تبلیغات Poll بازیابی کنید. شیء tags آرایه‌ای از اشیاء TagSegment است.

  2. از شناسه کامل رویداد تبلیغ برای یافتن یک شیء TagSegment با نوع progress استفاده کنید.

  3. از ۱۷ کاراکتر اول شناسه رویداد تبلیغ برای یافتن یک شیء TagSegment از انواع دیگر استفاده کنید.

    از آنجا که برنامه‌ی کلاینت شما به صورت دوره‌ای فراداده‌های تبلیغاتی را جمع‌آوری می‌کند، ممکن است بین زمانی که پخش‌کننده‌ی ویدیوی شما با یک برچسب ID3 در جریان مواجه می‌شود و زمانی که فراداده‌ی مرتبط در دسترس قرار می‌گیرد، تأخیری رخ دهد. اگر برنامه‌ی کلاینت شما برچسب ID3 را در برچسب‌های ذخیره‌شده پیدا نکرد، برچسب را در صف نگه دارید و پس از جمع‌آوری فراداده‌ی بعدی، برچسب را دوباره پردازش کنید. برچسب را تا زمان اتمام پردازش در صف نگه دارید.

  4. بعد از اینکه TagSegment ایجاد کردید، از ویژگی ad_break_id به عنوان کلید برای یافتن شیء AdBreak در متادیتای تبلیغ ad_breaks استفاده کنید.

    مثال زیر یک شیء AdBreak را پیدا می‌کند:

    {
  "type":"mid",
  "duration":15,
  "ads":1
}

  5. از داده‌های TagSegment و AdBreak برای نمایش اطلاعات مربوط به موقعیت تبلیغ در متن تبلیغ استفاده کنید. برای مثال، Ad 1 of 3 .

ارسال پینگ‌های تأیید رسانه

برای هر رویداد تبلیغاتی، به جز نوع progress ، یک پینگ تأیید رسانه ارسال کنید. Google DAI رویدادهای progress نادیده می‌گیرد و ارسال مکرر این رویدادها ممکن است بر عملکرد برنامه شما تأثیر بگذارد.

برای تولید URL تأیید رسانه کامل یک رویداد تبلیغاتی، موارد زیر را انجام دهید:

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

  2. یک درخواست GET با URL کامل ارسال کنید: 

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

    در صورت موفقیت، کد وضعیت 202 دریافت می‌کنید. در غیر این صورت، کد خطای 404 دریافت خواهید کرد.

شما می‌توانید از ابزار نظارت بر فعالیت پخش زنده (SAM) برای بررسی گزارش تاریخچه‌ی تمام رویدادهای تبلیغاتی استفاده کنید. برای جزئیات بیشتر، به بخش نظارت و عیب‌یابی پخش زنده مراجعه کنید.