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

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

במדריך הזה מוסבר למפתחים איך לשתף עם 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

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

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

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

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

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

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

אימות השילוב

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

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

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

    צילום מסך של אפליקציית האימות
    איור 1. ההרשמה למינוי בוצעה בהצלחה

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

    צילום מסך של שגיאה באפליקציית האימות
    איור 2.המינוי לא הושלם

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

    צילום מסך של פרטי השגיאה באפליקציית האימות
    איור 3.שגיאות במינוי

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

    צילום מסך של שגיאה באפליקציית האימות
    איור 4.פרטי שגיאה במינוי