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

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

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

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

  • คีย์ชิ้นงานที่กำหนดเองสำหรับกิจกรรมไลฟ์สดที่กำหนดค่าด้วยประเภท DAI Pod serving redirect หากต้องการรับคีย์นี้ ให้ทำตามขั้นตอนต่อไปนี้

  • ตรวจสอบว่า SDK โฆษณาสื่ออินเทอร์แอกทีฟ (IMA) พร้อมใช้งานสำหรับแพลตฟอร์มของคุณหรือไม่ เราขอแนะนำให้ใช้ IMA SDK เพื่อเพิ่มรายได้ โปรดดูรายละเอียดที่หัวข้อตั้งค่า IMA SDK สำหรับ DAI

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

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

  1. ส่งคำขอ POST ไปยังเมธอดบริการไลฟ์สด โปรดดูรายละเอียดที่หัวข้อเมธอด: stream

  2. ส่งพารามิเตอร์การกำหนดเป้าหมายโฆษณาในรูปแบบ application/x-www-form-urlencoded หรือ application/json คำขอนี้จะลงทะเบียนเซสชันสตรีมกับ DAI ของ Google

    ตัวอย่างต่อไปนี้จะสร้างคำขอสตรีม

    การเข้ารหัสแบบฟอร์ม

    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 ที่กำหนดเวลาเพื่อส่งข้อมูลเมตาที่กำหนดเวลา โปรดดูรายละเอียดที่หัวข้อเกี่ยวกับ Common Media Application Format ที่มี 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 ออบเจ็กต์จากข้อมูลเมตาของโฆษณาแบบสำรวจ ออบเจ็กต์ 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 ยืนยันสื่อ

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