Engage SDK का इस्तेमाल करके, Google TV के साथ ऐप्लिकेशन एनटाइटलमेंट शेयर करना

इस गाइड में, डेवलपर के लिए निर्देश दिए गए हैं. इन निर्देशों की मदद से, वे Engage SDK टूल का इस्तेमाल करके, ऐप्लिकेशन की सदस्यता और एनटाइटलमेंट का डेटा Google TV के साथ शेयर कर सकते हैं. उपयोगकर्ताओं को वह कॉन्टेंट मिल सकता है जिसका ऐक्सेस उनके पास है. साथ ही, Google TV को उपयोगकर्ताओं को उनके हिसाब से कॉन्टेंट के सुझाव देने की सुविधा भी मिलती है. यह सुविधा, टीवी, मोबाइल, और टैबलेट पर Google TV के अनुभवों में सीधे तौर पर मिलती है.

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

डिवाइस एनटाइटलमेंट एपीआई का इस्तेमाल करने से पहले, मीडिया ऐक्शन फ़ीड को शामिल करना ज़रूरी है. अगर आपने पहले से ऐसा नहीं किया है, तो मीडिया ऐक्शन फ़ीड को शामिल करने की प्रोसेस पूरी करें.

सेशन की तैयारी

शुरू करने से पहले, यह तरीका अपनाएं पुष्टि करें कि आपका ऐप्लिकेशन, इस इंटिग्रेशन के लिए एपीआई लेवल 19 या उसके बाद के लेवल को टारगेट करता है

1. अपने ऐप्लिकेशन में com.google.android.engage लाइब्रेरी जोड़ें:

   इंटिग्रेशन में इस्तेमाल करने के लिए, अलग-अलग SDK टूल उपलब्ध हैं: एक मोबाइल ऐप्लिकेशन के लिए और एक टीवी ऐप्लिकेशन के लिए.

   मोबाइल के लिए

   
     dependencies {
       implementation 'com.google.android.engage:engage-core:1.5.5
     }
   

   टीवी के लिए

   
     dependencies {
       implementation 'com.google.android.engage:engage-tv:1.0.2
     }
   

2. AndroidManifest.xml फ़ाइल में, Engage सेवा के एनवायरमेंट को प्रोडक्शन पर सेट करें.

   मोबाइल APK के लिए

   
   <meta-data
         android:name="com.google.android.engage.service.ENV"
         android:value="PRODUCTION">
   </meta-data>
   

   For TV apk

   
   <meta-data
       android:name="com.google.android.engage.service.ENV"
       android:value="PRODUCTION">
   </meta-data>
   

3. Google को APK भेजने से पहले, अपनी AndroidManifest.xml फ़ाइल में, एंगेज सेवा के एनवायरमेंट को प्रोडक्शन पर सेट करें. बेहतर परफ़ॉर्मेंस और आने वाले समय में काम करने के लिए, डेटा सिर्फ़ तब पब्लिश करें, जब ऐप्लिकेशन फ़ोरग्राउंड में हो और उपयोगकर्ता उससे इंटरैक्ट कर रहा हो. जैसे, ऐप्लिकेशन लॉन्च करने, लॉगिन करने के बाद या ऐप्लिकेशन के इस्तेमाल के दौरान. बैकग्राउंड प्रोसेस से पब्लिश करने का सुझाव नहीं दिया जाता.

4. सदस्यता की जानकारी को इन इवेंट पर पब्लिश करें:

   1. उपयोगकर्ता आपके ऐप्लिकेशन में लॉग इन करता है.
   2. उपयोगकर्ता, प्रोफ़ाइलों के बीच स्विच करता है (अगर प्रोफ़ाइलें काम करती हैं).
   3. उपयोगकर्ता नई सदस्यता खरीदता है.
   4. उपयोगकर्ता, किसी मौजूदा सदस्यता को अपग्रेड करता है.
   5. उपयोगकर्ता की सदस्यता की समयसीमा खत्म हो जाती है.

SDK टूल इंटिग्रेशन

इस सेक्शन में, अलग-अलग तरह की सदस्यताओं को मैनेज करने के लिए, AccountProfile और SubscriptionEntity को लागू करने के लिए ज़रूरी कोड के उदाहरण और निर्देश दिए गए हैं.

उपयोगकर्ता खाता और प्रोफ़ाइल

Google TV पर अपने हिसाब से सुविधाएं पाने के लिए, खाते की जानकारी दें. AccountProfile का इस्तेमाल करके:

1. खाता आईडी: ऐसा यूनीक आइडेंटिफ़ायर जो उपयोगकर्ता के खाते की जानकारी देता है. यह खाते का असल आईडी या सही तरीके से छिपाया गया वर्शन हो सकता है.

// Set the account ID to which the subscription applies.
// Don't set the profile ID because subscription applies to account level.
val accountProfile = AccountProfile.Builder()
  .setAccountId("user_account_id")
  .setProfileId("user_profile id")
  .build();

एक ही टीयर की सदस्यता

मीडिया प्रोवाइडर की सेवाओं की बुनियादी सदस्यता वाले उपयोगकर्ताओं के लिए, ये ज़रूरी जानकारी दें. उदाहरण के लिए, ऐसी सेवा जिसकी एक सदस्यता टीयर है और जो पैसे चुकाकर मिलने वाले सभी कॉन्टेंट का ऐक्सेस देती है:

1. सदस्यता का टाइप: उपयोगकर्ता के पास मौजूद सदस्यता प्लान के बारे में साफ़ तौर पर बताएं.

   1. SUBSCRIPTION_TYPE_ACTIVE: उपयोगकर्ता के पास पैसे चुकाकर ली गई सदस्यता है.
   2. SUBSCRIPTION_TYPE_ACTIVE_TRIAL: उपयोगकर्ता के पास मुफ़्त में आज़माने की सुविधा वाली सदस्यता है.
   3. SUBSCRIPTION_TYPE_INACTIVE: उपयोगकर्ता के पास खाता है, लेकिन उसके पास कोई चालू सदस्यता या ट्रायल नहीं है.

2. खत्म होने का समय: मिलीसेकंड में समय. यह वैकल्पिक है. बताएं कि सदस्यता की समयसीमा कब खत्म होगी.

3. प्रोवाइडर के पैकेज का नाम: उस ऐप्लिकेशन के पैकेज का नाम डालें जो सदस्यता मैनेज करता है.

मीडिया प्रोवाइडर के सैंपल फ़ीड का उदाहरण.

"actionAccessibilityRequirement": [
  {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2022-06-01T07:00:00Z",
    "availabilityEnds": "2026-05-31T07:00:00Z",
    "requiresSubscription": {
    "@type": "MediaSubscription",
    // Don't match this string,
    // ID is only used to for reconciliation purpose
    "@id": "https://www.example.com/971bfc78-d13a-4419",
    // Don't match this, as name is only used for displaying purpose
    "name": "Basic common name",
    "commonTier": true
  }

यहां दिए गए उदाहरण में, किसी उपयोगकर्ता के लिए SubscriptionEntity बनाया गया है:

val subscription = SubscriptionEntity
  .Builder()
  setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .build();

Premium की सदस्यता

अगर ऐप्लिकेशन में कई टीयर वाले प्रीमियम सदस्यता पैकेज ऑफ़र किए जाते हैं, जिनमें सामान्य टीयर के अलावा ज़्यादा कॉन्टेंट या सुविधाएं शामिल होती हैं, तो सदस्यता में एक या उससे ज़्यादा एनटाइटलमेंट जोड़कर इसकी जानकारी दें.

इस एनटाइटलमेंट में ये फ़ील्ड होते हैं:

1. आइडेंटिफ़ायर: इस एनटाइटलमेंट के लिए ज़रूरी आइडेंटिफ़ायर स्ट्रिंग. यह एनटाइटलमेंट आइडेंटिफ़ायर में से किसी एक से मैच करना चाहिए. ध्यान दें कि यह आईडी फ़ील्ड नहीं है. यह आइडेंटिफ़ायर, Google TV पर पब्लिश किए गए मीडिया प्रोवाइडर के फ़ीड में दिया गया होता है.
2. नाम: यह सहायक जानकारी है और इसका इस्तेमाल एनटाइटलमेंट मैच करने के लिए किया जाता है. एनटाइटलमेंट का ऐसा नाम देना ज़रूरी नहीं है जिसे कोई भी पढ़ सके. हालांकि, ऐसा करने से डेवलपर और सहायता टीम, दोनों को उपयोगकर्ता के एनटाइटलमेंट को समझने में मदद मिलती है. उदाहरण के लिए: Sling Orange.
3. Expiration TimeMillis: अगर इस एनटाइटलमेंट की समयसीमा, सदस्यता की समयसीमा से अलग है, तो इस एनटाइटलमेंट के लिए समयसीमा खत्म होने का समय, मिलीसेकंड में बताएं. डिफ़ॉल्ट रूप से, सदस्यता की समयसीमा खत्म होने पर एनटाइटलमेंट भी खत्म हो जाएगा.

मीडिया प्रोवाइडर के फ़ीड के इस सैंपल स्निपेट के लिए:

"actionAccessibilityRequirement": [
  {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2022-06-01T07:00:00Z",
    "availabilityEnds": "2026-05-31T07:00:00Z",
    "requiresSubscription": {
    "@type": "MediaSubscription",
    // Don't match this string,
    // ID is only used to for reconciliation purpose
    "@id": "https://www.example.com/971bfc78-d13a-4419",

    // Don't match this, as name is only used for displaying purpose
    "name": "Example entitlement name",
    "commonTier": false,
    // match this identifier in your API. This is the crucial
    // entitlement identifier used for recommendation purpose.
    "identifier": "example.com:entitlementString1"
  }

नीचे दिए गए उदाहरण में, सदस्यता वाले उपयोगकर्ता के लिए SubscriptionEntity बनाया गया है:

// Subscription with entitlements.
// The entitlement expires at the same time as its subscription.
val subscription = SubscriptionEntity
  .Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds
  .setExpirationTimeMillis(1767052800000)
  .addEntitlement(
    SubscriptionEntitlement.Builder()
    // matches with the identifier in media provider feed
    .setEntitlementId("example.com:entitlementString1")
    .setDisplayName("entitlement name1")
    .build()
  )
  .build();

// Subscription with entitlements
// The entitement has different expiration time from its subscription
val subscription = SubscriptionEntity
  .Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds
  .setExpirationTimeMillis(1767052800000)
  .addEntitlement(
    SubscriptionEntitlement.Builder()
    .setEntitlementId("example.com:entitlementString1")
    .setDisplayName("entitlement name1")
    // You may set the expiration time for entitlement
    // December 15, 2025 10:00:00 AM in milliseconds
    .setExpirationTimeMillis(1765792800000)
    .build())
  .build();

लिंक की गई सेवा के पैकेज की सदस्यता

आम तौर पर, सदस्यताएं उस ऐप्लिकेशन के मीडिया प्रोवाइडर की होती हैं जिसने उन्हें जारी किया है. हालांकि, सदस्यता में लिंक किए गए सेवा पैकेज का नाम बताकर, सदस्यता को लिंक किए गए सेवा पैकेज के लिए एट्रिब्यूट किया जा सकता है.

नीचे दिए गए कोड सैंपल में, उपयोगकर्ता की सदस्यता बनाने का तरीका बताया गया है.

// Subscription for linked service package
val subscription = SubscriptionEntity
  .Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .build();

इसके अलावा, अगर उपयोगकर्ता के पास किसी सहायक सेवा की सदस्यता है, तो एक और सदस्यता जोड़ें और लिंक की गई सेवा के पैकेज का नाम तदनुसार सेट करें.

// Subscription for linked service package
val linkedSubscription = Subscription
  .Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("linked service package name")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .addBundledSubscription(
    BundledSubscription.Builder()
      .setBundledSubscriptionProviderPackageName(
        "bundled-subscription-package-name"
      )
      .setSubscriptionType(SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE)
      .setExpirationTimeMillis(111)
      .addEntitlement(
        SubscriptionEntitlement.Builder()
        .setExpirationTimeMillis(111)
        .setDisplayName("Silver subscription")
        .setEntitlementId("subscription.tier.platinum")
        .build()
      )
      .build()
  )
    .build();

इसके अलावा, लिंक की गई सेवा की सदस्यता में भी एनटाइटलमेंट जोड़े जा सकते हैं. हालांकि, ऐसा करना ज़रूरी नहीं है.

सदस्यता सेट उपलब्ध कराना

ऐप्लिकेशन के फ़ोरग्राउंड में होने पर, कॉन्टेंट पब्लिश करने की जॉब चलाएं.

SubscriptionCluster ऑब्जेक्ट पब्लिश करने के लिए, AppEngagePublishClient क्लास के publishSubscriptionCluster() तरीके का इस्तेमाल करें.

isServiceAvailable का इस्तेमाल करके देखें कि सेवा, इंटिग्रेशन के लिए उपलब्ध है या नहीं.

client.publishSubscription(
  PublishSubscriptionRequest.Builder()
    .setAccountProfile(accountProfile)
    .setSubscription(subscription)
    .build();
  )

setSubscription() का इस्तेमाल करके पुष्टि करें कि उपयोगकर्ता के पास सेवा की सिर्फ़ एक सदस्यता होनी चाहिए.

addLinkedSubscription() या addLinkedSubscriptions() का इस्तेमाल करें. ये लिंक की गई सदस्यताओं की सूची स्वीकार करते हैं. इससे उपयोगकर्ता के पास, लिंक की गई कोई सदस्यता नहीं हो सकती या एक से ज़्यादा सदस्यताएं हो सकती हैं.

अनुरोध मिलने पर, एक नई एंट्री बनाई जाती है. साथ ही, पुरानी एंट्री 60 दिनों के बाद अपने-आप मिट जाती है. सिस्टम हमेशा नई एंट्री का इस्तेमाल करता है. गड़बड़ी होने पर, पूरा अनुरोध अस्वीकार कर दिया जाता है और मौजूदा स्थिति को बनाए रखा जाता है.

सदस्यता को अप-टू-डेट रखना

1. बदलाव होने पर तुरंत अपडेट देने के लिए, जब भी उपयोगकर्ता की सदस्यता की स्थिति में बदलाव होता है, तो publishSubscriptionCluster() को कॉल करें. जैसे, सदस्यता चालू करना, बंद करना, अपग्रेड करना, डाउनग्रेड करना.

2. डेटा की सटीक जानकारी देने के लिए, हर महीने कम से कम एक बार publishSubscriptionCluster() को कॉल करें.

3. वीडियो डिस्कवरी का डेटा मिटाने के लिए, client.deleteClusters() तरीके का इस्तेमाल करके, उपयोगकर्ता का डेटा, Google TV सर्वर से मैन्युअल तरीके से मिटाएं. ऐसा, डेटा को 60 दिनों तक सेव रखने की स्टैंडर्ड अवधि खत्म होने से पहले करें. यह DeleteReason के आधार पर, खाता प्रोफ़ाइल या पूरे खाते के लिए, वीडियो डिस्कवरी का मौजूदा डेटा मिटा देता है.

   उपयोगकर्ता की सदस्यता हटाने के लिए कोड स्निपेट

     // If the user logs out from your media app, you must make the following call
     // to remove subscription and other video discovery data from the current
     // google TV device.
     client.deleteClusters(
       new DeleteClustersRequest.Builder()
         .setAccountProfile(
           AccountProfile
             .Builder()
             .setAccountId()
             .setProfileId()
             .build()
         )
       .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
       .build()
       )
     ```
   Following code snippet demonstrates removal of user subscription
   when user revokes the consent.
   
   ```Kotlin
     // If the user revokes the consent to share across device, make the call
     // to remove subscription and other video discovery data from all google
     // TV devices.
     client.deleteClusters(
       new DeleteClustersRequest.Builder()
         .setAccountProfile(
           AccountProfile
           .Builder()
           .setAccountId()
           .setProfileId()
           .build()
         )
         .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
         .build()
     )
     ```
   
   Following code demonstrates how to remove subscription data on user profile
   deletion.
   
   ```Kotlin
   // If the user delete a specific profile, you must make the following call
   // to remove subscription data and other video discovery data.
   client.deleteClusters(
     new DeleteClustersRequest.Builder()
     .setAccountProfile(
       AccountProfile
       .Builder()
       .setAccountId()
       .setProfileId()
       .build()
     )
     .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION)
     .build()
   )
   

टेस्ट करना

इस सेक्शन में, सदस्यता लागू करने की जांच करने के लिए सिलसिलेवार निर्देश दिए गए हैं. लॉन्च से पहले, डेटा की सटीक जानकारी और सही तरीके से काम करने की पुष्टि करें.

पब्लिश करने के लिए इंटिग्रेशन की चेकलिस्ट

1. पब्लिश करने की प्रोसेस तब शुरू होनी चाहिए, जब ऐप्लिकेशन फ़ोरग्राउंड में हो और उपयोगकर्ता उससे सक्रिय तौर पर इंटरैक्ट कर रहा हो.

2. पब्लिश करने के लिए:

   • उपयोगकर्ता पहली बार लॉग इन करता है.
   • उपयोगकर्ता ने प्रोफ़ाइल बदली है (अगर प्रोफ़ाइलें इस्तेमाल की जा सकती हैं).
   • उपयोगकर्ता नई सदस्यता खरीदता है.
   • उपयोगकर्ता ने सदस्यता अपग्रेड की.
   • उपयोगकर्ता की सदस्यता की समयसीमा खत्म हो जाती है.

3. देखें कि पब्लिश करने वाले इवेंट के लिए, ऐप्लिकेशन logcat में isServiceAvailable() और publishClusters() एपीआई को सही तरीके से कॉल कर रहा है या नहीं.

4. पुष्टि करने वाले ऐप्लिकेशन में डेटा दिख रहा है या नहीं, इसकी पुष्टि करें. पुष्टि करने वाले ऐप्लिकेशन में, सदस्यता को एक अलग लाइन में दिखाया जाना चाहिए. पब्लिश एपीआई का इस्तेमाल करने पर, डेटा पुष्टि करने वाले ऐप्लिकेशन में दिखना चाहिए.

   • पुष्टि करें कि ऐप्लिकेशन की Android मेनिफ़ेस्ट फ़ाइल में, Engage सेवा फ़्लैग को प्रोडक्शन पर नहीं सेट किया गया है.
   • Engage Verification ऐप्लिकेशन इंस्टॉल करें और उसे खोलें.
   • अगर पुष्टि करने वाले ऐप्लिकेशन में isServiceAvailable की वैल्यू false है, तो इसे true पर सेट करने के लिए, पुष्टि करने वाले ऐप्लिकेशन में Toggle बटन पर क्लिक करें.
   • ऐप्लिकेशन का पैकेज नाम डालें. इससे पब्लिश किया गया डेटा अपने-आप दिखता है.

5. ऐप्लिकेशन पर जाएं और इनमें से हर कार्रवाई करें:

   • साइन इन करें.
   • प्रोफ़ाइलों के बीच स्विच करें (अगर यह सुविधा काम करती है).
   • नई सदस्यता खरीदें.
   • किसी मौजूदा सदस्यता को अपग्रेड करना.
   • सदस्यता की समयसीमा खत्म हो गई.

इंटिग्रेशन की पुष्टि करना

अपने इंटिग्रेशन की जांच करने के लिए, पुष्टि करने वाले ऐप्लिकेशन का इस्तेमाल करें.

पुष्टि करने वाला ऐप्लिकेशन, एक Android ऐप्लिकेशन है. इसका इस्तेमाल करके, डेवलपर यह पुष्टि कर सकते हैं कि इंटिग्रेशन काम कर रहा है या नहीं. इस ऐप्लिकेशन में ऐसी सुविधाएं शामिल हैं जिनकी मदद से डेवलपर, डेटा की पुष्टि कर सकते हैं और ब्रॉडकास्ट इंटेंट को मैनेज कर सकते हैं. इससे, लॉन्च से पहले डेटा की सटीक जानकारी और सही तरीके से काम करने की पुष्टि करने में मदद मिलती है.

1. हर इवेंट के लिए, देखें कि ऐप्लिकेशन ने publishSubscription एपीआई को ट्रिगर किया है या नहीं. पुष्टि करने वाले ऐप्लिकेशन में, पब्लिश किए गए डेटा की पुष्टि करें. पुष्टि करने वाले ऐप्लिकेशन में देखें कि हर चीज़ हरे रंग में दिख रही है या नहीं

2. अगर एंटिटी की सारी जानकारी सही है, तो सभी एंटिटी में "सभी ठीक है" के तौर पर हरे रंग का सही का निशान दिखता है.

   

3. पुष्टि करने वाले ऐप्लिकेशन में भी समस्याओं को हाइलाइट किया जाता है

   

4. बंडल की गई सदस्यता में मौजूद समस्याएं देखने के लिए, टीवी रिमोट का इस्तेमाल करके उस सदस्यता पर फ़ोकस करें. इसके बाद, समस्याएं देखने के लिए क्लिक करें. बंडल की गई सदस्यता का कार्ड ढूंढने के लिए, आपको पहले लाइन पर फ़ोकस करना पड़ सकता है. इसके बाद, दाईं ओर जाएं. समस्याओं को लाल रंग से हाइलाइट किया जाता है, जैसा कि तीसरे चित्र में दिखाया गया है. साथ ही, रिमोट का इस्तेमाल करके नीचे की ओर बढ़कर, बंडल की गई सदस्यता में एनटाइटलमेंट से जुड़ी समस्याएं देखें

   

5. एनटाइटलमेंट से जुड़ी समस्याएं देखने के लिए, टीवी रिमोट का इस्तेमाल करके उस एनटाइटलमेंट पर फ़ोकस करें और समस्याएं देखने के लिए क्लिक करें. समस्याओं को लाल रंग से हाइलाइट किया गया है.