Engage SDK für Videoempfehlungen

In diesem Leitfaden wird beschrieben, wie Entwickler empfohlene Videoinhalte mit dem Engage SDK einbinden, um Empfehlungen auf verschiedenen Google-Plattformen wie Fernsehern, Smartphones und Tablets zu präsentieren.

Bei Empfehlungen wird der Empfehlungscluster verwendet, um Filme und Serien aus mehreren Apps in einer UI-Gruppierung anzuzeigen. Jeder Entwicklerpartner kann in jedem Empfehlungscluster maximal 25 Entitäten übertragen. Pro Anfrage können maximal 7 Empfehlungscluster vorhanden sein.

Vorarbeit

Führen Sie zuerst die folgenden Schritte aus. 1. Prüfen Sie, ob Ihre App für diese Integration auf API-Level 19 oder höher ausgerichtet ist.

  1. Fügen Sie der App die com.google.android.engage-Bibliothek hinzu.

    Für die Integration gibt es separate SDKs: eines für mobile Apps und eines für TV-Apps.

    Für Mobilgeräte

    
  dependencies {
    implementation 'com.google.android.engage:engage-core:1.5.5
  }

    für TV

    
  dependencies {
    implementation 'com.google.android.engage:engage-tv:1.0.2
  }

  2. Legen Sie in der Datei AndroidManifest.xml die Umgebung des Engage-Dienstes auf „Produktion“ fest.

    Für mobile apk

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

    For tv apk

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

  3. Führen Sie die Veröffentlichung für einen Dienst im Vordergrund aus.

  4. Empfehlungendaten höchstens einmal täglich veröffentlichen, ausgelöst durch

    1. Die erste Anmeldung des Nutzers am Tag. (oder)
    2. Wenn der Nutzer mit der Anwendung interagiert.

Integration

AppEngagePublishClient veröffentlicht den Empfehlungscluster. Verwenden Sie die Methode publishRecommendationClusters, um ein Empfehlungsobjekt zu veröffentlichen.

Mit isServiceAvailable()2 können Sie prüfen, ob der Dienst für die Einbindung verfügbar ist.

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.
  }
}

Empfehlungscluster und eine Veröffentlichungsanfrage

Cluster sind eine logische Gruppierung der Entitäten. In den folgenden Codebeispielen wird erläutert, wie Sie die Cluster entsprechend Ihren Anforderungen erstellen und eine Veröffentlichungsanfrage für alle Cluster erstellen.

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

Kontoprofil erstellen

Geben Sie Konto- und Profilinformationen an, damit Google TV personalisiert werden kann. Verwenden Sie AccountProfile, um Folgendes anzugeben:

  1. Konto-ID: Eine eindeutige Kennung, die das Konto des Nutzers in Ihrer Anwendung darstellt. Dies kann die tatsächliche Konto-ID oder eine entsprechend verschleierte Version sein.
  2. Profil-ID (optional): Wenn Ihre Anwendung mehrere Profile innerhalb eines einzelnen Kontos unterstützt, geben Sie eine eindeutige Kennung für das jeweilige Nutzerprofil an.
  3. Sprache(optional): Sie können die bevorzugte Sprache des Nutzers angeben. Dieses Feld ist nützlich, wenn Sie MediaActionFeedEntity in der RecommendationRequest senden.
// 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();

Wenn der Dienst die Anfrage erhält, werden innerhalb einer Transaktion die folgenden Aktionen ausgeführt:

  • Vorhandene RecommendationsCluster-Daten des Entwicklerpartners werden entfernt.
  • Die Daten aus der Anfrage werden analysiert und in der aktualisierten RecommendationsCluster gespeichert. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status bleibt erhalten.

Geräteübergreifende Synchronisierung

Mit dem Flag SyncAcrossDevices wird festgelegt, ob die Clusterdaten für Empfehlungen eines Nutzers mit Google TV geteilt und auf allen seinen Geräten wie Fernsehern, Smartphones und Tablets verfügbar sind. Damit die Empfehlung funktioniert, muss sie auf „wahr“ gesetzt sein.

Die Medienanwendung muss eine eindeutige Einstellung zur Aktivierung oder Deaktivierung der geräteübergreifenden Synchronisierung bieten. Erläutern Sie die Vorteile für den Nutzer und speichern Sie die Einstellung des Nutzers einmal und wenden Sie sie entsprechend in publishRecommendations Anfrage an. Damit Sie die geräteübergreifende Funktion optimal nutzen können, prüfen Sie, ob die App die Nutzereinwilligung einholt und SyncAcrossDevices bis true aktiviert.

Daten zur Videosuche löschen

Wenn du die Daten eines Nutzers vor Ablauf der standardmäßigen Aufbewahrungsfrist von 60 Tagen manuell vom Google TV-Server löschen möchtest, verwende die Methode client.deleteClusters(). Nach Erhalt des Antrags löscht der Dienst alle vorhandenen Daten zur Videosuche für das Kontoprofil oder für das gesamte Konto.

Das DeleteReason-Enum definiert den Grund für das Löschen von Daten. Mit dem folgenden Code werden Empfehlungen beim Logout entfernt.

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

Entitäten erstellen

Im SDK sind verschiedene Entitäten für jeden Artikeltyp definiert. Die folgenden Entitäten werden für den Empfehlungscluster unterstützt:

  1. MediaActionFeedEntity
  2. MovieEntity
  3. TvShowEntity

Beschreibung

Geben Sie für jede Entität eine kurze Beschreibung an. Diese Beschreibung wird angezeigt, wenn Nutzer den Mauszeiger auf die Entität bewegen, und enthält zusätzliche Details.

Plattformspezifische Wiedergabe-URIs

Erstelle Wiedergabe-URIs für jede unterstützte Plattform: Android TV, Android oder iOS. So kann das System den richtigen URI für die Videowiedergabe auf der jeweiligen Plattform auswählen.

In dem seltenen Fall, dass die Wiedergabe-URIs für alle Plattformen identisch sind, wiederhole den Vorgang für jede Plattform.

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

Posterbilder

Für Posterbilder sind ein URI und Pixelabmessungen (Höhe und Breite) erforderlich. Du kannst verschiedene Formfaktoren anvisieren, indem du mehrere Posterbilder angibst. Achte aber darauf, dass alle Bilder ein Seitenverhältnis von 16:9 und eine Mindesthöhe von 200 Pixeln haben, damit die Entität „Empfehlungen“ korrekt angezeigt wird, insbesondere im Entertainment Space von Google. Bilder mit einer Höhe von weniger als 200 Pixeln werden möglicherweise nicht angezeigt.

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)

Grund für Empfehlung

Optional können Sie einen Empfehlungsgrund angeben, der von Google TV verwendet werden kann, um dem Nutzer Gründe dafür zu nennen, warum ihm ein bestimmter Film oder eine bestimmte Serie empfohlen wird.

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

Zeitfenster für die Anzeige

Wenn eine Entität nur für begrenzte Zeit verfügbar sein soll, legen Sie eine benutzerdefinierte Ablaufzeit fest. Ohne explizite Ablaufzeit laufen Entitäten nach 60 Tagen automatisch ab und werden gelöscht. Legen Sie also nur dann ein Ablaufdatum fest, wenn die Entitäten früher ablaufen sollen. Sie können mehrere solcher Verfügbarkeitszeiträume angeben.

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

Wenn Sie Ihren Medienkatalog oder Media-Aktionsfeed in Google TV eingebunden haben, müssen Sie keine separaten Entitäten für Filme oder Serien erstellen. Stattdessen können Sie eine MediaActionFeed-Entität mit dem erforderlichen Feld „DataFeedElementId“ erstellen. Diese ID muss eindeutig sein und mit der ID im Media Action-Feed übereinstimmen. So können aufgenommene Feedinhalte identifiziert und Medieninhalte abgerufen werden.

val id = "dataFeedEleemntId"

MovieEntity

Hier ein Beispiel für das Erstellen einer MovieEntity mit allen erforderlichen Feldern:


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

Du kannst zusätzliche Daten wie Genres, Altersfreigaben, Veröffentlichungsdatum, Empfehlungsgrund und Verfügbarkeitszeiträume angeben, die von Google TV für erweiterte Darstellungen oder Filterzwecke verwendet werden können.

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

Hier ein Beispiel für das Erstellen einer TvShowEntity mit allen erforderlichen Feldern:

val tvShowEntity = TvShowEntity.Builder()
  .setName("Show title")
  .setDescription("A sentence describing TV Show.")
  .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
  .addPosterImages(images)
  .build();

Optional kannst du zusätzliche Daten wie Genres, Altersfreigaben, Empfehlungsgrund, Angebotspreis, Staffelanzahl oder Verfügbarkeitszeitraum angeben. Diese Daten können von Google TV für erweiterte Darstellungen oder Filterzwecke verwendet werden.

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

Hier ein Beispiel für das Erstellen eines MediaActionFeedEntity mit allen erforderlichen Feldern:


val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setDataFeedElementId(id)
  .build()

Optional können Sie zusätzliche Daten wie eine Beschreibung, den Grund für die Empfehlung und das Zeitfenster für die Anzeige angeben. Diese Daten können von Google TV für erweiterte Anzeigen oder Filterzwecke verwendet werden.

val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setName("Movie name or TV Show name")
  .setDescription("A sentence describing an entity")
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addPosterImages(images)
  .build()

Wenn Entwickler diese Schritte ausführen, können sie Empfehlungen für Videoinhalte in Google TV einbinden. So werden die Entdeckung und Interaktion von Inhalten für Nutzer gefördert und sie erhalten auf allen ihren Geräten eine einheitliche und personalisierte Wiedergabe.