Engage-SDK lesen: Anleitung zur technischen Integration von Drittanbietern

Sie können die App-Interaktion steigern, indem Sie Ihre Nutzer dort erreichen, wo sie sich gerade befinden. Mit dem Engage SDK können Sie personalisierte Empfehlungen und Folgeinhalte direkt auf verschiedenen On-Device-Oberflächen wie Sammlungen, Entertainment Space und im Google Play Store präsentieren. Die Integration vergrößert das APK im Durchschnitt um weniger als 50 KB (komprimiert) und dauert bei den meisten Apps etwa eine Woche. Weitere Informationen finden Sie auf unserer Unternehmenswebsite.

Dieser Leitfaden enthält Anleitungen für Entwicklerpartner, wie sie Lesematerial (E-Books, Hörbücher, Comics/Mangas, Blogs, Nachrichten und Zeitschriften) auf Engage-Inhaltsflächen bereitstellen können.

Unterstützung von Kategorien und Oberflächen

Die Berechtigung für die Engage SDK-Oberfläche richtet sich nach der Inhaltskategorie Ihrer App. Anhand der folgenden Tabelle können Sie feststellen, ob Sie die Voraussetzungen für bestimmte Oberflächen erfüllen:

Status Inhaltskategorie oder Anwendungsfall Unterstützte Oberflächen
Unterstützt
(Auf allen Oberflächen verfügbar)
  • E-Books
  • Comics & Manga
  • Hörbücher
  • Dienste für von Nutzern erstellte Inhalte im Langformat
  • Blogs
  • Sammlungen
  • Entertainment Space
  • Tab „Google Play Store-Apps“
  • Tab „Mein Play“ im Google Play Store (nur personalisierte Empfehlungen und Fortsetzung)
  • Seite mit dem Store-Eintrag im Google Play Store
Teilweise unterstützt
(Auf einigen Oberflächen verfügbar)
  • Nachrichten & Zeitschriften*
  • Sammlungen
  • Entertainment Space
Nicht unterstützt
  • E-Book- oder PDF-Reader
  • Buchrezensionen
  • Enzyklopädie / Wörterbuch
  • Übersetzer
  • Religiöse Texte

Nachrichten-Apps

Nachrichten-Apps bieten vielfältige Inhalte, für die jeweils eigene Teilnahmevoraussetzungen gelten. Da Engage SDK-Inhalte im Google Play Store auf die Premium-Optimierungstools von Google Play abgestimmt sind, sind Nachrichtenartikel und Videoclips aus Nachrichten-Apps nicht für den Google Play Store, aber für Sammlungen und Entertainment Space geeignet. Nicht traditionelle Nachrichteninhalte wie Podcasts und Rezepte können dagegen im Google Play Store angeboten werden:

Entitätstyp Für Sammlungen geeignet Für Entertainment Space berechtigt Für den Google Play Store geeignet
Nachrichtenartikel Ja (Tab „Lesen“) Ja (Tab „Lesen“) Nein
Videoclip Ja (Tab „Ansehen“) Ja (Tab „Ansehen“) Nein
Podcast Ja (Tab „Anhören“) Ja (Tab „Anhören“) Ja
Rezept Ja (Tab „Essen“) Nein Ja

Integrationsdetails

In diesem Abschnitt werden die Schritte, Datenmodelle und Begriffe beschrieben, die für die Einbindung des Engage SDK für Leseinhalte erforderlich sind.

Terminologie

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

  • Empfehlungscluster enthalten personalisierte Vorschläge für Inhalte von einzelnen Entwicklerpartnern.

    Ihre Empfehlungen haben die folgende Struktur:

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

      Abbildung 1. Entertainment Space-Benutzeroberfläche mit einem Empfehlungscluster von einem einzelnen Partner.

    • Entität: Ein Objekt, das ein einzelnes Element in einem Cluster darstellt. Eine Entität kann ein E-Book, ein Hörbuch, eine Buchreihe und mehr sein. Eine Liste der unterstützten Entitätstypen finden Sie im Abschnitt Entitätsdaten bereitstellen.

      Abbildung 2. Entertainment Space-Benutzeroberfläche mit einer einzelnen Entität im Empfehlungscluster eines einzelnen Partners.

  • Der Cluster Fortsetzen zeigt unvollendete Bücher von mehreren Entwicklerpartnern in einer einzigen UI-Gruppierung an. Jeder Entwicklerpartner darf maximal 10 Entitäten im Fortsetzungscluster übertragen.

    Abbildung 3. Entertainment Space-Benutzeroberfläche mit einem Fortsetzungscluster mit unvollständigen Empfehlungen von mehreren Partnern (derzeit ist nur eine Empfehlung sichtbar).

  • Der Cluster Empfohlen zeigt eine Auswahl von Artikeln mehrerer Entwicklerpartner in einer einzigen UI-Gruppierung. Es gibt einen einzelnen Cluster „Empfohlen“, der im oberen Bereich der Benutzeroberfläche mit einer Prioritätsplatzierung über allen Empfehlungsclustern angezeigt wird. Jeder Entwicklerpartner darf bis zu 10 Entitäten im Cluster „Empfohlen“ übertragen.

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

Vorarbeit

Mindest-API-Level: 19

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

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

Zusammenfassung

Das Design basiert auf der Implementierung eines gebundenen Dienstes.

Die Daten, die ein Client veröffentlichen kann, unterliegen den folgenden Limits für verschiedene Clustertypen:

Clustertyp Cluster limits Maximale Anzahl von Entitäten in einem Cluster
Cluster mit Empfehlungen Höchstens 7 Höchstens 50
Fortsetzungscluster Höchstens 1 Höchstens 20
Empfohlener Cluster Höchstens 1 Höchstens 20

Schritt 1: Daten zum Rechtssubjekt angeben

Im SDK sind verschiedene Entitäten definiert, die die einzelnen Artikeltypen darstellen. Wir unterstützen die folgenden Entitäten für die Kategorie „Lesen“:

  1. EbookEntity
  2. AudiobookEntity
  3. BookSeriesEntity

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

EbookEntity

Das Objekt EbookEntity stellt ein E-Book dar, z. B. das E-Book Becoming von Michelle Obama.

Attribut Anforderung Hinweise
Name Erforderlich
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Bildspezifikationen.
Autor Erforderlich Mindestens ein Autorenname muss angegeben werden.
URI des Aktionslinks Erforderlich

Der Deeplink zur Anbieter-App für das E-Book.

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

Veröffentlichungsdatum Optional In Epochen-Millisekunden, falls angegeben.
Beschreibung Optional Darf maximal 200 Zeichen lang sein, falls angegeben.
Preis Optional Freier Text
Seitenzahl Optional Muss eine positive Ganzzahl sein, falls angegeben.
Genre Optional Liste der Genres, die dem Buch zugeordnet sind.
Name der Reihe Optional Name der Reihe, zu der das E-Book gehört (z. B. Harry Potter).
Reiheneinheitenindex Optional Der Index des E-Books in der Reihe, wobei 1 das erste E-Book in der Reihe ist. Wenn beispielsweise Harry Potter und der Gefangene von Askaban das dritte Buch der Reihe ist, sollte hier „3“ angegeben werden.
Buchtyp fortsetzen Optional

TYPE_CONTINUE – Ein unvollendetes Buch fortsetzen.

TYPE_NEXT – Mit einem neuen Element einer Reihe fortfahren.

TYPE_NEW – Neu veröffentlicht.
Letzte Interaktion Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Fortsetzungscluster befindet.

*Neu* erworbene E-Books können Teil des Clusters „Weiterlesen“ sein.

In Epochen-Millisekunden.
Fortschritt in Prozent Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Fortsetzungscluster befindet.

Der Wert muss größer als 0 und kleiner als 100 sein.
DisplayTimeWindow – Zeitfenster für die Anzeige von Inhalten auf der Oberfläche festlegen
Startzeitstempel Optional

Der Epoch-Zeitstempel, nach dem der Inhalt auf der Oberfläche angezeigt werden soll.

Wenn nicht festgelegt, können Inhalte auf der Oberfläche angezeigt werden.

In Epochen-Millisekunden.
Endzeitstempel Optional

Der Zeitstempel, nach dem der Inhalt nicht mehr auf der Oberfläche angezeigt wird.

Wenn nicht festgelegt, können Inhalte auf der Oberfläche angezeigt werden.

In Epochen-Millisekunden.

AudiobookEntity

Das AudiobookEntity-Objekt stellt ein Hörbuch dar (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 Bildspezifikationen.
Autor Erforderlich Mindestens ein Autorenname muss 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 diesen FAQs.

Narrator Optional Es muss mindestens ein Name eines Sprechers angegeben werden.
Veröffentlichungsdatum Optional In Epochen-Millisekunden, falls angegeben.
Beschreibung Optional Darf maximal 200 Zeichen lang sein, falls angegeben.
Preis Optional Freier Text
Dauer Optional Muss ein positiver Wert sein, falls angegeben.
Genre Optional Liste der Genres, die dem Buch zugeordnet sind.
Name der Reihe Optional Name der Reihe, zu der das Hörbuch gehört (z. B. Harry Potter).
Reiheneinheitenindex Optional Der Index des Hörbuchs in der Reihe, wobei 1 das erste Hörbuch in der Reihe ist. Wenn beispielsweise Harry Potter und der Gefangene von Askaban das dritte Buch der Reihe ist, sollte hier „3“ angegeben werden.
Buchtyp fortsetzen Optional

TYPE_CONTINUE – Ein unvollendetes Buch fortsetzen.

TYPE_NEXT – Mit einem neuen Element einer Reihe fortfahren.

TYPE_NEW – Neu veröffentlicht.
Letzte Interaktion Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Fortsetzungscluster befindet.

In Epochen-Millisekunden.
Fortschritt in Prozent Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Fortsetzungscluster befindet.

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

Der Wert muss größer als 0 und kleiner als 100 sein.
DisplayTimeWindow – Zeitfenster für die Anzeige von Inhalten auf der Oberfläche festlegen
Startzeitstempel Optional

Der Epoch-Zeitstempel, nach dem der Inhalt auf der Oberfläche angezeigt werden soll.

Wenn nicht festgelegt, können Inhalte auf der Oberfläche angezeigt werden.

In Epochen-Millisekunden.
Endzeitstempel Optional

Der Zeitstempel, nach dem der Inhalt nicht mehr auf der Oberfläche angezeigt wird.

Wenn nicht festgelegt, können Inhalte auf der Oberfläche angezeigt werden.

In Epochen-Millisekunden.

BookSeriesEntity

Das BookSeriesEntity-Objekt stellt eine Buchreihe dar, z. B. die Harry Potter-Buchreihe mit 7 Büchern.

Attribut Anforderung Hinweise
Name Erforderlich
Posterbilder Erforderlich Es muss mindestens ein Bild angegeben werden. Weitere Informationen finden Sie unter Bildspezifikationen.
Autor Erforderlich Es muss mindestens ein Autorenname vorhanden sein.
URI des Aktionslinks Erforderlich

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

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

Anzahl der Bücher Erforderlich Anzahl der Bücher in der Buchreihe.
Beschreibung Optional Darf maximal 200 Zeichen lang sein, falls angegeben.
Genre Optional Liste der Genres, die dem Buch zugeordnet sind.
Buchtyp fortsetzen Optional

TYPE_CONTINUE – Ein unvollendetes Buch fortsetzen.

TYPE_NEXT – Mit einem neuen Element einer Reihe fortfahren.

TYPE_NEW – Neu veröffentlicht.
Letzte Interaktion Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Fortsetzungscluster befindet.

In Epochen-Millisekunden.
Fortschritt in Prozent Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Fortsetzungscluster befindet.

*Neu* erworbene Buchreihen können Teil des Clusters „Weiterlesen“ sein.

Der Wert muss größer als 0 und kleiner als 100 sein.
DisplayTimeWindow – Zeitfenster für die Anzeige von Inhalten auf der Oberfläche festlegen
Startzeitstempel Optional

Der Epoch-Zeitstempel, nach dem der Inhalt auf der Oberfläche angezeigt werden soll.

Wenn nicht festgelegt, können Inhalte auf der Oberfläche angezeigt werden.

In Epochen-Millisekunden.
Endzeitstempel Optional

Der Zeitstempel, nach dem der Inhalt nicht mehr auf der Oberfläche angezeigt wird.

Wenn nicht festgelegt, können Inhalte auf der Oberfläche angezeigt werden.

In Epochen-Millisekunden.

Bildspezifikationen

In der folgenden Tabelle sind die erforderlichen Spezifikationen für Bild-Assets aufgeführt:

Seitenverhältnis Unterstützte Cluster Mindestanzahl Pixel Empfohlene Pixel
Quadratisch (1 × 1) Alle Cluster 300 x 300 1200 × 1200
Querformat (1,91 × 1) Empfohlen und Fortsetzung 600 × 314 1200 × 628
Hochformat (4 : 5) Empfehlung 480 × 600 960 × 1200

Dateiformate

PNG, JPG, statisches GIF, WebP

Maximale Dateigröße

5.120 KB

Zusätzliche Empfehlungen

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

Beispiel

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

Es wird empfohlen, den Job zur Veröffentlichung von Inhalten im Hintergrund auszuführen (z. B. mit WorkManager) und regelmäßig oder ereignisbasiert zu planen (z. B. jedes Mal, wenn der Nutzer die App öffnet oder wenn er gerade 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 Integration verfügbar ist und ob die Inhalte auf dem Gerät angezeigt werden können.

Sie können die Dienstverfügbarkeit für jeden Clustertyp prüfen, den Sie veröffentlichen möchten. Die isServiceAvailable API akzeptiert ein Anfrageobjekt, ServiceAvailabilityRequest, das die Clustertypen enthält, für die die Dienstverfügbarkeit geprüft werden muss. Die für ServiceAvailabilityRequest erforderlichen ClusterType-Enum-Werte finden Sie in der folgenden Tabelle.

Clustertyp Clustertypkonstante Ganzzahlwert
Unbekannt TYPE_UNKNOWN 0
Empfehlungscluster TYPE_RECOMMENDATION 1
Empfohlener Cluster TYPE_FEATURED 2
Fortsetzungscluster TYPE_CONTINUATION 3
Nutzerverwaltungscluster TYPE_ENGAGEMENT 8
Abo-Cluster TYPE_SUBSCRIPTION 12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here such as retry.
    }
});
Funktion für bedingte Dienstverfügbarkeit

Einige integrierte Apps erfordern eine spezielle Konfiguration, bei der der Engage-Dienst zeitweise aktiviert und deaktiviert wird, um die Kosten für die Bereitstellung zu senken. Diese Strategie der unregelmäßigen Contentaufnahme wirkt sich jedoch negativ auf die Nutzerfreundlichkeit aus: Veraltete Inhalte werden nicht präsentiert und einige Oberflächen werden nicht bedient.

Ab Version 1.6.0 kann mit dem Engage SDK die Verfügbarkeit für bestimmte Clustertypen geprüft werden. Wenn Ihre App die unregelmäßige Aufnahme verwendet:

  • Fortsetzungscluster (z. B. „Weiterlesen“) bleiben auf allen unterstützten Geräten standardmäßig aktiviert.
  • Andere Clustertypen (z. B. Empfehlungen) werden zeitweise aktiviert und deaktiviert.

Wenn diese Standardkonfiguration nicht Ihren Anforderungen entspricht, wenden Sie sich an engage-developers@google.com.

Für SDK-Versionen vor v1.6.0 (eingestellt)

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

Diese API wird verwendet, um eine Liste von RecommendationCluster-Objekten zu veröffentlichen.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build());

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

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

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

publishFeaturedCluster

Diese API wird verwendet, um eine Liste von FeaturedCluster-Objekten zu veröffentlichen.

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 empfängt, werden die folgenden Aktionen innerhalb einer Transaktion ausgeführt:

  • Vorhandene FeaturedCluster-Daten des Entwicklerpartners werden entfernt.
  • Die Daten aus der Anfrage werden geparst und im aktualisierten empfohlenen Cluster gespeichert.

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

publishContinuationCluster

Diese API wird verwendet, um ein ContinuationCluster-Objekt zu veröffentlichen.

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

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

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

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

publishUserAccountManagementRequest

Diese API wird verwendet, um eine Anmeldekarte zu veröffentlichen . Die Anmeldeaktion leitet Nutzer zur Anmeldeseite der App weiter, damit die App Inhalte veröffentlichen oder personalisierte Inhalte bereitstellen kann.

Die folgenden Metadaten sind Teil der Anmeldekarte:

Attribut Anforderung Beschreibung
Aktions-URI Erforderlich Deeplink zur Aktion (z.B. zur Anmeldeseite der App)
Bild Optional – wenn nicht angegeben, muss der Titel angegeben werden

Auf der Karte angezeigtes Bild

Bilder im Seitenverhältnis 16:9 mit einer Auflösung von 1264 × 712
Titel Optional – wenn nicht angegeben, muss ein Bild angegeben werden Titel auf der Karte
Aktionstext Optional Text, der im CTA angezeigt wird (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 empfängt, werden die folgenden Aktionen innerhalb einer Transaktion ausgeführt:

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

Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

updatePublishStatus

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

  • Die Angabe des Status in allen Szenarien, auch wenn der Inhalt veröffentlicht ist (STATUS == PUBLISHED), ist wichtig, um Dashboards zu füllen, die diesen expliziten Status verwenden, um den Zustand und andere Messwerte Ihrer Integration zu vermitteln.
  • Wenn keine Inhalte veröffentlicht werden, der Integrationsstatus aber nicht fehlerhaft ist (STATUS == NOT_PUBLISHED), kann Google vermeiden, dass Benachrichtigungen in den Dashboards zum App-Zustand ausgelöst werden. Sie bestätigt, dass Inhalte aufgrund einer aus Sicht des Anbieters erwarteten Situation nicht veröffentlicht werden.
  • So können Entwickler Informationen dazu bereitstellen, wann die Daten veröffentlicht werden und wann nicht.
  • Google kann die Statuscodes verwenden, um den Nutzer zu bestimmten Aktionen in der App aufzufordern, damit er den App-Inhalt sehen oder das Problem beheben kann.

Die Liste der zulässigen Statuscodes für die Veröffentlichung lautet :

// 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 der Inhalt nicht veröffentlicht wird, weil ein Nutzer nicht angemeldet ist, empfiehlt Google, die Anmeldekarte zu veröffentlichen. Wenn Anbieter aus irgendeinem Grund die Anmeldekarte 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());

deleteRecommendationsClusters

Diese API wird verwendet, um den Inhalt von Empfehlungsclustern zu löschen.

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

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

deleteFeaturedCluster

Diese API wird verwendet, um den Inhalt des empfohlenen Clusters zu löschen.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Wenn der Dienst die Anfrage empfängt, werden die vorhandenen Daten aus dem empfohlenen Cluster entfernt. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

deleteContinuationCluster

Diese API wird verwendet, um den Inhalt des Fortsetzungsclusters zu löschen.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

Wenn der Dienst die Anfrage empfängt, werden die vorhandenen Daten aus dem Fortsetzungscluster entfernt. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

deleteUserManagementCluster

Diese API wird verwendet, um den Inhalt des UserAccountManagement-Clusters zu löschen.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Wenn der Dienst die Anfrage empfängt, werden die vorhandenen Daten aus dem UserAccountManagement-Cluster entfernt. Bei einem Fehler wird die gesamte Anfrage abgelehnt und der vorhandene Status beibehalten.

deleteClusters

Mit dieser API wird der Inhalt eines bestimmten Clustertyps gelöscht.

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 empfängt, 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 beibehalten.

Fehlerbehandlung

Es wird dringend empfohlen, das Ergebnis der Aufgabe von den Veröffentlichungs-APIs zu überwachen, damit eine Folgemaßnahme ergriffen 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 Aufrufs nicht verfügbar (z. B. weil er explizit deaktiviert ist).
3 SERVICE_CALL_EXECUTION_FAILURE Die Ausführung der Aufgabe ist aufgrund von Threading-Problemen fehlgeschlagen. In diesem Fall kann der Vorgang wiederholt werden.
4 SERVICE_CALL_PERMISSION_DENIED Der Aufrufer ist nicht berechtigt, den Dienstaufruf auszuführen.
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 Aufseiten des Dienstes ist ein Fehler aufgetreten.
7 SERVICE_CALL_RESOURCE_EXHAUSTED Der Dienstaufruf wird zu häufig ausgeführt.

Schritt 3: Broadcast-Intents verarbeiten

Zusätzlich zu Content API-Aufrufen über einen Job ist es auch erforderlich, einen BroadcastReceiver einzurichten, um die Anfrage für eine Inhaltsveröffentlichung zu empfangen.

Broadcast-Intents dienen hauptsächlich der Reaktivierung von Apps und der erzwungenen Datensynchronisierung. Broadcast-Intents sind nicht für den häufigen Versand gedacht. Er wird nur ausgelöst, wenn der Engage-Dienst feststellt, dass der Inhalt möglicherweise veraltet ist (z. B. eine Woche alt). So ist es wahrscheinlicher, dass der Nutzer aktuelle Inhalte sieht, auch wenn die Anwendung längere Zeit nicht ausgeführt wurde.

BroadcastReceiver muss auf die folgenden zwei Arten eingerichtet werden:

  • Registrieren Sie eine Instanz der Klasse BroadcastReceiver dynamisch mit Context.registerReceiver(). Dies ermöglicht die Kommunikation von Anwendungen, die noch im Speicher aktiv sind.

Kotlin

class AppEngageBroadcastReceiver : 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
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

Java

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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}

  • Deklarieren Sie eine Implementierung statisch mit dem <receiver>-Tag in Ihrer AndroidManifest.xml-Datei. Dadurch kann die Anwendung Broadcast-Intents empfangen, wenn sie nicht ausgeführt wird, und die Inhalte veröffentlichen.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      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>

Die folgenden Intents werden vom Dienst gesendet:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION Es wird empfohlen, einen publishRecommendationClusters-Anruf zu starten, wenn dieser Intent empfangen wird.
  • com.google.android.engage.action.PUBLISH_FEATURED Es wird empfohlen, einen publishFeaturedCluster-Anruf zu starten, wenn dieser Intent empfangen wird.
  • com.google.android.engage.action.PUBLISH_CONTINUATIONIt is recommended to start apublishContinuationCluster` aufrufen, wenn dieser Intent empfangen wird.

Integrationsworkflow

Eine detaillierte Anleitung zum Überprüfen der Integration nach Abschluss finden Sie im Workflow für die Integration von Engage-Entwicklern.

Häufig gestellte Fragen

Häufig gestellte Fragen zum Engage SDK

Kontakt

Wende dich bei Fragen während des Integrationsprozesses 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 die nächsten Schritte:

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