Atelier de programmation sur le SDK Engage
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

1. Introduction

Dernière mise à jour : 14/05/2025

Qu'est-ce que le SDK Engage ?

Le SDK Engage peut vous aider à booster l'engagement avec votre application en diffusant votre contenu personnalisé là où se trouvent les utilisateurs, sur plusieurs surfaces Google sur l'appareil. Avec le SDK Engage, votre application peut proposer des recommandations personnalisées (1:1) et du contenu de suivi pour susciter l'engagement des utilisateurs qui l'ont installée avant qu'ils n'ouvrent votre application.

Surfaces de contenu

Collections	Entertainment Space	Play Store (bientôt disponible)

Affichez vos contenus directement sur l'écran d'accueil de l'utilisateur avec un nouveau widget Play Store.	Créez de nouveaux points de contact pour les contenus de divertissement sur certaines tablettes Android.	Accédez à d'autres surfaces, à commencer par le Play Store cet été.

Objectifs de l'atelier

À la fin de cet atelier de programmation, vous disposerez d'une application vidéo Android capable d'envoyer du contenu sur une surface Google.

Prérequis

La dernière version du SDK Android
La dernière version d'Android Studio.
Un appareil mobile équipé d'Android 10 ou version ultérieure.
Un câble de données USB pour connecter votre appareil mobile à votre ordinateur de développement.

Expérience

Vous devez avoir de l'expérience en Java ou en Kotlin.
Vous devez avoir des connaissances en matière de développement Android.

2. Exécuter l'exemple d'application

Pour commencer, téléchargez le code d'application exemple qui vous aidera à suivre cet atelier de programmation.

Clonez le dépôt si vous avez installé Git.

git clone https://github.com/googlesamples/engage-sdk-samples.git

Vous pouvez également cliquer sur ce lien pour télécharger le code source et décompresser le fichier ZIP téléchargé.

Ce projet utilise le système de compilation Gradle. Pour créer ce projet, utilisez la commande de compilation gradlew ou l'option Importer un projet dans Android Studio.

Une fois le code téléchargé, deux exemples de projets s'affichent.

Pour les développeurs Java : utilisez l'application exemple de lecture

L'application est une bibliothèque de livres de base. L'utilisateur peut sélectionner un livre dans une liste, puis commencer à le lire. L'application montre comment les données de recommandations et de continuation sont publiées.

Pour les développeurs Kotlin : utilisez l'application exemple de visionnage

L'application est un lecteur vidéo de base. L'utilisateur peut sélectionner une vidéo dans une liste, puis commencer à la regarder. L'application montre comment les données de recommandations et de continuation sont publiées.

Pour obtenir d'autres ressources de formation en matière de développement Android, consultez les guides du développeur sur developer.android.com.

3. Créer une entité

Dans cet atelier de programmation, nous ferons référence au guide d'intégration du SDK Engage Read et au guide d'intégration du SDK Engage Watch pour les applications exemple de lecture et de visionnage, respectivement.

Entité : un objet représentant un seul élément dans un cluster. Une entité peut être un e-book, un film ou tout autre type de contenu pertinent.

Pour le contenu lu, le SDK dispose des types d'entités suivants :

EbookEntity
AudiobookEntity
BookSeriesEntity

Pour le contenu regardé, le SDK dispose des types d'entités suivants :

MovieEntity
TvShowEntity
TvSeasonEntity
TvEpisodeEntity
LiveStreamingVideoEntity
VideoClipEntity

Dans l'application exemple de lecture, accédez au fichier EbookToEntityConverter.java, qui contient des méthodes permettant de créer une EbookEntity à publier.

EbookEntity.Builder entityBuilder = new EbookEntity.Builder()
        .setName("NAME OF EBOOK")
        .addAuthor("AUTHOR NAME")
        .setActionLinkUri(Uri.parse("DEEPLINK URI OF THIS EBOOK"))
        ...
         .build()

Dans l'application exemple de visionnage, accédez au fichier ItemToEntityConverter.kt qui contient des méthodes permettant de créer une MovieEntity à publier.

val movieBuilder: MovieEntity.Builder =
      MovieEntity.Builder()
        .setName("NAME OF THE MOVIE")
        .addPosterImage(
          Image.Builder()
            .setImageUri(
              Uri.parse("android.resource://movie")
            )
            .setImageWidthInPixel(408)
            .setImageHeightInPixel(960)
            .setImageTheme(ImageTheme.IMAGE_THEME_LIGHT)
            .build()
        )
        .setPlayBackUri(Uri.parse(movie.playbackUri))
        .setReleaseDateEpochMillis(movie.releaseDate)
        .setAvailability(movie.availability)
        .setDurationMillis(movie.durationMillis)
        .addGenre(movie.genre)
          ..
           .build()

De même, dans votre application, vous pouvez également convertir vos propres éléments de données en entités Engage correspondants que vous souhaitez publier.

4. Créer un cluster "Recommandation"

Maintenant que nous avons créé une entité, nous pouvons la regrouper dans un cluster.

Les clusters sont des collections de contenus regroupés. Ils peuvent être visualisés sous la forme d'une vue d'interface utilisateur contenant un groupe d'éléments de contenu d'un seul développeur partenaire.

Figure.

Interface utilisateur d'Entertainment Space affichant un cluster "Recommandation" avec des entités Ebook d'un seul partenaire.

Pour la plupart des catégories, y compris les contenus de lecture et de visionnage, le SDK dispose des types de clusters suivants :

Les clusters Recommandation peuvent être personnalisés en fonction du comportement de l'utilisateur dans votre application et organisés par thème (nouveautés, baisses de prix ou thèmes préférés de l'utilisateur, par exemple). Chaque application peut fournir jusqu'à cinq clusters "Recommandation" par utilisateur.
Le cluster Continuation permet aux utilisateurs de reprendre un contenu en cours, comme un film ou un e-book inachevé, dans un seul groupe d'UI regroupant le contenu de plusieurs applications.
Le cluster Featured peut mettre en avant votre contenu héros dans un cluster multi-applications à l'aide d'un modèle d'interface utilisateur plus grand et plus premium.

Nous allons créer un cluster Recommendation à la fois pour les contenus de lecture et de visionnage.

Dans l'application exemple de lecture, accédez au fichier GetRecommendationClusters.java. Cela montre comment créer un cluster Recommandation.

RecommendationCluster.Builder clusterBuilder = new RecommendationCluster.Builder();
// Set the cluster title
clusterBuilder.setTitle("For You");
for (int id : ebookIds) {
  //Create an ebook entity.
  EbookEntity entity = EbookToEntityConverter.convert(id); 
  // Add the ebook entity to the cluster
  clusterBuilder.addEntity(entity);
}
// Build the cluster
return clusterBuilder.build();

Dans l'application exemple de visionnage, accédez au fichier ClusterRequestFactory.kt. Cela montre comment créer un cluster Recommandation.

// Loads all the movie data 
val recommendationsList = movieDao.loadMovieIsCurrentlyWatching(false)
val recommendationCluster = RecommendationCluster.Builder()
for (item in recommendationsList) {
   //Create a movie entity.
    val movieEntity = ItemToEntityConverter.convertMovie(item)
    // Add the movie entity to the cluster
    recommendationCluster.addEntity(movieEntity)
}
// Build the cluster
return recommendationCluster.build

5. Publier le cluster "Recommandation"

Maintenant que nous avons appris à créer une entité et à regrouper ces entités dans un cluster. L'étape suivante consiste à apprendre à publier le cluster.

AppEngagePublishClient est chargé d'établir la connexion pour publier le cluster.

Étape 1 : initialisez le client

// Java version
AppEngagePublishClient client = new AppEngagePublishClient(context);

// Kotlin version
val client = AppEngagePublishClient(context)

Étape 2 : créez la requête pour publier le cluster

Dans l'application exemple de lecture, vérifiez la méthode setRecommendations dans EngageServiceWorker.java.

// Initialize the builder
PublishRecommendationClustersRequest.Builder publishRequestBuilder = new PublishRecommendationClustersRequest.Builder();

// Add all Recommendation Clusters
for (RecommendationCluster cluster : clusters) {
   publishRequestBuilder.addRecommendationCluster(cluster);
}
// Build the request    
publishRequestBuilder.build();

Dans l'application exemple de visionnage, vérifiez la méthode constructRecommendationClustersRequest dans ClusterRequestFactory.kt.

// Initialize the builder
val request = PublishRecommendationClustersRequest.Builder()
// Add all Recommendation Cluster
.addRecommendationCluster(recommendationCluster)
// Build the request    
.build()

Étape 3 : appelez la méthode publishRecommendationClusters dans AppEngagePublishClient

Dans l'application exemple de lecture, vérifiez la méthode setRecommendations dans EngageServiceWorker.java.

client.publishRecommendationClusters(publishRequest);

Dans l'application exemple de visionnage, vérifiez la méthode publishRecommendations dans EngageServiceWorker.kt.

client.publishRecommendationClusters(request)

Utiliser l'API isServiceAvailable

Avant d'appeler l'API publish, vous devez appeler isServiceAvailable pour vous assurer que la publication est autorisée.

Dans l'application exemple de lecture, vérifiez la méthode startWork dans EngageServiceWorker.java.

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Dans l'application exemple de visionnage, vérifiez la méthode doWork dans EngageServiceWorker.kt.

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

6. État de la publication

Nous vous recommandons d'utiliser l'API updatePublishStatus pour indiquer pourquoi le contenu n'est pas publié. Cela permet à Google d'éviter les fausses alertes lorsque votre application ne publie pas de contenu intentionnellement, d'aider les utilisateurs à prendre des mesures correctives pour accéder à votre contenu et de vous fournir des renseignements sur l'état de publication de vos contenus.

Consultez les codes d'état sur le site pour les développeurs. Par exemple, si aucun contenu n'est affiché, car l'utilisateur doit se connecter, utilisez NOT_PUBLISHED_REQUIRES_SIGN_IN. Nous appliquerons ce code à l'étape suivante.

Dans l'application exemple de lecture, vérifiez la méthode publishAndSetResult dans EngageServiceWorker.kt.

int publishStatusCode;
              if (loggedInAccount.isPresent()) {
                // If an account is logged in and content is published
                publishStatusCode = AppEngagePublishStatusCode.PUBLISHED;
              } else {
                // If an account is not logged in and no content is published
                publishStatusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN;
              }
              setPublishStatus(client, publishStatusCode);
            })

Dans l'application exemple de visionnage, vérifiez la méthode publishUserAccountManagement dans EngageServiceWorker.kt.

private suspend fun publishUserAccountManagement(): Result {
    val publishTask: Task<Void>
    val statusCode: Int
    if (db.accountDao().isAccountSignedIn()) {
      // If an account is logged in and content is published
statusCode = AppEngagePublishStatusCode.PUBLISHED
    } else {
     // If an account is not logged in and no content is published
      statusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN
    }
    return publishAndProvideResult(publishTask, statusCode)
  }

7. WorkManager et intents de diffusion

WorkManager

Nous vous recommandons d'exécuter la tâche de publication de contenu en arrière-plan (à l'aide de WorkManager). Planifiez-la régulièrement (par exemple, tous les jours) et/ou en fonction des événements utilisateur (par exemple, lorsque l'application s'ouvre ou lorsque l'utilisateur termine une session de lecture). Les exemples ci-dessous portent sur une publication planifiée.

Dans l'application exemple de lecture, queuePeriodicSetEngageStateWorker dans le fichier SetEngageState.java montre un exemple de configuration d'un WorkManager.

// Create a work manager
WorkManager workManager = WorkManager.getInstance(appContext);

// Set up a periodic work request for 24 hrs.
PeriodicWorkRequest publishRequest =
        new PeriodicWorkRequest.Builder(
                EngageServiceWorker.class, /* repeatInterval= */ 24, TimeUnit.HOURS)
            .setInputData(clusterToPublishData)
            .build();
// Add the work request to queue
workManager.enqueueUniquePeriodicWork(
        publishWorkName, ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE, publishRequest);

Dans l'application exemple de visionnage, periodicallyCallEngageServiceWorker dans Publisher.kt montre un exemple de configuration d'un WorkManager.

// Set up a periodic work request for 24 hrs.
val workRequest = PeriodicWorkRequestBuilder<EngageServiceWorker>(
          repeatInterval = 24,
          repeatIntervalTimeUnit = TimeUnit.HOURS
        )
        .setInputData(workDataOf(PUBLISH_TYPE to publishType))
        .build()

// Create a work manager and add the work request to queue
WorkManager.getInstance(context)
.enqueueUniquePeriodicWork(
workerName,
ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
workRequest
)

Intents de diffusion

En plus d'effectuer des appels d'API de publication de contenu par l'intermédiaire d'une tâche, vous devez également configurer un objet BroadcastReceiver pour recevoir la requête de publication de contenu.

L'objectif des intents de diffusion est principalement de réactiver des applications et de forcer la synchronisation des données. Les intents de diffusion ne sont pas conçus pour être envoyés très fréquemment. Ils ne se déclenchent que lorsque le service Engage détermine que le contenu est peut-être obsolète (par exemple, s'il date d'il y a une semaine). De cette façon, l'utilisateur a plus de chances de bénéficier d'une expérience de contenu actualisée, même si l'application n'a pas été exécutée pendant une longue période.

Le BroadcastReceiver doit être configuré de deux manières :

Enregistrez dynamiquement une instance de la classe BroadcastReceiver à l'aide de Context.registerReceiver(). Cela permet la communication à partir d'applications restées actives en mémoire.

Ouvrez le fichier MainActivity.java dans l'application exemple de lecture pour vérifier les éléments suivants :

private void registerReceiver() {
    BroadcastReceiver publishReceiver = new EngageServiceBroadcastReceiver();
    IntentFilter filter = new IntentFilter();
    filter.addAction(Intents.ACTION_PUBLISH_RECOMMENDATION);
    filter.addAction(Intents.ACTION_PUBLISH_FEATURED);
    filter.addAction(Intents.ACTION_PUBLISH_CONTINUATION);
    int flags = ContextCompat.RECEIVER_EXPORTED;
    ContextCompat.registerReceiver(getApplicationContext(), publishReceiver, filter, flags);
  }

Déclarez une implémentation de manière statique avec la balise <receiver> dans votre fichier AndroidManifest.xml. Cela permet à l'application de recevoir des intents de diffusion lorsqu'elle n'est pas en cours d'exécution, et de publier le contenu.

Ouvrez le fichier AndroidManifest.xml dans l'application exemple de lecture pour vérifier les éléments suivants :

<receiver
        android:name=".publish.EngageServiceBroadcastReceiver"
        android:exported="true">
      <intent-filter>
        <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
        <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
        <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
             </intent-filter>
 </receiver>

Les intents suivants sont envoyés par le service :

com.google.android.engage.action.PUBLISH_RECOMMENDATION Il est recommandé de démarrer un appel publishRecommendationClusters lors de la réception de cet intent.
com.google.android.engage.action.PUBLISH_FEATURED Il est recommandé de démarrer un appel publishFeaturedCluster lors de la réception de cet intent.
com.google.android.engage.action.PUBLISH_CONTINUATION Il est recommandé de démarrer un appel publishContinuationCluster lors de la réception de cet intent.

8. Utiliser l'application de validation pour les tests

Téléchargez et utilisez l'application de validation pour valider votre intégration.

L'application de validation doit afficher chaque cluster sur une ligne distincte.

Saisissez le nom du package qui publie les données.

Vérifiez que toutes les entités du cluster sont publiées.

Vérifiez que tous les champs de l'entité sont publiés. Pour chaque élément de la ligne, les développeurs peuvent cliquer sur l'image poster pour vérifier l'intent.

Vérifier le flux de l'intent de diffusion

Utilisez l'application de validation pour vérifier l'intent de diffusion, cliquez sur le bouton en haut de l'interface utilisateur pour déclencher la logique d'envoi d'annonces.

9. Félicitations

Vous savez maintenant comment ajouter le SDK Engage à votre application Android.

Pour en savoir plus, consultez le guide du développeur et le site d'entreprise du SDK Engage.

Ressources

En fonction du type de contenu publié, le SDK contient différents types de classes d'entités. Vous trouverez la liste des entités disponibles dans le guide d'intégration pour chaque secteur ci-dessous.

Atelier de programmation sur le SDK Engage Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.