शुरू करना

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

इस गाइड में, किसी आसान वीडियो प्लेयर ऐप्लिकेशन में IMA SDK टूल को इंटिग्रेट करने का तरीका बताया गया है. अगर आपको इंटिग्रेशन का पूरा सैंपल देखना है या उसका पालन करना है, तो GitHub से आसान उदाहरण डाउनलोड करें. अगर आपको SDK टूल के साथ पहले से इंटिग्रेट किया गया HTML5 प्लेयर चाहिए, तो 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 वीडियो एलिमेंट बनाएं. इसमें एक रैपिंग एलिमेंट और वीडियो चलाने के लिए बटन शामिल होना चाहिए. style.css और ads.js फ़ाइलों को लोड करने के लिए, ज़रूरी टैग भी जोड़ें. इसके बाद, styles.css में बदलाव करें, ताकि वीडियो प्लेयर को मोबाइल डिवाइसों के हिसाब से रिस्पॉन्सिव बनाया जा सके. आखिर में, ads.js में, चलाएं बटन पर क्लिक करने पर वीडियो चलाने की सुविधा को ट्रिगर करें.

index.html 
<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>
 style.css 
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
 ads.js 
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

यह चरण पूरा करने के बाद, अपने ब्राउज़र में index.html खोलें. इसके लिए, डेवलपमेंट सर्वर का इस्तेमाल करें. ऐसा करने पर, आपको वीडियो एलिमेंट दिखेगा. साथ ही, 'चलाएं' बटन पर क्लिक करने पर, वीडियो शुरू हो जाएगा.

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

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

index.html 
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. पेज और वीडियो प्लेयर हैंडलर अटैच करना

JavaScript की मदद से वीडियो प्लेयर के व्यवहार में बदलाव करने के लिए, इवेंट हैंडलर जोड़ें. ये हैंडलर, इन कार्रवाइयों को ट्रिगर करते हैं:

  • पेज लोड होने के बाद, IMA SDK टूल को शुरू करें.
  • वीडियो चलाने के बटन पर क्लिक करने पर, विज्ञापन लोड करें. हालांकि, अगर विज्ञापन पहले से लोड हैं, तो ऐसा नहीं करें.
  • जब ब्राउज़र विंडो का साइज़ बदला जाता है, तो मोबाइल डिवाइसों के लिए पेज को रिस्पॉन्सिव बनाने के लिए, वीडियो एलिमेंट और adsManager डाइमेंशन अपडेट करें
ads.js 
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

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

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

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

index.html 
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
 style.css 
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
 ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

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

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

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

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var 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&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. AdsLoader इवेंट को सुनना

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

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

ads.js 
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. AdsManager शुरू करना

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

ads.js 
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. AdsManager को रिस्पॉन्सिव बनाना

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

ads.js 
...

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

...

10. AdsManager इवेंट को सुनना

AdsManager कई इवेंट भी ट्रिगर करता है, जिन्हें मैनेज करना ज़रूरी है. इन इवेंट का इस्तेमाल, कॉन्टेंट की स्थिति में होने वाले बदलावों को ट्रैक करने, कॉन्टेंट वीडियो को चलाने और रोकने के लिए ट्रिगर करने, और गड़बड़ियों को रजिस्टर करने के लिए किया जाता है.

गड़बड़ियों को मैनेज करना

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

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

चलाने और रोकने के इवेंट ट्रिगर करना

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

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  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);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

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

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

क्लिक करके वीडियो रोकने की सुविधा लागू करने के लिए, AdContainer में क्लिक हैंडलर जोड़ें और उस वीडियो पर चलाएं या रोकें इवेंट ट्रिगर करें.

ads.js 
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

नॉन-लीनियर विज्ञापनों पर वीडियो चलाना

जब कोई विज्ञापन चलने के लिए तैयार होता है, तो AdsManager, कॉन्टेंट वीडियो को रोक देता है. हालांकि, ऐसा नॉन-लीनियर विज्ञापनों के लिए नहीं होता. इनमें विज्ञापन दिखने के दौरान कॉन्टेंट चलता रहता है. नॉन-लीनियर विज्ञापनों के साथ काम करने के लिए, AdsManager इवेंट को उत्सर्जित करने के लिए सुनें LOADED इवेंट. इसके बाद, देखें कि विज्ञापन लीनियर है या नहीं. अगर नहीं है, तो वीडियो एलिमेंट पर वीडियो चलाना फिर से शुरू करें.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  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);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

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