Menyiapkan klien untuk pengalihan penayangan pod

Panduan ini membahas pengembangan aplikasi klien untuk memuat livestream HLS atau DASH dengan Pod serving API dan penyesuai manifes Anda.

Prasyarat

Sebelum melanjutkan, Anda harus memiliki hal berikut:

Membuat permintaan streaming

Saat pengguna memilih streaming, lakukan hal berikut:

  1. Buat permintaan POST ke metode layanan livestream. Untuk mengetahui detailnya, lihat Metode: stream.

  2. Teruskan parameter penargetan iklan dalam format application/x-www-form-urlencoded atau application/json. Permintaan ini mendaftarkan sesi streaming ke DAI Google.

    Contoh berikut membuat permintaan streaming:

    Encoding formulir

    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());
    

    Encoding 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());
    

    Jika berhasil, Anda akan melihat output yang mirip dengan berikut ini:

    {
    "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. Dalam respons JSON, temukan ID sesi streaming dan simpan data lainnya untuk langkah berikutnya.

Metadata iklan polling

Untuk melakukan polling metadata iklan, lakukan tindakan berikut:

  1. Baca nilai metadata_url dari respons pendaftaran streaming.

  2. Buat permintaan GET awal ke endpoint metadata_url.

    • Hilangkan parameter kueri delta_token. Proses ini memungkinkan server menampilkan metadata lengkap untuk jendela Perekam Video Digital (DVR) streaming. Jendela DVR berisi jangka waktu siaran yang tersedia untuk diputar ulang dan diputar oleh penonton. Respons mencakup kolom next_delta_token.
  3. Untuk mengoptimalkan bandwidth, simpan nilai next_delta_token dari respons terbaru.

  4. Pada permintaan berikutnya, kirim nilai tersebut sebagai parameter kueri delta_token. Server hanya menampilkan metadata yang berubah sejak token tersebut dibuat. Selalu kirim token terbaru yang Anda terima. Jangan mencoba mengurai, mengubah, atau membuat token. Untuk mengetahui detailnya, lihat Metode: metadata.

    Contoh berikut mengambil metadata iklan:

    // 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;
    }
    

    Jika berhasil, Anda akan menerima respons PodMetadata. Jika Anda memberikan parameter delta_token, respons hanya akan berisi iklan, jeda iklan, dan tag yang ditambahkan atau diperbarui server sejak server membuat token. Respons juga berisi nilai next_delta_token baru. Jika ada jeda iklan yang sudah tidak berlaku, respons juga akan menyertakan daftar obsolete_ad_break_ids jeda iklan yang akan dihapus dari cache Anda.

    {
      "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. Simpan objek tags dan gabungkan update ke dalam cache lokal Anda. Jika parameter obsolete_ad_break_ids ada, hapus jeda iklan tersebut serta iklan dan tag terkait dari cache Anda.

  6. Tetapkan timer menggunakan nilai polling_frequency untuk meminta metadata secara rutin. Dalam setiap polling, kirim nilai next_delta_token yang ditampilkan dalam respons metadata terbaru sebagai parameter kueri delta_token.

Memuat streaming ke pemutar video Anda

Setelah Anda memiliki ID sesi dari respons pendaftaran, teruskan ID tersebut ke penyesuai manifes, atau buat URL manifes untuk memuat streaming ke pemutar video.

Untuk meneruskan ID sesi, lihat dokumentasi penyesuai manifes Anda. Jika Anda mengembangkan penyesuai manifes, lihat Penyesuai manifes untuk livestream.

Contoh berikut menyusun URL manifes:

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

Saat pemutar Anda siap, mulai pemutaran.

Memproses peristiwa iklan

Periksa format penampung streaming Anda untuk metadata berjangka waktu:

  • Streaming HLS dengan penampung Transport Stream (TS) menggunakan tag ID3 berjangka waktu untuk membawa metadata berjangka waktu. Untuk mengetahui detailnya, lihat Tentang Common Media Application Format dengan HTTP Live Streaming (HLS).

  • Streaming DASH menggunakan elemen EventStream untuk menentukan peristiwa dalam manifes.

  • Streaming DASH menggunakan elemen InbandEventStream saat segmen berisi kotak Pesan Peristiwa (emsg) untuk data payload, termasuk tag ID3. Untuk mengetahui detailnya, lihat InbandEventStream.

  • Streaming CMAF, termasuk DASH dan HLS, menggunakan kotak emsg yang berisi tag ID3.

Untuk mengambil tag ID3 dari streaming Anda, lihat panduan pemutar video Anda. Untuk mengetahui detailnya, lihat Panduan menangani metadata berjangka waktu

Untuk mengambil ID peristiwa iklan dari tag ID3, lakukan tindakan berikut:

  1. Filter peristiwa menurut scheme_id_uri dengan urn:google:dai:2018 atau https://aomedia.org/emsg/ID3.
  2. Ekstrak array byte dari kolom message_data.

    Contoh berikut mendekode data emsg menjadi JSON:

    {
      "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
      "presentation_time": 27554,
      "timescale": 1000,
      "message_data": "ID3TXXXgoogle_1022389921",
      ...
    }
    
  3. Filter tag ID3 dengan format TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921
    

Menampilkan data peristiwa iklan

Untuk menemukan objek TagSegment, lakukan hal berikut:

  1. Ambil objek metadata iklan tags dari Polling metadata iklan. Objek tags adalah array objek TagSegment.

  2. Gunakan ID peristiwa iklan lengkap untuk menemukan objek TagSegment dengan jenis progress.

  3. Gunakan 17 karakter pertama ID peristiwa iklan untuk menemukan objek TagSegment dari jenis lain.

    Karena aplikasi klien Anda melakukan polling metadata iklan secara berkala, mungkin akan terjadi keterlambatan antara saat pemutar video menemukan tag ID3 dalam streaming dan saat metadata terkait tersedia. Jika aplikasi klien Anda tidak menemukan tag ID3 dalam tag yang disimpan, simpan tag dalam antrean dan proses ulang tag setelah polling metadata berikutnya. Pertahankan tag dalam antrean hingga pemrosesan selesai.

  4. Setelah Anda memiliki TagSegment, gunakan properti ad_break_id sebagai kunci untuk menemukan objek AdBreak dalam objek ad_breaks metadata iklan.

    Contoh berikut menemukan objek AdBreak:

    {
      "type":"mid",
      "duration":15,
      "ads":1
    }
    
  5. Gunakan data TagSegment dan AdBreak untuk menampilkan informasi tentang posisi iklan dalam jeda iklan. Misalnya, Ad 1 of 3.

Mengirim ping verifikasi media

Untuk setiap peristiwa iklan, kecuali jenis progress, kirim ping verifikasi media. DAI Google menghapus peristiwa progress, dan sering mengirim peristiwa ini dapat memengaruhi performa aplikasi Anda.

Untuk membuat URL verifikasi media lengkap dari peristiwa iklan, lakukan hal berikut:

  1. Dari respons streaming, tambahkan ID peristiwa iklan lengkap ke nilai media_verification_url.

  2. Buat permintaan GET dengan URL lengkap:

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

    Jika berhasil, Anda akan menerima respons status kode 202. Jika tidak, Anda akan menerima kode error 404.

Anda dapat menggunakan Pemantauan Aktivitas Streaming (SAM) untuk memeriksa log historis semua peristiwa iklan. Untuk mengetahui detailnya, lihat memantau dan memecahkan masalah livestream