שיתוף הרשאות לאפליקציות עם Google TV באמצעות Engage SDK

במדריך הזה מוסבר למפתחים איך לשתף עם Google TV נתונים של מינויים והרשאות גישה באפליקציה באמצעות Engage SDK. המשתמשים יכולים למצוא תוכן שהם זכאים לצפות בו, ולאפשר ל-Google TV לספק להם המלצות לתוכן רלוונטי מאוד, ישירות בממשקי Google TV בטלוויזיה, בנייד ובטאבלט.

דרישות מוקדמות

כדי להשתמש ב-API של זכויות השימוש במכשיר, צריך להפעיל את פיד הפעולות במדיה. אם עדיין לא עשיתם את זה, אתם צריכים להשלים את תהליך ההצטרפות לפיד של פעולות במדיה.

עבודה מקדימה

פועלים לפי ההוראות שבקטע עבודת הכנה במדריך לתחילת העבודה.

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

מינוי Premium

אם האפליקציה מציעה חבילות מינוי פרימיום בכמה רמות, שכוללות תוכן או תכונות מורחבים מעבר לרמה הרגילה, צריך להוסיף ל-Subscription הרשאה אחת או יותר.

לזכאות הזו יש את השדות הבאים:

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

אפשר גם להוסיף הרשאות למינוי לשירות מקושר.

הגדרת מינוי

מריצים את משימת פרסום התוכן כשהאפליקציה בחזית.

משתמשים ב-publishSubscriptionCluster() method מהמחלקה AppEngagePublishClient כדי לפרסם אובייקט SubscriptionCluster.

חשוב לאתחל את הלקוח ולבדוק את זמינות השירות כמו שמתואר במדריך לתחילת העבודה.

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

משתמשים ב-setSubscription() כדי לוודא שלמשתמש יש רק מינוי אחד לשירות.

משתמשים ב-addLinkedSubscription() או ב-addLinkedSubscriptions(), שמקבלים רשימה של מינויים מקושרים, כדי לאפשר למשתמש לקבל אפס מינויים מקושרים או יותר.

כשהשירות מקבל את הבקשה, נוצרת רשומה חדשה והרשומה הישנה נמחקת אוטומטית אחרי 60 ימים. המערכת תמיד משתמשת בערך האחרון. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.

שמירה על מינוי עדכני

1. כדי לספק עדכונים מיידיים כשמתבצעים שינויים, צריך להפעיל את publishSubscriptionCluster בכל פעם שסטטוס המינוי של המשתמש משתנה, למשל כשהוא מופעל, מושבת, משודרג או משונמך.

2. כדי לספק אימות קבוע של הנתונים ולשמור על רמת דיוק גבוהה, צריך להתקשר אל publishSubscriptionCluster לפחות פעם בחודש.

3. כדי למחוק את נתוני השימוש ב-Engage, צריך למחוק ידנית את נתוני המשתמש משרת Google TV לפני תקופת השמירה הרגילה של 60 יום, באמצעות השיטה 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. בודקים אם האפליקציה קוראת נכון לממשקי ה-API‏ isServiceAvailable() ו-publishClusters() ב-logcat, באירועי הפרסום.

4. מוודאים שהנתונים מוצגים באפליקציית האימות. המינוי צריך להופיע כשורה נפרדת באפליקציית האימות. כשמפעילים את ה-API לפרסום, הנתונים אמורים להופיע באפליקציית האימות.

5. עוברים לאפליקציה ומבצעים את כל הפעולות הבאות:

   • נכנסים לחשבון.
   • מעבר בין פרופילים (אם נתמך).
   • רכישת מינוי חדש.
   • שדרוג מינוי קיים.
   • המינוי יפוג.

אימות השילוב

כדי לבדוק את השילוב, משתמשים באפליקציית האימות.

1. לכל אחד מהאירועים, בודקים אם האפליקציה הפעילה את publishSubscription ה-API. בודקים את הנתונים שפורסמו באפליקציית האימות. מוודאים שהכול ירוק באפליקציית האימות

2. אם כל הפרטים של הישות נכונים, יוצג סימן וי ירוק עם הכיתוב "הכול תקין" ליד כל הישויות.

   

3. הבעיות מודגשות גם באפליקציית האימות

   

4. כדי לראות את הבעיות במינוי החבילה, משתמשים בשלט של הטלוויזיה כדי להתמקד במינוי החבילה הספציפי הזה ולוחצים כדי לראות את הבעיות. יכול להיות שתצטרכו קודם להעביר את המיקוד לשורה ואז ללחוץ על החץ שמאלה כדי למצוא את הכרטיס 'חבילת מינויים'. הבעיות מודגשות באדום, כמו שמוצג באיור 3. בנוסף, אפשר להשתמש בשלט כדי לרדת למטה ולראות את הבעיות בהרשאות בחבילת המינוי

   

5. כדי לראות את הבעיות בזכויות השימוש, משתמשים בשלט של הטלוויזיה כדי להתמקד בזכויות השימוש הספציפיות האלה ולוחצים כדי לראות את הבעיות. הבעיות מודגשות באדום.