Engage SDK Play: istruzioni per l'integrazione tecnica di terze parti

Google sta creando una piattaforma sul dispositivo che organizza app per verticali e consente una nuova esperienza immersiva per la fruizione personalizzata dei contenuti delle app e scoperta. Questa esperienza a schermo intero offre ai partner sviluppatori l'opportunità di mostrare i migliori contenuti avanzati in un canale dedicato esterno della propria app.

Questa guida contiene le istruzioni per gli sviluppatori partner per integrare il proprio audio utilizzando l'SDK Engage per compilare sia questa nuova area piattaforme Google esistenti.

Dettagli integrazione

Terminologia

Questa integrazione include i seguenti tre tipi di cluster: Recommendation, Continuazione e In primo piano.

• I cluster di consigli mostrano suggerimenti personalizzati per i contenuti da leggere di un singolo sviluppatore partner.

  I consigli hanno la seguente struttura:

  • Cluster dei suggerimenti:una visualizzazione UI che contiene un gruppo di contenuti consigliati dallo stesso partner di sviluppo.

    

  • Entità: un oggetto che rappresenta un singolo elemento in un cluster. Un'entità può essere una playlist, un audiolibro, un podcast e altro ancora. Consulta le Dati delle entità per un elenco delle entità supportate di testo.

    

• Il cluster Continuazione mostra i contenuti audio coinvolti di recente dagli utenti di più sviluppatori partner in un unico raggruppamento di UI. Ogni sviluppatore partner potrà trasmettere un massimo di 10 entità in Cluster di continuazione.

  

• Il cluster In primo piano mostra una selezione di elementi da più gli sviluppatori partner in un unico raggruppamento di UI. Ci sarà un singolo In primo piano cluster, che verrà visualizzato nella parte superiore della UI con priorità il posizionamento migliore rispetto a tutti i cluster di suggerimenti. Ogni sviluppatore partner autorizzato a trasmettere fino a 10 entità nel cluster In primo piano.

  

Attività preliminare

Livello API minimo: 19

Aggiungi la raccolta com.google.android.engage:engage-core alla tua app:

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

Riepilogo

La progettazione si basa sull'implementazione di un Google Cloud.

I dati che un cliente può pubblicare sono soggetti ai seguenti limiti per diversi tipi di cluster:

Passaggio 1: fornisci i dati dell'entità

L'SDK ha definito diverse entità per rappresentare ogni tipo di elemento. Supportiamo le seguenti entità per la categoria Ascolta:

1. MusicAlbumEntity
2. MusicArtistEntity
3. MusicTrackEntity
4. MusicVideoEntity
5. PlaylistEntity
6. PodcastSeriesEntity
7. PodcastEpisodeEntity
8. LiveRadioStationEntity
9. AudiobookEntity

I grafici riportati di seguito descrivono gli attributi e i requisiti disponibili per ogni tipo.

MusicAlbumEntity

L'oggetto MusicAlbumEntity rappresenta un album musicale (ad esempio, Mezzanotte di Taylor Swift).

MusicArtistEntity

L'oggetto MusicArtistEntity rappresenta un'arista musicale (ad esempio Adele).

MusicTrackEntity

L'oggetto MusicTrackEntity rappresenta una traccia musicale (ad esempio, Giallo di i Coldplay).

MusicVideoEntity

L'oggetto MusicVideoEntity rappresenta un video musicale (ad esempio, The Weeknd - Take My Breath (video musicale ufficiale)).

PlaylistEntity

L'oggetto PlaylistEntity rappresenta una playlist musicale (ad esempio, il video 10).

PodcastSeriesEntity

L'oggetto PodcastSeriesEntity rappresenta una serie di podcast (ad esempio, Questo American Life).

PodcastEpisodeEntity

L'oggetto PodcastEpisodeEntity rappresenta una serie di podcast (ad esempio, Spark Bird, puntata 754: This American Life).

LiveRadioStationEntity

L'oggetto LiveRadioStationEntity rappresenta una stazione radio in diretta (ad esempio, 98.1 The Breeze).

AudiobookEntity

L'oggetto AudiobookEntity rappresenta un audiolibro (ad esempio, l'audiolibro di Becoming di Michelle Obama).

Specifiche per le immagini

Di seguito sono elencate le specifiche obbligatorie per gli asset immagine:

Formati file

PNG, JPG, GIF statica, WebP

Dimensioni massime del file

5120 kB

Consigli aggiuntivi

• Area di sicurezza dell'immagine:inserisci i contenuti importanti al centro dell'80% della sezione dell'immagine.

Esempi

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();

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

Passaggio 2: fornisci i dati del cluster

Ti consigliamo di eseguire il job di pubblicazione dei contenuti in background (ad esempio, utilizzando WorkManager). e pianificato con cadenza regolare o evento (ad esempio, ogni volta l'utente apre l'app o quando ha appena aggiunto qualcosa al carrello).

AppEngagePublishClient è responsabile della pubblicazione dei cluster. Persone che seguo Le API sono disponibili nel client:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

Questa API viene utilizzata per verificare se il servizio è disponibile per l'integrazione e se i contenuti possono essere presentati sul dispositivo.

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

Questa API viene utilizzata per pubblicare un elenco di oggetti RecommendationCluster.

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni: una transazione:

• I dati esistenti relativi a RecommendationCluster dello sviluppatore partner verranno rimossi.
• I dati della richiesta vengono analizzati e archiviati nel suggerimento aggiornato di un cluster Kubernetes.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene viene mantenuta.

publishFeaturedCluster

Questa API viene utilizzata per pubblicare un elenco di oggetti FeaturedCluster.

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni: una transazione:

• I dati esistenti relativi a FeaturedCluster dello sviluppatore partner verranno rimossi.
• I dati della richiesta vengono analizzati e archiviati nel cluster in primo piano aggiornato.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene viene mantenuta.

publishContinuationCluster

Questa API viene utilizzata per pubblicare un oggetto ContinuationCluster.

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni: una transazione:

• I dati esistenti relativi a ContinuationCluster dello sviluppatore partner verranno rimossi.
• I dati della richiesta vengono analizzati e archiviati nella continuazione aggiornata di un cluster Kubernetes.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene viene mantenuta.

publishUserAccountManagementRequest

Questa API viene utilizzata per pubblicare una scheda di accesso . L'azione di accesso indirizza gli utenti a alla pagina di accesso dell'app, in modo che quest'ultima possa pubblicare contenuti (o fornire contenuti personalizzati)

I seguenti metadati fanno parte della scheda di accesso:

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

Quando il servizio riceve la richiesta, vengono eseguite le seguenti azioni: una transazione:

• I dati di UserAccountManagementCluster esistenti dallo sviluppatore partner sono rimosso.
• I dati della richiesta vengono analizzati e archiviati nel Cluster UserAccountManagementCluster.

In caso di errore, l'intera richiesta viene rifiutata e lo stato esistente viene viene mantenuta.

updatePublishStatus

Se, per qualsiasi motivo di business interno, nessuno dei cluster viene pubblicato, ti consigliamo vivamente di aggiornare lo stato di pubblicazione utilizzando API updatePubblicaStatus. Questo è importante perché :

• Indicare lo stato in tutti gli scenari, anche quando i contenuti vengono pubblicati (STATO == PUBBLICATO), è fondamentale per compilare le dashboard che utilizzano questo stato esplicito per comunicare lo stato di integrità e altre metriche della tua integrazione.
• Se non sono stati pubblicati contenuti, ma lo stato dell'integrazione non funziona (STATUS == NOT_PUBLISHERED), Google può evitare di attivare avvisi nell'app dashboard dell'integrità. Conferma che i contenuti non sono stati pubblicati a causa di un situazione prevista dal punto di vista del provider.
• Consente agli sviluppatori di capire quando i dati vengono pubblicati e quando .
• Google può utilizzare i codici di stato per sollecitare l'utente a eseguire determinate azioni nel dell'app in modo da poter vedere o risolvere i contenuti dell'app.

Ecco un elenco di codici di stato idonei per la pubblicazione :

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

Se i contenuti non vengono pubblicati perché un utente non ha eseguito l'accesso, Google consiglia di pubblicare la scheda di accesso. Se per qualsiasi motivo i fornitori non riescono a pubblicare la scheda di accesso ti consigliamo di chiamare l'API updatePubblicaStatus con il codice di stato NOT_PUBLISHERED_REQUIRES_SIGN_IN

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

deleteRecommendationClusters

Questa API viene utilizzata per eliminare i contenuti dei cluster dei suggerimenti.

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

Quando il servizio riceve la richiesta, rimuove i dati esistenti Cluster di suggerimenti. In caso di errore, l'intera richiesta viene rifiutata. e lo stato esistente viene mantenuto.

deleteFeaturedCluster

Questa API viene utilizzata per eliminare i contenuti del cluster in primo piano.

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti Cluster in primo piano. In caso di errore, l'intera richiesta viene rifiutata. e lo stato esistente viene mantenuto.

deleteContinuationCluster

Questa API viene utilizzata per eliminare i contenuti del cluster di continuazione.

client.deleteContinuationCluster()

client.deleteContinuationCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti Cluster di continuazione. In caso di errore, l'intera richiesta viene rifiutata. e lo stato esistente viene mantenuto.

deleteUserManagementCluster

Questa API viene utilizzata per eliminare i contenuti del cluster UserAccountManagement.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

Quando il servizio riceve la richiesta, rimuove i dati esistenti Cluster UserAccountManagement. In caso di errore, l'intera richiesta viene viene rifiutato e lo stato esistente viene mantenuto.

deleteClusters

Questa API viene utilizzata per eliminare i contenuti di un determinato tipo di cluster.

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

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

Quando il servizio riceve la richiesta, rimuove i dati esistenti da tutti corrispondenti ai tipi di cluster specificati. I clienti possono scegliere di superare uno o per molti tipi di cluster. In caso di errore, l'intera richiesta viene rifiutata e viene mantenuto.

Gestione degli errori

Ti consigliamo vivamente di ascoltare il risultato dell'attività dalle API di pubblicazione, ad esempio che è possibile eseguire un'azione di follow-up per recuperare e inviare nuovamente un'attività riuscita.

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

L'errore viene restituito come AppEngageException con la causa inclusa come un codice di errore.

Passaggio 3: gestisci gli intent di trasmissione

Oltre a effettuare chiamate all'API Publication di contenuti tramite un job, è anche necessario per configurare BroadcastReceiver per ricevere la richiesta di pubblicazione di contenuti.

L'obiettivo degli intent di trasmissione è principalmente la riattivazione dell'app e l'applicazione forzata dei dati sincronizzare. Gli intent di trasmissione non sono progettati per essere inviati molto spesso. È solo attivata quando il servizio Engage stabilisce che i contenuti potrebbero essere obsoleti (ad esempio, una settimana fa). In questo modo, l'utente può avere una maggiore sicurezza nuova esperienza con i contenuti, anche se l'applicazione non è stata eseguita per per un lungo periodo di tempo.

BroadcastReceiver deve essere configurato nei due modi seguenti:

• Registra dinamicamente un'istanza della classe BroadcastReceiver utilizzando Context.registerReceiver(). Ciò consente la comunicazione dalle applicazioni ancora in memoria.

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

}

• Dichiarare in modo statico un'implementazione con il tag <receiver> nel tuo AndroidManifest.xml file. Ciò consente all'applicazione di ricevere annunci quando non è in esecuzione e consente inoltre all'applicazione di pubblicare dei contenuti.

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

I seguenti intent verranno inviati dall' servizio:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION È consigliabile avviare una chiamata publishRecommendationClusters quando che ricevono questo intento.
• com.google.android.engage.action.PUBLISH_FEATURED Ti consigliamo di avviare una chiamata publishFeaturedCluster quando ricevi questo l'intento.
• com.google.android.engage.action.PUBLISH_CONTINUATION È consigliabile avviare una chiamata publishContinuationCluster quando ricevi questo intento.

Flusso di lavoro di integrazione

Per una guida passo passo sulla verifica dell'integrazione dopo il suo completamento, consulta Flusso di lavoro per l'integrazione degli sviluppatori del coinvolgimento.

Domande frequenti

Consulta le domande frequenti sull'SDK Engage per Domande frequenti.

Contact

Contatto engagement-developers@google.com se ci sono a eventuali domande durante il processo di integrazione. Il nostro team ti risponderà il prima possibile possibile.

Passaggi successivi

Dopo aver completato l'integrazione, i passaggi successivi sono i seguenti:

• Invia un'email a engagement-developers@google.com e collega l'APK integrato, pronto per essere testato da Google.
• Google eseguirà una verifica e una revisione interna per garantire che che funzioni come previsto. In caso di modifiche, Google ti contatterà con tutti i dettagli necessari.
• Quando il test è stato completato e non sono necessarie modifiche, Google ti contatterà per ti comunicherà che puoi iniziare a pubblicare l'APK aggiornato e integrato sul Play Store.
• Dopo che Google avrà confermato la pubblicazione dell'APK aggiornato su Play Store, il tuo Consiglio, In primo piano e Continuazione verranno pubblicati e saranno visibili agli utenti.