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 ক্লায়েন্ট-সাইড প্রয়োগের মধ্যে চারটি প্রধান SDK কম্পোনেন্ট থাকে, যা এই নির্দেশিকায় দেখানো হয়েছে:

  • AdDisplayContainer: একটি কন্টেনার অবজেক্ট যা নির্দিষ্ট করে যে IMA কোথায় বিজ্ঞাপন UI এলিমেন্ট রেন্ডার করে এবং ভিউয়েবিলিটি পরিমাপ করে, যার মধ্যে অ্যাক্টিভ ভিউ এবং ওপেন মেজারমেন্ট অন্তর্ভুক্ত।
  • AdsLoader: এমন একটি অবজেক্ট যা বিজ্ঞাপনের অনুরোধ করে এবং বিজ্ঞাপনের অনুরোধের উত্তর থেকে ইভেন্ট ম্যানেজ করে। আপনাকে শুধুমাত্র একটি বিজ্ঞাপন লোডার ইনস্ট্যানশিয়েট করতে হবে, যা অ্যাপ্লিকেশন চলাকালীন বারবার ব্যবহার করা যেতে পারে।
  • AdsRequest: বিজ্ঞাপনের অনুরোধকে সংজ্ঞায়িত করে এমন একটি অবজেক্ট। বিজ্ঞাপনের অনুরোধে VAST বিজ্ঞাপন ট্যাগের URL এবং বিজ্ঞাপনের ডাইমেনশনের মতো অতিরিক্ত প্যারামিটার উল্লেখ করা থাকে।
  • AdsManager: বিজ্ঞাপনের অনুরোধের উত্তর, বিজ্ঞাপন প্লেব্যাক নিয়ন্ত্রণ করে এবং SDK-এর মাধ্যমে ফায়ার করা বিজ্ঞাপন ইভেন্ট শোনার জন্য একটি অবজেক্ট।

পূর্বশর্ত

শুরু করার আগে, আপনার এগুলি লাগবে:

  • তিনটি খালি ফাইল:
    • index.html
    • style.css
    • ads.js
  • আপনার কম্পিউটারে ইনস্টল করা Python অথবা পরীক্ষার জন্য ব্যবহার করার মতো ওয়েব সার্ভার

১. ডেভেলপমেন্ট সার্ভার চালু করা

যেহেতু IMA SDK, যে পৃষ্ঠা থেকে এটি লোড করা হয়েছে সেই একই প্রোটোকল ব্যবহার করে নির্ভরতা লোড করে, তাই আপনার অ্যাপ পরীক্ষা করার জন্য আপনাকে একটি ওয়েব সার্ভার ব্যবহার করতে হবে। লোকাল ডেভেলপমেন্ট সার্ভার শুরু করার সবচেয়ে সহজ উপায় হল Python-এর বিল্ট-ইন সার্ভার ব্যবহার করা।

  1. কমান্ড লাইন ব্যবহার করে, যে ডিরেক্টরিতে আপনার index.html ফাইল আছে, সেখান থেকে এটি রান করুন: 
      python -m http.server 8000
  2. ওয়েব ব্রাউজার থেকে http://localhost:8000/ লিঙ্কে যান

এছাড়াও, আপনি অন্য যেকোনও ওয়েব সার্ভার ব্যবহার করতে পারেন, যেমন Apache HTTP Server।

২. সহজ ভিডিও প্লেয়ার তৈরি করা

প্রথমে, একটি সাধারণ HTML5 ভিডিও এলিমেন্ট তৈরি করতে index.html পরিবর্তন করুন, যা একটি র‍্যাপিং এলিমেন্টে থাকে এবং প্লেব্যাক ট্রিগার করার জন্য একটি বোতাম থাকে। নিচের উদাহরণে 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 চালু করুন এবং বিজ্ঞাপনের অনুরোধ করুন বিভাগে সংজ্ঞায়িত করা হয়েছে।

৩. IMA SDK ইমপোর্ট করা

এরপরে, index.html-এ স্ক্রিপ্ট ট্যাগ ব্যবহার করে IMA ফ্রেমওয়ার্ক যোগ করুন, এটি ads.js-এর ট্যাগ যোগ করার আগে করতে হবে। 

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

৪. বিজ্ঞাপন কন্টেনার তৈরি করা

বেশিরভাগ ব্রাউজারে, IMA SDK বিজ্ঞাপন ও বিজ্ঞাপন-সম্পর্কিত UI এলিমেন্ট, দুটিই দেখানোর জন্য একটি ডেডিকেটেড বিজ্ঞাপন কন্টেনার এলিমেন্ট ব্যবহার করে। এই কন্টেনারটি এমন সাইজের হতে হবে যাতে এটি উপরের বাঁদিকের কোণ থেকে ভিডিও এলিমেন্টের উপর ওভারলে করা যায়। এই কন্টেনারে রাখা বিজ্ঞাপনের উচ্চতা ও প্রস্থ adsManager অবজেক্টের মাধ্যমে সেট করা হয়, তাই আপনাকে ম্যানুয়ালি এইসব ভ্যালু সেট করতে হয় না।

এই বিজ্ঞাপন কন্টেনার এলিমেন্ট প্রয়োগ করতে, প্রথমে video-container এলিমেন্টের মধ্যে নতুন div তৈরি করুন। তারপর, video-element-এর উপরের বাঁদিকের কোণে এলিমেন্টকে পজিশন করতে CSS আপডেট করুন। সবশেষে, নতুন বিজ্ঞাপন কন্টেনার 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);
}

৫. AdsLoader ইনিশিয়ালাইজ করা এবং বিজ্ঞাপনের অনুরোধ করা

বিজ্ঞাপনের অনুরোধ করতে, একটি AdsLoader ইনস্ট্যান্স তৈরি করুন। AdsLoader কনস্ট্রাক্টর একটি AdDisplayContainer অবজেক্টকে ইনপুট হিসেবে নেয় এবং নির্দিষ্ট বিজ্ঞাপন ট্যাগ URL-এর সাথে যুক্ত AdsRequest অবজেক্ট প্রসেস করতে ব্যবহার করা যেতে পারে। এই উদাহরণে ব্যবহৃত বিজ্ঞাপন ট্যাগে ১০ সেকেন্ডের প্রি-রোল বিজ্ঞাপন রয়েছে। আপনি IMA Video Suite Inspector ব্যবহার করে এই বা যেকোনও বিজ্ঞাপন ট্যাগ URL পরীক্ষা করতে পারবেন।

পেশাদার পদ্ধতি হিসেবে, কোনও পৃষ্ঠার সম্পূর্ণ লাইফসাইকেলের জন্য 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);
}

৬. AdsLoader ইভেন্টের উত্তর দেওয়া

AdsLoader সফলভাবে বিজ্ঞাপন লোড করলে, এটি একটি ADS_MANAGER_LOADED ইভেন্ট এমিট করে। AdsManager অবজেক্ট শুরু করতে কলব্যাকে পাস করা ইভেন্ট পার্স করুন। বিজ্ঞাপন ট্যাগ URL-এর উত্তরে যেভাবে আলাদা আলাদা বিজ্ঞাপনকে সংজ্ঞায়িত করা হয়েছে, 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 fires the 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();
  }
}

৭. মোবাইল ডিভাইসে ক্লিক-টু-পজ ট্রিগার করুন

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

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

৯. প্লেয়ারের সাইজ পরিবর্তন করার সুবিধা

বিজ্ঞাপনের সাইজ ডায়নামিকভাবে পরিবর্তন করতে এবং ভিডিও প্লেয়ারের সাইজের সাথে ম্যাচ করতে অথবা স্ক্রিন ওরিয়েন্টেশনে পরিবর্তন ম্যাচ করতে, উইন্ডোর সাইজ পরিবর্তন সংক্রান্ত ইভেন্টের উত্তরে 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-এ নমুনা দেখুন।