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

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 ให้ทำตามขั้นตอนต่อไปนี้ ขั้นตอนต่อไปนี้

ส่งคำขอลงทะเบียนสตรีมไปยัง DAI Pod Serve API

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

ปลายทาง API

POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

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

{network_code} รหัสเครือข่าย Google Ad Manager 360
{custom_asset} ตัวระบุที่กำหนดเองซึ่งเชื่อมโยงกับเหตุการณ์นี้ใน Google Ad Manager

พารามิเตอร์เนื้อหาที่เข้ารหัสตามรูปแบบ

ชุดที่ไม่บังคับของการเข้ารหัสแบบฟอร์ม พารามิเตอร์การกำหนดเป้าหมาย

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 \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

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

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

ในกรณีที่เกิดข้อผิดพลาด ระบบจะส่งรหัสข้อผิดพลาด 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 ลงใน โปรแกรมเล่นวิดีโอและเริ่มเล่น

แบบสำรวจข้อมูลเมตาใหม่ของ AdBreak

แอปพลิเคชันมีหน้าที่เรียกข้อมูลเมตาสำหรับช่วงพักโฆษณาแต่ละครั้ง รู้ว่าจะต้องเรียกการแสดงผลใด ในการดำเนินการดังกล่าว คุณจะต้องตั้ง จับเวลาให้สำรวจ DAI API ของ metadata_url สำหรับโฆษณาใหม่เป็นประจำ ช่วงเวลาในการหยั่งสัญญาณที่ระบุไว้ใน polling_frequency ในการตอบกลับการลงทะเบียนสตรีม

คุณจะได้รับออบเจ็กต์ 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 รายการแรก ซ่อนการค้นหาของผู้เล่น ควบคุม และแสดงโฆษณาซ้อนทับที่อธิบายตำแหน่งปัจจุบันของโฆษณา break สำหรับการสอบ: "โฆษณา 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

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