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

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

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

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

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

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

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

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

शुरू करने से पहले, आपको इनकी ज़रूरत होगी:

  • तीन खाली फ़ाइलें:
    • 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>

index.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;
}
style.css
 
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();
});
ads.js

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

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

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

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

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

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

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

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

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

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);
}
ads.js

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();
}
ads.js

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

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

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

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

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

जब 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);
ads.js

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();
}
ads.js

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

विज्ञापन दिखाने के लिए तैयार होने पर, AdsManager कॉन्टेंट वीडियो को रोक देता है. हालांकि, यह सुविधा नॉन-लीनियर विज्ञापनों के लिए काम नहीं करती. नॉन-लीनियर विज्ञापनों में, विज्ञापन दिखने के दौरान भी कॉन्टेंट चलता रहता है. 

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

नॉन-लीनियर विज्ञापनों को सपोर्ट करने के लिए, 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();
  }
}
ads.js

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

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

क्लिक करके रोकने की सुविधा लागू करने के लिए, विंडो लोड लिसनर में 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();
  }
}
ads.js

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();
  }
}
ads.js

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);
  }
});
ads.js

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