वीओडी स्ट्रीम के लिए क्लाइंट वीडियो प्लेयर ऐप्लिकेशन

Google डीएआई पॉड सर्विंग एपीआई की मदद से, Google Ads की मदद से सर्वर-साइड पर विज्ञापन डाला जा सकता है. साथ ही, वीडियो स्टिचिंग को कंट्रोल किया जा सकता है.

इस गाइड में, पॉड सर्विंग एपीआई से इंटरैक्ट करने और IMA डीएआई SDK से मिलती-जुलती सुविधाएं पाने का तरीका बताया गया है. काम करने वाली सुविधाओं के बारे में खास सवालों के लिए, अपने Google खाता मैनेजर से संपर्क करें.

पॉड सर्विंग एपीआई, HLS या MPEG-DASH स्ट्रीमिंग प्रोटोकॉल में, पॉड सेवा स्ट्रीम के साथ काम करता है. इस गाइड में HLS स्ट्रीम पर फ़ोकस किया गया है. साथ ही, खास चरणों में HLS और MPEG-DASH के बीच के मुख्य अंतर को हाइलाइट किया गया है.

वीओडी स्ट्रीम के लिए अपने ऐप्लिकेशन में पॉड सर्विंग एपीआई को इंटिग्रेट करने के लिए, यह तरीका अपनाएं:

Ad Manager से स्ट्रीम के लिए रजिस्ट्रेशन का अनुरोध करें

स्ट्रीम के रजिस्ट्रेशन एंडपॉइंट पर पोस्ट अनुरोध करें. इसके बदले में, आपको एक JSON रिस्पॉन्स मिलता है, जिसमें स्ट्रीम आईडी शामिल होता है. इसे आपके मेनिफ़ेस्ट में बदलाव करने वाले सर्वर और उससे जुड़े पॉड सर्विंग एपीआई एंडपॉइंट पर भेजा जाता है.

एपीआई एंडपॉइंट

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 प्लेबैक ट्रैकिंग इवेंट को पिंग करने के लिए बेस यूआरएल. इस बेस यूआरएल में विज्ञापन इवेंट आईडी जोड़कर, मीडिया की पुष्टि करने वाला एक पूरा यूआरएल बनाया जाता है.
metadata_url विज्ञापन के पॉड के मेटाडेटा के लिए अनुरोध करने का यूआरएल.
stream_id मौजूदा स्ट्रीम सेशन की पहचान करने के लिए इस्तेमाल की जाने वाली स्ट्रिंग.
valid_for मौजूदा स्ट्रीम सेशन के खत्म होने में बचा समय, dhms (दिन, घंटे, मिनट, सेकंड) फ़ॉर्मैट में है. उदाहरण के लिए, 2h0m0.000s, दो घंटे की अवधि दिखाता है.
valid_until वह समय जब मौजूदा स्ट्रीम सेशन खत्म होगा, yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm फ़ॉर्मैट में ISO 8601 तारीख और समय की स्ट्रिंग के तौर पर.

अनुरोध का उदाहरण (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"
}

गड़बड़ियां होने पर, स्टैंडर्ड एचटीटीपी गड़बड़ी कोड, JSON रिस्पॉन्स बॉडी के बिना लौटाए जाते हैं.

JSON के रिस्पॉन्स को पार्स करें और काम की वैल्यू सेव करें.

मेनिफ़ेस्ट मेनिफ़ेस्ट से स्ट्रीम मेनिफ़ेस्ट का अनुरोध करें

हर मेनिफ़ेस्ट में बदलाव करने वाले टूल का अनुरोध और रिस्पॉन्स फ़ॉर्मैट अलग-अलग होता है. मैनिप्यूलेशन की सेवा देने वाली कंपनी की खास ज़रूरतों को समझने के लिए, उनसे संपर्क करें. अगर खुद का मेनिफ़ेस्ट मैन्युफ़ैक्चरर लागू किया जा रहा है, तो इस कॉम्पोनेंट की ज़रूरी शर्तों को समझने के लिए, मेनिफ़ेस्ट मैनिफ़ेस्टर गाइड पढ़ें.

आम तौर पर, सेशन के हिसाब से अलग-अलग मेनिफ़ेस्ट बनाने के लिए, आपको ऊपर दिए गए रजिस्ट्रेशन एंडपॉइंट से मिले स्ट्रीम आईडी को, अपने मेनिफ़ेस्ट में बदलाव करने वाले टूल में पास करना होगा. जब तक कि मेनिफ़ेस्ट फ़ाइल में बदलाव करने वाले ने साफ़ तौर पर जानकारी न दी हो, तब तक आपके मेनिफ़ेस्ट के अनुरोध का जवाब एक वीडियो स्ट्रीम होगा. इसमें कॉन्टेंट और विज्ञापन, दोनों शामिल होंगे.

अनुरोध का उदाहरण (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

स्ट्रीम चलाएं

मेनिफ़ेस्ट में फ़ेरबदल करने वाले सर्वर से मिले मेनिफ़ेस्ट को वीडियो प्लेयर में लोड करें और वीडियो चलाना शुरू करें.

Ad Manager से विज्ञापनों के पॉड के मेटाडेटा का अनुरोध करें

पहले चरण में metadata_url पर GET का अनुरोध करें. यह चरण तब पूरा होना चाहिए, जब आपको अपने मेनिफ़ेस्ट मैन्युफ़ैक्चरर से सिले हुए मेनिफ़ेस्ट मिल गए हों. इससे आपको एक JSON ऑब्जेक्ट मिलता है, जिसमें ये पैरामीटर शामिल होते हैं:

tags स्ट्रीम में दिखने वाले सभी विज्ञापन इवेंट वाले की-वैल्यू पेयर का सेट. कुंजियां, किसी विज्ञापन इवेंट आईडी के पहले 17 वर्ण होती हैं, जो स्ट्रीम के तय समय वाले मेटाडेटा में दिखती हैं. इसके अलावा, progress तरह के इवेंट के मामले में, पूरा विज्ञापन इवेंट आईडी दिखता है.

हर वैल्यू एक ऑब्जेक्ट है, जिसमें ये पैरामीटर मौजूद होते हैं:

ad ऐसे विज्ञापन का आईडी जो ads ऑब्जेक्ट में मौजूद किसी कुंजी से मेल खाता है.
ad_break_id विज्ञापन के लिए ऐसे ब्रेक का आईडी जो ad_breaks ऑब्जेक्ट में किसी कुंजी से मेल खाता है.
type विज्ञापन इवेंट का टाइप. विज्ञापन इवेंट के टाइप:
start विज्ञापन की शुरुआत में सक्रिय होता है.
firstquartile पहले क्वार्टाइल के आखिर में सक्रिय होता है.
midpoint विज्ञापन के बीच में ही सक्रिय होता है.
thirdquartile तीसरे क्वार्टाइल के आखिर में सक्रिय होता है.
complete विज्ञापन के आखिर में सक्रिय होता है.
progress इसे पूरे विज्ञापन के दौरान समय-समय पर चालू किया जाता है, ताकि ऐप्लिकेशन को यह सूचना दी जा सके कि विज्ञापन के लिए ब्रेक चल रहा है.
ads स्ट्रीम में दिखने वाले सभी विज्ञापनों की जानकारी देने वाले की-वैल्यू पेयर का सेट. कुंजियां, ऐसे विज्ञापन आईडी होते हैं जो ऊपर दिए गए tags ऑब्जेक्ट में मौजूद वैल्यू से मैच करते हैं. हर वैल्यू एक ऑब्जेक्ट है, जिसमें ये पैरामीटर मौजूद होते हैं:
ad_break_id विज्ञापन के लिए ऐसे ब्रेक का आईडी जो ad_breaks ऑब्जेक्ट में किसी कुंजी से मेल खाता है.
position विज्ञापन ब्रेक में मौजूद विज्ञापनों के सेट में, फ़्लोटिंग पॉइंट सेकंड में वह पोज़िशन जिस पर यह विज्ञापन दिखता है.
duration फ़्लोटिंग पॉइंट सेकंड में विज्ञापन की लंबाई.
clickthrough_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-टीएस स्ट्रीम के लिए, मेटाडेटा इन-बैंड आईडी3 v2.3 टैग के तौर पर दिखता है. हर मेटाडेटा टैग का आईडी TXXX होता है और वैल्यू की शुरुआत google_ स्ट्रिंग से होती है और उसके बाद वर्णों की एक सीरीज़ होती है. यह वैल्यू विज्ञापन इवेंट आईडी है.

TXXX में XXX, प्लेसहोल्डर नहीं है. स्ट्रिंग TXXX, ID3 टैग आईडी है. इसे "उपयोगकर्ता के तय किए गए टेक्स्ट" के लिए रिज़र्व किया गया है.

आईडी3 टैग का उदाहरण

TXXXgoogle_1234567890123456789

MP4 स्ट्रीम के लिए, इन्हें इन-बैंड मैसेज इवेंट के तौर पर भेजा जाता है, जो ID3 v2.3 टैग को एम्युलेट करते हैं. काम के हर मैसेज के बॉक्स की scheme_id_uri वैल्यू, https://aomedia.org/emsg/ID3 या https://developer.apple.com/streaming/emsg-id3 होती है. साथ ही, ID3TXXXgoogle_ से शुरू होने वाली message_data वैल्यू होती है. ID3TXXX प्रीफ़िक्स के बिना, message_data की यह वैल्यू विज्ञापन इवेंट आईडी है.

मैसेज बॉक्स का उदाहरण

डेटा स्ट्रक्चर, आपके मीडिया प्लेयर की लाइब्रेरी के आधार पर अलग-अलग हो सकता है.

अगर विज्ञापन इवेंट आईडी google_1234567890123456789 है, तो रिस्पॉन्स ऐसा दिखेगा:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

कुछ मीडिया प्लेयर लाइब्रेरी अपने-आप ईमेल इवेंट पेश करती हैं, जो आईडी3 टैग को नेटिव आईडी3 टैग के तौर पर एम्युलेट करते हैं. इस मामले में, MP4 स्ट्रीम, MPEG_TS के तौर पर एक जैसे आईडी3 टैग पेश करती हैं.

क्लाइंट वीडियो प्लेयर ऐप्लिकेशन का यूज़र इंटरफ़ेस (यूआई) अपडेट करना

हर विज्ञापन इवेंट आईडी को चौथे चरण में, tags ऑब्जेक्ट में मौजूद किसी कुंजी से मैच किया जा सकता है. इन वैल्यू का मिलान करने की प्रोसेस दो चरणों में होती है:

  1. पूरे विज्ञापन इवेंट आईडी से मैच करने वाली कुंजी के लिए, tags ऑब्जेक्ट देखें. अगर कोई मैच मिलता है, तो इवेंट टाइप और उससे जुड़े ad और ad_break ऑब्जेक्ट वापस लाएं. ये इवेंट, progress टाइप के होने चाहिए.

    अगर विज्ञापन इवेंट आईडी के पूरे आईडी से मैच नहीं होता है, तो विज्ञापन इवेंट आईडी के पहले 17 वर्णों से मेल खाने वाली कुंजी का पता लगाने के लिए, tags ऑब्जेक्ट की जांच करें. इवेंट टाइप और उससे जुड़े ad और ad_break ऑब्जेक्ट वापस लाएं. इससे, progress के अलावा अन्य टाइप के सभी इवेंट फिर से उपलब्ध होंगे.

  2. वापस लाई गई इस जानकारी का इस्तेमाल अपने प्लेयर के यूज़र इंटरफ़ेस (यूआई) को अपडेट करने के लिए करें. उदाहरण के लिए, जब आपको कोई start या पहला progress इवेंट मिलता है, तो अपने प्लेयर के सीक-कंट्रोल छिपाएं और विज्ञापन ब्रेक में मौजूदा विज्ञापन की स्थिति बताने वाला ओवरले दिखाएं. उदाहरण के लिए: "तीन में से 1 विज्ञापन".

विज्ञापन इवेंट आईडी के उदाहरण

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"
  },
  ...
}

मीडिया की पुष्टि के लिए पिंग भेजें

जब भी progress के अलावा किसी दूसरे प्रकार का विज्ञापन इवेंट मिलता है, तो Ad Manager को मीडिया की पुष्टि करने के लिए पिंग भेजना ज़रूरी है.

किसी विज्ञापन इवेंट की मीडिया की पुष्टि करने वाला पूरा यूआरएल जनरेट करने के लिए, स्ट्रीम के रजिस्ट्रेशन रिस्पॉन्स में मौजूद media_verification_url वैल्यू में पूरा विज्ञापन इवेंट आईडी जोड़ें.

पूरे यूआरएल के साथ जीईटी अनुरोध करें. अगर पुष्टि का अनुरोध स्वीकार कर लिया जाता है, तो आपको स्टेटस कोड 202 के साथ एचटीटीपी रिस्पॉन्स मिलता है. ऐसा न होने पर, आपको एचटीटीपी गड़बड़ी कोड 404 मिलेगा.

अनुरोध का उदाहरण (cURL)

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

कामयाब जवाब का उदाहरण

HTTP/1.1 202 Accepted

अन्य संसाधन