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

(SSAI) สำหรับสตรีม VOD ที่มี API การแสดงพ็อดการแทรกโฆษณาแบบไดนามิก (DAI) ของ Google

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 คือรหัสเหตุการณ์โฆษณา

ตัวอย่างกล่อง emsg

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

หากรหัสเหตุการณ์โฆษณาคือ 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

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