Engage-SDK lesen: Anleitung zur technischen Integration von Drittanbietern

Google entwickelt eine On-Device-Oberfläche, die die Apps der Nutzer nach Branchen sortiert und ein neues immersives Erlebnis für personalisierte App-Inhalte ermöglicht. Diese Vollbildfunktion bietet Entwicklerpartnern die Möglichkeit, ihre besten Rich-Content-Inhalte in einem eigenen Kanal außerhalb ihrer App zu präsentieren.

Dieser Leitfaden enthält Anleitungen für Entwicklerpartner, wie sie ihre lesbaren Inhalte integrieren und mit dem Engage SDK sowohl diese neue Fläche als auch vorhandene Google-Oberflächen füllen können.

Integrationsdetail

Terminologie

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

  • Empfehlungscluster zeigen personalisierte Vorschläge für Inhalte, die von einem einzelnen Entwicklerpartner gelesen werden sollten.

    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 eines einzelnen Partners.

    • 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-UI mit einer einzelnen Entität im Empfehlungscluster eines Partners.

  • Im Cluster Continuation werden noch nicht fertiggestellte Bücher von mehreren Entwicklerpartnern in einer einzigen UI-Gruppierung angezeigt. Jeder Entwicklerpartner darf maximal 10 Entitäten im Continuation-Cluster senden.

    Abbildung 3: Entertainment Space-UI mit einem Continuation-Cluster mit noch nicht abgeschlossenen Empfehlungen von mehreren Partnern (derzeit ist nur eine Empfehlung sichtbar).

  • Der Cluster Featured zeigt eine Auswahl von Elementen von mehreren Entwicklerpartnern in einer einzigen UI-Gruppierung. Es wird einen einzelnen hervorgehobenen Cluster geben, der oben auf der Benutzeroberfläche angezeigt wird und Priorität über allen Empfehlungsclustern hat. Jeder Entwicklerpartner darf bis zu 10 Entitäten im Cluster „Empfohlen“ senden.

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

Vorbereitung

Mindest-API-Level: 19

Füge deiner App die com.google.android.play:engage-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.4.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 Entitätslimits in einem Cluster
Empfehlungscluster Höchstens 5 Höchstens 50
Fortsetzungs-Cluster Höchstens 1 Höchstens 10
Hervorgehobener Cluster Höchstens 1 Höchstens 10

Schritt 1: Entitätsdaten angeben

Im SDK wurden verschiedene Entitäten definiert, die die einzelnen Artikeltypen darstellen. Für die Kategorie „Lesen“ werden die folgenden Entitäten unterstützt:

  1. EbookEntity
  2. AudiobookEntity
  3. BookSeriesEntity

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

EbookEntity

Das EbookEntity-Objekt steht für ein E-Book, z. B. das E-Book Becoming von Michelle Obama.

Attribut Anforderungen Hinweise
Name Erforderlich
Posterbilder Erforderlich Mindestens ein Bild muss angegeben werden. Weitere Informationen findest du in den Bildspezifikationen.
Verfasser Erforderlich Es muss mindestens ein Name des Autors angegeben werden.
Aktionslink-URI Erforderlich

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

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

Veröffentlichungsdatum Optional In Epochenmillisekunden, falls angegeben.
Beschreibung Optional Muss maximal 200 Zeichen lang sein, falls angegeben.
Preis Optional Freier Text
Seitenzahl Optional Muss eine positive Ganzzahl sein, falls angegeben.
Genre Optional Liste der mit dem Buch verknüpften Genres.
Name der Reihe Optional Der Name der Reihe, zu der das E-Book gehört (z. B. Harry Potter).
Einheitenindex der Reihe Optional Der Index des E-Books der Reihe, wobei 1 das erste E-Book der Reihe ist. Wenn beispielsweise Harry Potter und der Gefangene von Askaban das 3. Buch der Reihe ist, sollte der Wert auf 3 festgelegt werden.
Mit Buchtyp fortfahren Optional

TYPE_NEXT – Fortsetzung eines unvollendeten Buchs.

TYPE_NEXT: Fahre mit einem neuen aus einer Reihe fort.

TYPE_NEW – neu veröffentlicht.
Letzte Interaktionsdauer Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Continuation-Cluster befindet.

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

In Millisekunden der Epoche.
Fortschritt in Prozent abgeschlossen Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Continuation-Cluster 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 Epochenzeitstempel, nach dem der Inhalt auf der Oberfläche angezeigt werden soll.

Wenn die Richtlinie nicht konfiguriert ist, können die Inhalte auf der Oberfläche angezeigt werden.

In Millisekunden der Epoche.
Endzeitstempel Optional

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

Wenn die Richtlinie nicht konfiguriert ist, können die Inhalte auf der Oberfläche angezeigt werden.

In Millisekunden der Epoche.

AudiobookEntity

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

Attribut Anforderungen Hinweise
Name Erforderlich
Posterbilder Erforderlich Mindestens ein Bild muss angegeben werden. Weitere Informationen findest du in den Bildspezifikationen.
Verfasser Erforderlich Es muss mindestens ein Name des Autors angegeben werden.
Narrator Erforderlich Es muss mindestens der Name eines Sprechers angegeben werden.
Aktionslink-URI Erforderlich

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

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

Veröffentlichungsdatum Optional In Epochenmillisekunden, falls angegeben.
Beschreibung Optional Muss maximal 200 Zeichen lang sein, falls angegeben.
Preis Optional Freier Text
Dauer Optional Muss ein positiver Wert sein, falls angegeben.
Genre Optional Liste der mit dem Buch verknüpften Genres.
Name der Reihe Optional Name der Reihe, zu der das Hörbuch gehört, z. B. Harry Potter.
Einheitenindex der Reihe Optional Der Index des Hörbuchs in der Reihe, wobei 1 das erste Hörbuch der Reihe ist. Wenn beispielsweise Harry Potter und der Gefangene von Askaban das 3. Buch der Reihe ist, sollte der Wert auf 3 festgelegt werden.
Mit Buchtyp fortfahren Optional

TYPE_NEXT – Fortsetzung eines unvollendeten Buchs.

TYPE_NEXT: Fahre mit einem neuen aus einer Reihe fort.

TYPE_NEW – neu veröffentlicht.
Letzte Interaktionsdauer Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Continuation-Cluster befindet.

In Millisekunden der Epoche.
Fortschritt in Prozent abgeschlossen Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Continuation-Cluster befindet.

*Neu* beschaffte 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 Epochenzeitstempel, nach dem der Inhalt auf der Oberfläche angezeigt werden soll.

Wenn die Richtlinie nicht konfiguriert ist, können die Inhalte auf der Oberfläche angezeigt werden.

In Millisekunden der Epoche.
Endzeitstempel Optional

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

Wenn die Richtlinie nicht konfiguriert ist, können die Inhalte auf der Oberfläche angezeigt werden.

In Millisekunden der Epoche.

BookSeriesEntity

Das BookSeriesEntity-Objekt steht für eine Buchreihe (z. B. die Buchreihe Harry Potter mit 7 Büchern).

Attribut Anforderungen Hinweise
Name Erforderlich
Posterbilder Erforderlich Mindestens ein Bild muss angegeben werden. Weitere Informationen findest du in den Bildspezifikationen.
Verfasser Erforderlich Mindestens ein Autorenname muss vorhanden sein.
Aktionslink-URI 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 findest du in diesen FAQs.

Anzahl der Bücher Erforderlich Anzahl der Bücher in der Reihe.
Beschreibung Optional Muss maximal 200 Zeichen lang sein, falls angegeben.
Genre Optional Liste der mit dem Buch verknüpften Genres.
Mit Buchtyp fortfahren Optional

TYPE_NEXT – Fortsetzung eines unvollendeten Buchs.

TYPE_NEXT: Fahre mit einem neuen aus einer Reihe fort.

TYPE_NEW – neu veröffentlicht.
Letzte Interaktionsdauer Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Continuation-Cluster befindet.

In Millisekunden der Epoche.
Fortschritt in Prozent abgeschlossen Bedingt erforderlich

Muss angegeben werden, wenn sich das Element im Continuation-Cluster 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 Epochenzeitstempel, nach dem der Inhalt auf der Oberfläche angezeigt werden soll.

Wenn die Richtlinie nicht konfiguriert ist, können die Inhalte auf der Oberfläche angezeigt werden.

In Millisekunden der Epoche.
Endzeitstempel Optional

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

Wenn die Richtlinie nicht konfiguriert ist, können die Inhalte auf der Oberfläche angezeigt werden.

In Millisekunden der Epoche.

Bildspezifikationen

Im Folgenden sind die erforderlichen Spezifikationen für Bild-Assets aufgeführt:

Seitenverhältnis Anforderungen Mindestanzahl von Pixeln Empfohlene Pixel
Quadrat (1 × 1) Erforderlich 300 × 300 1200 × 1200
Querformat (1,91 × 1) Optional 600 × 314 1200 × 628
Hochformat (4 x 5) Optional 480 × 600 960 × 1200

Dateiformate

PNG, JPG, statisches GIF, WebP

Maximale Dateigröße

5.120 KB

Weitere Empfehlungen

  • Bildbereich:Wichtige Inhalte sollten in den mittleren 80% des Bilds positioniert werden.

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 Inhaltsveröffentlichung 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 gerade etwas in den Einkaufswagen gelegt hat).

AppEngagePublishClient ist für die Veröffentlichung von Clustern verantwortlich. Folgende 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 der Inhalt auf dem Gerät angezeigt werden kann.

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("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 innerhalb einer Transaktion die folgenden Aktionen 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

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

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

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

publishContinuationCluster

Diese API wird zum Veröffentlichen eines ContinuationCluster-Objekts verwendet.

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 innerhalb einer Transaktion die folgenden Aktionen ausgeführt:

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

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

publishUserAccountManagementRequest

Dieses API wird zum Veröffentlichen einer Anmeldekarte verwendet . Durch die Anmeldeaktion werden Nutzer zur Anmeldeseite der App weitergeleitet, wo sie Inhalte veröffentlichen oder personalisiertere Inhalte bereitstellen kann.

Die folgenden Metadaten sind Teil der Anmeldekarte:

Attribut Anforderungen Beschreibung
Aktions-URI Erforderlich Deeplink zur Aktion (d.h. Weiterleitung zur Anmeldeseite der App)
Bild Optional – Wenn nicht angegeben, muss ein Titel angegeben werden.

Bild auf der Karte

Bilder mit einem Seitenverhältnis von 16:9 und einer Auflösung von 1.264 x 712
Titel Optional – Wenn nicht angegeben, muss das Bild zur Verfügung gestellt werden Titel der Karte
Aktionstext Optional Text im CTA (z.B. „Anmeldung“)
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 innerhalb einer Transaktion die folgenden Aktionen ausgeführt:

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

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

updatePublishStatus

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

  • Die Angabe des Status ist in allen Szenarien wichtig, selbst wenn der Inhalt veröffentlicht wird (STATUS = VERÖFFENTLICHT), um Dashboards mit diesem expliziten Status auszufüllen, um den Zustand und andere Messwerte Ihrer Integration zu vermitteln.
  • Wenn kein Inhalt veröffentlicht ist, der Integrationsstatus aber nicht fehlerhaft ist (STATUS == NOT_PUBLISHED), kann Google verhindern, dass Benachrichtigungen in den Dashboards zum Anwendungszustand ausgelöst werden. Damit wird bestätigt, dass Inhalte aufgrund einer aus Sicht des Anbieters erwarteten Situation nicht veröffentlicht werden.
  • Es hilft Entwicklern, zu verstehen, 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 den App-Inhalt sehen oder überwinden können.

Die Liste der zulässigen Veröffentlichungsstatuscodes 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 die Inhalte nicht veröffentlicht werden, weil ein Nutzer nicht angemeldet ist, empfiehlt Google, die Anmeldekarte zu veröffentlichen. Wenn Anbieter die Anmeldekarte aus irgendeinem Grund nicht veröffentlichen können, empfehlen wir, die updatePublishStatus API 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

Diese API wird zum Löschen des Inhalts von Empfehlungsclustern verwendet.

Kotlin


client.deleteRecommendationClusters()

Java


client.deleteRecommendationClusters();

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 zum Löschen des Inhalts des hervorgehobenen Clusters verwendet.

Kotlin


client.deleteFeaturedCluster()

Java


client.deleteFeaturedCluster();

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

deleteContinuationCluster

Diese API wird zum Löschen des Inhalts des Fortsetzungsclusters verwendet.

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 zum Löschen des Inhalts des UserAccountManagement-Clusters verwendet.

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

Diese API wird zum Löschen des Inhalts eines bestimmten Clustertyps verwendet.

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 bestehende Status beibehalten.

Fehlerbehandlung

Es wird dringend empfohlen, das Aufgabenergebnis der Publish-APIs zu beobachten, damit eine Folgeaktion 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 mit der Ursache als Fehlercode zurückgegeben.

Fehlercode Hinweis
SERVICE_NOT_FOUND Der Dienst ist auf dem angegebenen Gerät nicht verfügbar.
SERVICE_NOT_AVAILABLE Der Dienst ist auf dem jeweiligen Gerät verfügbar, aber zum Zeitpunkt des Aufrufs nicht verfügbar (z. B. weil er explizit deaktiviert wurde).
SERVICE_CALL_EXECUTION_FAILURE Die Taskausführung ist aufgrund von Threading-Problemen fehlgeschlagen. In diesem Fall kann ein neuer Versuch unternommen werden.
SERVICE_CALL_PERMISSION_DENIED Der Aufrufer ist nicht berechtigt, den Dienstaufruf zu tätigen.
SERVICE_CALL_INVALID_ARGUMENT Die Anfrage enthält ungültige Daten, z. B. mehr als die zulässige Anzahl von Clustern.
SERVICE_CALL_INTERNAL Auf der Dienstseite ist ein Fehler aufgetreten.
SERVICE_CALL_RESOURCE_EXHAUSTED Der Dienstaufruf erfolgt zu häufig.

Schritt 3: Broadcast-Intents verarbeiten

Neben Aufrufen der API zur Veröffentlichung von Inhalten über einen Job ist es auch erforderlich, eine BroadcastReceiver einzurichten, um die Anfrage für eine Inhaltsveröffentlichung zu empfangen.

Der Zweck von Broadcast-Intents besteht hauptsächlich darin, Apps zu reaktivieren und die Datensynchronisierung zu erzwingen. Broadcast-Intents sind nicht darauf ausgelegt, sehr häufig zu senden. Sie wird nur ausgelöst, wenn der Engage-Dienst feststellt, dass der Inhalt möglicherweise veraltet ist (z. B. eine Woche alt). Auf diese Weise wird dem Nutzer mehr Sicherheit bei der Nutzung neuer Inhalte geboten, auch wenn die Anwendung über einen längeren Zeitraum hinweg nicht ausgeführt wurde.

BroadcastReceiver muss auf zwei Arten eingerichtet werden:

  • Registrieren Sie mit Context.registerReceiver() eine Instanz der BroadcastReceiver-Klasse dynamisch. Dies ermöglicht die Kommunikation von Anwendungen, die sich noch im Speicher 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 mit dem Tag <receiver> in der Datei AndroidManifest.xml statisch. Die Anwendung kann dann Broadcast-Intents empfangen, wenn sie nicht ausgeführt wird, und die Inhalte können veröffentlicht werden.
<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>

Die folgenden Intents werden vom Dienst gesendet:

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

Integrationsworkflow

Eine detaillierte Anleitung zum Prüfen der Einbindung nach Abschluss finden Sie unter Workflow für die Entwicklerintegration.

Häufig gestellte Fragen

Weitere Informationen findest du in den häufig gestellten Fragen zum Engage SDK.

Kontakt

Wenden Sie sich an Engage-developers@google.com, wenn während des Integrationsprozesses Fragen auftreten. Unser Team wird sich so schnell wie möglich mit Ihnen in Verbindung setzen.

Nächste Schritte

Nach Abschluss dieser Integration sind deine nächsten Schritte:

  • Senden Sie eine E-Mail an Engage-developers@google.com und hängen Sie Ihr integriertes APK an, das zum Testen durch Google bereit ist.
  • Google führt intern eine Überprüfung durch, um sicherzustellen, dass die Integration wie erwartet funktioniert. Falls Änderungen erforderlich sind, werden Sie von Google über die erforderlichen Details informiert.
  • Wenn die Tests abgeschlossen sind und keine Änderungen erforderlich sind, werden Sie von Google darüber informiert, dass Sie mit der Veröffentlichung des aktualisierten und integrierten APKs im Play Store beginnen 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.