Codelab do SDK Engage

1. Introdução

Última atualização: 14/05/2025

O que é o SDK Engage?

O SDK Engage pode ajudar a aumentar o engajamento do seu app, mostrando o conteúdo personalizado do app onde os usuários estão em várias plataformas do Google no dispositivo. Com o SDK Engage, seu app pode oferecer recomendações e conteúdo de continuação personalizados (individuais) para engajar os usuários que instalaram o app antes que eles abram o aplicativo.

Superfícies de conteúdo

Coleções

Entertainment Space

Play Store (em breve)

Leve seu conteúdo diretamente para a tela inicial do usuário com um novo widget da Play Store.

Crie novos pontos de contato para conteúdo de entretenimento em alguns tablets Android.

Acesse outras plataformas, começando pela Play Store neste verão.

O que você vai criar

Ao concluir este codelab, você terá um app Android de vídeo que poderá enviar conteúdo para uma plataforma do Google.

O que é necessário

  • O SDK do Android mais recente.
  • A versão mais recente do Android Studio.
  • Um dispositivo móvel com Android 10 ou mais recente.
  • Um cabo de dados USB para conectar seu dispositivo móvel ao computador de desenvolvimento.

Experiência

  • Você precisa ter experiência com Java ou Kotlin.
  • Você precisa ter conhecimento em desenvolvimento para Android.

2. Executar o app de amostra

Para começar, baixe o código de exemplo do app para acompanhar este codelab.

Clone o repositório se você tiver o git instalado.

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

Se preferir, clique neste link para baixar o código-fonte e descompactar o arquivo ZIP.

Este projeto usa o sistema de build do Gradle. Para criar esse projeto, use o comando de build gradlew ou use Import Project no Android Studio.

Depois de baixar o código, você vai encontrar dois projetos de exemplo.

  • Para desenvolvedores Java: use o app de exemplo read

O app é uma biblioteca de livros básica. O usuário pode selecionar um livro de uma lista e começar a leitura. O app demonstra como os dados de recomendações e continuação são publicados.

  • Para desenvolvedores Kotlin: use o app de exemplo watch.

O app é uma biblioteca de vídeos básica. O usuário pode selecionar um vídeo em uma lista e assistir. O app demonstra como os dados de recomendações e continuação são publicados.

Para mais recursos sobre desenvolvimento para Android, acesse os guias para desenvolvedores em developer.android.com.

3. Criar uma entidade

Neste codelab, vamos nos referir ao Guia de integração do SDK Engage Read e ao Guia de integração do SDK Engage Watch para apps de exemplo read e watch, respectivamente.

Entidade: é um objeto que representa um único item em um cluster. Uma entidade pode ser um e-book, um filme ou qualquer tipo de conteúdo relevante.

Para conteúdo no app read, o SDK tem os seguintes tipos de entidade:

  • EbookEntity
  • AudiobookEntity
  • BookSeriesEntity

Para conteúdo no app watch, o SDK tem os seguintes tipos de entidade:

  • MovieEntity
  • TvShowEntity
  • TvSeasonEntity
  • TvEpisodeEntity
  • LiveStreamingVideoEntity
  • VideoClipEntity

No app de exemplo read, acesse o arquivo EbookToEntityConverter.java, que contém métodos para criar uma EbookEntity para publicação.

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

No app de exemplo watch, acesse o arquivo ItemToEntityConverter.kt, que contém métodos para criar uma MovieEntity para publicação.

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

Da mesma forma, no seu aplicativo, você também pode converter seus próprios itens de dados em entidades do Engage correspondentes que gostaria de publicar.

4. Criar um cluster de recomendação

Agora que criamos uma entidade, podemos agrupar em um cluster.

Os clusters são um conjunto de conteúdo agrupado. Elas podem ser exibidas como uma visualização de interface que contém um grupo de itens de conteúdo de um único parceiro de desenvolvimento.

e8ec28fa54ac7eec.pngFigura.

UI do Entertainment Space mostrando um cluster de recomendação com entidades de e-book de um único parceiro.

Para a maioria das categorias, incluindo conteúdo do read e watch, o SDK tem os seguintes tipos de cluster:

  • Os clusters de recomendação podem ser personalizados com base no comportamento do usuário no app e organizados por tema, como lançamentos, reduções de preço ou temas favoritos do usuário. Cada app pode fornecer até cinco clusters de recomendação por usuário.
  • O cluster de continuação ajuda os usuários a retomar o conteúdo em andamento, como um filme ou e-book inacabado, em um único grupo de UIs com conteúdo de vários apps.
  • O cluster de destaque pode destacar seu conteúdo hero em um cluster de vários apps usando um modelo de UI maior e mais premium.

Vamos criar um cluster de recomendações para conteúdo dos apps read e watch.

No app de exemplo read, acesse o arquivo GetRecommendationClusters.java, que mostra um exemplo de como criar um cluster de recomendação.

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

No app de exemplo watch, acesse o arquivo ClusterRequestFactory.kt, que mostra um exemplo de como criar um cluster de recomendação.

// 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. Publicar o cluster de recomendação

Agora que aprendemos a criar uma entidade e agrupar essas entidades em um cluster. A próxima etapa é aprender a publicar o cluster.

O AppEngagePublishClient é responsável por fazer a conexão para publicar o cluster.

Etapa 1: inicializar o cliente.

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

// Kotlin version
val client = AppEngagePublishClient(context)

Etapa 2: criar a solicitação para publicar o cluster

No app de exemplo read, confira o método setRecommendations em 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();

No app de exemplo watch, confira o método constructRecommendationClustersRequest em ClusterRequestFactory.kt.

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

Etapa 3: chamar o método publishRecommendationClusters no AppEngagePublishClient

No app de exemplo read, confira o método setRecommendations em EngageServiceWorker.java.

client.publishRecommendationClusters(publishRequest);

No app de exemplo watch, confira o método publishRecommendations em EngageServiceWorker.kt.

client.publishRecommendationClusters(request)

Usar a API isServiceAvailable

Antes de chamar a API publish, é necessário chamar isServiceAvailable para garantir que a publicação seja permitida.

No app de exemplo read, confira o método startWork em 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.
    }
}

No app de exemplo watch, confira o método doWork em 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. Status de publicação

Recomendamos usar a API updatePublishStatus para indicar por que o conteúdo não foi publicado. Isso ajuda o Google a evitar alertas falsos quando o app não publica conteúdo intencionalmente, orienta os usuários a tomar medidas corretivas para acessar o conteúdo e fornece insights sobre a saúde da publicação do conteúdo.

Consulte os códigos de status no site para desenvolvedores. Por exemplo, se nenhum conteúdo for mostrado porque um usuário precisa fazer login, use NOT_PUBLISHED_REQUIRES_SIGN_IN. Vamos aplicar esse código na próxima etapa.

No app de exemplo read, confira o método publishAndSetResult em 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);
            })

No app de exemplo watch, confira o método publishUserAccountManagement em 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 e intents de transmissão

WorkManager

Recomendamos executar o job de publicação de conteúdo em segundo plano (usando o WorkManager). Agende a execução frequente dele (por exemplo, diariamente) e/ou com base em eventos do usuário (por exemplo, quando o app é aberto ou depois que o usuário termina uma sessão de leitura). Os exemplos abaixo se concentram em uma publicação agendada.

No app de exemplo read, queuePeriodicSetEngageStateWorker no arquivo SetEngageState.java mostra um exemplo de como configurar um 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);

No app de amostra watch, o método periodicallyCallEngageServiceWorker em Publisher.kt mostra um exemplo de como configurar um 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 transmissão

Além de fazer chamadas de API de conteúdo de publicação usando um job, também é necessário configurar umBroadcastReceiver para receber a solicitação de publicação de conteúdo.

O objetivo principal das intents de transmissão é reativar o app e forçar a sincronização de dados. As intents de transmissão não são projetadas para envio muito frequente. Elas só são acionadas quando o serviço do Engage determina que o conteúdo pode estar desatualizado (por exemplo, é de uma semana atrás). Dessa forma, há mais confiança de que o usuário poderá ter uma nova experiência de conteúdo, mesmo que o aplicativo não tenha sido executado por um longo período.

O BroadcastReceiver precisa ser configurado de duas maneiras:

  • Registre dinamicamente uma instância da classe BroadcastReceiver usando Context.registerReceiver(). Isso permite a comunicação de aplicativos que ainda estão ativos na memória.

Abra o arquivo MainActivity.java no app de exemplo read para conferir o seguinte:

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);
  }
  • Declare estaticamente uma implementação com a tag <receiver> no arquivo AndroidManifest.xml. Isso permite que o aplicativo receba intents de transmissão quando não está em execução e também permite que ele publique o conteúdo.

Abra o arquivo AndroidManifest.xml no app de exemplo read para conferir o seguinte:

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

As intents abaixo são enviadas pelo serviço:

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION É recomendável iniciar uma chamada publishRecommendationClusters ao receber essa intent.
  • com.google.android.engage.action.PUBLISH_FEATURED É recomendável iniciar uma chamada publishFeaturedCluster ao receber essa intent.
  • com.google.android.engage.action.PUBLISH_CONTINUATION É recomendável iniciar uma chamada publishContinuationCluster ao receber essa intent.

8. Usar o app de verificação para testes

Baixe e use o app de verificação para conferir a integração.

O app de verificação mostra cada cluster como uma linha separada.

  • Insira o nome do pacote que está publicando os dados.

d1ad850cd02991d.png

  • Verifique se todas as entidades no cluster foram publicadas.

3953d00488212411.png

  • Confirme se todos os campos da entidade foram publicados. Para cada item na linha, os desenvolvedores podem clicar na imagem do pôster para verificar a intent.

23cd19224397adf3.png

Verificar o fluxo da intent de transmissão

Use o app de verificação para conferir a intent de transmissão. Clique no botão na parte de cima da interface para acionar a lógica de envio de transmissões.

9cb0b5315057fbe1.png

9. Parabéns

Agora você sabe como adicionar o SDK Engage ao seu app Android.

Para mais detalhes, consulte o guia para desenvolvedores e o site comercial do SDK Engage.

Recursos

Com base no tipo de conteúdo publicado, o SDK contém diferentes tipos de classes de entidade. Confira a lista de entidades disponíveis no guia de integração para cada categoria listada abaixo: