IMA SDK टूल सेट अप करना

प्लैटफ़ॉर्म चुनें: HTML5 Android iOS tvOS

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

इस गाइड में, IMA SDK टूल को किसी सामान्य वीडियो प्लेयर ऐप्लिकेशन में इंटिग्रेट करने का तरीका बताया गया है. अगर आपको इंटिग्रेशन का पूरा सैंपल देखना है या उसके साथ-साथ इंटिग्रेट करना है, तो GitHub से सामान्य उदाहरण डाउनलोड करें. अगर आपको ऐसा HTML5 प्लेयर चाहिए जिसमें SDK टूल पहले से इंटिग्रेट हो, तो Video.js के लिए IMA SDK प्लग इन देखें.

IMA क्लाइंट-साइड की खास जानकारी

IMA क्लाइंट-साइड को लागू करने के लिए, SDK टूल के चार मुख्य कॉम्पोनेंट की ज़रूरत होती है. इनके बारे में इस गाइड में बताया गया है:

  • AdDisplayContainer: यह एक कंटेनर ऑब्जेक्ट है. इससे यह तय होता है कि IMA, विज्ञापन यूज़र इंटरफ़ेस (यूआई) के एलिमेंट कहां रेंडर करता है और विज्ञापन दिखने से जुड़े आंकड़े कहां मेज़र करता है, इसमें ऐक्टिव व्यू और ओपन मेज़रमेंट शामिल हैं.
  • AdsLoader: यह एक ऑब्जेक्ट है, जो विज्ञापनों का अनुरोध करता है और विज्ञापन अनुरोध के जवाबों से जुड़े इवेंट मैनेज करता है. आपको सिर्फ़ एक विज्ञापन लोडर को इंस्टैंशिएट करना चाहिए. इसका इस्तेमाल, ऐप्लिकेशन के पूरे लाइफ़साइकल में किया जा सकता है.
  • AdsRequest: यह एक ऑब्जेक्ट है, जो विज्ञापन अनुरोध को तय करता है. विज्ञापन अनुरोधों में, वीएएसटी विज्ञापन टैग का यूआरएल और अतिरिक्त पैरामीटर तय किए जाते हैं. जैसे, विज्ञापन के डाइमेंशन.
  • AdsManager: यह एक ऑब्जेक्ट है, जिसमें विज्ञापन अनुरोध का जवाब शामिल होता है. यह विज्ञापन चलाने की सुविधा को कंट्रोल करता है. साथ ही, SDK टूल से ट्रिगर होने वाले विज्ञापन इवेंट को सुनता है.

ज़रूरी शर्तें

शुरू करने से पहले, आपके पास ये चीज़ें होनी चाहिए:

  • तीन खाली फ़ाइलें:
    • index.html
    • style.css
    • ads.js
  • आपके कंप्यूटर पर Python इंस्टॉल होना चाहिए या टेस्ट करने के लिए कोई वेब सर्वर होना चाहिए

1. डेवलपमेंट सर्वर शुरू करना

IMA SDK टूल, डिपेंडेंसी लोड करने के लिए उसी प्रोटोकॉल का इस्तेमाल करता है जिससे पेज लोड होता है, इसलिए, आपको अपने ऐप्लिकेशन की जांच करने के लिए, वेब सर्वर का इस्तेमाल करना होगा. स्थानीय डेवलपमेंट सर्वर शुरू करने का सबसे आसान तरीका है कि Python के बिल्ट-इन सर्वर का इस्तेमाल किया जाए.

  1. कमांड लाइन का इस्तेमाल करके, उस डायरेक्ट्री से यह कमांड चलाएं जिसमें आपकी index.html फ़ाइल मौजूद है: 
      python -m http.server 8000
  2. वेब ब्राउज़र में, http://localhost:8000/ पर जाएं

किसी अन्य वेब सर्वर का भी इस्तेमाल किया जा सकता है. जैसे, Apache HTTP Server.

2. सामान्य वीडियो प्लेयर बनाना

सबसे पहले, index.html में बदलाव करके, रैपिंग एलिमेंट में शामिल एक सामान्य HTML5 वीडियो एलिमेंट बनाएं. साथ ही, वीडियो चलाने के लिए एक बटन बनाएं. यहां दिए गए उदाहरण में, IMA SDK टूल इंपोर्ट किया गया है और AdDisplayContainer कंटेनर एलिमेंट सेट अप किया गया है. ज़्यादा जानकारी के लिए, क्रमशः IMA SDK टूल इंपोर्ट करना और विज्ञापन कंटेनर बनाना से जुड़े चरण देखें. 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});

style.css और ads.js फ़ाइलें लोड करने के लिए, ज़रूरी टैग जोड़ें. इसके बाद, styles.css में बदलाव करके, वीडियो प्लेयर को मोबाइल डिवाइसों के लिए रिस्पॉन्सिव बनाएं. आखिर में, ads.js में अपने वैरिएबल तय करें और 'चलाएं' बटन पर क्लिक करने पर, वीडियो चलाना शुरू करें.

ध्यान दें कि ads.js कोड स्निपेट में setUpIMA() को कॉल किया गया है. इसकी परिभाषा, AdsLoader को शुरू करना और विज्ञापन अनुरोध करना सेक्शन में दी गई है.

3. IMA SDK टूल इंपोर्ट करना

इसके बाद, index.html में ads.js के टैग से पहले, स्क्रिप्ट टैग का इस्तेमाल करके IMA फ़्रेमवर्क जोड़ें. 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

4. विज्ञापन कंटेनर बनाना

ज़्यादातर ब्राउज़र में, IMA SDK टूल, विज्ञापनों और विज्ञापन से जुड़े यूज़र इंटरफ़ेस (यूआई) के एलिमेंट, दोनों को दिखाने के लिए, विज्ञापन कंटेनर एलिमेंट का इस्तेमाल करता है. इस कंटेनर का साइज़ ऐसा होना चाहिए कि यह वीडियो एलिमेंट को ऊपर-बाईं ओर से ओवरले करे. इस कंटेनर में दिखाए जाने वाले विज्ञापनों की ऊंचाई और चौड़ाई, adsManager ऑब्जेक्ट से सेट होती है. इसलिए, आपको इन वैल्यू को मैन्युअल तरीके से सेट करने की ज़रूरत नहीं होती.

विज्ञापन कंटेनर एलिमेंट को लागू करने के लिए, सबसे पहले एक नया div video-container एलिमेंट में बनाएं. इसके बाद, सीएसएस को अपडेट करके, एलिमेंट को ऊपर-बाईं ओर रखें video-element. आखिर में, नया विज्ञापन कंटेनर div इस्तेमाल करके, AdDisplayContainer ऑब्जेक्ट बनाने के लिए, createAdDisplayContainer() फ़ंक्शन जोड़ें. 

<div id="adContainer"></div>
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}

5. AdsLoader को शुरू करना और विज्ञापन अनुरोध करना

विज्ञापनों का अनुरोध करने के लिए, एक AdsLoader इंस्टेंस बनाएं. AdsLoader कंस्ट्रक्टर, इनपुट के तौर पर AdDisplayContainer ऑब्जेक्ट लेता है. इसका इस्तेमाल, तय किए गए विज्ञापन टैग यूआरएल से जुड़े AdsRequest ऑब्जेक्ट को प्रोसेस करने के लिए किया जा सकता है. इस उदाहरण में इस्तेमाल किए गए विज्ञापन टैग में, 10 सेकंड का प्री-रोल विज्ञापन शामिल है. IMA वीडियो सुइट इंस्पेक्टर का इस्तेमाल करके, इस या किसी भी विज्ञापन टैग यूआरएल की जांच की जा सकती है.

सबसे सही तरीका यह है कि किसी पेज के पूरे लाइफ़साइकल के लिए, AdsLoader का सिर्फ़ एक इंस्टेंस बनाए रखें. अतिरिक्त विज्ञापन अनुरोध करने के लिए, नया AdsRequest ऑब्जेक्ट बनाएं, लेकिन उसी AdsLoader का फिर से इस्तेमाल करें. ज़्यादा जानकारी के लिए, IMA SDK टूल के अक्सर पूछे जाने वाले सवाल देखें.

AdsLoader.addEventListener का इस्तेमाल करके, लोड किए गए विज्ञापनों और गड़बड़ी वाले इवेंट को सुनें और उनका जवाब दें. इन इवेंट को सुनें:

  • ADS_MANAGER_LOADED
  • AD_ERROR

onAdsManagerLoaded() और onAdError() लिसनर बनाने के लिए, यह उदाहरण देखें: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&' +
      'output=vast&unviewed_position_start=1&env=vp&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}

6. AdsLoader इवेंट का जवाब देना

जब AdsLoader विज्ञापन लोड कर लेता है, तो ADS_MANAGER_LOADED इवेंट ट्रिगर होता है. ऑब्जेक्ट को शुरू करने के लिए, कॉलबैक को पास किए गए इवेंट को पार्स करें.AdsManager AdsManager विज्ञापन टैग यूआरएल के जवाब के मुताबिक, अलग-अलग विज्ञापन लोड करता है.

पक्का करें कि लोड करने की प्रोसेस के दौरान होने वाली गड़बड़ियों को ठीक किया जाए. अगर विज्ञापन लोड नहीं होते हैं, तो पक्का करें कि मीडिया चलाने की सुविधा, विज्ञापनों के बिना जारी रहे. इससे उपयोगकर्ता के कॉन्टेंट देखने में कोई रुकावट नहीं आएगी. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}

onAdsManagerLoaded() फ़ंक्शन में सेट किए गए लिसनर के बारे में ज़्यादा जानकारी के लिए, ये सब-सेक्शन देखें:

AdsManager की गड़बड़ियां ठीक करना

AdsLoader के लिए बनाया गया गड़बड़ी हैंडलर, AdsManager के लिए भी गड़बड़ी हैंडलर के तौर पर काम कर सकता है. onAdError() फ़ंक्शन का फिर से इस्तेमाल करने वाला इवेंट हैंडलर देखें. 

adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);

वीडियो चलाने और रोकने से जुड़े इवेंट मैनेज करना

जब AdsManager विज्ञापन दिखाने के लिए तैयार होता है, तो वह CONTENT_PAUSE_REQUESTED इवेंट ट्रिगर करता है. इस इवेंट को मैनेज करने के लिए, वीडियो प्लेयर को रोकें. इसी तरह, जब कोई विज्ञापन पूरा हो जाता है, तो AdsManager CONTENT_RESUME_REQUESTED इवेंट ट्रिगर करता है. इस इवेंट को मैनेज करने के लिए, कॉन्टेंट वीडियो को फिर से चलाएं. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);

onContentPauseRequested() और onContentResumeRequested() फ़ंक्शन की परिभाषाओं के लिए, यह उदाहरण देखें: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}

नॉन-लीनियर विज्ञापनों के दौरान कॉन्टेंट चलाने की सुविधा मैनेज करना

जब कोई विज्ञापन चलने के लिए तैयार होता है, तो AdsManager, कॉन्टेंट वीडियो को रोक देता है. हालांकि, यह व्यवहार नॉन-लीनियर विज्ञापनों के लिए लागू नहीं होता. इनमें विज्ञापन दिखाए जाने के दौरान, कॉन्टेंट चलता रहता है और विज्ञापन दिखाया जाता है. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);

नॉन-लीनियर विज्ञापनों के लिए, AdsManager से LOADED इवेंट ट्रिगर होने का इंतज़ार करें. देखें कि विज्ञापन लीनियर है या नहीं. अगर नहीं है, तो वीडियो एलिमेंट पर वीडियो चलाना जारी रखें.

onAdLoaded() फ़ंक्शन की परिभाषा के लिए, यह उदाहरण देखें. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}

7. मोबाइल डिवाइसों पर, क्लिक करने पर वीडियो रोकने की सुविधा ट्रिगर करना

चूंकि AdContainer वीडियो एलिमेंट को ओवरले करता है, इसलिए उपयोगकर्ता अंतर्निहित प्लेयर के साथ सीधे इंटरैक्ट नहीं कर सकते. इससे मोबाइल डिवाइसों पर उपयोगकर्ता उलझन में पड़ सकते हैं, क्योंकि वे वीडियो प्लेयर पर टैप करके वीडियो रोकने की उम्मीद करते हैं. इस समस्या को हल करने के लिए, IMA SDK टूल, विज्ञापन ओवरले से IMA SDK टूल के ज़रिए मैनेज न किए जाने वाले सभी क्लिक, AdContainer एलिमेंट को पास करता है. यहां इन्हें मैनेज किया जा सकता है. यह सुविधा, मोबाइल के अलावा अन्य ब्राउज़र पर दिखने वाले लीनियर विज्ञापनों के लिए लागू नहीं होती. ऐसा इसलिए, क्योंकि विज्ञापन पर क्लिक करने से क्लिकथ्रू लिंक खुल जाता है.

क्लिक करने पर वीडियो रोकने की सुविधा लागू करने के लिए, विंडो लोड लिसनर में कॉल किया गया adContainerClick() क्लिक हैंडलर फ़ंक्शन जोड़ें. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}

8. AdsManager शुरू करना

विज्ञापन चलाने के लिए, AdsManager को शुरू करें. मोबाइल ब्राउज़र के लिए, जहां विज्ञापन अपने-आप नहीं चलाए जा सकते, वहां विज्ञापन चलाने की सुविधा को ट्रिगर करने के लिए, पेज के साथ उपयोगकर्ता के इंटरैक्शन का इस्तेमाल करें. जैसे, 'चलाएं' बटन पर क्लिक करना. 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}

9. वीडियो प्लेयर का साइज़ बदलने की सुविधा देना

विज्ञापनों का साइज़ डाइनैमिक तरीके से बदलने और वीडियो प्लेयर के साइज़ के मुताबिक होने या स्क्रीन ओरिएंटेशन में होने वाले बदलावों के मुताबिक होने के लिए, विंडो के साइज़ में बदलाव से जुड़े इवेंट के जवाब में, adsManager.resize() को कॉल करें. 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});

बस इतना ही! अब IMA SDK टूल की मदद से, विज्ञापनों का अनुरोध किया जा सकता है और उन्हें दिखाया जा सकता है. एसडीके टूल की ज़्यादा बेहतर सुविधाओं के बारे में जानने के लिए, अन्य गाइड या GitHub पर मौजूद सैंपल देखें.