Diese Seite wurde von der Cloud Translation API übersetzt.

Engage SDK Shopping: 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.

Dieses Handbuch enthält eine Anleitung für Entwicklerpartner, wie sie ihre Shopping-Inhalte integrieren und mit dem Engage SDK sowohl diesen neuen Bereich als auch vorhandene Google-Plattformen wie Entertainment Space füllen können.

Integrationsdetail

Details zur Integration finden Sie unten:

Terminologie

Diese Integration umfasst die folgenden fünf Clustertypen: Empfehlung, Empfohlen, Einkaufswagen, Einkaufsliste und Neu anordnen.

Empfehlungscluster zeigen personalisierte Shopping-Vorschläge eines einzelnen Entwicklerpartners. Diese Empfehlungen können für den Nutzer personalisiert oder generalisiert werden (z. B. angesagte Artikel). Hiermit können Sie Produkte, Veranstaltungen, Angebote, Werbeaktionen und Abos nach Bedarf präsentieren.

Ihre Empfehlungen haben die folgende Struktur:
- Empfehlungscluster: Eine UI-Ansicht, die eine Gruppe von Empfehlungen desselben Entwicklerpartners enthält.
- ShoppingEntity:Ein Objekt, das einen einzelnen Artikel in einem Cluster darstellt.
Der Cluster Featured zeigt den Hero-ShoppingEntity, der von vielen Entwicklerpartnern ausgewählt wurde, in einer UI-Gruppierung. Es gibt einen einzelnen hervorgehobenen Cluster, der oben in der UI angezeigt wird und dessen Priorität über allen Empfehlungsclustern liegt. Jeder Entwicklerpartner darf eine einzelne ShoppingEntity im Cluster „Empfohlen“ veröffentlichen.
Der Cluster Einkaufswagen zeigt eine Vorschau auf Einkaufswagen von vielen Entwicklerpartnern in einer UI-Gruppierung und fordert Nutzer auf, ihre ausstehenden Einkaufswagen abzuschließen. Es gibt einen einzelnen Einkaufswagen-Cluster, der sich oben in der Benutzeroberfläche befindet und dessen Priorität über allen Empfehlungsclustern liegt. Jeder Entwicklerpartner darf eine einzelne ShoppingCart im Einkaufswagencluster senden.

Ihr Einkaufswagen hat die folgende Struktur:
- Einkaufswagen-Cluster: Eine UI-Ansicht, die eine Gruppe von Einkaufswagenvorschauen von vielen Entwicklerpartnern enthält.
- ShoppingCart: Ein Objekt, das die Einkaufswagenvorschau für einen einzelnen Entwicklerpartner darstellt und im Einkaufswagencluster angezeigt wird. ShoppingCart muss die Gesamtzahl der Artikel im Einkaufswagen anzeigen und kann auch Bilder für einige Artikel im Einkaufswagen des Nutzers enthalten.
Der Cluster Einkaufsliste zeigt eine Vorschau der Einkaufslisten mehrerer Entwicklerpartner in einer UI-Gruppierung an. Nutzer werden aufgefordert, zur entsprechenden App zurückzukehren, um ihre Listen zu aktualisieren und zu vervollständigen. Es gibt einen einzigen Einkaufslisten-Cluster.
Der Cluster Neu anordnen zeigt eine Vorschau der vorherigen Bestellungen mehrerer Entwicklerpartner in einer UI-Gruppierung an und fordert Nutzer auf, ihre Reihenfolge zu ändern. Es gibt einen einzelnen Cluster zur Neuanordnung.
- Bei der Neuanordnung des Clusters muss die Gesamtzahl der Elemente in der vorherigen Bestellung des Nutzers sowie eine der folgenden Optionen angezeigt werden:
  - Bilder für X Artikel in der vorherigen Bestellung des Nutzers.
  - Labels für X Elemente in der vorherigen Bestellung des Nutzers.

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

Weitere Informationen finden Sie unter Paketsichtbarkeit in Android 11.

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 25 `ShoppingEntity`
Hervorgehobener Cluster	Höchstens 1	Höchstens 1 `ShoppingEntity`
Einkaufswagencluster	Höchstens 1	Höchstens 1 `ShoppingCart`
Einkaufslistencluster	Höchstens 1	Höchstens 1 `ShoppingListEntity`
Cluster für Shopping neu anordnen	Höchstens 1	Höchstens 1 `ReorderEntity`

Schritt 1: Entitätsdaten angeben

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

ShoppingEntity
ShoppingCart
ShoppingList
Reorder

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

`ShoppingEntity`

Das ShoppingEntity-Objekt steht für ein Produkt, eine Werbeaktion, ein Angebot, ein Abo oder ein Ereignis, das Entwicklerpartner veröffentlichen möchten.

`ShoppingEntity`

Attribut	Anforderungen	Beschreibung	Formatieren
Posterbilder	Erforderlich	Mindestens ein Bild muss angegeben werden.	Siehe Bildspezifikationen für eine Orientierungshilfe.
Aktions-URI	Erforderlich	Der Deeplink zu der Seite in der App, auf der Details zur Entität angezeigt werden. Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen findest du in diesen FAQs.	URI
Titel	Optional	Der Name der Entität.	Freier Text Empfohlene Textgröße: unter 90 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Preis – aktuell	Bedingt erforderlich	Der aktuelle Preis der Entität. Muss angegeben werden, wenn ein durchgestrichener Preis angegeben ist.	Freier Text
Preis – durchgestrichen	Optional	Der ursprüngliche Preis der Entität, der in der UI durchgestrichen wird.	Freier Text
Zusatzinformationen	Optional	Callout zur Hervorhebung einer Werbeaktion, eines Ereignisses oder einer Aktualisierung für die Entität, falls verfügbar.	Freier Text Empfohlene Textgröße: unter 45 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Kleingedrucktes mit Zusatzinformationen	Optional	Kleingedruckter Text für das Callout.	Freier Text Empfohlene Textgröße: unter 45 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Bewertung (optional) – Hinweis: Alle Bewertungen werden mithilfe unseres standardmäßigen Bewertungssystems angezeigt.
Bewertung – Maximalwert	Erforderlich	Der Maximalwert der Bewertungsskala. Muss angegeben werden, wenn auch der aktuelle Wert für die Bewertung angegeben ist.	Zahl >= 0,0
Bewertung – aktueller Wert	Erforderlich	Der aktuelle Wert der Bewertung der Entität. Muss angegeben werden, wenn auch der Höchstwert für die Bewertung angegeben ist.	Zahl >= 0,0
Bewertung – Anzahl	Optional	Die Anzahl der Bewertungen für die Entität.	String
DisplayTimeWindow (optional): Legen Sie ein Zeitfenster fest, für das Inhalte auf der Oberfläche angezeigt werden sollen.
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.	Epochenzeitstempel in Millisekunden
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.	Epochenzeitstempel in Millisekunden

`ShoppingCart`

Attribut	Anforderungen	Beschreibung	Formatieren
Aktions-URI	Erforderlich	Der Deeplink zum Einkaufswagen in der Partner-App. Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen findest du in diesen FAQs.	URI
Anzahl der Elemente	Erforderlich	Die Anzahl der Artikel (nicht nur die Anzahl der Produkte) im Einkaufswagen. Beispiel: Wenn sich im Warenkorb drei identische Hemden und ein Hut befinden, sollte diese Zahl 4 sein.	Ganzzahl >= 1
Aktionstext	Optional	Der Call-to-Action-Text der Schaltfläche im Einkaufswagen, z. B. Meine Einkaufstasche. *Wenn der Entwickler keinen Aktionstext bereitstellt, wird standardmäßig Einkaufswagen ansehen* verwendet.** Dieses Attribut wird ab Version 1.1.0 unterstützt.	String
Titel	Optional	Der Titel des Einkaufswagens, z. B. Meine Einkaufstasche. *Wenn vom Entwickler kein Titel angegeben wird, wird Dein Einkaufswagen* als Standardeinstellung verwendet.**	Freier Text Empfohlene Textgröße: unter 25 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Bilder des Einkaufswagens	Optional	Bilder der einzelnen Produkte im Einkaufswagen Es können bis zu 10 Bilder nach Priorität geordnet angezeigt werden. Die tatsächliche Anzahl der angezeigten Bilder hängt vom Formfaktor des Geräts ab.	Siehe Bildspezifikationen für eine Orientierungshilfe.
Elementlabels	Optional	Die Liste der Labels für Artikel auf der Einkaufsliste. Die tatsächliche Anzahl der angezeigten Labels hängt vom Formfaktor des Geräts ab.	Liste der Freitextlabels Empfohlene Textgröße: unter 20 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
DisplayTimeWindow (optional): Legen Sie ein Zeitfenster fest, für das Inhalte auf der Oberfläche angezeigt werden sollen.
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.	Epochenzeitstempel in Millisekunden
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.	Epochenzeitstempel in Millisekunden

`ShoppingList`

Attribut	Anforderungen	Beschreibung	Formatieren
Aktions-URI	Erforderlich	Der Deeplink zur Einkaufsliste in der App des Partners. Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen findest du in diesen FAQs.	URI
Anzahl der Elemente	Erforderlich	Die Anzahl der Artikel in der Einkaufsliste.	Ganzzahl >= 1
Titel	Optional	Der Titel der Liste, z. B. Ihre Einkaufsliste. *Wenn vom Entwickler kein Titel angegeben wird, wird Einkaufsliste* als Standardeinstellung verwendet.**	Freier Text Empfohlene Textgröße: unter 25 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Elementlabels	Erforderlich	Die Liste der Labels für Artikel auf der Einkaufsliste. Es muss mindestens ein Label angegeben werden. Es können bis zu zehn Labels nach Priorität angegeben werden. Die tatsächliche Anzahl der angezeigten Labels hängt vom Geräteformfaktor ab.	Liste der Freitextlabels Empfohlene Textgröße: unter 20 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)

`ShoppingReorderCluster`

Attribut	Anforderungen	Beschreibung	Formatieren
Aktions-URI	Erforderlich	Der Deeplink für die Neuanordnung in der App des Partners. Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen findest du in diesen FAQs.	URI
Aktionstext	Optional	Der Call-to-Action-Text der Schaltfläche auf der Schaltfläche „Neu anordnen“, z. B. Noch einmal bestellen *Wenn vom Entwickler kein Aktionstext angegeben wird, wird Neu anordnen* als Standardeinstellung verwendet.** Dieses Attribut wird ab Version 1.1.0 unterstützt.	String
Anzahl der Elemente	Erforderlich	Die Anzahl der Artikel (nicht nur die Anzahl der Produkte) in der vorherigen Bestellung. Beispiel: Wenn es in der vorherigen Bestellung 3 kleine Kaffeesorten und 1 Croissant gab, sollte diese Zahl 4 sein.	Ganzzahl >= 1
Titel	Erforderlich	Der Titel des neu angeordneten Artikels.	Freier Text Empfohlene Textgröße: unter 40 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Elementlabels	Optional (Falls nicht vorhanden, sollten Posterbilder zur Verfügung gestellt werden.)	Die Liste der Artikellabels für die vorherige Bestellung. Es können bis zu 10 Labels nach Priorität angegeben werden. Die tatsächliche Anzahl der angezeigten Labels hängt vom Geräteformfaktor ab.	Liste mit freiem Text Empfohlene Textgröße pro Label: unter 20 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Posterbilder	Optional (Wenn nicht angegeben, sollten Artikellabels angegeben werden.)	Bilder der Artikel in der vorherigen Bestellung. Es können bis zu 10 Bilder nach Priorität geordnet angezeigt werden. Die tatsächliche Anzahl der angezeigten Bilder hängt vom Formfaktor des Geräts ab.	Siehe Bildspezifikationen für eine Orientierungshilfe.

Bildspezifikationen

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

Seitenverhältnis	Mindestanzahl von Pixeln	Empfohlene Pixel
Quadrat (1 × 1) Bevorzugt für Cluster ohne Feature	300 × 300	1200 × 1200
Querformat (1,91 × 1) Bevorzugt für hervorgehobene Cluster	600 × 314	1200 × 628
Hochformat (4 x 5)	480 × 600	960 × 1200

Seitenverhältnis

Mindestanzahl von Pixeln

Empfohlene Pixel

Quadrat (1 × 1)

Bevorzugt für Cluster ohne Feature

300 × 300

1200 × 1200

Querformat (1,91 × 1)

Bevorzugt für hervorgehobene Cluster

600 × 314

1200 × 628

Hochformat (4 x 5)

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.
Verwenden Sie einen transparenten Hintergrund, damit das Bild im Modus „Dunkles und helles Design“ richtig angezeigt werden kann.

Schritt 2: Clusterdaten angeben

Es empfiehlt sich, 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 wenn der Nutzer gerade etwas in den Einkaufswagen gelegt hat).

AppEngageShoppingClient ist für die Veröffentlichung von Shopping-Clustern verantwortlich.

Die folgenden APIs werden für die Veröffentlichung von Clustern im Client bereitgestellt:

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishShoppingCart
publishShoppingList
publishShoppingReorderCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteShoppingCartCluster
deleteShoppingListCluster
deleteShoppingReorderCluster
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.

Ein RecommendationCluster-Objekt kann die folgenden Attribute haben:

Attribut	Anforderungen	Beschreibung
Liste von ShoppingEntity	Erforderlich	Eine Liste der ShoppingEntity-Objekte, aus denen die Empfehlungen für diesen Empfehlungscluster bestehen.
Titel	Erforderlich	Der Titel für den Empfehlungscluster. Empfohlene Textgröße: unter 25 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)
Aktions-URI	Optional	Der Deeplink zu der Seite in der Partner-App, auf der Nutzer die vollständige Liste der Empfehlungen sehen können. Hinweis: Sie können Deeplinks für die Attribution verwenden. Weitere Informationen findest du in diesen FAQs.

Attribut

Anforderungen

Beschreibung

Liste von ShoppingEntity

Erforderlich

Eine Liste der ShoppingEntity-Objekte, aus denen die Empfehlungen für diesen Empfehlungscluster bestehen.

Titel

Erforderlich

Der Titel für den Empfehlungscluster.

Empfohlene Textgröße: unter 25 Zeichen (Bei zu langem Text werden möglicherweise Auslassungspunkte angezeigt.)

Aktions-URI

Optional

Der Deeplink zu der Seite in der Partner-App, auf der Nutzer die vollständige Liste der Empfehlungen sehen können.

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

Kotlin


client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build())

Java


client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build());

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

Alle vorhandenen Daten des Empfehlungsclusters werden entfernt.
Die Daten aus der Anfrage werden geparst und in neuen Empfehlungsclustern gespeichert.

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

`publishFeaturedCluster`

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

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.

`publishShoppingCart`

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

Kotlin


client.publishShoppingCart(
            PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java


client.publishShoppingCart(
            new PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

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

Vorhandene ShoppingCart-Daten des Entwicklerpartners werden entfernt.
Die Daten aus der Anfrage werden geparst und im aktualisierten Einkaufswagencluster gespeichert.

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

`publishShoppingList`

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

Kotlin


client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

Java


client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

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

Vorhandene FoodShoppingList-Daten des Entwicklerpartners werden entfernt.
Die Daten aus der Anfrage werden geparst und im aktualisierten Einkaufslistencluster gespeichert.

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

`publishShoppingReorderCluster`

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

Kotlin


client.publishShoppingReorderCluster(
            PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java


client.publishShoppingReorderCluster(
            new PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    new ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

Vorhandene ShoppingReorderCluster-Daten des Entwicklerpartners werden entfernt.
Die Daten aus der Anfrage werden geparst und im aktualisierten Cluster zur Neuanordnung 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.

`deleteShoppingCartCluster`

Diese API wird zum Löschen des Inhalts des Einkaufswagen-Clusters verwendet.

Kotlin


client.deleteShoppingCartCluster()

Java


client.deleteShoppingCartCluster();

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

`deleteShoppingListCluster`

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

Kotlin


client.deleteShoppingListCluster()

Java


client.deleteShoppingListCluster();

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

`deleteShoppingReorderCluster`

Diese API wird zum Löschen des Inhalts des Clusters für die Neuanordnung von Shopping-Kampagnen verwendet.

Kotlin


client.deleteShoppingReorderCluster()

Java


client.deleteShoppingReorderCluster();

Wenn der Dienst die Anfrage empfängt, werden die vorhandenen Daten aus dem Cluster für die Neuanordnung von Shopping-Anzeigen 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.

Kotlin


client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java


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.

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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART))

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST))

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER))
}

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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is
// received

// Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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 Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST));

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

}

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.shopping.PUBLISH_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
      </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.shopping.PUBLISH_SHOPPING_CART Es wird empfohlen, einen publishShoppingCart-Aufruf zu starten, wenn dieser Intent empfangen wird.
com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST Es wird empfohlen, einen publishShoppingList-Aufruf zu starten, wenn dieser Intent empfangen wird.
com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER Es wird empfohlen, einen publishReorderCluster-Aufruf zu starten, 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 antwortet so schnell wie möglich.

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 eine interne Ü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 Einkaufswagen veröffentlicht und für Nutzer sichtbar.