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

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

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

#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 में स्क्रिप्ट टैग का इस्तेमाल करके, IMA फ़्रेमवर्क जोड़ें. इसे ads.js टैग से पहले जोड़ें. 

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

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

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

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

<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);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);

  // 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 उन क्लिक को विज्ञापन ओवरले से 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();
  }
}

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