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

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

คู่มือนี้แสดงวิธีโต้ตอบกับ Pod Feeds 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 Serve API ที่เกี่ยวข้อง

ปลายทาง API

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

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

{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/linear/pods/api/v1/network/21775744923/custom_asset/an-public-test-asset/stream

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

{
  "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 ระบบจะส่งเหตุการณ์เหล่านี้ในรูปแบบอีเมลในกลุ่มที่จำลองแท็ก 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",
  ...
}

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

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

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

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

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

HTTP/1.1 202 Accepted

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