במדריך הזה מוסבר למפתחים איך לשתף נתונים של מינויים וזכויות שימוש באפליקציות עם Google TV באמצעות Engage SDK. המשתמשים יכולים למצוא תוכן שהם זכאים לצפות בו ולהפעיל את Google TV כדי לקבל המלצות לתוכן רלוונטי מאוד, ישירות בממשקי Google TV בטלוויזיה, בנייד ובטאבלט.
דרישות מוקדמות
כדי להשתמש ב-API של הרשאות למכשירים, צריך להפעיל את פיד פעולות המדיה. אם עדיין לא עשיתם את זה, צריך להשלים את תהליך ההצטרפות לפיד של פעולות שקשורות למדיה.
עבודה מקדימה
לפני שמתחילים, צריך לבצע את השלבים הבאים: מוודאים שרמת ה-API לטירגוט של האפליקציה היא 19 ומעלה לשילוב הזה
מוסיפים את ספריית
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 }מגדירים את סביבת השירות של Engage כסביבת ייצור בקובץ
AndroidManifest.xml.ל-APK לנייד
<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>לפני ששולחים את ה-APK ל-Google, צריך להגדיר את סביבת השירות של Engage כסביבת ייצור בקובץ AndroidManifest.xml. כדי להשיג ביצועים אופטימליים ותאימות עתידית, כדאי לפרסם נתונים רק כשהאפליקציה פועלת ברקע והמשתמש מקיים איתה אינטראקציה פעילה, למשל כשהוא מפעיל את האפליקציה, אחרי שהוא מתחבר או במהלך שימוש פעיל. לא מומלץ לפרסם מתהליכים ברקע.
פרסום פרטי המינוי באירועים הבאים:
- המשתמש מתחבר לאפליקציה.
- המשתמש עובר בין פרופילים (אם יש תמיכה בפרופילים).
- המשתמש רוכש מינוי חדש.
- המשתמש משדרג מינוי קיים.
- המינוי של המשתמש יפוג.
שילוב
בקטע הזה מופיעות דוגמאות קוד והוראות להטמעה של AccountProfile ושל SubscriptionEntity כדי לנהל סוגים שונים של מינויים.
חשבון משתמש ופרופיל
כדי להפעיל תכונות מותאמות אישית ב-Google TV, צריך לספק פרטי חשבון. אפשר להשתמש ב-AccountProfile כדי לספק:
- מזהה חשבון: מזהה ייחודי שמייצג את החשבון של המשתמש. יכול להיות שזה מזהה החשבון בפועל או גרסה מוסתרת שלו.
// 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();
מינוי לרמה משותפת
למשתמשים עם מינויים בסיסיים לשירותים של ספקי מדיה, למשל שירות עם רמת מינוי אחת שמאפשרת גישה לכל התוכן בתשלום, צריך לספק את הפרטים החיוניים הבאים:
סוג המינוי: צריך לציין בבירור את תוכנית המינוי הספציפית של המשתמש.
-
SUBSCRIPTION_TYPE_ACTIVE: למשתמש יש מינוי פעיל בתשלום. -
SUBSCRIPTION_TYPE_ACTIVE_TRIAL: למשתמש יש מינוי לתקופת ניסיון. -
SUBSCRIPTION_TYPE_INACTIVE: למשתמש יש חשבון אבל אין מינוי פעיל או תקופת ניסיון.
-
זמן התפוגה: זמן אופציונלי באלפיות השנייה. מציינים מתי המינוי יפוג.
שם החבילה של הספק: מציינים את שם החבילה של האפליקציה שמטפלת במינוי.
דוגמה לשימוש בפיד של ספק המדיה לדוגמה.
"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
אם האפליקציה מציעה חבילות מינוי פרימיום בכמה רמות, שכוללות תוכן או תכונות נוספים מעבר לרמה הרגילה, צריך להוסיף למינוי זכאות אחת או יותר.
לזכאות הזו יש את השדות הבאים:
- Identifier: מחרוזת המזהה הנדרשת להרשאה הזו. הערך הזה צריך להיות זהה לאחד ממזהי הזכאות (שימו לב שזה לא שדה המזהה) שמופיעים בפיד של ספק המדיה שפורסם ב-Google TV.
- שם: זהו מידע עזר שמשמש להתאמת הרשאות. אמנם לא חובה, אבל כדאי לספק שם הרשאה שקל לקרוא כדי לשפר את ההבנה של הרשאות המשתמשים גם למפתחים וגם לצוותי התמיכה. לדוגמה: Sling Orange.
- 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 יום. המערכת תמיד משתמשת בערך האחרון. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
שמירה על מינוי עדכני
- כדי לספק עדכונים מיידיים כשמתבצעים שינויים, צריך להפעיל את הפונקציה
publishSubscriptionCluster()בכל פעם שסטטוס המינוי של המשתמש משתנה, למשל כשהוא מופעל, מושבת, משודרג או משודרג לאחור. כדי לספק אימות קבוע של הדיוק המתמשך, צריך להתקשר אל
publishSubscriptionCluster()לפחות פעם בחודש.כדי למחוק את נתוני הגילוי של סרטונים, צריך למחוק באופן ידני את נתוני המשתמש משרת 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() )
בדיקה
בקטע הזה מפורט מדריך שלב אחר שלב לבדיקת ההטמעה של המינוי. לפני ההשקה, חשוב לוודא שהנתונים מדויקים ושהפונקציונליות תקינה.
רשימת משימות לפרסום שילוב
הפרסום צריך להתבצע כשהאפליקציה בחזית והמשתמש מבצע בה פעולות באופן פעיל.
פרסום כאשר:
- המשתמש נכנס לחשבון בפעם הראשונה.
- המשתמש משנה את הפרופיל (אם יש תמיכה בפרופילים).
- המשתמש רוכש מינוי חדש.
- המשתמש משדרג את המינוי.
- המינוי של המשתמש יפוג.
בודקים אם האפליקציה קוראת נכון לממשקי ה-API
isServiceAvailable()ו-publishClusters()ב-logcat, באירועי הפרסום.מוודאים שהנתונים מוצגים באפליקציית האימות. המינוי אמור להופיע באפליקציית האימות בשורה נפרדת. כשמפעילים את ה-API לפרסום, הנתונים אמורים להופיע באפליקציית האימות.
- מוודאים שהערך של Engage Service Flag לא מוגדר כייצור בקובץ Android Manifest של האפליקציה.
- מתקינים ופותחים את אפליקציית Engage Verification.
- אם הערך של
isServiceAvailableהואfalseבאפליקציית האימות, לוחצים על הלחצןToggleבאפליקציית האימות כדי להגדיר אותו ל-true. - מזינים את שם החבילה של האפליקציה. הנתונים שפורסמו מוצגים באופן אוטומטי.
עוברים לאפליקציה ומבצעים את כל הפעולות הבאות:
- מתחברים לחשבון.
- לעבור בין פרופילים (אם האפשרות הזו נתמכת).
- רכישת מינוי חדש.
- שדרוג מינוי קיים.
- המינוי יפוג.
אימות השילוב
כדי לבדוק את השילוב, משתמשים .
אפליקציית האימות היא אפליקציית Android שמפתחים יכולים להשתמש בה כדי לוודא שהשילוב פועל. האפליקציה כוללת יכולות שעוזרות למפתחים לאמת נתונים ולשדר כוונות. כך אפשר לוודא שהנתונים מדויקים ושהפונקציות פועלות כמו שצריך לפני ההשקה.
- לכל אחד מהאירועים, בודקים אם האפליקציה הפעילה את
publishSubscriptionה-API. בודקים את הנתונים שפורסמו באפליקציית האימות. מוודאים שהכל ירוק באפליקציית האימות אם כל המידע על הישות נכון, יופיע סימן וי ירוק עם הכיתוב 'הכול בסדר' בכל הישויות.
איור 1. המינוי בוצע בהצלחה הבעיות מודגשות גם באפליקציית האימות
איור 2.המינוי לא הושלם כדי לראות את הבעיות במינוי החבילה, משתמשים בשלט של הטלוויזיה כדי להתמקד במינוי החבילה הספציפי הזה ולוחצים כדי לראות את הבעיות. יכול להיות שתצטרכו קודם להעביר את המיקוד לשורה ואז לזוז ימינה כדי למצוא את הכרטיס 'מינוי בחבילה'. הבעיות מודגשות באדום, כמו שמוצג באיור 3. בנוסף, אפשר להשתמש בשלט כדי לגלול למטה ולראות את הבעיות בהרשאות של מינוי בחבילה.
איור 3. שגיאות במינוי כדי לראות את הבעיות בזכויות השימוש, משתמשים בשלט של הטלוויזיה כדי להתמקד בזכויות השימוש הספציפיות האלה ולוחצים כדי לראות את הבעיות. הבעיות מסומנות באדום.
איור 4. פרטי שגיאה במינוי
הורדה
לפני ההורדה, עליכם לאשר את התנאים וההגבלות הבאים.