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

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

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

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

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

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

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

ปลายทาง API

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

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

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

JSON ของการตอบกลับ

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

curl -X POST \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -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 ที่มีรายการต่อไปนี้แทน ได้แก่

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

ตัวอย่างคำขอ (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 แท็กทั้งหมด. กล่องข้อความอีเมลที่เกี่ยวข้องแต่ละช่องจะมีค่า 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 ยืนยันสื่อ

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

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

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

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

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

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

HTTP/1.1 202 Accepted

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

• เอกสารเกี่ยวกับ IMA SDK
• ประเภทการใช้งานโปรแกรมเล่น DAI การเปรียบเทียบ