Android TV की विज्ञापन लाइब्रेरी का इस्तेमाल शुरू करना

Android TV विज्ञापन लाइब्रेरी, उपयोगकर्ताओं को Google TV पर विज्ञापन अनुभव को कंट्रोल करने के लिए एक यूज़र इंटरफ़ेस उपलब्ध कराती है. इस गाइड में, Android TV विज्ञापन लाइब्रेरी को अपने मौजूदा PAL Android TV ऐप्लिकेशन में इंटिग्रेट करने का तरीका बताया गया है.

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

• शुरू करें गाइड को पूरा करें
• Android PAL SDK का 20.0.1 या इसके बाद का वर्शन

विज्ञापनों से जुड़ी पारदर्शिता और कंट्रोल

Android TV की विज्ञापन लाइब्रेरी, विज्ञापन के दौरान पारदर्शिता दिखाने और विज्ञापन के लिए ब्रेक के दौरान कंट्रोल की सुविधाएं (AT&C) देने की सुविधा देती है. जब उपयोगकर्ता इन-स्ट्रीम विज्ञापनों के दौरान, Google के टीवी विज्ञापन आइकॉन के साथ इंटरैक्ट करते हैं, तो टीवी लॉन्चर ऐप्लिकेशन, एटीएंडसी मेन्यू को सिस्टम ओवरले के तौर पर रेंडर करता है. इसमें, विज्ञापन के बारे में ज़्यादा जानने के लिए एक छोटा यूआरएल और क्यूआर कोड दिखता है. साथ ही, एक ही विज्ञापन को दिखाने से रोकने के लिए एक बटन भी दिखता है.

Google के दिखाए जा रहे टीवी विज्ञापन आइकॉन को, AdChoices आइकॉन के लिए तय की गई, VAST आइकॉन को रेंडर करने की ज़रूरी शर्तों के मुताबिक रेंडर किया जाना चाहिए.

Google के टीवी विज्ञापन आइकॉन पर क्लिक करने से, उपयोगकर्ता को इस विज्ञापन के बारे में जानकारी (एटीए) वेबपेज का छोटा यूआरएल और क्यूआर कोड दिखता है.

Android TV विज्ञापन लाइब्रेरी को इंटिग्रेट करना

ATV विज्ञापन लाइब्रेरी इंपोर्ट करना

Android TV विज्ञापन लाइब्रेरी के लिए, अपनी ऐप्लिकेशन-लेवल की Gradle फ़ाइल में यह डिपेंडेंसी जोड़ें. आम तौर पर, यह फ़ाइल app/build.gradle होती है:

dependencies {
   ...
   implementation 'com.google.android.tv:tv-ads:1.0.1'
}

AD_ID की अनुमति का एलान करना

Android TV विज्ञापन लाइब्रेरी, विज्ञापन आईडी को ऐक्सेस कर सके, इसके लिए अपने AndroidManifest.xml में यह लाइन जोड़ें:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

PAL SDK टूल के साथ इंटिग्रेट करना

Android TV विज्ञापन लाइब्रेरी, डिवाइस पर आइडेंटिफ़ायर इकट्ठा करने के लिए, SignalCollector क्लास का इस्तेमाल करती है. ये आइडेंटिफ़ायर, विज्ञापनों का अनुरोध करने के लिए ज़रूरी होते हैं. PAL SDK, इन सिग्नल को पढ़ने और नॉन्स बनाने के लिए, NonceRequest.Builder क्लास का इस्तेमाल करता है.

PAL SDK टूल के साथ काम करने के लिए, Android TV विज्ञापन लाइब्रेरी को सेट अप करने के लिए, अपने PAL ऐप्लिकेशन में बोल्ड लाइनें जोड़ें:

public class VideoPlayerActivity extends Activity {
  ...
  private SignalCollector signalCollector;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    signalCollector = new SignalCollector();
    ...
  }
  ...
  public generateNonceForAdRequest() {
    ...
    NonceRequest nonceRequest = NonceRequest.builder()
        ...
        .platformSignalCollector(signalCollector)
        .build();
    ...
  }

VAST रिस्पॉन्स को पार्स करना

जब Android TV विज्ञापन लाइब्रेरी के सिग्नल के साथ विज्ञापन का अनुरोध किया जाता है, तो Google विज्ञापन सर्वर अलग-अलग स्क्रीन रिज़ॉल्यूशन के लिए, एक या एक से ज़्यादा <IconClickFallbackImage> चाइल्ड के साथ <Icon> टैग वाला VAST रिस्पॉन्स भेजेंगे. VAST को पार्स करने के लिए, VAST एक्सएमएल रिस्पॉन्स को पार्स करने के निर्देशों का पालन करें.

यहां <Icon> टैग और उसके चाइल्ड टैग के VAST 4.2 स्ट्रक्चर का सैंपल दिया गया है. इसमें बोल्ड में काम का डेटा दिया गया है.

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="4.2">
 <Ad id="123456">
  <Wrapper>
   ...
   <Creatives>
    ...
    <Creative id="7891011" AdID="ABCD123456EF" sequence="1">
     ...
     <Linear>
      ...
      <Icons>
       ...
       <Icon program="TV Ads by Google" width="106" height="20" xPosition="24" yPosition="20"
        duration="00:00:10" offset="00:00:00" apiFramework="VAST" altText="Why This Ad?">
        <StaticResource creativeType="image/png">
         <![CDATA[https://imasdk.googleapis.com/formats/ata/gtv_ads_badge.png]]>
        </StaticResource>
        <IconClicks>
         ...
         <IconClickThrough><![CDATA[https://myadcenter.google.com]]></IconClickThrough>
         <IconClickFallbackImages>
          <IconClickFallbackImage width="950" height="600">
           <AltText>Sample alt text</AltText>
           <StaticResource creativeType="image/png">
            <![CDATA[https://google.com?atvatc=1&atvatcmd=Eg8KDQoLbXV0ZV9hZF91cmwKAgoA]]>
           </StaticResource>
          </IconClickFallbackImage>
          ...
         </IconClickFallbackImages>
        </IconClicks>
       </Icon>
       ...
      </Icons>
     ...
     </Linear>
     ...
    </Creative>
    ...
   </Creatives>
   ...
  </Wrapper>
  ...
 </Ad>
</VAST>

इसी तरह, <IconClickFallbackImages> को VAST 3.0 के जवाबों को पार्स करने के लिए PAL गाइड में दिए गए VAST 3.0 के उदाहरण के स्ट्रक्चर का इस्तेमाल करके पार्स किया जा सकता है.

VAST को पार्स करते समय, हर <IconClickFallbackImage> टैग के लिए एक IconClickFallbackImage ऑब्जेक्ट बनाएं और IconClickFallbackImage.Builder का इस्तेमाल करके, उसे पार्स किए गए डेटा से पॉप्युलेट करें. इसी तरह, IconClickFallbackImage ऑब्जेक्ट की सूची को <IconClickFallbackImages> टैग को दिखाने वाले IconClickFallbackImages ऑब्जेक्ट में पास करने के लिए, IconClickFallbackImages.Builder का इस्तेमाल करें.

import com.google.android.tv.ads.IconClickFallbackImage;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.Arrays;
...
  IconClickFallbackImages getIconClickFallbackImages(...) {
    // Use parsed VAST IconClickFallbackImages data to build a list of
    // IconClickFallbackImage objects.

    int parsedWidth;
    int parsedHeight;
    String parsedAltText;
    String parsedCreativeType;
    String parsedStaticResourceUri;
    // Read the <IconClickFallbackImage> node and its children to set
    // parsedWidth, parsedHeight, ...

    IconClickFallbackImages iconClickFallbackImages =
        IconClickFallbackImages.builder(
                Arrays.asList(
                    IconClickFallbackImage.builder()
                        .setWidth(parsedWidth)
                        .setHeight(parsedHeight)
                        .setAltText(parsedAltText)
                        .setCreativeType(parsedCreativeType)
                        .setStaticResourceUri(parsedStaticResourceUri)
                        .build()))
            .build();

    return iconClickFallbackImages;
  }

नियम और शर्तें रेंडर करना

Android TV विज्ञापन लाइब्रेरी, AT&C मेन्यू या स्टैंडर्ड VAST IconClickFallbackImage को रेंडर करने का तरीका AdsControlsManager.handleIconClick() उपलब्ध कराती है.

यहां दिया गया स्निपेट, Android TV विज्ञापन लाइब्रेरी को सेट अप करता है, ताकि AT&C मेन्यू और VAST आइकॉन क्लिक फ़ॉलबैक इमेज को रेंडर किया जा सके.

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import com.google.android.tv.ads.AdsControlsManager;
import com.google.android.tv.ads.IconClickFallbackImage;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.ArrayList;
import java.util.List;

public final class VideoPlayerActivity extends Activity {
  ...
  private AdsControlsManager adsControlsManager;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    adsControlsManager = new AdsControlsManager(this);
    ...
  }
  ...

  /**
   * Called when the user interacts with any VAST Icon.
   * @param view.
   */
  public void onVastIconClicked(View view) {
    IconClickFallbackImages iconClickFallbackImages;
    // Populate the IconClickFallbackImages object from the parsed VAST data.
    ...
    adsControlsManager.handleIconClick(iconClickFallbackImages);
    ...
  }
}

AdsControlsManager.handleIconClick() को कॉल करने से, Android Activity शुरू होता है, ताकि ऐक्टिविटी की लाइफ़साइकल में होने वाले बदलावों को सुनने के लिए, onPause() और onResume() जैसे स्टैंडर्ड लाइफ़साइकल कॉलबैक का इस्तेमाल किया जा सके.

[ज़रूरी नहीं] कस्टम फ़ॉलबैक इमेज रेंडरर उपलब्ध कराना

अगर आपके ऐप्लिकेशन के लिए, हार्डवेयर से जुड़ी पाबंदियां या यूज़र एक्सपीरियंस से जुड़ी पाबंदियां जैसी खास ज़रूरी शर्तें हैं, तो AdsControlsManager.setCustomFallbackImageRenderer() का इस्तेमाल करके कॉलबैक फ़ंक्शन सेट किया जा सकता है. Android TV विज्ञापन लाइब्रेरी, फ़ॉलबैक इमेज की पुष्टि करेगी, ताकि यह पता लगाया जा सके कि दिए गए कस्टम रेंडरर का इस्तेमाल किया जा सकता है या नहीं. कस्टम रेंडरिंग का इस्तेमाल सिर्फ़ VAST IconClickFallbackImage के लिए किया जाएगा, न कि AT&C मेन्यू के लिए.

import android.app.Activity;
import android.os.Bundle;
import com.google.android.tv.ads.AdsControlsManager;
import com.google.android.tv.ads.CustomFallbackImageRenderer;
import com.google.android.tv.ads.IconClickFallbackImages;
import java.util.List;

public final class VideoPlayerActivity extends Activity {
  ...
  private AdsControlsManager adsControlsManager;
  ...
  @Override
  public void onCreate(Bundle savedInstanceState) {
    ...
    adsControlsManager = new AdsControlsManager(this);
    adsControlsManager.setCustomFallbackImageRenderer(
        new CustomFallbackImageRendererImpl());
    ...
  }

  private static class CustomFallbackImageRendererImpl implements CustomFallbackImageRenderer {
    @Override
    public void render(IconClickFallbackImages iconClickFallbackImages) {
      // Render the fallback images using a custom layout
      ...
    }
  }
  ...
}

Android TV की विज्ञापन लाइब्रेरी के बारे में Google को सुझाव/राय देना या शिकायत करना

हम Android TV ऐप्लिकेशन के इंटिग्रेशन और माइग्रेशन के बारे में आपके अनुभव के बारे में जानना चाहते हैं. हमारे किसी इंजीनियर के साथ मीटिंग शेड्यूल करने के लिए, अपने Google खाता मैनेजर से संपर्क करें.

रिलीज़ का इतिहास

वर्शन	रिलीज़ की तारीख	नोट
1.0.1	2025-01-09	विज्ञापनों के लिए उपलब्ध पारदर्शिता और कंट्रोल फ़ॉर्मैट को अपडेट करता है.
1.0.0	2023-05-16	लॉगिंग की सुविधा जोड़ता है. minSdk के लिए, एपीआई लेवल 21 तक की सुविधा देता है. क्रैश ठीक करने के लिए, गड़बड़ी ठीक करने की सुविधा और डिपेंडेंसी को अपडेट करता है.
1.0.0-alpha02	2022-11-17	Android मेनिफ़ेस्ट को अपडेट करता है, ताकि Leanback सुविधा को ज़रूरी न बनाया जा सके.
1.0.0-alpha01	2022-09-07	शुरुआती रिलीज़.