המדריך הזה מכיל הוראות למפתחים שרוצים לשלב את תוכן הווידאו המומלץ שלהם באמצעות Engage SDK, כדי לאכלס את חוויות ההמלצות בפלטפורמות השונות של Google, כמו טלוויזיה, נייד וטאבלט.
ההמלצות מתבססות על אשכול ההמלצות כדי להציג סרטים ותוכניות טלוויזיה ממספר אפליקציות בקיבוץ אחד בממשק המשתמש. כל שותף פיתוח יכול לשדר עד 25 ישויות בכל אשכול המלצות, ולכל בקשה יכולים להיות עד 7 אשכולות המלצות.
עבודה מוקדמת
לפני שמתחילים, צריך לבצע את השלבים הבאים. 1. כדי לשלב את הרכיב הזה, צריך לוודא שהאפליקציה מטרגטת ל-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
.לאפליקציה לנייד
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
ל-tv apk
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
ביצוע פרסום בשירות שפועל בחזית.
לפרסם את נתוני ההמלצות פעם ביום לכל היותר, בהתאם לאחד מהאירועים הבאים:
- הכניסה הראשונה של המשתמש באותו יום. (או)
- כשהמשתמש מתחיל אינטראקציה עם האפליקציה.
שילוב
AppEngagePublishClient
מפרסם את אשכול ההמלצות. משתמשים בשיטה publishRecommendationClusters
כדי לפרסם אובייקט של המלצות.
משתמשים ב-isServiceAvailable()
2 כדי לבדוק אם השירות זמין לשילוב.
val client = AppEngagePublishClient(context)
client.isServiceAvailable().addOnCompleteListener { task ->
if (task.isSuccessful) {
// Handle IPC call success
if(task.result) {
// Service is available on the device, proceed with content publish
// calls.
client.publishRecommendationClusters(recommendationRequest)
} else {
// Service is not available
}
} else {
// The IPC call itself fails, proceed with error handling logic here,
// such as retry.
}
}
אשכולות של המלצות ובקשה לפרסום
אשכולות הם קיבוץ לוגי של הישויות. בדוגמאות הקוד הבאות מוסבר איך ליצור את האשכולות בהתאם להעדפות שלכם ואיך ליצור בקשת פרסום לכל האשכולות.
// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
.Builder()
.addEntity(movie)
.addEntity(tvShow)
.setTitle("Popular Movies")
.build()
// cluster for top searches
val recommendationCluster2 = RecommendationCluster
.Builder()
.addEntity(movie)
.addEntity(tvShow)
.setTitle("Top Searches")
.build()
// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
.Builder()
.setSyncAcrossDevices(true)
.setAccountProfile(accountProfile)
.addRecommendationCluster(recommendationCluster1)
.addRecommendationCluster(recommendationCluster2)
.build()
יצירת פרופיל חשבון
כדי ליהנות מחוויית שימוש מותאמת אישית ב-Google TV, צריך לספק פרטי חשבון ופרופיל. אפשר להשתמש ב-AccountProfile
כדי לספק:
- מזהה חשבון: מזהה ייחודי שמייצג את החשבון של המשתמש באפליקציה. זה יכול להיות מזהה החשבון בפועל או גרסה שעברה ערפול באופן מתאים.
- מזהה פרופיל (אופציונלי): אם האפליקציה תומכת במספר פרופילים בחשבון אחד, יש לספק מזהה ייחודי לפרופיל המשתמש הספציפי.
- אזור(אופציונלי): אפשר לציין את השפה המועדפת של המשתמש.
השדה הזה שימושי אם שולחים
MediaActionFeedEntity
ב-RecommendationRequest
.
// If app only supports account
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.build();
// If app supports both account and profile
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.setProfileId("profile_id")
.build();
// set Locale
val accountProfile = AccountProfile.Builder()
.setAccountId("account_id")
.setProfileId("profile_id")
.setLocale("en-US")
.build();
כשהבקשה מתקבלת בשירות, מתבצעות הפעולות הבאות בעסקה אחת:
- הנתונים הקיימים של
RecommendationsCluster
מהשותף המפתח יוסרו. - הנתונים מהבקשה מנותחים ונשמרים ב-
RecommendationsCluster
המעודכן. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
סנכרון בין מכשירים
הדגל SyncAcrossDevices
קובע אם נתוני האשכולות של ההמלצות של המשתמש ישותפו עם Google TV ויהיה אפשר לגשת אליהם במכשירים השונים שלו, כמו טלוויזיה, טלפון וטאבלט. כדי שההמלצה תפעל, צריך להגדיר אותה כ-true.
קבלת הסכמה
באפליקציית המדיה צריכה להיות הגדרה ברורה להפעלה או להשבתה של סנכרון בין מכשירים. כדאי להסביר למשתמש את היתרונות ולשמור את ההעדפה של המשתמש פעם אחת ולהחיל אותה בבקשה publishRecommendations
בהתאם. כדי להפיק את המקסימום מהתכונה 'מעבר בין מכשירים', צריך לוודא שהאפליקציה מקבלת את הסכמת המשתמש ומפעילה את SyncAcrossDevices
עד true
.
מחיקת הנתונים של מודעות וידאו Discovery
כדי למחוק באופן ידני את הנתונים של משתמש מהשרת של Google TV לפני תקופת השמירה הרגילה של 60 יום, משתמשים בשיטה client.deleteClusters()
. לאחר קבלת הבקשה, השירות מחק את כל הנתונים הקיימים לגבי חשיפת הסרטונים בפרופיל החשבון או בחשבון כולו.
המאפיין המסווג DeleteReason
מגדיר את הסיבה למחיקת הנתונים.
הקוד הבא מסיר את ההמלצות בזמן היציאה מהחשבון.
// If the user logs out from your media app, you must make the following call
// to remove recommendations data from the current google TV device,
// otherwise, the recommendations data persists on the current
// google TV device until 60 days later.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(AccountProfile())
.setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
.build()
)
// If the user revokes the consent to share data with Google TV,
// you must make the following call to remove recommendations data from
// all current google TV devices. Otherwise, the recommendations data persists
// until 60 days later.
client.deleteClusters(
new DeleteClustersRequest.Builder()
.setAccountProfile(AccountProfile())
.setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
.build()
)
יצירת ישויות
ב-SDK מוגדרות ישויות שונות שמייצגות כל סוג פריט. יש תמיכה באובייקטים הבאים באשכול ההמלצות:
MediaActionFeedEntity
MovieEntity
TvShowEntity
תיאור
מוסיפים תיאור קצר לכל ישות. התיאור הזה יוצג כשמשתמשים יעבירו את העכבר מעל הישות, ויעניק להם פרטים נוספים.
מזהי URI ספציפיים לפלטפורמה להפעלה
יוצרים מזהי URI להפעלה לכל פלטפורמה נתמכת: Android TV, Android או iOS. כך המערכת תוכל לבחור את ה-URI המתאים להפעלת הסרטון בפלטפורמה הרלוונטית.
במקרים נדירים שבהם מזהי ה-URI להפעלה זהים בכל הפלטפורמות, צריך לחזור על הפעולה בכל פלטפורמה.
// Required. Set this when you want recommended entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_TV)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV Android app
val playbackUriAndroid = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
.build()
// Optional. Set this when you want recommended entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri
.Builder()
.setPlatformType(PlatformType.TYPE_IOS)
.setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
.build()
val platformSpecificPlaybackUris =
Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)
// Provide appropriate rating for the system.
val contentRating = new RatingSystem
.Builder()
.setAgencyName("MPAA")
.setRating("PG-13")
.build()
תמונות של פוסטרים
לתמונות פוסטרים נדרשים מזהה URI ומאפייני פיקסלים (גובה ורוחב). כדי לטרגט גורמים שונים של פורמטים, כדאי לספק כמה תמונות של פוסטרים. עם זאת, חשוב לוודא שכל התמונות הן ביחס גובה-רוחב של 16:9 ובגובה מינימלי של 200 פיקסלים, כדי שהישות 'המלצות' תוצג בצורה נכונה, במיוחד במרחב הבידור של Google. יכול להיות שתמונות בגובה של פחות מ-200 פיקסלים לא יוצגו.
Image image1 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
.setImageHeightInPixel(300)
.setImageWidthInPixel(169)
.build()
Image image2 = new Image.Builder()
.setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
.setImageHeightInPixel(640)
.setImageWidthInPixel(360)
.build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)
הסיבה להמלצה
אפשר לספק סיבה להמלצה, שמערכת Google TV תוכל להשתמש בה כדי ליצור סיבות להצעת סרט או תוכנית טלוויזיה ספציפיים למשתמש.
//Allows us to construct reason: "Because it is top 10 on your Channel"
val topOnPartner = RecommendationReasonTopOnPartner
.Builder()
.setNum(10) //any valid integer value
.build()
//Allows us to construct reason: "Because it is popular on your Channel"
val popularOnPartner = RecommendationReasonPopularOnPartner
.Builder()
.build()
//Allows us to construct reason: "New to your channel, or Just added"
val newOnPartner = RecommendationReasonNewOnPartner
.Builder()
.build()
//Allows us to construct reason: "Because you watched Star Wars"
val watchedSimilarTitles = RecommendationReasonWatchedSimilarTitles
.addSimilarWatchedTitleName("Movie or TV Show Title")
.addSimilarWatchedTitleName("Movie or TV Show Title")
.Builder()
.build()
//Allows us to construct reason: "Recommended for you by ChannelName"
val recommendedForUser = RecommendationReasonRecommendedForUser
.Builder()
.build()
val watchAgain = RecommendationReasonWatchAgain
.Builder()
.build()
val fromUserWatchList = RecommendationReasonFromUserWatchlist
.Builder()
.build()
val userLikedOnPartner = RecommendationReasonUserLikedOnPartner
.Builder()
.setTitleName("Movie or TV Show Title")
.build()
val generic = RecommendationReasonGeneric.Builder().build()
חלון הזמן להצגה
אם ישות צריכה להיות זמינה רק לזמן מוגבל, צריך להגדיר לה זמן תפוגה מותאם אישית. ללא תאריך תפוגה מפורש, התוקף של הישויות יפוג באופן אוטומטי והן יימחקו אחרי 60 יום. לכן, כדאי להגדיר מועד תפוגה רק אם אתם רוצים שהישויות יפוג תוקפן מוקדם יותר. אפשר לציין כמה חלונות זמינות כאלה.
val window1 = DisplayTimeWindow
.Builder()
.setStartTimeStampMillis(now()+ 1.days.toMillis())
.setEndTimeStampMillis(now()+ 30.days.toMillis())
val window2 = DisplayTimeWindow
.Builder()
.setEndTimeStampMillis(now()+ 30.days.toMillis())
val availabilityTimeWindows: List<DisplayTimeWindow> = listof(window1,window2)
DataFeedElementId
אם שילבתם את קטלוג המדיה או את פיד הפעולות של המדיה עם Google TV, אין צורך ליצור ישויות נפרדות לסרט או לתוכנית טלוויזיה. במקום זאת, תוכלו ליצור ישות MediaActionFeed שכוללת את השדה הנדרש DataFeedElementId. המזהה הזה חייב להיות ייחודי ולהתאים למזהה בפיד של פעולות המדיה, כי הוא עוזר לזהות את תוכן הפיד שעבר הטמעה ולבצע חיפושים של תוכן מדיה.
val id = "dataFeedEleemntId"
MovieEntity
דוגמה ליצירת MovieEntity
עם כל השדות הנדרשים:
val movieEntity = MovieEntity.Builder()
.setName("Movie name")
.setDescription("A sentence describing movie.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
// Suppose the duration is 2 hours, it is 72000000 in milliseconds
.setDurationMills(72000000)
.build()
אתם יכולים לספק נתונים נוספים כמו ז'אנרים, דירוגים של תוכן, תאריך פרסום, הסיבה להמלצה וחלונות זמינות. Google TV עשויה להשתמש בנתונים האלה לצורכי סינון או להצגה משופרת.
val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("pg-13").build();
val contentRatings = Arrays.asList(rating1);
//Suppose release date is 11-02-2025
val releaseDate = 1739233800000L
val movieEntity = MovieEntity.Builder()
...
.addGenres(genres)
.setReleaseDateEpochMillis(releaseDate)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.build()
TvShowEntity
דוגמה ליצירת TvShowEntity
עם כל השדות הנדרשים:
val tvShowEntity = TvShowEntity.Builder()
.setName("Show title")
.setDescription("A sentence describing TV Show.")
.addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
.addPosterImages(images)
.build();
אפשר גם לספק נתונים נוספים, כמו ז'אנרים, דירוגים של תוכן, הסיבה להמלצה, מחיר המבצע, מספר העונות או חלון הזמינות, שמערכת Google TV עשויה להשתמש בהם למטרות של תצוגות משופרות או סינון.
val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder()
.setAgencyName("MPAA")
.setRating("pg-13")
.build();
val price = Price.Builder()
.setCurrentPrice("$14.99")
.setStrikethroughPrice("$16.99")
.build();
val contentRatings = Arrays.asList(rating1);
val seasonCount = 5;
val tvShowEntity = TvShowEntity.Builder()
...
.addGenres(genres)
.addContentRatings(contentRatings)
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addAllAvailabilityTimeWindows(availabilityTimeWindows)
.setSeasonCount(seasonCount)
.setPrice(price)
.build()
MediaActionFeedEntity
דוגמה ליצירת MediaActionFeedEntity
עם כל השדות הנדרשים:
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setDataFeedElementId(id)
.build()
אפשר גם לספק נתונים נוספים, כמו תיאור, הסיבה להמלצה וחלון זמן להצגה. Google TV עשויה להשתמש בנתונים האלה למטרות של תצוגות משופרות או סינון.
val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
.setName("Movie name or TV Show name")
.setDescription("A sentence describing an entity")
.setRecommendationReason(topOnPartner or watchedSimilarTitles)
.addPosterImages(images)
.build()
בעזרת ההוראות האלה, מפתחים יכולים לשלב המלצות לתוכן וידאו ב-Google TV, וכך לשפר את חוויית הצפייה של המשתמשים ולספק להם חוויה עקבית ומותאמת אישית בכל המכשירים שלהם.