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, nova solicitação 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.

Como testar links diretos

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>

Como calcular o impacto da integração?

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 recurso "Continuar assistindo 2.0"?

O recurso "Continuar assistindo 2.0" (API Video Discovery) leva a experiência de "retomar de onde parou" a outro nível. É uma atualização significativa que permite aos espectadores retomar o conteúdo em uma variedade maior de dispositivos. Imagine começar um filme no Google TV e continuar assistindo no smartphone durante o trajeto para o trabalho. Essa é a praticidade do recurso "Continuar assistindo 2.0".

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.

Quais são os benefícios de usar o recurso "Continuar assistindo 2.0"?

Resposta: Com o recurso "Continuar assistindo 2.0", os espectadores podem retomar o conteúdo de onde pararam com mais facilidade, 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 recurso "Continuar assistindo 2.0" ajuda a trazer os usuários de volta ao seu app, mesmo em dispositivos novos. 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 recurso "Continuar assistindo 2.0" funciona em outras experiências de mídia do Android, como os Cubos do Play e outros apps de mídia do Google.
• Compatibilidade com versões anteriores: se você já usa o recurso antigo Assistir a seguir, não há problema. O recurso "Continuar assistindo 2.0" é 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 a versão 2.0. O sistema mais antigo "Assistir em seguida entre dispositivos" está sendo desativado.

Quais plataformas têm suporte para o recurso "Continuar assistindo 2.0"?

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. Cubos de brincar
6. Entertainment Space do Google
7. Dispositivos iOS (com integração da API REST).

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

Sim, o SDK Engage é para o recurso "Continuar assistindo 2.0". É necessário fazer a integração com o recurso "Continuar assistindo 2.0".

O recurso "Continuar assistindo 2.0" está disponível para todos?

O recurso "Continuar Assistindo 2.0" 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 recurso "Continuar assistindo 2.0" para todos os desenvolvedores em breve.

Para um lançamento tranquilo e bem-sucedido, temos proteções para gerenciar o lançamento. Isso envolve uma lista de permissões no Continue Assistindo 2.0 e uma verificação separada no SDK Engage. Seja você um parceiro do EAP ou queira começar 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.

Existe um tamanho de imagem recomendado que devemos fornecer?

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 vantagens significativas para o recurso "Continuar assistindo", incluindo:

• Experiência integrada em todos os Google TVs:os usuários podem começar a assistir em um Google TV e continuar em qualquer outro dispositivo 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 recurso "Continuar assistindo" está disponível no app Google TV para dispositivos móveis 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 recurso "Continuar assistindo" pede que os usuários voltem a interagir com o app, aumentando a retenção.

• Expansão para outras plataformas:essa integração estende o recurso "Continuar assistindo" para outras plataformas de mídia do Google, como Android, Play Cubes, tablets e outros apps e plataformas de mídia do Google no Android, maximizando o engajamento do usuário em dispositivos.

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

Cada parceiro de desenvolvedor pode ter no máximo 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 EngageSDK 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 com sucesso. 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 vejam 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 seu 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 recurso "Continuar assistindo" 2.0 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 seu tempo e esforço 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 criado para detectar possíveis problemas com a integração do recurso "Continuar assistindo 2.0". 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: forneça 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 seu 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 recurso "Continuar assistindo 2.0"?

O AccountProfile foi criado para apps que usam contas de usuários individuais. No entanto, entendemos que alguns apps, como o seu, podem depender de logins anônimos. Confira como o recurso Continuar Assistindo 2.0 funciona nesse cenário:

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

Em resumo: embora seja possível integrar o recurso "Continuar assistindo 2.0" 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?

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 recurso "Continuar assistindo" 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 "Continuar assistindo", mas usar apenas "accountId" ao excluir, o sistema talvez não consiga identificar e remover os itens corretamente.

O profileId é obrigatório para o recurso "Continuar assistindo 2.0"?

• accountId é obrigatório. Isso identifica o usuário em todos os dispositivos.
• O profileId é crucial para uma boa experiência do usuário. Embora seja tecnicamente opcional, o profileId é altamente recomendado se o serviço oferecer suporte a vários perfis, como muitos serviços de streaming. Por que isso é tão importante? Sem o profileId, o recurso "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 o profileId garante que o recurso "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 de ContinueWatching na combinação accountId-profileId. Qualquer dispositivo do Google conectado com a mesma Conta do Google vai receber os dados atualizados mais recentes da mesma conta associada(accountId-profileId) na linha "Continuar assistindo".

É necessário vincular a conta para implementar o recurso "Continuar assistindo" 2.0?

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

Perguntas sobre a sincronização entre dispositivos

O que significa "sincronizar entre dispositivos" quando os usuários dão consentimento?

Com o consentimento do usuário para "sincronizar em todos os 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 falso?

A flag UserConsentToSyncAcrossDevices 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 recurso "Continuar assistindo" só vai funcionar 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".

Como o consentimento do usuário para compartilhar o histórico de exibição é obtido em dispositivos que não são Android

dispositivos? 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 previsão de lançamento da API REST é março de 2025. Isso está documentado em "Continue Assistindo 2.0" (em inglês), documentação para desenvolvedores.

Perguntas legadas sobre o recurso "Assistir a seguir"

A API Video Discovery vai substituir a API Assistir a seguir?

A API Video Discovery será compatível com versões anteriores em todos os dispositivos Android TV que oferecem suporte à API Assistir depois. Todos os desenvolvedores precisam usar a API Video Discovery (Continuar Assistindo 2.0) para publicar na linha "Continuar assistindo".

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, 605000 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: mostramos apenas cinco cards por app de terceiros no CW.
2. Ao selecionar o card que acabou de aparecer na linha "Continuar assistindo", o vídeo vai continuar sendo reproduzido do ponto certo. Observação: o conteúdo novo ou antigo vai retomar a reprodução de onde parou.
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: o CW para GoogleAccount2 vai mostrar conteúdos de terceiros que 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 em "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. "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 em "Continuar assistindo".
9. Confirme se nenhum item não assistido aparece 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 em 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 aparece na linha "Continuar 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, 3p account / profile: account 1 / profile_1. Assistir conteúdo e verificar se os dados do CW mostram o conteúdo assistido pela conta_1/perfil_1 de terceiros

17. TV2: GoogleAccount: mom. Verifique os dados de CW do primeiro cenário. Agora faça login no app de terceiros com outra conta. Conta / perfil de terceiros: account_2 / profile_2. Assistir conteúdo e verificar se os dados do CW mostram o conteúdo assistido pela conta_2/perfil_2 de terceiros

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 /app de terceiros foi instalada, mas não foi feita login. Em um novo dispositivo(faça uma redefinição de fábrica), o CW mostra os dados do último app de terceiros usado pela Conta do Google.
19. 1. Observação: a linha "Continuar assistindo" não vai mostrar conteúdo de terceiros se a GoogleAccount ainda não estiver associada a um perfil de terceiros.

Não consigo encontrar a opção "Continuar assistindo" no app Google TV para iOS. O que aconteceu?

Você precisa enviar links diretos do iOS para que a opção "Continuar assistindo" apareça em dispositivos iOS.

Com que frequência preciso atualizar as informações do recurso "Continuar assistindo"? Preciso atualizar as informações do recurso "Continuar assistindo" 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 causa uma tensã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 "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 passa para segundo plano.

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