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

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

ประเด็นสำคัญ: ก่อนที่จะพิจารณาใช้ API นี้ ให้ตรวจสอบว่ามี IMA อยู่แล้วหรือไม่ DAI SDK สำหรับแพลตฟอร์มที่คุณเลือก แนะนำให้ใช้ IMA DAI SDK บนแพลตฟอร์ม ในประเทศที่ให้บริการ Pod Serve API มีไว้เพื่อใช้ใน แพลตฟอร์มที่ไม่มี IMA DAI SDK

คู่มือนี้แสดงวิธีโต้ตอบกับ 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

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

{network_code}

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

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

targeting_parameters

ออบเจ็กต์ JSON ที่มีรหัสแหล่งที่มาของเนื้อหา (cmsid), รหัสวิดีโอ (vid) และ การกำหนดเป้าหมายโฆษณา พารามิเตอร์ ต้องระบุ

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":{"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 และจัดเก็บค่าที่เกี่ยวข้อง

เคล็ดลับ: URL ที่ระบุในการตอบกลับของ API อาจเปลี่ยนแปลงได้โดยไม่ต้อง ประกาศ ดังนั้น ให้ใช้ URL ตามที่ระบุไว้ในการตอบกลับ API แทน สร้างขึ้นมาเอง วิธีนี้จะช่วยให้มั่นใจได้ว่าโค้ดของคุณจะทำงานต่อไปได้ ได้อย่างถูกต้องเมื่อ URL เปลี่ยนแปลง

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

เคล็ดลับ: ไม่ควรส่งเหตุการณ์โฆษณาประเภท progress ไปยัง Ad Manager เหล่านี้ มีขึ้นเพื่อแจ้งแอปโปรแกรมเล่นวิดีโอของไคลเอ็นต์ว่าช่วงพักโฆษณา ซึ่งเล่นในสถานการณ์ที่อาจไม่ได้รับเหตุการณ์เริ่มต้น ตัวอย่างเช่น หากผู้ใช้ค้นหาตำแหน่งหรือเริ่มเล่นที่ตำแหน่งที่เฉพาะเจาะจง การประทับเวลาที่อยู่ระหว่างโฆษณา ผู้ใช้จะไม่ได้รับเหตุการณ์เริ่มต้น เหตุการณ์ความคืบหน้าที่ส่งไปยัง Ad Manager จะถูกทิ้ง ซึ่งอาจส่งผลในทางลบ ประสิทธิภาพของแอปเลย

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

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

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

HTTP/1.1 202 Accepted

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

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