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

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

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

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

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

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

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

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

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

इस सेक्शन में, अलग-अलग तरह की सदस्यताओं को मैनेज करने के लिए 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 पर कॉल करें.

3. वीडियो डिस्कवरी का डेटा मिटाने के लिए, उपयोगकर्ता के डेटा को Google TV सर्वर से मैन्युअल तरीके से मिटाएं. ऐसा, डेटा के रखरखाव की 60 दिनों की स्टैंडर्ड अवधि से पहले करें. इसके लिए, client.deleteClusters तरीके का इस्तेमाल करें. इससे खाते की प्रोफ़ाइल या पूरे खाते के लिए, वीडियो डिस्कवरी से जुड़ा मौजूदा डेटा मिट जाता है. यह इस बात पर निर्भर करता है कि 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)
     .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 video discovery 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 video discovery 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. एनटाइटलमेंट से जुड़ी समस्याएं देखने के लिए, टीवी रिमोट का इस्तेमाल करके उस एनटाइटलमेंट पर फ़ोकस करें और समस्याएं देखने के लिए क्लिक करें. समस्याओं को लाल रंग में हाइलाइट किया जाता है.