Engage SDK – Listen: Anleitung zur technischen Integration von Drittanbietern

Google entwickelt eine On-Device-Oberfläche, auf der die Apps der Nutzer nach Branchen organisiert werden. So können Nutzer personalisierte App-Inhalte noch besser entdecken und nutzen. Diese Vollbildansicht bietet Entwicklerpartnern die Möglichkeit, ihre besten Inhalte in einem speziellen Kanal außerhalb ihrer App zu präsentieren.

Dieser Leitfaden enthält eine Anleitung für Entwicklerpartner, wie sie ihre Audioinhalte mit dem Engage SDK einbinden, um sowohl diese neue Oberfläche als auch bestehende Google-Oberflächen zu befüllen.

Integrationsdetails

Terminologie

Diese Integration umfasst die folgenden drei Clustertypen: Empfehlung, Fortsetzung und Empfohlen.

  • In Clustern vom Typ Empfehlung werden personalisierte Lesevorschläge von einem einzelnen Entwicklerpartner angezeigt.

    Ihre Empfehlungen haben folgende Struktur:

    • Empfehlungscluster:Eine UI-Ansicht, die eine Gruppe von Empfehlungen desselben Entwicklerpartners enthält.

      Abbildung 1. Benutzeroberfläche von Entertainment Space mit einem Empfehlungscluster von einem einzelnen Partner
    • Entität: Ein Objekt, das ein einzelnes Element in einem Cluster darstellt. Ein Element kann beispielsweise eine Playlist, ein Hörbuch oder ein Podcast sein. Eine Liste der unterstützten Entitätstypen finden Sie im Abschnitt Entitätsdaten bereitstellen.

      Abbildung 2. Benutzeroberfläche von Entertainment Space mit einer einzelnen Entität im Empfehlungscluster eines einzelnen Partners.
  • Im Cluster Fortsetzung werden Audioinhalte von mehreren Entwicklerpartnern in einer einzigen UI-Gruppierung angezeigt, mit denen Nutzer in letzter Zeit interagiert haben. Jeder Entwicklerpartner darf maximal 10 Entitäten im Fortsetzungscluster übertragen.

    Abbildung 3: Benutzeroberfläche von Entertainment Space mit einem Fortsetzungscluster mit nicht abgeschlossenen Empfehlungen von mehreren Partnern (derzeit ist nur eine Empfehlung zu sehen).
  • Der Cluster Empfohlen enthält eine Auswahl von Elementen verschiedener Entwicklerpartner in einer einzigen UI-Gruppierung. Es gibt einen einzelnen „Empfohlen“-Cluster, der oben in der Benutzeroberfläche mit Vorrang vor allen Empfehlungsclustern angezeigt wird. Jeder Entwicklerpartner kann bis zu zehn Entitäten im Cluster „Empfohlen“ übertragen.

    Abbildung 4: Die Benutzeroberfläche von Entertainment Space mit einem „Empfohlen“-Cluster mit Empfehlungen von mehreren Partnern (derzeit ist nur eine Empfehlung zu sehen).

Vorarbeit

Mindest-API-Level: 19

Fügen Sie Ihrer App die com.google.android.engage:engage-core-Bibliothek hinzu:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

Zusammenfassung

Das Design basiert auf einer Implementierung eines gebundenen Dienstes.

Die Daten, die ein Kunde veröffentlichen kann, unterliegen den folgenden Einschränkungen für verschiedene Clustertypen:

Clustertyp Cluster limits Maximale Entitätslimits in einem Cluster
Empfehlungscluster Höchstens 7 Maximal 50
Fortsetzungscluster Maximal 1 Maximal 20
Empfohlener Cluster Maximal 1 Maximal 20

Schritt 1: Entitätsdaten angeben

Im SDK sind verschiedene Entitäten für jeden Artikeltyp definiert. Für die Kategorie „Anhören“ werden die folgenden Entitäten unterstützt:

  1. MusicAlbumEntity
  2. MusicArtistEntity
  3. MusicTrackEntity
  4. MusicVideoEntity
  5. PlaylistEntity
  6. PodcastSeriesEntity
  7. PodcastEpisodeEntity
  8. LiveRadioStationEntity
  9. AudiobookEntity

In den folgenden Diagrammen sind die verfügbaren Attribute und Anforderungen für jeden Typ aufgeführt.

MusicAlbumEntity

Das MusicAlbumEntity-Objekt steht für ein Musikalbum, z. B. Midnights von Taylor Swift.

Attribut Anforderung Hinweise
Name Erforderlich Der Titel des Musikalbums.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
URI der Infoseite Erforderlich

Der Deeplink zur Anbieter-App mit Details zum Musikalbum.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Künstler Erforderlich Liste der Künstler im Musikalbum.
Wiedergabe-URI Optional

Ein Deeplink, über den die Wiedergabe des Albums in der Anbieter-App gestartet wird.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Anzahl der Titel Optional Die Anzahl der Songs im Musikalbum.
Genres Optional Liste der Genres im Musikalbum.
Albumformat Optional

ALBUM (einschließlich LP und Doppel-LP)

EP

EINZIGES

Mixtape

Musiklabels Optional Liste der Musiklabels, die mit dem Album verknüpft sind.
Auf dem Gerät heruntergeladen Optional Boolescher Wert, der angibt, ob das Musikalbum auf das Gerät heruntergeladen wurde.
Explizit Optional

Ein boolescher Wert, der angibt, ob die Inhalte explizit sind

Für Elemente, die anstößige Inhalte enthalten oder eine Altersfreigabe haben, sollte „TRUE“ festgelegt werden. Anstößige Inhalte sind mit dem Tag „E“ gekennzeichnet.

Erscheinungsdatum Optional Das Erscheinungsdatum des Albums in Epoch-Millisekunden.
Dauer Optional Die Dauer des Albums in Millisekunden.
Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

Prozentsatz des Fortschritts Optional

Empfohlen für Artikel im Fortsetzungscluster.

Ganzzahl zwischen 0 und 100

MusicArtistEntity

Das MusicArtistEntity-Objekt steht für einen Musiker (z. B. Adele).

Attribut Anforderung Hinweise
Name Erforderlich Name des Musikkünstlers.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
URI der Infoseite Erforderlich

Der Deeplink zur Anbieter-App mit Details zum Künstler.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Wiedergabe-URI Optional

Der Deeplink, über den die Songs des Künstlers in der Anbieter-App wiedergegeben werden.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

MusicTrackEntity

Das MusicTrackEntity-Objekt steht für einen Musiktitel, z. B. Yellow von Coldplay.

Attribut Anforderung Hinweise
Name Erforderlich Titel des Musiktitels.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
Wiedergabe-URI Erforderlich

Ein Deeplink, über den die Wiedergabe des Musiktitels in der Anbieter-App gestartet wird.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Künstler Erforderlich Liste der Künstler für den Musiktitel.
URI der Infoseite Optional

Ein Deeplink zur Anbieter-App mit Details zum Musiktitel.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Dauer Optional Die Dauer des Titels in Millisekunden.
Album Optional Der Name des Albums, zu dem der Titel gehört.
Auf dem Gerät heruntergeladen Optional Boolescher Wert, der angibt, ob der Musiktitel auf das Gerät heruntergeladen wurde.
Explizit Optional

Ein boolescher Wert, der angibt, ob die Inhalte explizit sind

Für Elemente, die anstößige Inhalte enthalten oder eine Altersfreigabe haben, sollte „TRUE“ festgelegt werden. Anstößige Inhalte sind mit dem Tag „E“ gekennzeichnet.

Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

Prozentsatz des Fortschritts Optional

Empfohlen für Artikel im Fortsetzungscluster.

Ganzzahl zwischen 0 und 100

MusicVideoEntity

Das MusicVideoEntity-Objekt steht für ein Musikvideo, z. B. The Weeknd – Take My Breath (Official Music Video).

Attribut Anforderung Hinweise
Name Erforderlich Titel des Musikvideos.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
Wiedergabe-URI Erforderlich

Ein Deeplink, über den das Musikvideo in der App des Anbieters wiedergegeben wird.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

URI der Infoseite Optional

Ein Deeplink zur Anbieter-App mit Details zum Musikvideo.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Dauer Optional Dauer des Videos in Millisekunden.
Anzahl der Aufrufe Optional Die Anzahl der Aufrufe des Videos im Freitextformat.
Künstler Optional Liste der Künstler des Musikvideos.
Altersfreigabe Optional Liste der Altersfreigaben des Titels.
Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Auf dem Gerät heruntergeladen Optional Boolescher Wert, der angibt, ob das Musikvideo auf das Gerät heruntergeladen wurde.
Explizit Optional

Ein boolescher Wert, der angibt, ob die Inhalte explizit sind

Für Elemente, die anstößige Inhalte enthalten oder eine Altersfreigabe haben, sollte „TRUE“ festgelegt werden. Anstößige Inhalte sind mit dem Tag „E“ gekennzeichnet.

Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

Prozentsatz des Fortschritts Optional

Empfohlen für Artikel im Fortsetzungscluster.

Ganzzahl zwischen 0 und 100

PlaylistEntity

Das PlaylistEntity-Objekt steht für eine Musikplaylist, z. B. die Top 10-Playlist der USA.

Attribut Anforderung Hinweise
Name Erforderlich Titel der Playlist.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
Wiedergabe-URI Erforderlich

Ein Deeplink, über den die Musikplaylist in der Anbieter-App wiedergegeben wird.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

URI der Infoseite Optional

Ein Deeplink zur Anbieter-App mit Details zur Musikplaylist.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Dauer Optional Die Dauer der Playlist in Millisekunden.
Anzahl der Titel Optional Die Anzahl der Songs in der Musikplaylist.
Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Auf dem Gerät heruntergeladen Optional Boolescher Wert, der angibt, ob die Playlist auf das Gerät heruntergeladen wurde.
Explizit Optional

Ein boolescher Wert, der angibt, ob die Inhalte explizit sind

Für Elemente, die anstößige Inhalte enthalten oder eine Altersfreigabe haben, sollte „TRUE“ festgelegt werden. Anstößige Inhalte sind mit dem Tag „E“ gekennzeichnet.

Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

Prozentsatz des Fortschritts Optional

Empfohlen für Artikel im Fortsetzungscluster.

Ganzzahl zwischen 0 und 100

PodcastSeriesEntity

Das PodcastSeriesEntity-Objekt steht für eine Podcastreihe (z. B. This American Life).

Attribut Anforderung Hinweise
Name Erforderlich Titel der Podcastreihe.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
URI der Infoseite Erforderlich

Ein Deeplink zur Anbieter-App mit Details zur Podcastreihe.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Wiedergabe-URI Optional

Ein Deeplink, über den die Podcastreihe in der Anbieter-App wiedergegeben wird.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Anzahl der Folgen Optional Die Anzahl der Folgen in der Podcastreihe.
Produktionsname Optional Der Name der Produktion der Podcastreihe.
Hosts Optional Liste der Moderatoren der Podcast-Serie.
Genres Optional Liste der Genres der Podcastreihe.
Auf das Gerät heruntergeladen Optional Boolescher Wert, der angibt, ob der Podcast auf das Gerät heruntergeladen wurde.
Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Explizit Optional

Ein boolescher Wert, der angibt, ob die Inhalte explizit sind

Für Elemente, die anstößige Inhalte enthalten oder eine Altersfreigabe haben, sollte „TRUE“ festgelegt werden. Anstößige Inhalte sind mit dem Tag „E“ gekennzeichnet.

Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

PodcastEpisodeEntity

Das PodcastEpisodeEntity-Objekt steht für eine Podcastreihe (z. B. Spark Bird, Folge 754: This American Life).

Attribut Anforderung Hinweise
Name Erforderlich Der Titel der Podcastfolge.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
Wiedergabe-URI Erforderlich

Ein Deeplink, über den die Podcastfolge in der Anbieter-App wiedergegeben wird.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Titel der Podcast-Serie Erforderlich Der Name der Podcastreihe, zu der die Folge gehört.
Dauer Erforderlich Die Dauer der Podcastfolge in Millisekunden.
Publish Date Erforderlich Veröffentlichungsdatum des Podcasts (in Epoch-Millisekunden)
URI der Infoseite Optional

Ein Deeplink zur Anbieter-App mit Details zur Podcastfolge.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Produktionsname Optional Der Name der Produktion der Podcastreihe.
Folgenindex Optional Der Index der Folge in der Serie (der erste Index ist 1).
Hosts Optional Liste der Moderatoren der Podcastfolge.
Genres Optional Liste der Genres der Podcastfolge.
Auf das Gerät heruntergeladen Optional Boolescher Wert, der angibt, ob die Podcastfolge auf das Gerät heruntergeladen wurde.
Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Video-Podcast Optional Boolescher Wert, der angibt, ob die Podcastfolge Videoinhalte enthält
Explizit Optional

Ein boolescher Wert, der angibt, ob die Inhalte explizit sind

Für Elemente, die anstößige Inhalte enthalten oder eine Altersfreigabe haben, sollte „TRUE“ festgelegt werden. Anstößige Inhalte sind mit dem Tag „E“ gekennzeichnet.

Typ für „Als Nächstes anhören“ Optional

Empfohlen für Elemente im Fortsetzungscluster

TYPE_CONTINUE – Fortsetzung eines nicht abgeschlossenen Audioelements.

TYPE_NEXT: Mit einem neuen Element einer Reihe fortfahren.

TYPE_NEW – Neu veröffentlicht.

Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

Prozentsatz des Fortschritts Optional

Empfohlen für Artikel im Fortsetzungscluster.

Ganzzahl zwischen 0 und 100

LiveRadioStationEntity

Das LiveRadioStationEntity-Objekt steht für einen Live-Radiosender (z. B. 98.1 The Breeze).

Attribut Anforderung Hinweise
Name Erforderlich Titel des Live-Radiosenders.
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
Wiedergabe-URI Erforderlich

Ein Deeplink, über den der Radiosender in der Anbieter-App wiedergegeben wird.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

URI der Infoseite Optional

Ein Deeplink zur Anbieter-App mit Details zum Radiosender.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Häufigkeit Optional Die Frequenz, mit der der Radiosender ausgestrahlt wird (z. B. „98,1 FM“).
Titel der Serie Optional Die aktuelle Sendung, die auf dem Radiosender läuft.
Hosts Optional Liste der Moderatoren des Radiosenders.
Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Zeitpunkt der letzten Interaktion Optional

Empfohlen für Artikel im Fortsetzungscluster. Kann für das Ranking verwendet werden.

In Epochen-Millisekunden

AudiobookEntity

Das AudiobookEntity-Objekt steht für ein Hörbuch, z. B. das Hörbuch Becoming von Michelle Obama.

Attribut Anforderung Hinweise
Name Erforderlich
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Anforderungen an Bilder.
Autor Erforderlich Es muss mindestens ein Autor angegeben werden.
Narrator Erforderlich Es muss mindestens der Name eines Erzählers angegeben werden.
URI des Aktionslinks Erforderlich

Der Deeplink zur Anbieter-App für das Hörbuch.

Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen finden Sie in dieser FAQ.

Veröffentlichungsdatum Optional In Epoch-Millisekunden, falls angegeben.
Beschreibung Optional Muss maximal 200 Zeichen lang sein.
Preis Optional Freier Text
Dauer Optional Muss ein positiver Wert sein, falls angegeben.
Genre Optional Liste der Genres, die mit dem Buch verknüpft sind.
Name der Reihe Optional Name der Reihe, zu der das Hörbuch gehört (z. B. Harry Potter).
Index der Reiheneinheit Optional Der Index des Hörbuchs in der Reihe. Die Nummer 1 steht für das erste Hörbuch in der Reihe. Wenn Harry Potter und der Gefangene von Askaban beispielsweise das dritte Buch der Reihe ist, sollte hier die Zahl 3 festgelegt werden.
Art des Weiterlesen-Buchs Optional

TYPE_CONTINUE – Fortsetzen eines unvollendeten Buchs.

TYPE_NEXT: Mit einem neuen Element einer Reihe fortfahren.

TYPE_NEW – Neu veröffentlicht.

Zeitpunkt der letzten Interaktion Bedingt erforderlich

Muss angegeben werden, wenn sich der Artikel im Fortsetzungscluster befindet.

In Epochen-Millisekunden.

Prozentsatz des Fortschritts Bedingt erforderlich

Muss angegeben werden, wenn sich der Artikel im Fortsetzungscluster befindet.

*Kürzlich* erworbene Hörbücher können Teil des Clusters „Weiterlesen“ sein.

Der Wert muss größer als 0 und kleiner als 100 sein.

DisplayTimeWindow: Legt ein Zeitfenster für die Anzeige von Inhalten auf der Oberfläche fest.
Startzeitstempel Optional

Der Epoch-Zeitstempel, nach dem die Inhalte auf der Oberfläche angezeigt werden sollen.

Wenn sie nicht festgelegt ist, können Inhalte auf der Oberfläche präsentiert werden.

In Epochen-Millisekunden.

Endzeitstempel Optional

Der Epoch-Zeitstempel, nach dem die Inhalte nicht mehr angezeigt werden.

Wenn sie nicht festgelegt ist, können Inhalte auf der Oberfläche präsentiert werden.

In Epochen-Millisekunden.

Bildspezifikationen

Die erforderlichen Spezifikationen für Bild-Assets finden Sie unten:

Seitenverhältnis Anforderung Mindestanzahl Pixel Empfohlene Pixel
Quadratisch (1 × 1) Erforderlich 300 × 300 1200 × 1200
Querformat (1,91 × 1) Optional 600 × 314 1.200 × 628
Hochformat (4 : 5) Optional 480 x 600 960 × 1.200

Dateiformate

PNG, JPG, statisches GIF, WebP

Maximale Dateigröße

5.120 KB

Weitere Empfehlungen

  • Bildbereich:Platzieren Sie wichtige Inhalte in den mittleren 80% des Bildes.

Beispiele

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();
AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

Schritt 2: Clusterdaten angeben

Wir empfehlen, den Job zum Veröffentlichen von Inhalten im Hintergrund auszuführen (z. B. mit WorkManager) und regelmäßig oder auf Ereignisbasis zu planen (z. B. jedes Mal, wenn der Nutzer die App öffnet oder etwas in den Einkaufswagen gelegt hat).

AppEngagePublishClient ist für die Veröffentlichung von Clustern verantwortlich. Die folgenden APIs sind im Client verfügbar:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • deleteUserManagementCluster
  • deleteClusters

isServiceAvailable

Mit dieser API wird geprüft, ob der Dienst für die Einbindung verfügbar ist und ob die Inhalte auf dem Gerät präsentiert werden können.

Kotlin

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.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

publishRecommendationClusters

Mit dieser API wird eine Liste von RecommendationCluster-Objekten veröffentlicht.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

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

  • Vorhandene RecommendationCluster-Daten des Entwicklerpartners werden entfernt.
  • Die Daten aus der Anfrage werden analysiert und im aktualisierten Empfehlungscluster gespeichert.

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status bleibt erhalten.

publishFeaturedCluster

Mit dieser API wird eine Liste von FeaturedCluster-Objekten veröffentlicht.

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

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

  • Vorhandene FeaturedCluster-Daten des Entwicklerpartners werden entfernt.
  • Die Daten aus der Anfrage werden analysiert und im aktualisierten „Empfohlen“-Cluster gespeichert.

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status bleibt erhalten.

publishContinuationCluster

Mit dieser API wird ein ContinuationCluster-Objekt veröffentlicht.

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

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

  • Vorhandene ContinuationCluster-Daten des Entwicklerpartners werden entfernt.
  • Die Daten aus der Anfrage werden analysiert und im aktualisierten Fortsetzungscluster gespeichert.

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status bleibt erhalten.

publishUserAccountManagementRequest

Mit dieser API wird eine Anmeldekarte veröffentlicht . Die Anmeldeaktion leitet Nutzer zur Anmeldeseite der App weiter, damit die App Inhalte veröffentlichen oder personalisiertere Inhalte bereitstellen kann.

Die folgenden Metadaten sind Teil der Anmeldekarte:

Attribut Anforderung Beschreibung
Aktions-URI Erforderlich Deeplink zur Aktion (d.h. zur Anmeldeseite der App)
Bild Optional. Wenn nicht angegeben, muss „Titel“ angegeben werden.

Auf der Karte angezeigtes Bild

Bilder mit einem Seitenverhältnis von 16:9 und einer Auflösung von 1.264 x 712

Titel Optional. Wenn nicht angegeben, muss „Image“ angegeben werden. Titel auf der Karte
Aktionstext Optional Text im CTA (z.B. „Anmelden“)
Untertitel Optional Optionaler Untertitel auf der Karte

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

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

  • Vorhandene UserAccountManagementCluster-Daten des Entwicklerpartners werden entfernt.
  • Die Daten aus der Anfrage werden analysiert und im aktualisierten Cluster „UserAccountManagementCluster“ gespeichert.

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status bleibt erhalten.

updatePublishStatus

Wenn aus internen geschäftlichen Gründen keiner der Cluster veröffentlicht wird, empfehlen wir dringend, den Veröffentlichungsstatus mit der updatePublishStatus API zu aktualisieren. Das ist aus folgenden Gründen wichtig :

  • Der Status muss in allen Fällen angegeben werden, auch wenn die Inhalte veröffentlicht wurden (STATUS == PUBLISHED). Andernfalls können Dashboards nicht mit diesem expliziten Status gefüllt werden, um den Zustand und andere Messwerte deiner Integration zu vermitteln.
  • Wenn keine Inhalte veröffentlicht werden, der Integrationsstatus aber nicht fehlerhaft ist (STATUS == NOT_PUBLISHED), kann Google Warnungen in den Dashboards zur App-Integrität vermeiden. Hiermit wird bestätigt, dass Inhalte aufgrund einer erwarteten Situation aus Sicht des Anbieters nicht veröffentlicht werden.
  • Sie hilft Entwicklern, Aufschluss darüber zu geben, wann die Daten veröffentlicht werden und wann nicht.
  • Google kann die Statuscodes verwenden, um Nutzer zu bestimmten Aktionen in der App anzuregen, damit sie die App-Inhalte sehen oder überwinden können.

Folgende Veröffentlichungsstatuscodes sind zulässig :

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

Wenn die Inhalte aufgrund einer fehlenden Nutzeranmeldung nicht veröffentlicht werden, empfiehlt Google, die Anmeldekarte zu veröffentlichen. Wenn Anbieter die Anmeldekarte aus irgendeinem Grund nicht veröffentlichen können, empfehlen wir, die API updatePublishStatus mit dem Statuscode NOT_PUBLISHED_REQUIRES_SIGN_IN aufzurufen.

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

Mit dieser API können Sie den Inhalt von Empfehlungsclustern löschen.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Wenn der Dienst die Anfrage erhält, werden die vorhandenen Daten aus den Empfehlungsclustern entfernt. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status beibehalten.

deleteFeaturedCluster

Mit dieser API können Sie den Inhalt des „Empfohlen“-Clusters löschen.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Wenn der Dienst die Anfrage erhält, werden die vorhandenen Daten aus dem „Empfohlen“-Cluster entfernt. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status beibehalten.

deleteContinuationCluster

Mit dieser API können Sie den Inhalt eines Fortsetzungsclusters löschen.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Wenn der Dienst die Anfrage erhält, entfernt er die vorhandenen Daten aus dem Fortsetzungscluster. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status beibehalten.

deleteUserManagementCluster

Mit dieser API können Sie den Inhalt des Clusters „UserAccountManagement“ löschen.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Wenn der Dienst die Anfrage erhält, entfernt er die vorhandenen Daten aus dem Cluster „UserAccountManagement“. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der aktuelle Status bleibt erhalten.

deleteClusters

Mit dieser API können Sie den Inhalt eines bestimmten Clustertyps löschen.

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

Wenn der Dienst die Anfrage erhält, werden die vorhandenen Daten aus allen Clustern entfernt, die den angegebenen Clustertypen entsprechen. Clients können einen oder mehrere Clustertypen übergeben. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status bleibt erhalten.

Fehlerbehandlung

Es wird dringend empfohlen, das Aufgabenergebnis aus den Veröffentlichungs-APIs abzuhören, damit eine Folgeaktion ausgeführt werden kann, um eine erfolgreiche Aufgabe wiederherzustellen und noch einmal einzureichen.

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

Der Fehler wird als AppEngageException zurückgegeben, wobei die Ursache als Fehlercode enthalten ist.

Fehlercode Fehlername Hinweis
1 SERVICE_NOT_FOUND Der Dienst ist auf dem angegebenen Gerät nicht verfügbar.
2 SERVICE_NOT_AVAILABLE Der Dienst ist auf dem angegebenen Gerät verfügbar, aber zum Zeitpunkt des Anrufs nicht (z. B. weil er explizit deaktiviert ist).
3 SERVICE_CALL_EXECUTION_FAILURE Die Ausführung der Aufgabe ist aufgrund von Problemen mit dem Thread fehlgeschlagen. In diesem Fall kann der Vorgang wiederholt werden.
4 SERVICE_CALL_PERMISSION_DENIED Der Anrufer ist nicht berechtigt, den Dienst anzurufen.
5 SERVICE_CALL_INVALID_ARGUMENT Die Anfrage enthält ungültige Daten (z. B. mehr als die zulässige Anzahl von Clustern).
6 SERVICE_CALL_INTERNAL Es ist ein Fehler auf Dienstebene aufgetreten.
7 SERVICE_CALL_RESOURCE_EXHAUSTED Der Dienstaufruf wird zu häufig ausgeführt.

Schritt 3: Broadcast-Intents verarbeiten

Zusätzlich zu API-Aufrufen für die Veröffentlichung von Inhalten über einen Job muss auch eine BroadcastReceiver eingerichtet werden, um die Anfrage für die Veröffentlichung von Inhalten zu erhalten.

Broadcast-Intents dienen hauptsächlich zur Reaktivierung von Apps und zum Erzwingen der Datensynchronisierung. Broadcast-Intents sind nicht für häufige Übermittlungen vorgesehen. Sie wird nur ausgelöst, wenn der Engage-Dienst feststellt, dass die Inhalte möglicherweise veraltet sind (z. B. eine Woche alt). So ist die Wahrscheinlichkeit höher, dass Nutzer aktuelle Inhalte sehen, auch wenn die Anwendung seit einiger Zeit nicht ausgeführt wurde.

Das BroadcastReceiver muss auf eine der folgenden beiden Arten eingerichtet werden:

  • Registrieren Sie eine Instanz der Klasse BroadcastReceiver dynamisch mit Context.registerReceiver(). So ist die Kommunikation von Anwendungen möglich, die sich noch im Arbeitsspeicher befinden.
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}
  • Deklarieren Sie eine Implementierung statisch mit dem <receiver>-Tag in der Datei AndroidManifest.xml. So kann die Anwendung Broadcast-Intents empfangen, wenn sie nicht ausgeführt wird, und die Inhalte veröffentlichen.
<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

Der Dienst sendet die folgenden Intents:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Wir empfehlen, bei Erhalt dieser Absicht einen publishRecommendationClusters-Aufruf zu starten.
  • com.google.android.engage.action.PUBLISH_FEATURED Wir empfehlen, bei Erhalt dieser Absicht einen publishFeaturedCluster-Anruf zu starten.
  • com.google.android.engage.action.PUBLISH_CONTINUATION Wir empfehlen, bei Erhalt dieser Absicht einen publishContinuationCluster-Anruf zu starten.

Integrationsablauf

Eine detaillierte Anleitung zum Überprüfen Ihrer Integration nach Abschluss finden Sie unter Integrationsablauf für Entwickler.

Häufig gestellte Fragen

Häufig gestellte Fragen zum Engage SDK

Kontakt

Wenn Sie während der Integration Fragen haben, wenden Sie sich an engage-developers@google.com. Unser Team wird sich so schnell wie möglich bei Ihnen melden.

Nächste Schritte

Nach Abschluss dieser Integration sind folgende Schritte erforderlich:

  • Senden Sie eine E-Mail an engage-developers@google.com und hängen Sie Ihr integriertes APK an, das für den Test durch Google bereit ist.
  • Google führt eine interne Überprüfung durch, um sicherzustellen, dass die Integration wie erwartet funktioniert. Falls Änderungen erforderlich sind, wird Google Sie mit allen erforderlichen Details kontaktieren.
  • Wenn die Tests abgeschlossen sind und keine Änderungen erforderlich sind, werden Sie von Google benachrichtigt, dass Sie das aktualisierte und integrierte APK im Play Store veröffentlichen können.
  • Nachdem Google bestätigt hat, dass Ihr aktualisiertes APK im Play Store veröffentlicht wurde, werden die Cluster Empfehlung, Empfohlen und Fortsetzung veröffentlicht und für Nutzer sichtbar.