शुरू करें

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

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

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

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

  • AdDisplayContainer: यह एक कंटेनर ऑब्जेक्ट है, जहां विज्ञापन रेंडर किए जाते हैं.
  • AdsLoader: एक ऐसा ऑब्जेक्ट जो विज्ञापनों का अनुरोध करता है और विज्ञापनों के अनुरोध के जवाबों के इवेंट मैनेज करता है. आपको सिर्फ़ एक विज्ञापन लोडर को इंस्टैंशिएट करना चाहिए. इसका इस्तेमाल पूरे ऐप्लिकेशन के दौरान किया जा सकता है.
  • AdsRequest: विज्ञापन अनुरोध को परिभाषित करने वाला एक ऑब्जेक्ट. विज्ञापन अनुरोध VAST विज्ञापन टैग के लिए यूआरएल के साथ-साथ अतिरिक्त पैरामीटर, जैसे कि विज्ञापन आयाम भी तय करते हैं.
  • 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 एचटीटीपी सर्वर का भी इस्तेमाल करने का विकल्प है.

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

सबसे पहले, रैपिंग एलिमेंट में शामिल एक सामान्य HTML5 वीडियो एलिमेंट बनाने के लिए, index.html में बदलाव करें और वीडियो चलाने के लिए एक बटन दबाएं. साथ ही, 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. Ads Manager शुरू करें

विज्ञापन चलाना शुरू करने के लिए, आपको 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, वीडियो एलिमेंट को ओवरले करता है, इसलिए उपयोगकर्ता दिए गए प्लेयर से सीधे इंटरैक्ट नहीं कर सकते. इससे मोबाइल डिवाइस इस्तेमाल करने वाले वे लोग भ्रम में पड़ सकते हैं जो वीडियो प्लेयर पर टैप करके, वीडियो चलाना रोक सकते हैं. इस समस्या को हल करने के लिए, 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 पर सैंपल देखें.