Codelab sobre el SDK de Engage
Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

1. Introducción

Última actualización: 14/5/2025

¿Qué es el SDK de Engage?

El SDK de Engage puede ayudarte a aumentar la participación con tu app, ya que lleva el contenido personalizado de la app a donde están los usuarios en varias plataformas de Google integradas en el dispositivo. Con el SDK de Engage, tu app puede mostrar recomendaciones personalizadas (1:1) y contenido de continuación para atraer a los usuarios que la instalaron antes de que la abran.

Plataformas de contenido

Colecciones	Entertainment Space	Play Store (próximamente)

Lleva tu contenido directamente a la pantalla principal del usuario con un nuevo widget de Play Store.	Crea nuevos puntos de contacto para el contenido de entretenimiento en tablets Android seleccionadas.	Accede a plataformas adicionales, comenzando por Play Store este verano.

Qué compilarás

Cuando completes este codelab, tendrás una app de video para Android que podrá enviar contenido a una plataforma de Google.

Requisitos

La versión más reciente del SDK de Android
La versión más reciente de Android Studio
Un dispositivo móvil con Android 10 o versiones posteriores
Un cable de datos USB para conectar tu dispositivo móvil a la computadora de desarrollo

Experiencia

Deberás tener experiencia en Java o Kotlin.
Deberás tener conocimientos sobre desarrollo en Android.

2. Ejecuta la app de ejemplo

Para comenzar, descarga el código de la app de ejemplo que te ayudará a seguir este codelab.

Si tienes git instalado, clona el repositorio.

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

Como alternativa, haz clic en este vínculo para descargar el código fuente y descomprimir el archivo ZIP descargado.

En este proyecto, se usa el sistema de compilación Gradle. Para compilar el proyecto, usa el comando de compilación gradlew o "Import Project" en Android Studio.

Después de descargar el código, verás dos proyectos de muestra.

Para desarrolladores de Java: Usa la app de ejemplo de lectura.

La app es una biblioteca de libros básica. El usuario puede seleccionar un libro de una lista y, luego, comenzar a leerlo. La app muestra cómo se publican los datos de Recommendations y Continuation.

Para desarrolladores de Kotlin: Usa la app de ejemplo de visualización.

La app es una biblioteca de videos básica. El usuario puede seleccionar un video de una lista y, luego, comenzar a mirarlo. La app muestra cómo se publican los datos de Recommendations y Continuation.

Para obtener más recursos sobre el desarrollo en Android, visita las guías para desarrolladores en developer.android.com.

3. Compila una entidad

En este codelab, nos referiremos a la Guía de integración de lectura del SDK de Engage y a la Guía de integración de visualización del SDK de Engage para las apps de ejemplo de lectura y visualización, respectivamente.

Entidad es un objeto que representa un solo elemento en un clúster. Una entidad puede ser un libro electrónico, una película o cualquier tipo de contenido relevante.

Para el contenido de lectura, el SDK tiene los siguientes tipos de entidades:

EbookEntity
AudiobookEntity
BookSeriesEntity

Para el contenido de visualización, el SDK tiene los siguientes tipos de entidades:

MovieEntity
TvShowEntity
TvSeasonEntity
TvEpisodeEntity
LiveStreamingVideoEntity
VideoClipEntity

En la app de ejemplo de lectura, ve al archivo EbookToEntityConverter.java, que contiene métodos para compilar una EbookEntity para su publicación.

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

En la app de ejemplo de visualización, ve al archivo ItemToEntityConverter.kt, que contiene métodos para compilar una MovieEntity para su publicación.

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 manera similar, en tu aplicación, también puedes convertir tus propios elementos de datos en las entidades de Engage correspondientes que deseas publicar.

4. Compila un clúster de Recommendation

Ahora que creamos una entidad, podemos agruparlas en un clúster.

Los clústeres son un conjunto de contenido agrupado. Se pueden visualizar como una vista de la IU que contiene un grupo de elementos de contenido de un solo socio desarrollador.

Figure.

IU de Entertainment Space que muestra un clúster de Recommendation con entidades de libros electrónicos de un solo socio.

Para la mayoría de las categorías, incluido el contenido de lectura y visualización, el SDK tiene los siguientes tipos de clústeres:

Los clústeres de Recommendation se pueden personalizar en función del comportamiento de los usuarios en tu app y organizar por tema, como nuevos lanzamientos, reducciones de precios o los temas favoritos de los usuarios. Cada app puede proporcionar hasta 5 clústeres de Recommendation por usuario.
El clúster de Continuation ayuda a los usuarios a reanudar el contenido en curso, como una película o un libro electrónico sin terminar, en una sola agrupación de IU con contenido de varias apps.
El clúster de Featured puede destacar tu contenido hero en un clúster de múltiples apps con una plantilla de IU más grande y premium.

Crearemos un clúster de Recommendation para el contenido de lectura y visualización.

En la app de ejemplo de lectura, ve al archivo GetRecommendationClusters.java, que muestra un ejemplo de cómo compilar un clúster de Recommendation.

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

En la app de ejemplo de visualización, ve al archivo ClusterRequestFactory.kt, que muestra un ejemplo de cómo compilar un clúster de Recommendation.

// 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. Publica el clúster de Recommendation

Ahora que aprendimos a crear una entidad y a agruparlas en un clúster, el siguiente paso es aprender a publicar el clúster.

AppEngagePublishClient es responsable de establecer la conexión para publicar el clúster.

Paso 1: Inicializa el cliente

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

// Kotlin version
val client = AppEngagePublishClient(context)

Paso 2: Crea la solicitud para publicar el clúster

En la app de ejemplo de lectura, consulta el método setRecommendations en 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();

En la app de ejemplo de visualización, consulta el método constructRecommendationClustersRequest en ClusterRequestFactory.kt.

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

Paso 3: Llama al método publishRecommendationClusters en AppEngagePublishClient

En la app de ejemplo de lectura, consulta el método setRecommendations en EngageServiceWorker.java.

client.publishRecommendationClusters(publishRequest);

En la app de ejemplo de visualización, consulta el método publishRecommendations en EngageServiceWorker.kt.

client.publishRecommendationClusters(request)

Usa la API de isServiceAvailable

Antes de llamar a la API de publicación, es necesario llamar a isServiceAvailable para asegurarse de que se permita la publicación.

En la app de ejemplo de lectura, consulta el método startWork en 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.
    }
}

En la app de ejemplo de visualización, consulta el método doWork en 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. Estado de publicación

Te recomendamos que uses la API de updatePublishStatus para indicar por qué no se publica el contenido. Esto ayuda a Google a evitar alertas falsas cuando tu app no publica contenido de forma intencional, a guiar a los usuarios para que tomen medidas correctivas para acceder a tu contenido y a proporcionarte estadísticas sobre el estado de publicación de tu contenido.

Consulta el sitio para desarrolladores para obtener los códigos de estado. Por ejemplo, si no se muestra contenido porque un usuario necesita acceder a su cuenta, usa NOT_PUBLISHED_REQUIRES_SIGN_IN. Aplicaremos este código en el siguiente paso.

En la app de ejemplo de lectura, consulta el método publishAndSetResult en 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);
            })

En la app de ejemplo de visualización, consulta el método publishUserAccountManagement en 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 y los intents de transmisión

WorkManager

Recomendamos que ejecutes el trabajo de publicación de contenido en segundo plano (con WorkManager). Establece que aparezca con cierta frecuencia (p. ej., todos los días) o en función de eventos del usuario (p. ej., cuando se abre la app o después de que el usuario finaliza una sesión de lectura). Los siguientes ejemplos se centran en una publicación programada.

En la app de ejemplo de lectura, queuePeriodicSetEngageStateWorker en el archivo SetEngageState.java muestra un ejemplo de cómo configurar 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);

En la app de ejemplo de visualización, periodicallyCallEngageServiceWorker en Publisher.kt muestra un ejemplo de cómo configurar 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 transmisión

Además de realizar llamadas a las APIs de publicación de contenido a través de un trabajo, también se requiere configurar un BroadcastReceiver para recibir la solicitud de publicación de contenido.

El objetivo de los intents de transmisión es principalmente reactivar apps y forzar la sincronización de datos. Los intents de transmisión no están diseñados para enviarse con mucha frecuencia. Solo se activan cuando el servicio de Engage determina que el contenido puede estar inactivo (por ejemplo, si es de hace una semana). De esa manera, será más probable que el usuario tenga una experiencia de contenido actualizada, incluso si la aplicación no se ejecutó durante un período prolongado.

El BroadcastReceiver debe configurarse de las siguientes dos maneras:

Registra de forma dinámica una instancia de la clase BroadcastReceiver con Context.registerReceiver(). Esto permite la comunicación desde aplicaciones que aún están activas en la memoria.

Abre el archivo MainActivity.java en la app de ejemplo de lectura para verificar lo siguiente:

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

Declara de forma estática una implementación con la etiqueta <receiver> en tu archivo AndroidManifest.xml. Esto permite que la aplicación reciba intents de transmisión cuando no está en ejecución y que la aplicación publique el contenido.

Abre el archivo AndroidManifest.xml en la app de ejemplo de lectura para verificar lo siguiente:

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

El servicio envía los siguientes intents:

com.google.android.engage.action.PUBLISH_RECOMMENDATION. Te recomendamos iniciar una llamada a publishRecommendationClusters cuando recibas este intent.
com.google.android.engage.action.PUBLISH_FEATURED. Te recomendamos iniciar una llamada a publishFeaturedCluster cuando recibas este intent.
com.google.android.engage.action.PUBLISH_CONTINUATION. Te recomendamos iniciar una llamada a publishContinuationCluster cuando recibas este intent.

8. Usa la app de verificación para realizar pruebas

Descarga y usa la app de verificación para verificar tu integración.

La app de verificación debe mostrar cada clúster como una fila independiente.

Ingresa el nombre del paquete que publica los datos.

Verifica que todas las entidades del clúster se hayan publicado.

Verifica que todos los campos de la entidad se hayan publicado. Para cada elemento de la fila, los desarrolladores pueden hacer clic en la imagen de póster y verificar el intent.

Verifica el flujo de intents de transmisión

Usa la app de verificación para verificar el intent de transmisión. Haz clic en el botón en la parte superior de la IU para activar la lógica de envío de transmisiones.

9. Felicitaciones

Ahora sabes cómo agregar el SDK de Engage a tu app para Android.

Para obtener más detalles, consulta la guía para desarrolladores y el sitio empresarial del SDK de Engage.

Recursos

Según el tipo de contenido que se publica, el SDK contiene diferentes tipos de clases de entidades. Puedes ver la lista de entidades disponibles en la guía de integración de cada vertical que se indica a continuación:

Codelab sobre el SDK de Engage Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.