Engage SDK להמלצות על סרטונים

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

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

עבודה מוקדמת

לפני שמתחילים, צריך לבצע את השלבים הבאים. 1. כדי לשלב את הרכיב הזה, צריך לוודא שהאפליקציה מטרגטת ל-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>
    

    ל-tv apk

    
    <meta-data
        android:name="com.google.android.engage.service.ENV"
        android:value="PRODUCTION">
    </meta-data>
    
  3. ביצוע פרסום בשירות שפועל בחזית.

  4. לפרסם את נתוני ההמלצות פעם ביום לכל היותר, בהתאם לאחד מהאירועים הבאים:

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

שילוב

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 כדי לספק:

  1. מזהה חשבון: מזהה ייחודי שמייצג את החשבון של המשתמש באפליקציה. זה יכול להיות מזהה החשבון בפועל או גרסה שעברה ערפול באופן מתאים.
  2. מזהה פרופיל (אופציונלי): אם האפליקציה תומכת במספר פרופילים בחשבון אחד, יש לספק מזהה ייחודי לפרופיל המשתמש הספציפי.
  3. אזור(אופציונלי): אפשר לציין את השפה המועדפת של המשתמש. השדה הזה שימושי אם שולחים 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 מוגדרות ישויות שונות שמייצגות כל סוג פריט. יש תמיכה באובייקטים הבאים באשכול ההמלצות:

  1. MediaActionFeedEntity
  2. MovieEntity
  3. 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, וכך לשפר את חוויית הצפייה של המשתמשים ולספק להם חוויה עקבית ומותאמת אישית בכל המכשירים שלהם.