איך משלבים המלצות במכשיר באמצעות Engage SDK

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

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

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

הכנה

מבצעים את ההוראות בקטע Pre-work במדריך לתחילת העבודה.

  1. מבצעים את הפרסום בשירות שפועל בחזית.
  2. פרסום נתוני ההמלצות פעם ביום לכל היותר, כתוצאה מאחד מהאירועים הבאים:
    • ההתחברות הראשונה של המשתמש באותו יום. (או)
    • כשהמשתמש מתחיל לבצע אינטראקציה עם האפליקציה.

שילוב

‫AppEngagePublishClient מפרסם את אשכול ההמלצות. משתמשים ב-method‏ publishRecommendationClusters כדי לפרסם אובייקט המלצות.

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

client.publishRecommendationClusters(recommendationRequest)

עדכון או הוספה (upsert) של אשכולות המלצות

אשכולות הם קיבוץ לוגי של הישויות. בדוגמאות הקוד הבאות מוסבר איך ליצור את האשכולות לפי ההעדפות שלכם, ואיך ליצור בקשת פרסום ולעדכן או להוסיף (upsert) את כל האשכולות.

הערך של RecommendationClusterType קובע איך האשכול יוצג.

// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
  .Builder()
  .addEntity(movie1)
  .addEntity(movie2)
  .addEntity(movie3)
  .addEntity(movie4)
  .addEntity(tvShow)
  // This cluster is meant to be used as an individual provider row
  .setRecommendationClusterType(TYPE_PROVIDER_ROW)
  .setTitle("Popular Movies")
  .build()

// cluster for live TV programs
val recommendationCluster2 = RecommendationCluster
  .Builder()
  .addEntity(liveTvProgramEntity1)
  .addEntity(liveTvProgramEntity2)
  .addEntity(liveTvProgramEntity3)
  .addEntity(liveTvProgramEntity4)
  .addEntity(liveTvProgramEntity5)
 // This cluster is meant to be used as an individual provider row
  .setRecommendationClusterType(TYPE_PROVIDER_ROW)
  .setTitle("Popular Live TV Programs")
  .build()

// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
  .Builder()
  .setSyncAcrossDevices(true)
  .setAccountProfile(accountProfile)
  .addRecommendationCluster(recommendationCluster1)
  .addRecommendationCluster(recommendationCluster2)
  .build()

כשהשירות מקבל את הבקשה, הפעולות הבאות מתרחשות בטרנזקציה אחת:

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

סנכרון בין מכשירים

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

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

מחיקת הנתונים של Engage

כדי למחוק באופן ידני נתונים של משתמש מהשרת של Google TV לפני תקופת השמירה הרגילה של 60 יום, צריך להשתמש ב-method‏ client.deleteClusters(). כשהשירות מקבל את הבקשה, הוא מוחק את כל נתוני Engage הקיימים בפרופיל החשבון או בחשבון כולו.

ה-enum‏ 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(
  DeleteClustersRequest.Builder()
    .setAccountProfile(accountProfile)
    .setDeleteReason(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(
  DeleteClustersRequest.Builder()
    .setAccountProfile(accountProfile)
    .setDeleteReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

יצירת ישויות

ב-SDK מוגדרות ישויות שונות שמייצגות כל סוג פריט. אפשר להשתמש בישויות הבאות באשכול ההמלצות:

  1. MediaActionFeedEntity
  2. MovieEntity
  3. TvShowEntity
  4. LiveTvChannelEntity
  5. LiveTvProgramEntity

הוספת תיאורים

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

טקסט של קריאה לפעולה

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

תגים

אפשר לספק רשימה של תגים לכל ישות. אפשר להשתמש בתגים כדי לסווג ולסנן.

מזהי 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 = RatingSystem
  .Builder()
  .setAgencyName("MPAA")
  .setRating("PG-13")
  .build()

תמונות של פוסטרים

תמונות של פוסטרים צריכות לכלול URI ומידות בפיקסלים (גובה ורוחב). כדי להתאים את התוכן למכשירים שונים, כדאי לספק כמה תמונות פוסטר. עם זאת, חשוב לוודא שלכל התמונות יש יחס גובה-רוחב של 16:9 וגובה מינימלי של 200 פיקסלים, כדי שהישות "המלצות" תוצג בצורה נכונה, במיוחד בחבילת הבידור של Google. יכול להיות שלא יוצגו תמונות שהגובה שלהן קטן מ-200 פיקסלים.

val image1 = Image.Builder()
  .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
  .setImageHeightInPixel(300)
  .setImageWidthInPixel(169)
  .build()

val image2 = 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
  .Builder()
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .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 userLikedTitle = RecommendationReasonUserLikedTitle
  .Builder()
  .setLikedTitleName("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())
  .build()

val window2 = DisplayTimeWindow
  .Builder()
  .setEndTimestampMillis(now() + 30.days.toMillis())
  .build()

val availabilityTimeWindows: List<DisplayTimeWindow> = listOf(window1, window2)

DataFeedElementId

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

val id = "dataFeedElementId"

MovieEntity

דוגמה ליצירת MovieEntity עם כל שדות החובה:

val movieEntity = MovieEntity.Builder()
  .setName("Movie name")
  .setDescription("A sentence describing movie.")
  .addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
  .addPosterImages(images)
  // Suppose the duration is 2 hours, it is 72000000 in milliseconds
  .setDurationMillis(72000000)
  .setCallToActionText("Watch Now")
  .addTag("Action")
  .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.")
  .addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
  .addPosterImages(images)
  .setCallToActionText("Watch Now")
  .addTag("Drama")
  .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)
  .setCallToActionText("Watch Now")
  .addTag("Action")
  .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()

LiveTvChannelEntity

זה מייצג ערוץ טלוויזיה בשידור חי. דוגמה ליצירת LiveTvChannelEntity עם כל שדות החובה:

val liveTvChannelEntity = LiveTvChannelEntity.Builder()
  .setName("Channel Name")
  // ID of the live TV channel
  .setEntityId("https://www.example.com/channel/12345")
  .setDescription("A sentence describing this live TV channel.")
  // channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
  .addPlatformSpecificPlaybackUris(channelPlaybackUris)
  .setLogoImage(logoImage)
  .setCallToActionText("Watch Now")
  .addTag("News")
  .build()

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

val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build()
val contentRatings = Arrays.asList(rating1)

val liveTvChannelEntity = LiveTvChannelEntity.Builder()
  ...
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner)
  .build()

LiveTvProgramEntity

זהו כרטיס של תוכנית טלוויזיה בשידור חי שמשודרת או מתוכננת לשידור בערוץ טלוויזיה בשידור חי. דוגמה ליצירת LiveTvProgramEntity עם כל שדות החובה:

val liveTvProgramEntity = LiveTvProgramEntity.Builder()
  // First set the channel information
  .setChannelName("Channel Name")
  .setChannelId("https://www.example.com/channel/12345")
  // channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
  .addPlatformSpecificPlaybackUris(channelPlaybackUris)
  .setChannelLogoImage(channelLogoImage)
  // Then set the program or card specific information.
  .setName("Program Name")
  .setEntityId("https://www.example.com/schedule/123")
  .setDescription("Program Description")
  .addAvailabilityTimeWindow(
      DisplayTimeWindow.Builder()
        .setStartTimestampMillis(1756713600000L) // 2025-09-01T07:30:00+0000
        .setEndTimestampMillis(1756715400000L) // 2025-09-01T08:00:00+0000
        .build()
  )
  .addPosterImage(programImage)
  .setCallToActionText("Watch Now")
  .addTag("Sports")
  .build()

אם רוצים, אפשר לספק נתונים נוספים כמו סיווגי תוכן, ז'אנרים או סיבה להמלצה.

val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build()
val contentRatings = Arrays.asList(rating1)
val genres = Arrays.asList("Action", "Science fiction")

val liveTvProgramEntity = LiveTvProgramEntity.Builder()
  ...
  .addContentRatings(contentRatings)
  .addGenres(genres)
  .setRecommendationReason(topOnPartner)
  .build()