Perguntas frequentes sobre o Engage SDK

Perguntas frequentes sobre publicação

Quem gerencia o job de publicação de conteúdo?

O desenvolvedor do app gerencia o job de publicação de conteúdo e envia solicitações para o serviço do Engage. Dessa forma, os parceiros têm mais controle sobre quando e como publicar conteúdo para os usuários. Isso evita ativar o app do parceiro com muita frequência para publicar conteúdo.

O desenvolvedor precisa publicar todos os tipos de cluster?

Tecnicamente, os desenvolvedores podem publicar apenas um cluster, mas recomendamos que incluam mais. Se não fizerem isso, eles perdem a oportunidade de gerar um engajamento maior com o conteúdo. É recomendável publicar todos os tipos de clusters em cada categoria.

Com que frequência o parceiro do desenvolvedor precisa publicar dados usando o gerenciador de trabalho enquanto o app está em execução?

Isso é decidido pelo parceiro do desenvolvedor. O Google recomenda publicar uma ou duas vezes por dia para conteúdo de recomendação geral e usar uma metodologia orientada a eventos para carrinho de compras, reordenar e outros conteúdos de continuidade (por exemplo, iniciar o worker como um callback do usuário adicionando itens ao carrinho ou parando um filme na metade). Para apps sociais, é fundamental publicar clusters de recomendação atualizados após cada uso do app. Os usuários de apps sociais têm mais interesse nas recomendações mais recentes e preferem ver uma postagem no máximo uma vez.

Quando o desenvolvedor precisa chamar APIs de exclusão?

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 removem o conteúdo anterior automaticamente.

Perguntas frequentes sobre intents de transmissão

Por que os desenvolvedores de apps Android precisam se registrar para intents de transmissão?

Para mostrar conteúdo novo ao usuário, use intents de transmissão para acionar uma sincronização de dados quando os usuários não usam o app com frequência.

Não foi possível testar a intent de transmissão

O app de verificação não é compatível com o teste de intents de transmissão com permissão. Você precisa remover as permissões durante o teste e adicioná-las novamente antes de mudar o SDK para a versão de produção na Etapa 6.

Execução em segundo plano não permitida

Ao registrar a intent de transmissão, você pode encontrar este erro:

Background execution not allowed: receiving Intent
{ act=com.google.android.engage.action.PUBLISH_RECOMMENDATION .. }

Você precisa registrar os broadcast receivers de maneira dinâmica.

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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,
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null));
...

}

Perguntas frequentes sobre fluxo de trabalho

Durante a integração com o SDK, você pode encontrar estes erros:

Erros de validação no nível do app, cluster e entidade

Os resumos nos níveis de app, cluster e entidade mostram uma contagem de erros de validação. Esses erros correspondem a campos obrigatórios ausentes ou valores inválidos fornecidos. As mensagens de erro aparecem em vermelho abaixo de cada campo relevante. Corrija todos os erros de validação e verifique se está tudo certo antes de compartilhar o APK.

Os links diretos estão associados ao nome do pacote. Uma boa maneira de testar links diretos é usando a ferramenta adb.

adb shell am start -W -a android.intent.action.VIEW -d <DEEPLINK URI> <PACKAGE NAME>

Os links diretos são uma ótima maneira de acompanhar a atribuição. Os URLs de links diretos que direcionam o usuário ao seu app podem ser incluídos com outros parâmetros de acompanhamento. Por exemplo: "http://xx/deeplink?source_tag=engage".

Os desenvolvedores podem adicionar os próprios parâmetros de acompanhamento e usar a atribuição para calcular o impacto.

Perguntas frequentes sobre o Engage para TV 2.0

Dúvidas gerais

O que é o Engage?

O recurso "Retomar de onde parou" do Engage é um upgrade significativo que permite aos espectadores retomar o conteúdo em uma variedade maior de dispositivos. Imagine começar um filme no Google TV e continuar sem problemas no smartphone durante o trajeto. Essa é a força do Engage.

Esse novo sistema foi projetado para aumentar o engajamento e a retenção dos espectadores, oferecendo uma experiência tranquila e sem atrito em todo o ecossistema do Google.

A API Video Discovery é a mesma coisa que o Engage?

Sim, são iguais. O SDK Engage é uma biblioteca que inclui suporte para a linha "Continuar assistindo". O Engage é compatível com mais tipos de entidades de conteúdo do que vídeo, por isso a integração não é mais chamada de "Descoberta de vídeo".

Quais são os benefícios de usar o Engage?

Resposta: Com o recurso Engajamento, os espectadores podem retomar o conteúdo de onde pararam com mais facilidade do que nunca, em qualquer dispositivo. Veja como funciona:

  • Experiência integrada no Google: comece a assistir no Google TV e continue sem problemas no smartphone Android, iPhone ou tablet Android. Ele funciona até mesmo em dispositivos em que você ainda não instalou o app.
  • Aumento do engajamento e da retenção: o Engage ajuda a trazer os usuários de volta ao seu app, mesmo em novos dispositivos. Ao permitir que os usuários retomem os programas favoritos, você aumenta as chances de eles continuarem assistindo.
  • Maior alcance: além do Google TV, o Engage funciona em outras experiências de mídia do Android, como as Galerias do Google Play e outros apps de mídia do Google.
  • Compatível com versões anteriores: se você já usa o recurso mais antigo Assistir a seguir, não há problema. O Engage é compatível com versões anteriores, então sua integração atual ainda vai funcionar.

Observação importante: todas as novas integrações do recurso "Continuar assistindo" precisam usar o Engage. O sistema mais antigo "Assistir em seguida entre dispositivos" está sendo desativado.

Quais plataformas são compatíveis com o Engage?

  1. Google TV
  2. Android TV (somente no dispositivo, mas compatível com o SDK Engage)
  3. App Google TV para dispositivos móveis Android
  4. App Google TV para dispositivos móveis iOS
  5. Coleções do Google Play
  6. Entertainment Space do Google
  7. Dispositivos iOS (com integração da API REST).

O SDK Engage é para o recurso "Continuar assistindo"?

Sim, o SDK Engage oferece suporte a conteúdo para a linha "Continuar assistindo". É necessário fazer a integração com o Engage.

O Engage está disponível para todos?

O Engage está sendo lançado em fases.

  • Acesso antecipado: inicialmente, vamos conceder acesso a um grupo seleto de parceiros por meio de um programa de acesso antecipado (PAA).
  • Ampliação do acesso: estamos trabalhando para disponibilizar o Engage a todos os desenvolvedores em breve.

Para um lançamento tranquilo e bem-sucedido, temos salvaguardas para gerenciar o lançamento. Isso envolve uma lista de permissões no lado do Engage e uma verificação separada no SDK Engage. Seja um parceiro do PAA ou queira fazer a integração em breve, entre em contato para que possamos configurar as permissões de acesso antes de você começar a integração do SDK Engage.

Os requisitos de imagem foram atualizados na seção Criar entidades.

Com essa nova documentação da API, os dados de "Continuar assistindo" extraídos do cliente pelo servidor do Google serão refletidos em todos os dispositivos?

A nova API oferece melhorias significativas para o conteúdo na linha "Continuar assistindo", incluindo:

  • Experiência integrada em todos os dispositivos Google TV:os usuários podem começar a assistir em um Google TV e continuar em qualquer outro Google TV conectado com a mesma conta. Esse recurso também funciona com versões mais antigas do Android TV.

  • Integração com apps para dispositivos móveis:o conteúdo do Engage aparece no app Google TV para Android e iOS, permitindo que os usuários alternem entre a TV e os dispositivos móveis.

  • Retenção de usuários aprimorada:mesmo em dispositivos sem o app instalado ou em que o usuário não fez login, o conteúdo da linha "Continuar assistindo" incentiva os usuários a se engajarem novamente com o app, aumentando a retenção.

  • Expansão para outras plataformas:o Engage se estende a outras plataformas de mídia do Google, como Android, Coleções do Google Play, tablets e outros apps e plataformas de mídia do Google no Android, maximizando o engajamento do usuário em todos os dispositivos.

Qual é o limite de entidades que posso publicar no cluster de continuação?

Cada parceiro de desenvolvimento está limitado a um máximo de cinco entidades no cluster de continuação. Esse limite é para uma distribuição justa de conteúdo na linha "Continuar assistindo" do Google TV, que é um espaço compartilhado para vários provedores de mídia.

O que acontece se eu tentar publicar mais de cinco entidades?

O SDK Engage vai rejeitar sua solicitação de publicação se ela exceder o limite de cinco entidades. É preciso reduzir o número de entidades na solicitação para publicar. Inclua apenas as entidades em que os usuários pararam de assistir. Na maioria dos casos, haverá apenas algumas entidades desse tipo. Quando há mais de cinco entidades desse tipo, você pode escolher as mais recentes para publicar.

Por que há um limite no número de entidades?

A linha "Continuar assistindo" no Google TV mostra conteúdo de vários provedores de mídia. Limitar o número de entidades por provedor para que os usuários tenham uma seleção diversificada de conteúdo de todas as fontes favoritas, promovendo uma experiência justa e equilibrada.

Perguntas sobre o app de verificação

É obrigatório testar meu app com o app de verificação antes do envio?

Sim, é essencial testar o app com o app de verificação antes de enviar o APK.

Entendemos que você pode ter confiança na sua implementação, mas a integração do Engage tem muitos componentes complexos. O app de verificação funciona como uma rede de segurança, detectando possíveis problemas no início e economizando tempo e esforço valiosos a longo prazo.

É como um check-up rápido que ajuda a garantir um lançamento tranquilo e uma ótima experiência do usuário.

Ao identificar e resolver problemas com antecedência, você evita a frustração de rejeições e reenvios.

Para enviar o APK, inclua uma captura de tela mostrando que o app passou pelo processo de verificação.

Quais são alguns erros comuns a serem evitados durante a integração?

O app de verificação foi projetado para detectar possíveis problemas com a integração do Engage e do Google Analytics. Confira alguns erros comuns que os desenvolvedores costumam encontrar:

Para todos os tipos de conteúdo (filmes, episódios de TV, transmissões ao vivo, videoclipes):

  • Links ausentes: verifique se você forneceu URIs (links) válidos específicos da plataforma para seu conteúdo. Esses links informam ao sistema onde encontrar seu conteúdo em cada plataforma.
  • Títulos ausentes: não se esqueça de incluir títulos em todo o conteúdo. Isso ajuda os usuários a identificar o que estavam assistindo.
  • Proporções de imagem: verifique se todas as imagens associadas ao seu conteúdo têm uma proporção próxima a 16:9. Isso garante que as imagens sejam exibidas corretamente em diferentes telas.

Para episódios de TV:

  • Informações completas do episódio: inclua o título do programa, o número do episódio e o número da temporada. Isso ajuda a organizar os episódios e permite que os usuários naveguem em uma série.
  • Posição de reprodução precisa: verifique se a última posição de reprodução é menor ou igual à duração total do episódio. Isso garante que os usuários retomem do ponto certo.

Para filmes:

  • Posição de reprodução precisa: assim como nos episódios de TV, verifique se a última posição de reprodução está correta.

Para vídeos com transmissão ao vivo:

  • Informações do streamer: inclua o nome do streamer nas transmissões ao vivo.

Para videoclipes:

  • Informações do criador de conteúdo: especifique o criador do clipe.

Lembre-se: o app de verificação vai sinalizar esses problemas para que você possa corrigi-los antes de enviar o app. Isso economiza tempo e garante uma experiência mais tranquila para os usuários.

Perguntas sobre conta e perfil

Meu app usa logins de usuários anônimos. O AccountProfile ainda é necessário para o Engage?

O AccountProfile foi projetado para apps que usam contas de usuários individuais. No entanto, entendemos que alguns apps, como o seu, podem depender de logins anônimos. Veja como o Engage funciona nesse cenário:

  • O AccountProfile é tecnicamente obrigatório, mas você ainda pode integrar o Engage mesmo que seu app não tenha um sistema de contas de usuário.
  • Limitado ao uso no dispositivo: os recursos entre dispositivos do Engage dependem da identificação de usuários em diferentes dispositivos. Como os logins anônimos não fornecem isso, o recurso será limitado ao dispositivo atual do usuário.
  • Como configurar: para fazer isso, desative a sincronização entre dispositivos. Isso garante que as entradas de continuação apareçam apenas no dispositivo específico em que o conteúdo foi iniciado.

Em resumo: embora seja possível integrar o Engage com logins anônimos, os usuários só poderão retomar o conteúdo no mesmo dispositivo.

Posso usar AccountProfile apenas com accountId e sem profileId, mesmo quando meu app oferece suporte a accountId e profileId?

O AccountProfile exige accountId e profileId para funcionar corretamente. Confira os motivos:

  • Identificação consistente: accountId identifica o usuário, enquanto profileId distingue entre diferentes perfis na conta do usuário (se aplicável). Ao fornecer os dois, você garante que o Engage rastreie e mostre o conteúdo de cada perfil individual com precisão.
  • Prevenção de erros: usar accountId e profileId de forma inconsistente em diferentes chamadas de API pode causar erros e comportamentos inesperados. Por exemplo, se você incluir os dois ao adicionar conteúdo ao Engage, mas usar apenas accountId ao excluir, o sistema talvez não consiga identificar e remover corretamente os itens desejados.

O profileId é necessário para o Engage?

  • O campo accountId é obrigatório. Isso identifica o usuário em todos os dispositivos.
  • profileId é fundamental para uma boa experiência do usuário. Embora seja tecnicamente opcional, profileId é altamente recomendável se o serviço for compatível com vários perfis, como muitos serviços de streaming. Por que isso é tão importante? Porque, sem profileId, a linha "Continuar assistindo" pode mostrar conteúdo de outros perfis na mesma conta. Isso pode levar a uma experiência confusa e frustrante para os usuários.
  • Em resumo: fornecer profileId garante que o conteúdo apresentado na linha "Continuar assistindo" reflita com precisão o histórico de exibição de cada pessoa. A menos que seu app não seja compatível com o conceito de perfil em uma conta, você precisa fornecer esse recurso.

Como o Google usa o profileId?

Se o serviço oferecer diferentes perfis para assistir conteúdo, accountId e profileId serão usados para associar o conteúdo assistido no dispositivo à Conta do Google conectada nele. O Google registraria os dados do ContinueWatching na combinação de accountId e profileId. Qualquer dispositivo do Google conectado à mesma Conta do Google vai receber os dados atualizados mais recentes do mesmo accountId e profileId associados na linha "Continuar assistindo".

É preciso vincular uma conta para implementar o Engage?

Não é necessário vincular uma conta. Ela está sendo despriorizada, e todos os casos de uso relacionados serão cobertos pela nova API Entitlements.

Perguntas sobre a sincronização entre dispositivos

Com o consentimento do usuário para "sincronizar em vários dispositivos", o conteúdo que ele está assistindo será salvo nos servidores do Google TV, permitindo que ele continue de onde parou em qualquer dispositivo conectado. Sem consentimento, o histórico de exibição permanece local no dispositivo atual.

Podemos definir "sincronizar entre dispositivos" como "false"?

A flag setUserConsentToSyncAcrossDevices controla se os dados de ContinuationCluster de um usuário são sincronizados entre os dispositivos dele (TV, smartphone, tablet etc.). Se essa flag estiver definida como "false", o conteúdo de "Continuar assistindo" só vai aparecer no mesmo dispositivo.

Para aproveitar ao máximo nosso recurso entre dispositivos, recomendamos que seu app obtenha o consentimento do usuário e defina SyncAcrossDevices como "true".

de dispositivos móveis? Quais pontos de dados são compartilhados com servidores de terceiros em dispositivos que não são Android?

O consentimento é coletado no nível do usuário (perfil ou conta). Depois que o consentimento é obtido, os payloads de "Continuar assistindo" com base no engajamento podem ser enviados para qualquer lugar. Assim, o Google pode refletir o estado de retomada da ubiquidade dos usuários em todas as entidades com que eles têm engajamento parcial ou futuro, em qualquer dispositivo, sem precisar pedir consentimento novamente em cada dispositivo ou plataforma. Os parceiros vão enviar o estado mais recente de "Continuar assistindo" (conforme a especificação) associado ao ID do perfil (que foi depositado no Android).

Perguntas sobre a API REST

Há documentação sobre a API REST?

A data prevista para a API REST é março de 2025, conforme documentado na documentação para desenvolvedores do Engage.

Perguntas legadas sobre o recurso "Assistir a seguir"

O Engage vai substituir a API Assistir a seguir?

O Engage será compatível com versões anteriores em todos os dispositivos Android TV que oferecem suporte à API Assistir depois. Para integrar no Google TV e em outras plataformas que oferecem suporte ao Engage, os desenvolvedores precisam usar o SDK Engage.

Perguntas sobre testes e integração

Qual é a diferença entre LastPlayBackPositionTimeMillis e duração?

LastPlayBackPositionTimeMillis precisa refletir a duração da reprodução em milissegundos em que o usuário parou de assistir (por exemplo, 605.000 ms para 10 minutos e 5 segundos). Ela nunca pode ser maior que a duração total da entidade.

Já LastEngagementTime é o carimbo de data/hora em que o usuário interagiu com o conteúdo pela última vez.

Quais casos de teste devemos realizar?

Confira abaixo os casos de teste para o Google TV que nosso controle de qualidade realiza. Testes semelhantes podem ser realizados em outras plataformas também.

  1. Assista um vídeo com mais de 20 minutos por cerca de 5 minutos. Saia do app. O card de vídeo vai aparecer na linha "Continuar assistindo". Observação: Só mostramos cinco cards por app de terceiros no CW.
  2. Ao selecionar o card que acabou de aparecer na linha "Continuar assistindo", o vídeo deve continuar sendo reproduzido do ponto certo. Observação: qualquer conteúdo novo ou antigo deve retomar a reprodução de onde foi interrompido.
  3. Mudar de conta no dispositivo GTV também muda os cards na linha "Continuar assistindo". Apenas os vídeos da conta atual devem aparecer. Classificada por ordem de data. O perfil do app de terceiros CW será misturado. Observação: a CW para GoogleAccount2 vai mostrar conteúdos de terceiros que a GoogleAccount2 assistiu
  4. Saia do app com o botão VOLTAR > Verifique se o card aparece na linha "Continuar assistindo".
  5. Oculte o vídeo na linha "Continuar assistindo". Ele não deve aparecer novamente. Teste se o conteúdo oculto permanece oculto por mais de 24 horas e mesmo depois que o app é aberto após 24 horas. Confirme se ocultar um item não oculta vários itens.
  6. Disponibilidade de conteúdo na linha "Continuar assistindo" com metadados completos: imagem do card, nome do app, título, número do episódio e da temporada para conteúdo de TV
  7. A opção "Verificar progresso" aparece na barra de progresso.
  8. O usuário assistiu o conteúdo até os créditos finais. O conteúdo não aparece na linha "Continuar assistindo".
  9. Confirme se não há itens não assistidos na linha "Continuar assistindo".
  10. Confirme se os itens do CW estão organizados em ordem cronológica com base em quando a atividade de assistir aconteceu e não quando o app foi aberto pela última vez ou no último dia
  11. Confirme se os detalhes do episódio e da temporada no card do CW correspondem ao que foi assistido no conteúdo episódico.
  12. Confirme se os itens concluídos (com créditos ou mais) não aparecem na linha "Continuar assistindo"
  13. Desligue o dispositivo na metade do episódio/filme/programa. "Desligue o dispositivo na metade do episódio/filme/programa. Verifique se, ao ligar o dispositivo e em outra TV, o CW mostra o card certo, na posição e barra de progresso corretas"
  14. Desligue o dispositivo depois de assistir o episódio 1 completo e verifique
  15. O episódio 1 é lançado e não reaparece na linha "Continue assistindo" [no segundo dispositivo e ao ligar o dispositivo de teste]
    1. O episódio 2 (se disponível) vai aparecer na linha "Continuar assistindo" [no segundo dispositivo e ao ligar o dispositivo de teste]
  16. Primeiro cenário: TV1: GoogleAccount: mom, conta / perfil de terceiros: conta 1 / profile_1. Assista ao conteúdo e verifique se os dados do CW mostram o conteúdo assistido por 3P account_1/profile_1

  17. TV2: GoogleAccount: mom. Verifique os dados do CW no primeiro cenário. Agora faça login no app de terceiros com outra conta. Conta / perfil de terceiros: account_2 / profile_2. Assista conteúdo e verifique se os dados do CW mostram o conteúdo assistido por 3p account_2/profile_2

  18. GoogleAccount: mom. Nova capa de dispositivo /app de terceiros não instalado. Em um novo dispositivo(faça uma redefinição de fábrica), verifique se o CW mostra dados do último app de terceiros usado pela Conta do Google. Observação: a linha do CW não deve mostrar conteúdo de terceiros se o GAIA ainda não estiver associado a um perfil de terceiros em outro dispositivo.

    1. GoogleAccount: mom. Uma nova capa de dispositivo /um app de terceiros foi instalado, mas não conectado. Em um novo dispositivo(faça uma redefinição de fábrica), verifique se o CW mostra dados do último app de terceiros usado pela Conta do Google.
    1. Observação: a linha "Continuar assistindo" não deve mostrar conteúdo de terceiros se a GoogleAccount ainda não estiver associada a um perfil de terceiros.

Não consigo encontrar o conteúdo de continuação no app Google TV para iOS. O que aconteceu?

Você precisa enviar links diretos do iOS para que o conteúdo apareça na linha "Continuar assistindo" em dispositivos iOS.

Com que frequência devo atualizar as informações de conteúdo da linha "Continuar assistindo"? Preciso atualizar com frequência, como a cada 15 segundos?

Não, atualizações frequentes não são recomendadas. Confira os motivos:

  • Impacto na performance: o envio contínuo de atualizações coloca uma pressão desnecessária nos servidores, o que pode diminuir a velocidade do sistema para todos.
  • Dados desnecessários: enquanto um usuário assiste ativamente, a posição de reprodução muda constantemente. O envio de atualizações a cada poucos segundos cria muitos dados redundantes que não são úteis para retomar a reprodução.

Quando atualizar as informações de conteúdo da linha "Continuar assistindo":

Foque em capturar mudanças significativas no progresso de visualização do usuário. Confira os principais cenários:

  • Reprodução pausada ou interrompida: quando um usuário pausa ou para de assistir, envie uma atualização para armazenar a posição atual.
  • App fechado ou em segundo plano: se um usuário sair do app ou mudar para outro app enquanto assiste um vídeo, envie uma atualização para salvar o progresso.
  • Quando o usuário remove um item da linha "Continuar assistindo" no app

Como atualizar com eficiência:

Em vez de atualizações programadas, use eventos no player de vídeo ou no ciclo de vida do app para acionar atualizações. Exemplo:

  • onPause, onStop: quando a reprodução de vídeo é pausada ou interrompida.
  • onAppClose, onAppBackgrounded: quando o app é fechado ou movido para o segundo plano.

Ao seguir estas diretrizes, você garante o uso eficiente dos recursos e ainda oferece uma experiência integrada na linha "Continuar assistindo" para seus usuários.