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

این راهنما، توسعه یک برنامه کلاینت برای بارگذاری پخش زنده 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": "8d2b2292-6356-4c0e-94be-cece01d2df2e: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 به نقطه پایانی ارسال کنید. برای جزئیات بیشتر، به Method: metadata مراجعه کنید.

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

    const response = await fetch(metadata_url);
console.log(await response.json());

    در صورت موفقیت، پاسخ PodMetadata را برای وقفه‌های تبلیغاتی فعلی و آینده دریافت خواهید کرد:

    {
  "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
    },
    ...
  }
}

  3. شیء tags را برای مراحل بعدی ذخیره کنید.

  4. با استفاده از مقدار polling_frequency یک تایمر تنظیم کنید تا به طور منظم برای همه وقفه‌های تبلیغاتی متوالی، فراداده درخواست کند.

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

بعد از اینکه شناسه جلسه را از پاسخ ثبت نام دریافت کردید، شناسه را به کنترل‌کننده مانیفست خود منتقل کنید، یا یک 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_1234567890123456789",
  ...
}

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

    TXXXgoogle_1234567890123456789

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

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

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

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

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

  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_5555555555123456789`;

const response = await fetch(completeUrl);

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

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