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

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

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

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

प्री-वर्क

शुरुआती निर्देशों की गाइड में दिए गए प्री-वर्क के निर्देशों को पूरा करें.

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

इंटिग्रेशन

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

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

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

1. SubscriptionType: साफ़ तौर पर बताएं कि उपयोगकर्ता के पास कौनसा सदस्यता प्लान है.

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

2. ExpirationTimeMillis: यह मिलीसेकंड में तय की गई वह अवधि होती है. यह अवधि तय करना ज़रूरी नहीं है. यह बताएं कि सदस्यता कब खत्म होगी.

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

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

"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()

प्रीमियम सदस्यता

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

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

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

मीडिया सेवा देने वाली कंपनी के फ़ीड के सैंपल के इस उदाहरण के लिए:

"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() तरीके का इस्तेमाल करें.

शुरुआती निर्देशों की गाइड में बताए गए तरीके से, क्लाइंट को शुरू करें और सेवा की उपलब्धता की जांच करें.

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

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

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

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

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

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

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

   syncAcrossDevices

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

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

   // If the user logs out from your media app, you must make the following call
   // to remove subscription and other Engage data from the current
   // google TV device.
   client.deleteClusters(
     new DeleteClustersRequest.Builder()
       .setAccountProfile(accountProfile)
     .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
     .build()
     )
   

   यहां दिया गया कोड स्निपेट, उपयोगकर्ता की सदस्यता हटाने का तरीका दिखाता है. ऐसा तब होता है, जब उपयोगकर्ता सहमति वापस ले लेता है:

   // If the user revokes the consent to share across device, make the call
   // to remove subscription and other Engage data from all google
   // TV devices.
   client.deleteClusters(
     new DeleteClustersRequest.Builder()
       .setAccountProfile(accountProfile)
       .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
       .build()
   )
   

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

   // If the user delete a specific profile, you must make the following call
   // to remove subscription data and other Engage data.
   client.deleteClusters(
     new DeleteClustersRequest.Builder()
     .setAccountProfile(accountProfile)
     .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION)
     .build()
   )
   

जांच करना

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

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

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

2. वीडियो को कब पब्लिश करना है:

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

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

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

5. ऐप्लिकेशन पर जाएं और यहां दी गई हर कार्रवाई करें:

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

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

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

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

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

   

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

   

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

   

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