Richtlinien für die Veröffentlichung von Engage SDK-Clustern

Dieser Leitfaden enthält eine Reihe von Richtlinien für die Cluster-Veröffentlichung, die Entwickler bei der Integration des Engage SDK verwenden können.

Empfehlungscluster

Clustertitel

Wir empfehlen, einen eindeutigen und relevanten Clustertitel anzugeben, der Nutzern mehr Informationen zum Inhalt des Clusters gibt.

Hier sind einige Beispiele für gute, auf den Inhalt basierende Cluster-Titel:

  • Shopping-bezogene Cluster
    • Blitzangebote
    • Must-haves der Woche
    • Im Zusammenhang mit Ihrem Kauf von Pixel Buds
    • Gummistiefel für Damen
  • Büchersammlungen zum Thema Gesundheit
    • Gesundheit, Geist und Körper
    • Empfehlungen für dich in der Kategorie „Gesundheit“
    • Bestseller in der Kategorie Fitness

Clusterinhalt

Beim Veröffentlichen von Empfehlungsclustern müssen Entwickler berücksichtigen, ob der Nutzer in der Anwendung des Entwicklers angemeldet ist oder nicht.

Wenn der Nutzer angemeldet ist

Wenn der Nutzer in der Entwickler-App angemeldet ist, empfehlen wir, Cluster mit personalisierten oder nutzergenerierten Inhalten zu veröffentlichen. Da personalisierte und von Nutzern erstellte Inhalte relevanter für die Nutzer sind, sind sie motivierter, die Entwickler-App über die Google-Oberfläche aufzurufen.

  • Personalisierte Empfehlungen können veröffentlicht werden.
    • Hier einige Beispiele für personalisierte Empfehlungen:
      • Empfehlungen basierend auf dem Wiedergabeverlauf des Nutzers.
      • Ähnliche Bücher wie Bücher, die im Leseverlauf des Nutzers enthalten sind.
      • Titel der Lieblingsinterpreten des Nutzers
  • Bibliotheken mit von Nutzern erstellten Inhalten können veröffentlicht werden.
    • Hier einige Beispiele für Bibliotheken mit von Nutzern erstellten Inhalten:
      • Die Merkliste des Nutzers aus der Entwickler-App.
      • Eine Liste der Lieblingskünstler des Nutzers aus der Entwickler-App.
Empfehlungstyp Strategie für die Inhaltsaktualität Richtlinie zur Aktualität von Inhalten
Personalisierte Empfehlungen

Lenient

Wir empfehlen, die Empfehlungen einmal täglich zu aktualisieren, damit Nutzer täglich neue Empfehlungen sehen können.

 Da Nutzer keine genauen Erwartungen an den Inhalt der Empfehlung haben, kann die Strategie zur Aktualität der Inhalte nachsichtig sein.
Bibliotheken mit von Nutzern erstellten Inhalten

Strikt

Wir empfehlen, die Inhaltsbibliothek zu aktualisieren, wenn Nutzer die Entwickler-App verlassen.

 Diese Inhalte müssen mit den Daten übereinstimmen, die auf Google-Plattformen angezeigt werden. Das liegt daran, dass Nutzer im Gegensatz zu personalisierten Empfehlungen exakte Inhalte erwarten. Jede erhebliche Verzögerung bei der Veröffentlichung ist für die Nutzer verwirrend. Daher muss die Strategie für die Aktualität der Inhalte strikt sein.

Wenn der Nutzer nicht angemeldet ist

Auch wenn ein Nutzer nicht bei der Entwickler-App angemeldet ist, empfehlen wir dennoch, Cluster zu veröffentlichen, damit Nutzer die Entwickler-App über die Google-Oberfläche aufrufen können.

  • Nicht personalisierte Empfehlungscluster sollten veröffentlicht werden.
    • Hier einige Beispiele für nicht personalisierte Empfehlungen:
      • Die 10 besten Bücher, die dieses Jahr gelesen wurden.
      • Neue Filme
      • Angesagte Podcasts.
  • Veröffentlichen Sie eine Anmeldeseite.
    • Um Nutzer zu ermutigen, sich in der Entwickler-App anzumelden, können Entwickler zusammen mit dem nicht personalisierten Empfehlungscluster eine Anmeldekarte veröffentlichen. Weitere Informationen zum Veröffentlichen einer Anmeldekarte findest du im folgenden Abschnitt.
Empfehlungstyp Strategie für die Inhaltsaktualität Richtlinie zur Aktualität von Inhalten
Nicht personalisierte Empfehlungen

Lenient

Wir empfehlen, die Empfehlungen einmal pro Tag zu aktualisieren.

 Da Nutzer keine genauen Erwartungen an den Inhalt der Empfehlung haben, kann die Strategie zur Aktualität der Inhalte nachsichtig sein.
Anmeldekarte in Empfehlungen

Strikt

Wir empfehlen, den Status der Anmeldekarte zu aktualisieren, wenn Nutzer die Entwickler-App verlassen.

Nachdem sich Nutzer angemeldet haben, müssen Entwickler die Karte durch Aufrufen der deleteUserManagementCluster() API löschen.

Es ist wichtig, dass der Anmeldestatus mit der Google-Oberfläche synchronisiert wird. Es ist für Nutzer verwirrend, wenn sie eine Anmeldekarte in der Google-Oberfläche sehen, wenn sie bereits angemeldet sind. Daher muss die Strategie für die Aktualität der Inhalte strikt sein.

Fortsetzungs-Cluster

Beim Veröffentlichen von Fortsetzungsclustern müssen Entwickler berücksichtigen, ob der Nutzer in der Anwendung des Entwicklers angemeldet ist oder nicht.

Wenn der Nutzer angemeldet ist

  • Von Nutzern erstellte Continuation-Cluster sollten veröffentlicht werden.
    • Hier sind einige Beispiele für nutzergenerierte Continuation-Cluster:
      • Die Wiedergabe an der Stelle fortsetzen, an der der Nutzer aufgehört hat.
      • Lesen Sie dort weiter, wo der Nutzer aufgehört hat.
Fortsetzungstyp Strategie für die Inhaltsaktualität Richtlinie zur Aktualität von Inhalten
Von Nutzern erstellte Fortsetzungs-Cluster

Strikt

Wir empfehlen, die Inhaltsbibliothek zu aktualisieren, wenn Nutzer die Entwickler-App verlassen.

 Diese Inhalte müssen mit den Daten synchronisiert sein, die auf den Oberflächen von Google angezeigt werden. Das liegt daran, dass Nutzer im Gegensatz zu personalisierten Empfehlungen exakte Inhalte erwarten. Jede erhebliche Verzögerung bei der Veröffentlichung ist für die Nutzer verwirrend. Daher muss die Strategie für die Aktualität der Inhalte strikt sein.

Wenn der Nutzer nicht angemeldet ist

Fortsetzungspfade sind in erster Linie für angemeldete Nutzer gedacht. Sie können jedoch auch Fortsetzungscluster für nicht angemeldete Nutzer veröffentlichen, wenn Ihre Anwendung Gastsitzungen unterstützt.

Nutzerverwaltungs-Cluster

Der Nutzerverwaltungscluster soll Nutzer hauptsächlich dazu bringen, bestimmte Aktionen in der Anbieter-App auszuführen. Durch die Anmeldeaktion werden Nutzer zur Anmeldeseite der App weitergeleitet, damit die App Inhalte veröffentlichen oder personalisiertere Inhalte bereitstellen kann.

Anmeldekarte

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

appEngagePublishClient.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();

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

Nachdem sich Nutzer angemeldet haben, müssen Entwickler die Karte durch Aufrufen der deleteUserManagementCluster() API löschen.

Veröffentlichungsstatus aktualisieren

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, empfehlen wir, 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());

WorkManager für die Clusterveröffentlichung

Wir empfehlen die Verwendung von WorkManager zum Veröffentlichen von Clustern, da dies die empfohlene Lösung für Hintergrundarbeit ist, bei der die Ausführung sowohl opportunistisch als auch garantiert sein muss.

  • WorkManager führt Ihre Hintergrundarbeit so schnell wie möglich aus.
  • WorkManager übernimmt die Logik zum Starten Ihrer Arbeit unter verschiedenen Bedingungen, auch wenn ein Nutzer Ihre App verlässt.

Wenn der Nutzer die Anwendung verlässt, empfehlen wir, einen Hintergrundjob zu starten, der Fortsetzungscluster zusammen mit Empfehlungsclustern veröffentlicht. Ein guter Ort für diese Logik ist Activity.onStop(). Dieser wird aufgerufen, wenn der Nutzer die App verlässt.

Wir empfehlen, mit PeriodicWorkRequest einen wiederkehrenden Job zu planen, bei dem alle 24 Stunden Cluster veröffentlicht werden. Mithilfe einer CANCEL_AND_REENQUEUE-Richtlinie zum Auslösen der Arbeit können Entwickler dafür sorgen, dass WorkManager die aktualisierten Daten jedes Mal sendet, wenn ein Nutzer die App verlässt. So wird verhindert, dass Nutzer veraltete Daten sehen.

Das folgende Beispiel veranschaulicht dies:

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

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.

Entwickler müssen sich jedoch nicht ausschließlich auf Broadcasts verlassen, da sie nur in bestimmten Szenarien ausgelöst werden – hauptsächlich für die Reaktivierung von Apps und das Erzwingen einer Datensynchronisierung. Sie werden nur ausgelöst, wenn der Google Engage-Dienst feststellt, dass der Inhalt möglicherweise veraltet ist. Auf diese Weise gibt es eine höhere Gewissheit, dass dem Nutzer neue Inhalte angezeigt werden, auch wenn die Anwendung längere Zeit nicht geöffnet 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 Arbeitsspeicher befinden.
  • 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.