SDK Engage Food: instruções técnicas de integração de terceiros

O Google está criando uma plataforma no dispositivo que organiza os apps dos usuários por categoria e possibilita uma nova experiência imersiva para consumo e descoberta de conteúdo personalizado de apps. Essa experiência em tela cheia oferece aos parceiros dos desenvolvedores uma oportunidade de mostrar o melhor conteúdo avançado em um canal dedicado fora do app.

Este guia contém instruções para que os parceiros dos desenvolvedores integrem conteúdo de comida, usando o SDK Engage para preencher essa nova área e as plataformas do Google.

Detalhe de integração

Terminologia

Essa integração inclui os cinco tipos de cluster a seguir: recomendação, em destaque, carrinho de compras de comida, lista de compras de comida e pedir de novo.

• Os clusters de recomendação mostram sugestões personalizadas de comidas de um parceiro de desenvolvedor. Essas recomendações podem ser personalizadas para o usuário ou generalizadas (por exemplo, novas promoções). Use-as para mostrar receitas, lojas, pratos, supermercados e assim por diante, conforme achar adequado.

  • Um cluster de recomendação pode ser formado por listas de ProductEntity, StoreEntity ou RecipeEntity, mas não por uma combinação de diferentes tipos de entidade.

• O cluster de destaque mostra a principal ProductEntity, StoreEntity ou RecipeEntity de vários parceiros de desenvolvedores em um grupo de interfaces. Há um único cluster de destaque, mostrado perto da parte de cima da interface, com um posicionamento prioritário acima de todos os clusters de recomendação. Cada parceiro de desenvolvimento pode transmitir uma única entidade de um tipo "Destaque" com suporte, com muitas entidades (possivelmente de tipos diferentes) de vários desenvolvedores de apps no cluster Destaque.

• O cluster de carrinho de compras de alimentos mostra uma prévia dos carrinhos de compras de supermercado de vários parceiros de desenvolvimento em um grupo de interfaces, incentivando os usuários a concluir os carrinhos pendentes. Há um único cluster de carrinho de compras de alimentos.

  • O cluster do carrinho de compras de comida precisa mostrar a contagem total de itens no carrinho e também pode incluir imagens de alguns itens no carrinho do usuário.

• O cluster de lista de compras de alimentos mostra uma prévia das listas de compras de supermercado de vários parceiros de desenvolvimento em um grupo de interfaces, solicitando que os usuários retornem ao app correspondente para atualizar e concluir as listas. Há um único cluster de lista de compras de alimentos.

• O cluster de pedir de novo mostra uma prévia dos pedidos anteriores de vários parceiros para desenvolvedores em um grupo de interfaces, pedindo que os usuários façam pedidos novamente. Há um único cluster de "pedir de novo".

  • O cluster de pedir de novo precisa mostrar o número total de itens no pedido anterior do usuário e incluir uma das opções abaixo:

    • Imagens de alguns itens do pedido anterior do usuário.
    • Rótulos de alguns itens do pedido anterior do usuário.

Pré-trabalho

Nível mínimo da API: 19

Adicione a biblioteca com.google.android.play:engage ao app:

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

Resumo

O design é baseado na implementação de um serviço vinculado.

Os dados que um cliente pode publicar estão sujeitos aos seguintes limites para diferentes tipos de clusters:

Tipo de cluster	Limites de cluster	Limites máximos de entidades em um cluster
Clusters de recomendação	No máximo 5	No máximo 25 (ProductEntity, RecipeEntity ou StoreEntity)
Cluster de destaque	No máximo 1	No máximo 1 (ProductEntity, RecipeEntity ou StoreEntity)
Cluster de carrinho de compras de comida	No máximo 1	No máximo 1 ShoppingCartEntity
Cluster da lista de compras de comida	No máximo 1	No máximo 1 ShoppingListEntity
Cluster de pedir alimentos de novo	No máximo 1	No máximo 1 ReorderEntity

Etapa 1: fornecer dados da entidade

O SDK definiu entidades diferentes para representar cada tipo de item. Oferecemos suporte às seguintes entidades na categoria "Comida":

1. ProductEntity
2. StoreEntity
3. RecipeEntity
4. FoodShoppingCart
5. FoodShoppingList
6. FoodReorderCluster

As tabelas abaixo descrevem os atributos e os requisitos disponíveis para cada tipo.

ProductEntity

O objeto ProductEntity representa um item (como um item de supermercado, um prato de um restaurante ou uma promoção) que os parceiros de desenvolvedores querem publicar.

Atributo	Requisito	Descrição	Formato
Poster images	Obrigatório	É necessário fornecer pelo menos uma imagem.	Consulte as orientações em Especificações de imagem.
Action Uri	Obrigatório	O link direto para a página no app que mostra detalhes sobre o produto. Observação: é possível usar links diretos para atribuição. Consulte as perguntas frequentes.	URI
Título	Opcional	O nome do produto.	Texto livre Tamanho de texto recomendado: menos de 90 caracteres (um texto muito longo será mostrado com reticências)
Price - current	Obrigatório sob certas condições	O preço atual do produto. Precisa ser fornecido se o preço tachado for informado.	Texto livre
Price - strikethrough	Opcional	O preço original da entidade, que aparece com desconto na interface.	Texto livre
Callout	Opcional	Frase de destaque para apresentar uma promoção, evento ou atualização do produto, se disponível.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Callout fine print	Opcional	Texto com os termos da frase de destaque.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Classificação (opcional): todas as classificações são mostradas usando nosso sistema padrão de avaliação com estrelas.
Rating - max value	Obrigatório	O valor máximo da escala de avaliação. Precisa ser fornecido se o valor atual da classificação também for informado.	Número maior ou igual a 0,0
Rating - current value	Obrigatório	O valor atual da classificação da entidade. Precisa ser fornecido se o valor máximo de avaliação também for fornecido.	Número maior ou igual a 0,0
Rating - count	Opcional	O número de classificações recebidas pela entidade.	String
DisplayTimeWindow (opcional): define uma janela de tempo para que um conteúdo seja mostrado na plataforma
Start Timestamp	Opcional	Carimbo de data/hora da época depois da qual o conteúdo será mostrado na plataforma. Se não for definido, o conteúdo poderá ser mostrado na plataforma.	Carimbo de data/hora da época em milissegundos
End Timestamp	Opcional	Carimbo de data/hora da época depois da qual o conteúdo não será mais mostrado na plataforma. Se não for definido, o conteúdo poderá ser mostrado na plataforma.	Carimbo de data/hora da época em milissegundos

StoreEntity

O objeto StoreEntity representa uma loja individual que os parceiros de desenvolvedores querem publicar, como um restaurante ou mercado.

Atributo	Requisito	Descrição	Formato
Poster images	Obrigatório	É necessário fornecer pelo menos uma imagem.	Consulte as orientações em Especificações de imagem.
Action Uri	Obrigatório	O link direto para a página no app que mostra detalhes sobre a loja. Observação: é possível usar links diretos para atribuição. Consulte as perguntas frequentes.	URI
Título	Opcional	O nome da loja.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Localização	Opcional	A localização da loja.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Callout	Opcional	Frase de destaque para apresentar uma promoção, evento ou atualização para a loja, se disponível.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Callout fine print	Opcional	Texto com os termos da frase de destaque.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Descrição	Opcional	Uma descrição da loja.	Texto livre Tamanho de texto recomendado: menos de 90 caracteres (um texto muito longo será mostrado com reticências)
Observação: todas as classificações são mostradas usando nosso sistema padrão de avaliação por estrelas.
Rating - max value	Obrigatório sob certas condições	O valor máximo da escala de avaliação. Precisa ser fornecido se o valor atual da classificação também for informado.	Número maior ou igual a 0,0
Rating - current value	Obrigatório sob certas condições	O valor atual da classificação da entidade. Precisa ser fornecido se o valor máximo de avaliação também for fornecido.	Número maior ou igual a 0,0
Rating - count	Opcional	O número de classificações recebidas pela entidade.	String

RecipeEntity

O objeto RecipeEntity representa um item de receita que os parceiros de desenvolvedores querem publicar.

Atributo	Requisito	Descrição	Formato
Poster images	Obrigatório	É necessário fornecer pelo menos uma imagem.	Consulte as orientações em Especificações de imagem.
Action Uri	Obrigatório	O link direto para a página no app que mostra detalhes sobre a receita. Observação: é possível usar links diretos para atribuição. Consulte as perguntas frequentes.	URI
Título	Opcional	O nome da receita.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Author	Opcional	O autor da receita.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Cook/Preparation time	Opcional	O tempo de cozimento da receita.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Callout	Opcional	Frase de destaque para apresentar uma promoção, evento ou atualização da receita, se disponível.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Categoria	Opcional	A categoria da receita.	Texto livre Tamanho de texto recomendado: menos de 45 caracteres (um texto muito longo será mostrado com reticências)
Descrição	Opcional	Uma descrição da receita.	Texto livre Tamanho de texto recomendado: menos de 90 caracteres (um texto muito longo será mostrado com reticências)
Observação: todas as classificações são mostradas usando nosso sistema padrão de avaliação por estrelas.
Rating - max value	Obrigatório sob certas condições	O valor máximo da escala de avaliação. Precisa ser fornecido se o valor atual da classificação também for informado.	Número maior ou igual a 0,0
Rating - current value	Obrigatório sob certas condições	O valor atual da classificação da entidade. Precisa ser fornecido se o valor máximo de avaliação também for fornecido.	Número maior ou igual a 0,0
Rating - count	Opcional	O número de classificações recebidas pela entidade.	String

FoodShoppingCart

Atributo	Requisito	Descrição	Formato
Action Uri	Obrigatório	O link direto para o carrinho de compras no app do parceiro. Observação: é possível usar links diretos para atribuição. Consulte as perguntas frequentes.	URI
Number of items	Obrigatório	Número de itens (não apenas o número de produtos) no carrinho de compras. Por exemplo: se houver três laranjas e uma maçã no carrinho, esse número deverá ser 4.	Número inteiro: a partir de 1
Título	Opcional	O título do carrinho (por exemplo, Seu carrinho). Se o desenvolvedor não fornecer nenhum título, Seu carrinho será o padrão.	Texto livre Tamanho de texto recomendado: menos de 25 caracteres (um texto muito longo será mostrado com reticências)
Action Text	Opcional	O texto de call-to-action do botão no carrinho de compras (por exemplo, Sua sacola de compras). Se o desenvolvedor não fornecer um texto de ação, o padrão será View Cart (conferir carrinho). Esse atributo tem suporte na versão 1.1.0 ou mais recente.	String
Cart images	Opcional	Imagens de cada produto no carrinho. É possível fornecer até 10 imagens em ordem de prioridade. O número real de imagens exibidas depende do formato do dispositivo.	Consulte as orientações em Especificações de imagem.
Item labels	Opcional	Lista de rótulos para itens na lista de compras. O número real de rótulos mostrados depende do formato do dispositivo.	Lista de rótulos de texto livre Tamanho de texto recomendado: menos de 20 caracteres (um texto muito longo será mostrado com reticências)
DisplayTimeWindow (opcional): define uma janela de tempo para que um conteúdo seja mostrado na plataforma
Start Timestamp	Opcional	Carimbo de data/hora da época depois da qual o conteúdo será mostrado na plataforma. Se não for definido, o conteúdo poderá ser mostrado na plataforma.	Carimbo de data/hora da época em milissegundos
End Timestamp	Opcional	Carimbo de data/hora da época depois da qual o conteúdo não será mais mostrado na plataforma. Se não for definido, o conteúdo poderá ser mostrado na plataforma.	Carimbo de data/hora da época em milissegundos

FoodShoppingList

Atributo	Requisito	Descrição	Formato
Action Uri	Obrigatório	O link direto para a lista de compras no app do parceiro. Observação: é possível usar links diretos para atribuição. Consulte as perguntas frequentes.	URI
Number of items	Obrigatório	Número de itens na lista de compras.	Número inteiro: a partir de 1
Título	Opcional	O título da lista (por exemplo, Sua lista de compras). Se o desenvolvedor não fornecer nenhum título, a lista de compras será o padrão.	Texto livre Tamanho de texto recomendado: menos de 25 caracteres (um texto muito longo será mostrado com reticências)
Item labels	Obrigatório	Lista de rótulos para itens na lista de compras. Pelo menos um rótulo precisa ser fornecido, com até 10 rótulos em ordem de prioridade. O número real de rótulos exibidos depende do formato do dispositivo.	Lista de rótulos de texto livre Tamanho de texto recomendado: menos de 20 caracteres (um texto muito longo será mostrado com reticências)

FoodReorderCluster

Atributo	Requisito	Descrição	Formato
Action Uri	Obrigatório	O link direto para fazer um novo pedido no app do parceiro. Observação: é possível usar links diretos para atribuição. Consulte as perguntas frequentes.	URI
Action Text	Opcional	O texto de call-to-action do botão para fazer o pedido novamente (por exemplo, Pedir de novo). Se o desenvolvedor não fornecer um texto de ação, o padrão será Reorder (pedir novamente). Esse atributo tem suporte na versão 1.1.0 ou mais recente.	String
Number of items	Obrigatório	O número de itens (não apenas o número de produtos) no pedido anterior. Por exemplo: se houver três cafés pequenos e um croissant no pedido anterior, esse número deverá ser 4.	Número inteiro: a partir de 1
Título	Obrigatório	O título do item do novo pedido.	Texto livre Tamanho de texto recomendado: menos de 40 caracteres (um texto muito longo será mostrado com reticências)
Item labels	Opcional Se não forem fornecidos, as imagens do pôster precisam ser fornecidas.	Lista de rótulos de itens para o pedido anterior. É possível fornecer até 10 rótulos em ordem de prioridade. O número real de rótulos exibidos depende do formato do dispositivo.	Lista de texto livre Tamanho de texto recomendado por rótulo: menos de 20 caracteres (um texto muito longo será mostrado com reticências)
Poster images	Opcional Se não forem fornecidos, os rótulos de item devem ser fornecidos.	Imagens dos itens no pedido anterior. É possível fornecer até 10 imagens em ordem de prioridade. O número real de imagens exibidas depende do formato do dispositivo.	Consulte as orientações em Especificações de imagem.

Especificações da imagem

Consulte abaixo as especificações necessárias para recursos de imagem:

Proporção	Mínimo de pixels	Pixels recomendados
Quadrada (1 x 1) Preferida	300 x 300	1.200 x 1.200
Paisagem (1,91 x 1)	600 x 314	1.200 x 628
Retrato (4 x 5)	480 x 600	960 x 1.200

Formatos de arquivo

PNG, JPG, GIF estático, WebP

Tamanho máximo do arquivo

5.120 KB

Recomendações adicionais

• Área de segurança da imagem: posicione o conteúdo importante no centro da imagem, ocupando 80% do espaço.
• Use um plano de fundo transparente para que a imagem possa ser exibida corretamente nas configurações do tema claro e escuro.

Etapa 2: fornecer dados do cluster

É recomendável executar o job de publicação de conteúdo em segundo plano (por exemplo, usando o WorkManager) e o programar com frequência ou por evento (por exemplo, toda vez que o usuário abrir o app ou adicionar algo ao carrinho).

O AppEngageFoodClient é responsável por publicar clusters de alimentos.

Estas são as APIs para publicar clusters no cliente:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishFoodShoppingCart
• publishFoodShoppingList
• publishReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteFoodShoppingCartCluster
• deleteFoodShoppingListCluster
• deleteReorderCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

Essa API é usada para conferir se o serviço está disponível para integração e se o conteúdo pode ser apresentado no dispositivo.

Kotlin

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

Java

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

Observação: é recomendável manter um job periódico em execução para verificar se o serviço será disponibilizado mais tarde. A disponibilidade do serviço pode mudar com upgrades de versão do Android, upgrades de app, instalações e desinstalações. Ao fazer verificações periódicas de jobs em determinado intervalo de tempo, os dados poderão ser publicados quando o serviço estiver disponível.

publishRecommendationClusters

Essa API é usada para publicar uma lista de objetos RecommendationCluster.

Um objeto RecommendationCluster pode ter os seguintes atributos:

Atributo	Requisito	Descrição
List of ProductEntity, StoreEntity, or RecipeEntity	Obrigatório	Uma lista de entidades que compõem as recomendações desse cluster de recomendação. As entidades de um único cluster precisam ser do mesmo tipo.
Título	Obrigatório	O título do cluster de recomendação (por exemplo, Ofertas para o menu de Natal). Tamanho de texto recomendado: menos de 25 caracteres (um texto muito longo será mostrado com reticências)
Action Uri	Opcional	O link direto para a página no app do parceiro em que os usuários podem acessar a lista completa de recomendações. Observação: é possível usar links diretos para atribuição. Consulte as perguntas frequentes.

Importante: as APIs de publicação são APIs de inserção que substituem o conteúdo já existente. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build());

Quando o serviço recebe a solicitação, as ações abaixo ocorrem em uma transação:

• Todos os dados do cluster de recomendação são removidos.
• Os dados da solicitação são analisados e armazenados em novos clusters de recomendação.

Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

publishFeaturedCluster

Essa API é usada para publicar um objeto FeaturedCluster.

Importante: as APIs de publicação são APIs de inserção que substituem o conteúdo já existente. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente.

Kotlin

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

Java

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

Quando o serviço recebe a solicitação, as ações abaixo ocorrem em uma transação:

• Os dados do FeaturedCluster do parceiro do desenvolvedor são removidos.
• Os dados da solicitação são analisados e armazenados no cluster de destaque atualizado.

Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

publishFoodShoppingCart

Essa API é usada para publicar um objeto FoodShoppingCart.

Importante: as APIs de publicação são APIs de inserção que substituem o conteúdo já existente. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente.

Kotlin

client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

Quando o serviço recebe a solicitação, as ações abaixo ocorrem em uma transação:

• Os dados do FoodShoppingCart do parceiro do desenvolvedor são removidos.
• Os dados da solicitação são analisados e armazenados no cluster de carrinho de compras atualizado.

Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

publishFoodShoppingList

Essa API é usada para publicar um objeto FoodShoppingList.

Importante: as APIs de publicação são APIs de inserção que substituem o conteúdo já existente. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente.

Kotlin

client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

Quando o serviço recebe a solicitação, as ações abaixo ocorrem em uma transação:

• Os dados do FoodShoppingList do parceiro do desenvolvedor são removidos.
• Os dados da solicitação são analisados e armazenados no cluster de lista de compras atualizado.

Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

publishReorderCluster

Essa API é usada para publicar um objeto FoodReorderCluster.

Importante: as APIs de publicação são APIs de inserção que substituem o conteúdo já existente. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente.

Kotlin

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

Quando o serviço recebe a solicitação, as ações abaixo ocorrem em uma transação:

• Os dados do FoodReorderCluster do parceiro do desenvolvedor são removidos.
• Os dados da solicitação são analisados e armazenados no cluster de novo pedido atualizado.

Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

publishUserAccountManagementRequest

Essa API é usada para publicar um card de login. A ação de login direciona os usuários à página de login do app para que ele possa publicar ou oferecer conteúdo mais personalizado.

Os metadados abaixo fazem parte do card de login:

Atributo	Requisito	Descrição
Action Uri	Obrigatório	Link direto para a ação (ou seja, leva à página de login do app)
Imagem	Opcional: se não for fornecido, o título precisa ser fornecido	Imagem mostrada no card Imagens com proporção de 16 x 9 e resolução de 1.264 x 712
Título	Opcional: se não for fornecido, a imagem precisará ser fornecida	Título do card
Action Text	Opcional	Texto mostrado no CTA (por exemplo, "Fazer login")
Subtitle	Opcional	Subtítulo opcional do card

Importante: as APIs de publicação são APIs de inserção que substituem o conteúdo já existente. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente.

Kotlin

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

Java

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 o serviço recebe o pedido, as seguintes ações ocorrem em uma transação:

• Os dados do UserAccountManagementCluster do parceiro do desenvolvedor são removidos.
• Os dados do pedido são analisados e armazenados no cluster UserAccountManagementCluster atualizado.

Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

updatePublishStatus

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, o Google recomenda 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.

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

Essa API é usada para excluir o conteúdo dos clusters de recomendação.

Importante: as APIs de exclusão só precisam ser chamadas quando não há conteúdo a ser publicado. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente. Entre em contato com engage-developers@ antes de usar APIs de exclusão.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

Quando o serviço recebe o pedido, ele remove os dados atuais dos clusters de recomendação. Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

Observação: essa API está disponível na versão 1.1.0 e mais recentes.

deleteFeaturedCluster

Essa API é usada para excluir o conteúdo do cluster de destaque.

Importante: as APIs de exclusão só precisam ser chamadas quando não há conteúdo a ser publicado. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente. Entre em contato com engage-developers@ antes de usar APIs de exclusão.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

Quando o serviço recebe o pedido, ele remove os dados atuais do cluster de destaque. Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

Observação: essa API está disponível na versão 1.1.0 e mais recentes.

deleteFoodShoppingCartCluster

Essa API é usada para excluir o conteúdo do cluster de carrinho de compras de alimentos.

Importante: as APIs de exclusão só precisam ser chamadas quando não há conteúdo a ser publicado. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente. Entre em contato com engage-developers@ antes de usar APIs de exclusão.

Kotlin

client.deleteFoodShoppingCartCluster()

Java

client.deleteFoodShoppingCartCluster();

Quando o serviço recebe a solicitação, ele remove os dados atuais do cluster de carrinho de compras de alimentos. Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

Observação: essa API está disponível na versão 1.1.0 e mais recentes.

deleteFoodShoppingListCluster

Essa API é usada para excluir o conteúdo do cluster de lista de compras de alimentos.

Importante: as APIs de exclusão só precisam ser chamadas quando não há conteúdo a ser publicado. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente. Entre em contato com engage-developers@ antes de usar APIs de exclusão.

Kotlin

client.deleteFoodShoppingListCluster()

Java

client.deleteFoodShoppingListCluster();

Quando o serviço recebe a solicitação, ele remove os dados atuais do cluster de lista de compras de alimentos. Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

Observação: essa API está disponível na versão 1.1.0 e mais recentes.

deleteReorderCluster

Essa API é usada para excluir o conteúdo do FoodReorderCluster.

Importante: as APIs de exclusão só precisam ser chamadas quando não há conteúdo a ser publicado. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente. Entre em contato com engage-developers@ antes de usar APIs de exclusão.

Kotlin

client.deleteReorderCluster()

Java

client.deleteReorderCluster();

Quando o serviço recebe o pedido, ele remove os dados atuais do cluster de "pedir de novo". Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

Observação: essa API está disponível na versão 1.1.0 e mais recentes.

deleteUserManagementCluster

Essa API é usada para excluir o conteúdo do cluster UserAccountManagement.

Importante: as APIs de exclusão só precisam ser chamadas quando não há conteúdo a ser publicado. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente. Entre em contato com engage-developers@ antes de usar APIs de exclusão.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

Quando o serviço recebe o pedido, ele remove os dados atuais do cluster UserAccountManagement. Em caso de erro, a solicitação inteira é rejeitada e o estado atual é mantido.

Observação: essa API está disponível na versão 1.1.0 e mais recentes.

deleteClusters

Essa API é usada para excluir o conteúdo de determinado tipo de cluster.

Importante: as APIs de exclusão só precisam ser chamadas quando não há conteúdo a ser publicado. Não chame APIs de exclusão e publicação em seguida para substituir o conteúdo. As APIs de publicação fazem isso de forma inerente. Entre em contato com engage-developers@ antes de usar APIs de exclusão.

Kotlin

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

Java

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

Quando o serviço recebe a solicitação, ele remove os dados de todos os clusters que correspondem aos tipos especificados. Os clientes podem transmitir um ou vários tipos de clusters. Em caso de erro, a solicitação inteira é rejeitada e o estado existente é mantido.

Tratamento de erros

É recomendável detectar o resultado da tarefa nas APIs de publicação. Com isso, uma ação de acompanhamento pode ser realizada para recuperar e reenviar uma tarefa bem-sucedida.

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

O erro é retornado como AppEngageException e a causa é incluída como um código de erro.

Código do erro	Observação
SERVICE_NOT_FOUND	O serviço não está disponível no dispositivo.
SERVICE_NOT_AVAILABLE	O serviço está disponível no dispositivo em questão, mas não no momento da chamada (por exemplo, está desativado).
SERVICE_CALL_EXECUTION_FAILURE	A execução da tarefa falhou devido a problemas de linha de execução. Nesse caso, ela pode ser repetida.
SERVICE_CALL_PERMISSION_DENIED	O autor da chamada não tem permissão para fazer a chamada de serviço.
SERVICE_CALL_INVALID_ARGUMENT	A solicitação contém dados inválidos (por exemplo, tem um número de clusters maior do que o permitido).
SERVICE_CALL_INTERNAL	Há um erro no serviço.
SERVICE_CALL_RESOURCE_EXHAUSTED	A chamada de serviço é feita com muita frequência.

Etapa 3: 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.

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.

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 shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART
// broadcast is received

// Trigger shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST
// broadcast is received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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 Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_LIST));

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));

}

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

<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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
   </receiver>
</application>

As intents a seguir serão enviadas pelo serviço:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Recomendamos que você inicie uma chamada publishRecommendationClusters ao receber essa intent.
• com.google.android.engage.action.PUBLISH_FEATURED Recomendamos que você inicie uma chamada publishFeaturedCluster ao receber essa intent.
• com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART Recomendamos que você inicie uma chamada publishFoodShoppingCart ao receber essa intent.
• com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST Recomendamos que você inicie uma chamada publishFoodShoppingList ao receber essa intent.
• com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER Recomendamos que você inicie uma chamada publishReorderCluster ao receber essa intent.

Fluxo de trabalho de integração

Para acessar um guia explicativo sobre como verificar a integração após a conclusão, consulte Fluxo de trabalho de integração de desenvolvedor.

Perguntas frequentes

Consulte as Perguntas frequentes sobre o SDK Engage para acessar as perguntas frequentes.

Contato

Entre em contato com [e-mail] se tiver perguntas durante o processo de integração. Nossa equipe vai responder assim que possível.

Próximas etapas

Depois de concluir essa integração, as próximas etapas serão as seguintes:

• Envie um e-mail para [e-mail] e anexe seu APK integrado pronto para ser testado pelo Google.
• O Google vai realizar uma verificação e revisão internamente para garantir que a integração funcione conforme o esperado. Se for necessário fazer mudanças, o Google entrará em contato informando todos os detalhes necessários.
• Quando o teste estiver concluído e nenhuma mudança for necessária, o Google entrará em contato para informar que você pode começar a publicar o APK atualizado e integrado na Play Store.
• Depois que o Google confirmar a publicação do APK atualizado na Play Store, seus clusters de recomendação, destaque, carrinho de compras, lista de compras e pedir de novo serão publicados e ficarão visíveis aos usuários.