แอปโปรแกรมเล่นวิดีโอของไคลเอ็นต์สำหรับสตรีม VOD

Google DAI Pod Serving API ช่วยให้คุณทำการแทรกโฆษณาฝั่งเซิร์ฟเวอร์ที่ขับเคลื่อนโดย Google Ads ได้ในขณะที่ยังคงควบคุมการต่อวิดีโอของคุณเอง

คู่มือนี้จะแสดงวิธีโต้ตอบกับ Pod Serving API และทําให้ฟังก์ชันการทํางานคล้ายกับ IMA DAI SDK หากมีคำถามเฉพาะเกี่ยวกับฟังก์ชันการทำงานที่รองรับ โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าของ Google

Pod Serving API รองรับสตรีมที่ให้บริการพ็อดในโปรโตคอลสตรีมมิง HLS หรือ MPEG-DASH คู่มือนี้มุ่งเน้นที่สตรีม HLS และไฮไลต์ความแตกต่างที่สำคัญระหว่าง HLS กับ MPEG-DASH ในขั้นตอนต่างๆ

หากต้องการผสานรวม Pod Serving API เข้ากับแอปสำหรับสตรีม VOD ให้ทำตามขั้นตอนต่อไปนี้

ส่งคําขอลงทะเบียนสตรีมไปยัง Ad Manager

ส่งคำขอ POST ไปยังปลายทางการลงทะเบียนสตรีม จากนั้นคุณจะได้รับคําตอบ JSON ที่มีรหัสสตรีมเพื่อส่งไปยังเซิร์ฟเวอร์การจัดการไฟล์ Manifest และปลายทาง Pod Serving API ที่เชื่อมโยง

ปลายทาง API

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

พารามิเตอร์เส้นทาง

{network_code} รหัสเครือข่าย Google Ad Manager 360

พารามิเตอร์ของเนื้อหา JSON

targeting_parameters ออบเจ็กต์ JSON ที่มีพารามิเตอร์การกำหนดเป้าหมายโฆษณา ต้องระบุ

JSON ของคำตอบ

media_verification_url URL พื้นฐานสําหรับการ ping เหตุการณ์การติดตามการเล่น URL การยืนยันสื่อที่สมบูรณ์จะสร้างขึ้นโดยการต่อท้ายรหัสเหตุการณ์โฆษณาไปยัง URL พื้นฐานนี้
metadata_url URL เพื่อขอข้อมูลเมตาของพ็อดโฆษณา
stream_id สตริงที่ใช้ระบุเซสชันสตรีมปัจจุบัน
valid_for ระยะเวลาที่เหลือจนกว่าเซสชันสตรีมปัจจุบันจะหมดอายุในรูปแบบ dhms (วัน ชั่วโมง นาที วินาที) ตัวอย่างเช่น 2h0m0.000s แสดงระยะเวลา 2 ชั่วโมง
valid_until เวลาที่เเซสชันสตรีมปัจจุบันหมดอายุในรูปแบบสตริงวันที่และเวลา ISO 8601 ในyyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm

ตัวอย่างคำขอ (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

ตัวอย่างการตอบกลับ

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

ในกรณีที่เกิดข้อผิดพลาด ระบบจะแสดงรหัสข้อผิดพลาด HTTP มาตรฐานโดยไม่มีเนื้อหาการตอบกลับ JSON

แยกวิเคราะห์การตอบกลับ JSON และจัดเก็บค่าที่เกี่ยวข้อง

ขอไฟล์ Manifest ของสตรีมจากเครื่องมือจัดการไฟล์ Manifest

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

โดยทั่วไป คุณต้องส่งรหัสสตรีมที่ปลายทางการลงทะเบียนด้านบนแสดงผลไปยังเครื่องมือจัดการไฟล์ Manifest เพื่อให้สร้างไฟล์ Manifest สำหรับเซสชันที่เฉพาะเจาะจง การตอบกลับคําขอไฟล์ Manifest จะเป็นสตรีมวิดีโอที่มีทั้งเนื้อหาและโฆษณา เว้นแต่ว่าเครื่องมือจัดการไฟล์ Manifest จะระบุไว้อย่างชัดเจน

ตัวอย่างคำขอ (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

ตัวอย่างการตอบกลับ (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

เล่นสตรีม

โหลดไฟล์ Manifest ที่ได้รับจากเซิร์ฟเวอร์การจัดการไฟล์ Manifest ลงในวิดีโอเพลเยอร์แล้วเริ่มเล่น

ขอข้อมูลเมตาของพ็อดโฆษณาจาก Ad Manager

ส่งคำขอ GET ไปยัง metadata_url ที่คุณได้รับในขั้นตอนที่ 1 ขั้นตอนนี้ต้องเกิดขึ้นหลังจากที่คุณได้รับไฟล์ Manifest ที่ต่อกันจากเครื่องมือจัดการไฟล์ Manifest ในทางกลับกัน คุณจะได้รับออบเจ็กต์ JSON ที่มีพารามิเตอร์ต่อไปนี้

tags ชุดคู่คีย์-ค่าที่มีเหตุการณ์โฆษณาทั้งหมดที่ปรากฏในสตรีม คีย์คืออักขระ 17 ตัวแรกของรหัสเหตุการณ์โฆษณาที่ปรากฏในข้อมูลเมตาแบบกำหนดเวลาของสตรีม หรือในกรณีที่เป็นเหตุการณ์ประเภท progress จะเป็นรหัสเหตุการณ์โฆษณาแบบเต็ม

ค่าแต่ละค่าคือออบเจ็กต์ที่มีพารามิเตอร์ต่อไปนี้

ad รหัสของโฆษณาที่ตรงกับคีย์ในออบเจ็กต์ ads
ad_break_id รหัสของช่วงพักโฆษณาที่ตรงกับคีย์ในออบเจ็กต์ ad_breaks
type ประเภทเหตุการณ์โฆษณา ประเภทเหตุการณ์โฆษณามีดังนี้
start เริ่มทํางานในช่วงต้นของโฆษณา
firstquartile เริ่มทํางานเมื่อสิ้นสุดควอร์ไทล์แรก
midpoint เริ่มทํางานเมื่อโฆษณาเล่นถึงครึ่งทาง
thirdquartile เริ่มทํางานเมื่อสิ้นสุดควอร์ไทล์ที่ 3
complete เริ่มทํางานเมื่อโฆษณาสิ้นสุด
progress เริ่มทํางานเป็นระยะๆ ตลอดทั้งโฆษณาเพื่อแจ้งให้แอปทราบว่ากําลังเล่นช่วงพักโฆษณา
ads ชุดคู่คีย์-ค่าที่อธิบายโฆษณาทั้งหมดที่ปรากฏในสตรีม คีย์คือรหัสโฆษณาที่ตรงกับค่าที่พบในออบเจ็กต์ tags ที่ระบุไว้ด้านบน ค่าแต่ละค่าคือออบเจ็กต์ที่มีพารามิเตอร์ต่อไปนี้
ad_break_id รหัสของช่วงพักโฆษณาที่ตรงกับคีย์ในออบเจ็กต์ ad_breaks
position ตําแหน่งที่โฆษณานี้ปรากฏภายในชุดโฆษณาในช่วงพักโฆษณาเป็นวินาทีทศนิยม
duration ความยาวของโฆษณาเป็นวินาทีแบบทศนิยม
clickthrough_url URL ที่ควรเปิดขึ้นเมื่อผู้ใช้โต้ตอบกับโฆษณานี้ หากรองรับ
ad_breaks ชุดคู่คีย์-ค่าที่อธิบายช่วงพักโฆษณาทั้งหมดที่ปรากฏในสตรีม คีย์คือรหัสช่วงพักโฆษณาที่ตรงกับค่าที่พบในออบเจ็กต์ tags และ ads ที่ระบุไว้ด้านบน ค่าแต่ละค่าคือออบเจ็กต์ที่มีพารามิเตอร์ต่อไปนี้
type ประเภทของช่วงพักโฆษณา ประเภทช่วงพักโฆษณา ได้แก่ pre (โฆษณาตอนต้น) mid (โฆษณาตอนกลาง) และpost (โฆษณาตอนท้าย)
duration ระยะเวลาของช่วงพักโฆษณาเป็นวินาทีแบบทศนิยม
ads จํานวนโฆษณาในช่วงพักโฆษณานี้

จัดเก็บค่าเหล่านี้เพื่อเชื่อมโยงกับเหตุการณ์ข้อมูลเมตาตามเวลาภายในสตรีมวิดีโอ

ตัวอย่างคำขอ (cURL)

curl https://dai.google.com/.../metadata

ตัวอย่างการตอบกลับ

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

รอรับเหตุการณ์โฆษณา

ฟังข้อมูลเมตาที่ตั้งเวลาไว้ผ่านเหตุการณ์โฆษณาที่ทริกเกอร์ในสตรีมเสียง/วิดีโอของวิดีโอเพลเยอร์

สำหรับสตรีม MPEG-TS ข้อมูลเมตาจะปรากฏเป็นแท็ก ID3 v2.3 ในแบนด์ แท็กข้อมูลเมตาแต่ละแท็กจะมีรหัส TXXX และค่าจะขึ้นต้นด้วยสตริง google_ ตามด้วยชุดอักขระ ค่านี้คือรหัสเหตุการณ์โฆษณา

XXX ใน TXXX ไม่ใช่ตัวยึดตําแหน่ง สตริง TXXX คือรหัสแท็ก ID3 ที่สงวนไว้สำหรับ "ข้อความที่ผู้ใช้กำหนด"

ตัวอย่างแท็ก ID3

TXXXgoogle_1234567890123456789

สำหรับสตรีม MP4 ระบบจะส่งข้อมูลเหล่านี้เป็นเหตุการณ์ emsg ในแบนด์ที่จำลองแท็ก ID3 v2.3 กล่องข้อความ emsg ที่เกี่ยวข้องแต่ละกล่องมีค่า scheme_id_uri เท่ากับ https://aomedia.org/emsg/ID3 หรือ https://developer.apple.com/streaming/emsg-id3 และมีค่า message_data ที่ขึ้นต้นด้วย ID3TXXXgoogle_ ค่า message_data นี้ที่ไม่มีส่วนนำหน้า ID3TXXX คือรหัสเหตุการณ์โฆษณา

ตัวอย่างกล่องข้อความอีเมล

โครงสร้างข้อมูลอาจแตกต่างกันไปโดยขึ้นอยู่กับคลังโปรแกรมเล่นสื่อ

หากรหัสเหตุการณ์โฆษณาคือ google_1234567890123456789 การตอบกลับจะมีลักษณะดังนี้ 

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

ไลบรารีโปรแกรมเล่นสื่อบางรายการจะแสดงเหตุการณ์ emsg ที่จำลองแท็ก ID3 เป็นแท็ก ID3 ดั้งเดิมโดยอัตโนมัติ ในกรณีนี้ สตรีม MP4 จะแสดงแท็ก ID3 เหมือนกับ MPEG_TS

อัปเดต UI ของแอปโปรแกรมเล่นวิดีโอไคลเอ็นต์

รหัสเหตุการณ์โฆษณาแต่ละรายการจะจับคู่กับคีย์ในแออบเจ็กต์ tags จากขั้นตอนที่ 4 ได้ การจับคู่ค่าเหล่านี้เป็นกระบวนการ 2 ขั้นตอน ดังนี้

  1. ตรวจสอบออบเจ็กต์ tags เพื่อหาคีย์ที่ตรงกับรหัสเหตุการณ์โฆษณาแบบเต็ม หากพบรายการที่ตรงกัน ให้ดึงข้อมูลประเภทเหตุการณ์และออบเจ็กต์ ad และ ad_break ที่เกี่ยวข้อง เหตุการณ์เหล่านี้ควรมีประเภทเป็น progress

    หากไม่พบรายการที่ตรงกันสําหรับรหัสเหตุการณ์โฆษณาแบบเต็ม ให้ตรวจสอบtags ออบเจ็กต์เพื่อหาคีย์ที่ตรงกับอักขระ 17 ตัวแรกของรหัสเหตุการณ์โฆษณา ดึงข้อมูลประเภทเหตุการณ์และออบเจ็กต์ ad และ ad_break ที่เชื่อมโยง ซึ่งจะดึงข้อมูลเหตุการณ์ทั้งหมดที่มีประเภทอื่นที่ไม่ใช่ progress

  2. ใช้ข้อมูลที่ดึงมานี้เพื่ออัปเดต UI ของโปรแกรมเล่น ตัวอย่างเช่น เมื่อคุณได้รับเหตุการณ์ start หรือ progress รายการแรก ให้ซ่อนตัวควบคุมการกรอของโปรแกรมเล่นและแสดงการวางซ้อนที่อธิบายตําแหน่งของโฆษณาปัจจุบันในช่วงพักโฆษณา เช่น "โฆษณา 1 จาก 3"

ตัวอย่างรหัสเหตุการณ์โฆษณา

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

ตัวอย่างออบเจ็กต์แท็ก

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

ส่งการแจ้งเตือนการยืนยันสื่อ

คุณต้องส่งคําสั่ง ping การยืนยันสื่อไปยัง Ad Manager ทุกครั้งที่ได้รับเหตุการณ์โฆษณาที่มีประเภทอื่นนอกเหนือจาก progress

หากต้องการสร้าง URL การยืนยันสื่อที่สมบูรณ์ของเหตุการณ์โฆษณา ให้ใส่รหัสเหตุการณ์โฆษณาแบบเต็มต่อท้ายค่า media_verification_url จากคำตอบการลงทะเบียนสตรีม

ส่งคําขอ GET ด้วย URL แบบเต็ม หากคำขอยืนยันสำเร็จ คุณจะได้รับคำตอบ HTTP ที่มีรหัสสถานะ 202 ไม่เช่นนั้น คุณจะได้รับรหัสข้อผิดพลาด HTTP 404

ตัวอย่างคำขอ (cURL)

curl https://{...}/media/google_5555555555123456789

ตัวอย่างการตอบกลับที่สำเร็จ

HTTP/1.1 202 Accepted

แหล่งข้อมูลเพิ่มเติม