Diretrizes de publicação de clusters do Engage SDK

Este guia inclui um conjunto de diretrizes para a publicação de clusters que os desenvolvedores podem usar ao fazer a integração com o SDK Engage.

Clusters de recomendação

Título do cluster

Recomendamos que o cluster tenha um título exclusivo e relevante que ofereça aos usuários mais informações sobre o conteúdo dele.

Confira alguns exemplos de bons títulos de clusters com base no conteúdo:

• Clusters relacionados a compras
  • Ofertas relâmpago
  • Promoções imperdíveis da semana
  • Relacionados à sua compra de Pixel Buds
  • Galochas femininas
• Clusters de livros sobre saúde
  • Saúde, mente e corpo
  • Recomendados para você na área da saúde
  • Mais vendidos de fitness

Conteúdo do cluster

Ao publicar clusters de recomendação, os desenvolvedores precisam considerar se o usuário está ou não conectado ao aplicativo deles.

Quando o usuário está conectado

Se o usuário estiver conectado ao app do desenvolvedor, é recomendável publicar clusters de conteúdo personalizado ou gerado pelo usuário. Como o conteúdo personalizado e gerado pelo usuário é mais relevante, o usuário fica mais motivado a visitar o app do desenvolvedor na plataforma do Google.

• É possível publicar recomendações personalizadas.
  • Confira a seguir alguns exemplos dessas recomendações:
    • Principais recomendações com base no histórico de exibição do usuário.
    • Livros semelhantes aos que estão no histórico de leitura do usuário.
    • Músicas dos artistas favoritos do usuário.
• Bibliotecas de conteúdo gerado pelo usuário podem ser publicadas.
  • Abaixo estão alguns exemplos de bibliotecas de conteúdo gerado pelo usuário:
    • Lista de interesses do usuário no app do desenvolvedor.
    • Uma lista dos artistas favoritos do usuário, informada por ele mesmo, no app do desenvolvedor.

Quando o usuário não está conectado

Mesmo que um usuário não esteja conectado ao app do desenvolvedor, recomendamos publicar clusters para que ele seja incentivado a acessar o app na plataforma do Google.

• Clusters de recomendação não personalizados precisam ser publicados.
  • Confira alguns exemplos de recomendações não personalizadas:
    • Os 10 principais livros lidos neste ano.
    • Filmes lançados recentemente.
    • Podcasts em alta.
• Publique um cartão de login.
  • Para incentivar os usuários a fazer login no app, os desenvolvedores podem publicar um card de login com o cluster de recomendações não personalizadas. Confira a seção abaixo para mais detalhes sobre como publicar um Card de login.

Clusters de continuação

Ao publicar clusters de continuação, os desenvolvedores precisam considerar se o usuário está ou não conectado ao aplicativo deles.

Quando o usuário está conectado

• Clusters de continuação gerados pelo usuário precisam ser publicados.
  • Consulte alguns exemplos de clusters de continuação gerados pelo usuário:
    • Continuar assistindo de onde o usuário parou.
    • Continuar lendo de onde o usuário parou.

Quando o usuário não está conectado

As jornadas de continuação são destinadas principalmente a usuários que fizeram login. No entanto, você também pode publicar clusters de continuação para usuários não conectados caso o app tenha suporte a sessões de visitante.

Cluster de Gerenciamento de usuários

O principal objetivo do cluster de Gerenciamento de usuários é incentivar a execução de ações específicas no app do provedor. Por exemplo, a ação de login direciona o usuário à página de login para que o app possa publicar ou oferecer conteúdo mais personalizado.

Card de login

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

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

appEngagePublishClient.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Depois que os usuários fizerem login, os desenvolvedores precisarão excluir o cartão chamando a API deleteUserManagementCluster().

Atualizar o status de publicação

Se, por qualquer motivo interno, nenhum dos clusters for publicado, é altamente recomendável atualizar o status de publicação usando a API updatePublishStatus. Isso é importante pelos seguintes motivos:

• Informar o status em todos os casos possíveis, mesmo quando o conteúdo é publicado (STATUS == PUBLISHED), é fundamental para preencher painéis que usam o status explícito para transmitir informações de integridade e outras métricas da integração.
• Se nenhum conteúdo for publicado, mas o status da integração não estiver corrompido (STATUS == NOT_PUBLISHED), o Google poderá evitar o acionamento de alertas nos painéis de integridade do app. Isso confirma que o conteúdo não foi publicado devido a uma situação esperada pelo provedor.
• Ajuda os desenvolvedores a oferecer insights sobre quando os dados foram publicados ou não.
• O Google pode usar os códigos de status para incentivar o usuário a executar ações específicas no app, como acessar o conteúdo ou resolver o problema.

Lista de códigos de status de publicação que podem ser usados:

// 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 o conteúdo não for publicado porque o usuário não estava conectado, recomendamos publicar o card de login. Se, por algum motivo, os provedores não conseguirem publicar o card de login, recomendamos chamar a API updatePublishStatus usando o código de status NOT_PUBLISHED_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());

WorkManager para publicação de clusters

É importante usar o WorkManager para publicar clusters, porque essa é a solução recomendada para trabalhos em segundo plano em que a execução precisa ser oportuna e garantida.

• O WorkManager executa o trabalho em segundo plano o mais rápido possível.
• Ele processa a lógica para iniciar o trabalho em várias condições, mesmo que um usuário saia do app.

Quando o usuário sai do app, recomendamos iniciar um job em segundo plano que publique clusters de continuação com clusters de recomendação. Um bom local para processar essa lógica é o Activity.onStop(), que é chamado quando o usuário sai do app.

Sugerimos usar PeriodicWorkRequest para programar um job recorrente que publique clusters a cada 24 horas. Os desenvolvedores podem garantir que o WorkManager envie dados atualizados sempre que um usuário sair do app usando uma política CANCEL_AND_REENQUEUE para acionar o trabalho. Isso ajuda a evitar que os usuários acessem dados desatualizados.

O exemplo a seguir demonstra isso:

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

Processar 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 um BroadcastReceiver para receber a solicitação de publicação de conteúdo.

No entanto, os desenvolvedores precisam ter cuidado para não depender apenas de transmissões, porque elas são acionadas apenas em determinadas situações, principalmente para reativar apps e para forçar uma sincronização de dados. Elas são acionadas somente quando o serviço Engage determina que o conteúdo pode estar desatualizado. Dessa forma, há mais confiança de que o usuário terá uma experiência de conteúdo atualizada, mesmo que o aplicativo não tenha sido aberto há muito tempo.

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