آماده کردن مشتری برای بازهدایت ارائه پاد

این راهنما توسعه برنامه کارخواه را برای بار کردن جاری‌سازی زنده HLS یا DASH با میانای برنامه‌سازی کاربردی Pod serving و دستکاری‌کننده مانیفست شما پوشش می‌دهد.

پیش‌نیازها

پیش‌از ادامه دادن، باید موارد زیر را داشته باشید:

درخواست جاری‌سازی

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

  1. درخواست POST به روش سرویس جاری‌سازی زنده ارسال کنید. برای جزئیات، روش: جاری‌سازی را ببینید.

  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 را از پاسخ ثبت جاری بخوانید.

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

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

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

    مثال زیر فراداده آگهی را واکشی می‌کند:

    // 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 ارسال کنید.

جاری‌سازی را در پخش‌کننده ویدیو بار کنید

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

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

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

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 زمان‌بندی‌شده برای حمل فراداده زمان‌بندی‌شده استفاده می‌کنند. برای جزئیات، درباره قالب برنامه رسانه مشترک با جاری‌سازی زنده اچ‌تی‌تی‌پی (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 را از فراداده آگهی نظرسنجی بازیابی کنید. شیء 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 را نادیده می‌گیرد و ارسال مکرر این رویدادها ممکن است بر عملکرد برنامه‌تان تأثیر بگذارد.

برای تولید نشانی وب کامل درستی‌سنجی رسانه برای رویداد آگهی، کارهای زیر را انجام دهید:

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

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

    // 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) برای بررسی گزارش سابقه همه رویدادهای آگهی استفاده کنید. برای جزئیات، به پایش و عیب‌یابی جاری‌سازی زنده مراجعه کنید.