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

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

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

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

עבודה מוקדמת

לפני שמתחילים, צריך לבצע את השלבים הבאים: מוודאים שהאפליקציה מטרגטת לרמת API 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. מגדירים את סביבת השירות של Engage לסביבת ייצור בקובץ AndroidManifest.xml.

    לאפליקציה לנייד

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

    ל-APK לטלוויזיה

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

  3. לפני שליחת קובץ ה-APK אל Google, צריך להגדיר את סביבת השירות של Engage כסביבת ייצור בקובץ AndroidManifest.xml. כדי לשפר את הביצועים ולשמור על תאימות עתידית, כדאי לפרסם נתונים רק כשהאפליקציה נמצאת בחזית והמשתמש מבצע פעילות פעילה בה, למשל כשהאפליקציה מופעלת, אחרי ההתחברות או במהלך שימוש פעיל. לא מומלץ לפרסם מתהליכים ברקע.

  4. פרסום פרטי המינוי באירועים הבאים:

    1. המשתמש מתחבר לאפליקציה.
    2. המשתמש עובר בין פרופילים (אם יש תמיכה בפרופילים).
    3. המשתמש רוכש מינוי חדש.
    4. משתמש משדרג מינוי קיים.
    5. פג התוקף של המינוי של המשתמש.

שילוב

בקטע הזה מפורטות דוגמאות הקוד וההוראות הנדרשות להטמעת 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. Expiration time: זמן אופציונלי באלפיות שנייה. מציינים מתי תוקף המינוי יפוג.

  3. Provider package name: שם החבילה של האפליקציה שמטפלת במינוי.

דוגמה לפיד של ספק המדיה לדוגמה.

"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

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

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

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

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

מסירת קבוצת מינויים

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

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

אפשר להשתמש ב-isServiceAvailable כדי לבדוק אם השירות זמין לשילוב.

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

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

    • מוודאים שהדגל של שירות Engage לא מוגדר לייצור בקובץ Android Manifest של האפליקציה.
    • מתקינים את אפליקציית Engage Verification ופותחים אותה.
    • אם הערך של isServiceAvailable הוא false באפליקציית האימות, לוחצים על הלחצן Toggle באפליקציית האימות כדי להגדיר אותו כ-true.
    • מזינים את שם החבילה של האפליקציה. הנתונים שפורסמו יוצגו באופן אוטומטי.

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

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

אימות השילוב

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

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

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

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

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

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

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

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

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

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

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