เตรียมไคลเอ็นต์สำหรับการเปลี่ยนเส้นทางการแสดงพ็อด

คู่มือนี้ครอบคลุมการพัฒนาแอปพลิเคชันไคลเอ็นต์เพื่อโหลดไลฟ์สด HLS หรือ DASH ด้วย Pod Serving API และตัวจัดการไฟล์ Manifest

ข้อกำหนดเบื้องต้น

คุณต้องมีสิ่งต่อไปนี้ก่อนดำเนินการต่อ

ส่งคำขอสตรีม

เมื่อผู้ใช้เลือกสตรีม ให้ทำดังนี้

  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 จากการตอบกลับการลงทะเบียนสตรีม

  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

โหลดสตรีมลงในวิดีโอเพลเยอร์

หลังจากได้รหัสเซสชันจากการตอบกลับการลงทะเบียนแล้ว ให้ส่งรหัสไปยัง เครื่องมือจัดการไฟล์ Manifest หรือสร้าง URL ของไฟล์ Manifest เพื่อโหลดสตรีมลงใน วิดีโอเพลเยอร์

หากต้องการส่งรหัสเซสชัน โปรดดูเอกสารประกอบของเครื่องมือจัดการ Manifest หากคุณ พัฒนาเครื่องมือจัดการไฟล์ Manifest โปรดดูเครื่องมือจัดการไฟล์ Manifest สำหรับ ไลฟ์สด

ตัวอย่างต่อไปนี้จะประกอบ URL ของไฟล์ Manifest

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 เพื่อระบุเหตุการณ์ในไฟล์ Manifest

  • สตรีม 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 ad metadata ออบเจ็กต์ tags คืออาร์เรย์ของออบเจ็กต์ TagSegment

  2. ใช้รหัสเหตุการณ์โฆษณาแบบเต็มเพื่อค้นหาออบเจ็กต์ TagSegment ที่มีประเภท progress

  3. ใช้ 17 อักขระแรกของรหัสเหตุการณ์โฆษณาเพื่อค้นหาออบเจ็กต์ 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

ส่งการ Ping เพื่อยืนยันสื่อ

สําหรับเหตุการณ์โฆษณาทุกรายการ ยกเว้นprogressประเภท ให้ส่งการปิงการยืนยันสื่อ DAI ของ Google จะทิ้งเหตุการณ์ 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) เพื่อตรวจสอบบันทึกประวัติของเหตุการณ์โฆษณาทั้งหมดได้ โปรดดูรายละเอียดที่หัวข้อตรวจสอบและแก้ปัญหาไลฟ์สด