Engage SDK Social: 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 Social-Media-Inhalte 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:

android skills add engage-sdk-integration

Integrationsdetails

Im folgenden Abschnitt finden Sie Details zur Integration.

Terminologie

Empfehlungscluster enthalten personalisierte Vorschläge von einzelnen Entwicklerpartnern.

Ihre Empfehlungen haben die folgende Struktur:

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

Jeder Empfehlungscluster besteht aus einem der folgenden beiden Entitätstypen :

• PortraitMediaEntity
• SocialPostEntity

PortraitMediaEntity muss ein Bild im Hochformat für den Beitrag enthalten. Profil- und interaktionsbezogene Metadaten sind optional.

• Posten

  • Bild im Porträtmodus und Zeitstempel oder
  • Bild im Porträtmodus + Textinhalt und Zeitstempel

• Profil

  • Avatar, Name oder Alias, zusätzliches Bild

• Interaktionen

  • Nur zählen und labeln oder
  • Anzahl und visuell (Symbol)

SocialPostEntity enthält Metadaten zu Profilen, Beiträgen und Interaktionen.

• Profil

  • Avatar, Name oder Alias, zusätzlicher Text, zusätzliches Bild

• Posten

  • Text und Zeitstempel oder
  • Rich Media (Bild oder Rich-URL) und Zeitstempel oder
  • Text und Rich Media (Bild oder Rich-URL) und Zeitstempel oder
  • Videovorschau (Thumbnail und Dauer) und Zeitstempel

• Interaktionen

  • Nur zählen und labeln oder
  • Anzahl und visuell (Symbol)

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:

Schritt 1: Daten zum Rechtssubjekt angeben

Im SDK sind verschiedene Entitäten definiert, die die einzelnen Artikeltypen darstellen. Das SDK unterstützt die folgenden Entitäten für die Kategorie „Soziale Netzwerke“:

1. PortraitMediaEntity
2. SocialPostEntity

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

PortraitMediaEntity

SocialPostEntity

Bildspezifikationen

Die Bilder müssen auf öffentlichen CDNs gehostet werden, damit Google darauf zugreifen kann.

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.
• Verwenden Sie einen transparenten Hintergrund, damit das Bild sowohl im dunklen als auch im hellen Design richtig angezeigt wird.

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 der Nutzer gerade einem neuen Konto gefolgt ist).

AppEngageSocialClient ist für die Veröffentlichung von sozialen Clustern verantwortlich.

Es gibt die folgenden APIs, um Cluster im Client zu veröffentlichen:

• isServiceAvailable
• publishRecommendationClusters
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• 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.

Für Engage SDK v1.6.0 und höher (empfohlen)

android skills add engage-sdk-integration

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

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.

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

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 Sie diese Funktion für einen Clustertyp aktivieren möchten, wenden Sie sich an engage-developers@google.com.

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

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

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.

Ein RecommendationCluster-Objekt kann die folgenden Attribute haben:

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build());

Wenn der Dienst die Anfrage empfängt, werden die folgenden Aktionen innerhalb einer Transaktion 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.

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:

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

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.

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

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.

client.deleteRecommendationsClusters()

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.

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

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.

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

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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.

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.

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // 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)
}

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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);
}

• 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>
   </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.

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 an engage-developers@google.com, wenn du während des Integrationsprozesses Fragen hast. 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 eine interne Ü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 die aktualisierte und integrierte APK im Play Store veröffentlichen kannst.
• Nachdem Google bestätigt hat, dass Ihr aktualisiertes APK im Google Play Store veröffentlicht wurde, werden Ihre Empfehlungscluster veröffentlicht und für Nutzer sichtbar.