Perguntas frequentes sobre o Engage SDK

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 conteúdo de recomendação geral e usar uma metodologia orientada a eventos para carrinho de compras, reordenação e outros conteúdos de continuação (por exemplo, iniciar o worker como um callback do usuário adicionando itens ao carrinho ou parando um filme no meio). Para apps de redes 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, de preferência, gostariam de 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.

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

}

Perguntas frequentes sobre fluxo de trabalho

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

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

A API Video Discovery permite que você continue assistindo o conteúdo de onde parou. É uma atualização significativa que permite que os espectadores retomem 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 força 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 atritos em todo o ecossistema do Google.

Quais são os benefícios de usar a seção "Continuar assistindo" 2.0?

Resposta: Com o recurso "Continuar assistindo" 2.0, os espectadores podem retomar o conteúdo de onde pararam, seja qual for o dispositivo que estão usando. Confira como funciona:

• Experiência perfeita no Google: comece a assistir no Google TV e continue sem problemas no smartphone, iPhone ou tablet Android. Ele funciona até mesmo em dispositivos em que você ainda não instalou o app.
• Maior engajamento e retenção: o recurso Continue assistindo 2.0 ajuda a trazer os usuários de volta ao app, mesmo em novos dispositivos. Ao permitir que os usuários retomem os programas favoritos, você aumenta as chances de eles continuarem assistindo.
• Alcance maior: além do Google TV, o recurso "Continuar assistindo 2.0" funciona em outras experiências de mídia do Android, como Play Cubes e outros apps de mídia do Google.
• Compatível com versões anteriores: se você já estiver usando o recurso Assistir a seguir mais antigo, não tem problema. A integração anterior vai continuar funcionando, porque a Continue Watching 2.0 é compatível com versões anteriores.

Observação importante: todas as novas integrações do Continue Watching precisam usar o Continue Watching 2.0. O sistema "Assistir a seguir entre dispositivos" mais antigo está sendo desativado.

Quais plataformas oferecem suporte ao Continue Watching 2.0?

1. Google TV
2. Android TV (somente no dispositivo, mas com suporte ao SDK Engage)
3. App Google TV para dispositivos móveis Android
4. App Google TV para dispositivos móveis iOS
5. Play Cubes
6. Google Entertainment Space
7. Dispositivos iOS (com integração da API REST).

O SDK Engage é para o Continue Watching 2.0?

Sim, o SDK Engage é para a seção "Continuar assistindo" 2.0. É necessário integrar o Continue Watching 2.0.

O Continue assistindo 2.0 está disponível para todos?

O Continue assistindo 2.0 está sendo lançado em fases.

• Acesso antecipado: inicialmente, estamos concedendo acesso a um grupo selecionado de parceiros por meio de um programa de acesso antecipado (PAA).
• Acesso expandido: estamos trabalhando para disponibilizar o Continue Watching 2.0 para todos os desenvolvedores em breve.

Para garantir um lançamento tranquilo e bem-sucedido, temos proteções para gerenciar o lançamento. Isso envolve uma lista de permissões no Continue Watching 2.0 e uma verificação separada no SDK Engage. Se você é um parceiro do EAP ou quer começar em breve, entre em contato para que possamos configurar as permissões de acesso antes de começar a integração com o SDK Engage.

Existe um tamanho de imagem recomendado?

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

Com essa nova documentação da API, os dados do Continue Watching serão extraídos pelo servidor do Google do cliente e refletidos em todos os dispositivos?

A nova API oferece vantagens significativas para a opção "Continuar assistindo", incluindo:

• Experiência otimizada em todos os Google TVs:os usuários podem começar a assistir em um Google TV e retomar 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 recurso "Continuar assistindo" está disponível no app para dispositivos móveis Google TV para Android e iOS, permitindo que os usuários alternem facilmente 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, a opção "Continuar assistindo" incentiva os usuários a interagir com o app, aumentando a retenção.

• Expansão para outras plataformas:essa integração estende o recurso "Continuar assistindo" a 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 é limitado a um máximo de cinco entidades no cluster de continuação. Esse limite garante a distribuição justa de conteúdo na linha "continuar assistindo" no 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. Reduza o número de entidades na sua solicitação para publicar com sucesso. Inclua apenas as entidades que os usuários deixaram de assistir. Na maioria dos casos, haverá apenas algumas dessas entidades. 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 garante que os usuários tenham acesso a uma seleção diversificada de conteúdo de todas as fontes favoritas, promovendo uma experiência justa e equilibrada.

Perguntas do app de verificação

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

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

Sabemos que você pode ter confiança na sua implementação, mas a integração Continue Watching 2.0 tem muitos componentes complexos. O app de verificação atua como uma rede de segurança, detectando possíveis problemas antecipadamente e economizando tempo e esforço no longo prazo.

Pense nisso como um exame 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 frustrações com rejeições e reenvios.

Para enviar o APK, é necessário incluir uma captura de tela mostrando que o app passou no processo de verificação.

#### Quais são alguns erros comuns que precisam ser evitados durante a integração?

O app de verificação foi projetado para detectar possíveis problemas com a integração Continue Watching 2.0. Confira alguns erros comuns que os desenvolvedores encontram:

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 para todo o conteúdo. Isso ajuda os usuários a identificar o que estavam assistindo.
• Proporções da 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 telas diferentes.

Para episódios de TV:

• Informações completas do episódio: inclua o título do programa, o número do episódio e da temporada. Isso ajuda a organizar os episódios e permite que os usuários naveguem dentro de 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 continuem no local correto.

Para filmes:

• Posição de reprodução precisa: semelhante aos 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 transmissor: inclua o nome do transmissor nas transmissões ao vivo.

Para videoclipes:

• Informações do criador: especifique o criador do videoclipe.

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

Perguntas sobre a conta e o perfil

Meu app usa logins de usuários anônimos. O AccountProfile ainda é necessário para a função "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 a Continuar assistindo 2.0 funciona neste cenário:

• O AccountProfile é tecnicamente obrigatório, mas você ainda pode integrar o Continue Watching 2.0 mesmo que seu app não tenha um sistema de conta 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 oferecem 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 "Continuar assistindo" apareçam apenas no dispositivo específico em que o conteúdo foi iniciado.

Resumo: embora seja possível integrar o Continue Watching 2.0 a logins anônimos, os usuários só poderão retomar o conteúdo no mesmo dispositivo.

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

O AccountProfile exige que o accountId e o profileId funcionem corretamente. Confira os motivos:

• Identificação consistente: o accountId identifica o usuário, enquanto o profileId distingue entre diferentes perfis na conta desse usuário (se aplicável). Ao fornecer os dois, você garante que o recurso "Continuar assistindo" rastreie e exiba conteúdo com precisão para cada perfil.
• Prevenção de erros: o uso inconsistente de accountId e profileId em diferentes chamadas de API pode levar a erros e comportamentos inesperados. Por exemplo, se você incluir os dois ao adicionar conteúdo à seção "Continuar assistindo", mas usar apenas accountId ao excluir conteúdo, o sistema talvez não consiga identificar e remover os itens corretos.

O profileId é obrigatório para a seção "Continuar assistindo" 2.0?

• O accountId é obrigatório. Isso identifica o usuário em vários 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? Porque, sem profileId, o Continue assistindo pode mostrar conteúdo de outros perfis na mesma conta. Isso pode causar uma experiência confusa e frustrante para os usuários.
• Resumindo: fornecer profileId garante que a seção "Continuar assistindo" reflita com precisão o histórico de exibição de cada pessoa. Forneça o perfil, a menos que seu app não ofereça suporte ao conceito de perfil em uma conta.

Como o Google usa o profileId?

Se o serviço oferecer perfis diferentes para assistir conteúdo, os valores "accountId" e "profileId" serão usados para associar o conteúdo assistido no dispositivo à Conta do Google conectada. O Google gravaria os dados de ContinueWatching com base na combinação de accountId-profileId. Qualquer dispositivo do Google que tenha essa mesma Conta do Google conectada vai receber os dados atualizados mais recentes das mesmas IDs de conta e perfis associados na linha "Continue assistindo".

A vinculação de contas é necessária para implementar a seção "Continuar assistindo" 2.0?

Não é necessário vincular a 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 de "sincronização entre dispositivos" do usuário, 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.

Posso definir a opção "Sincronizar entre dispositivos" como falsa?

A flag "UserConsentToSyncAcrossDevices" controla se os dados de ContinuationCluster de um usuário são sincronizados entre os dispositivos (TV, smartphone, tablet etc.).Se essa flag estiver definida como "false", a opção "Continuar assistindo" só vai acontecer no mesmo dispositivo.

Para aproveitar ao máximo nosso recurso entre dispositivos, recomendamos que seu app peça o consentimento do usuário e defina SyncAcrossDevices como verdadeiro.

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

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

O consentimento é coletado no nível do usuário (perfil ou conta). Depois de receber o consentimento, os payloads de continuação de exibição 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 as quais eles têm engajamento parcial ou próximo, em qualquer dispositivo, sem precisar pedir o consentimento novamente em cada dispositivo ou plataforma. Os parceiros vão enviar o estado de continuação de exibição mais recente dos usuários (conforme especificação) associado ao ID do perfil (que foi depositado no Android).

Perguntas sobre a API REST

Há documentação sobre a API REST?

O prazo para a API REST é março de 2025, conforme documentado nas documentação para desenvolvedores da Continue Watching 2.0.

Perguntas legadas do canal "Assistir a seguir"

A API Video Discovery vai substituir a API Watch Next?

A API Video Discovery será compatível com versões anteriores em todos os dispositivos Android TV que oferecem suporte à API Watch Next. Todos os desenvolvedores precisam usar a API Video Discovery (Continue Watching 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 da última interação do usuário com o conteúdo.

Quais são os casos de teste que precisamos realizar?

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

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. Selecionar o card que apareceu na linha "Continue Watching" vai continuar a reprodução do vídeo no ponto certo. Observação: qualquer conteúdo novo ou antigo vai retomar a reprodução de onde parou da última vez.
3. Mudar as contas no dispositivo GTV deve mudar os cards na linha "Continuar assistindo". Somente os vídeos da conta atual vão aparecer. Classificados em ordem recente. O CW do perfil de app de terceiros será misturado. Observação: a CW para GoogleAccount2 vai mostrar conteúdos de terceiros que GoogleAccount2 assistiu
4. Saia do app com o botão "VOLTAR" > Verifique se o cartão aparece na linha "Continue assistindo".
5. Ocultar o vídeo na linha "Continue Watching". Ele não vai aparecer novamente. Teste se o conteúdo oculto permanecer oculto por mais de 24 horas e mesmo depois que o app abrir após 24 horas. Confirme que ocultar um item não oculta vários itens.
   1. Disponibilidade de conteúdo na seção "Continuar assistindo" com metadados completos: imagem do card, nome do app, título, número do episódio da temporada para conteúdo de TV
6. A opção "Verificar progresso" aparece na barra de progresso
7. O usuário assistiu o conteúdo até os créditos finais. O conteúdo não aparece em Continuar assistindo
8. Confirmar que nenhum item não assistido aparece na linha "Continuar assistindo"
9. Confirme se os itens da CW são organizados cronologicamente com base no momento em que a atividade de exibição ocorreu, e não quando o app foi aberto pela última vez ou no último dia
10. Confirmar que os detalhes do episódio e da temporada no card da CW correspondem ao que foi assistido no conteúdo episódico
11. Confirmar que os itens concluídos (itens com créditos ou mais) não aparecem em continuar assistindo
12. Desligue o dispositivo no meio do episódio/filme/programa. "Desligue o dispositivo no meio do episódio/filme/programa. Verifique se, ao ligar o dispositivo e em outra TV, o CW exibe o card correto, na posição e na barra de progresso corretas.
13. Desligue o dispositivo depois de assistir o episódio 1 por completo e verifique
    1. O episódio 1 é removido e não aparece novamente na linha "Continuar assistindo" [no segundo dispositivo e ao ativar o dispositivo de teste]
    2. O episódio 2 (se disponível) precisa aparecer na linha "Continue assistindo" [no segundo dispositivo e ao ativar o dispositivo de teste]

14. Primeiro cenário: TV1: Conta do Google: mãe, conta de terceiros / perfil: conta 1 / profile_1. Assista conteúdo e verifique se os dados de CW mostram o conteúdo assistido pela conta de terceiros account_1/profile_1

    1. TV2: GoogleAccount: mãe. Verifique os dados de CW do primeiro cenário. Agora faça login no app de terceiros como uma conta diferente. Conta / perfil de terceiros: account_2 / profile_2. Assistir conteúdo e verificar que os dados de CW mostram conteúdo assistido por 3p account_2/profile_2

15. GoogleAccount: mãe. Novo estojo para dispositivo /app de terceiros não instalado. Em um novo dispositivo(FDR), o Verify CW mostra dados do último app de terceiros usado pela GoogleAccount. Observação: a linha de CW não mostra conteúdos de terceiros se o GAIA ainda não estiver associado a um perfil de terceiros em outro dispositivo.

    1. GoogleAccount: mãe. Caso de dispositivo novo /app de terceiros instalado, mas sem login. Em um novo dispositivo(FDR do dispositivo), o Verify CW mostra dados do último app de terceiros usado pela Conta do Google.
    2. Observação: quando o app é instalado e conectado, o estado de CW reflete o usuário ativo de terceiros conectado ao app de terceiros.
    3. Observação: a linha "Continuar assistindo" não mostra conteúdo de terceiros se a Conta do Google ainda não estiver associada a um perfil de terceiros.

O recurso "Continuar assistindo" não aparece no app iOS do Google TV. O que aconteceu?

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

Com que frequência preciso atualizar as informações de "Continuar assistindo"? Devo atualizar as informações de "Continuar assistindo" com frequência, como a cada 15 segundos?

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

• Impacto no desempenho: o envio contínuo de atualizações sobrecarrega nossos servidores, o que pode desacelerar o 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":

Concentre-se 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 dele.
• App fechado ou em segundo plano: se um usuário sair do app ou mudar para outro 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 de forma eficiente:

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 do vídeo é pausada ou interrompida.
• onAppClose, onAppBackgrounded: quando o app é fechado ou passa para o segundo plano.

Ao seguir essas diretrizes, você garante o uso eficiente de recursos e oferece uma experiência perfeita de Continuar assistindo aos usuários.