Preguntas frecuentes sobre el SDK de Engage

Preguntas frecuentes sobre la publicación

¿Quién administra el trabajo de publicación de contenido?

El desarrollador de apps administra el trabajo de publicación de contenido y envía solicitudes al servicio de Engage. De esta manera, los socios desarrolladores tienen un mayor control sobre cuándo y cómo publicar contenido para los usuarios. Esto evita activar la app del socio con demasiada frecuencia para publicar contenido.

¿Debe un desarrollador publicar todos los tipos de clústeres?

Si bien técnicamente los desarrolladores tienen la libertad de publicar un solo clúster, recomendamos que incluyan más. De lo contrario, los desarrolladores se perderán la oportunidad de generar una mejor interacción con su contenido. Te recomendamos que publiques todos los tipos de clústeres de cada vertical.

¿Con qué frecuencia el socio desarrollador debe publicar datos con el administrador de trabajo mientras se ejecuta la app?

Esto lo decidirá el socio desarrollador. Google recomienda publicar el contenido de recomendación general una o dos veces al día y usar una metodología basada en eventos para el carrito de compras, el reordenamiento y otro contenido de Continuation (por ejemplo, iniciar el trabajador como una devolución de llamada del usuario que agrega artículos al carrito o que detiene una película a la mitad). En el caso de las apps sociales, es fundamental publicar clústeres de recomendaciones actualizados después de cada uso de la app. Los usuarios de apps de redes sociales están más interesados en las recomendaciones más recientes y, lo ideal, es que quieran ver una publicación como máximo una vez.

¿Cuándo debe el desarrollador llamar a las APIs de Delete?

Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication quitan el contenido anterior automáticamente.

Preguntas frecuentes sobre intents de transmisión

¿Por qué los desarrolladores de apps para Android deben registrarse para utilizar intents de transmisión?

Para entregar contenido actualizado al usuario, debes usar intents de transmisión para activar una sincronización de datos en los casos en que los usuarios no usen la app con frecuencia.

No se permite la ejecución en segundo plano

Durante el registro del intent de transmisión, es posible que encuentres el siguiente error:

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

Debes registrar los receptores de emisión de forma 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));
...

}

Preguntas frecuentes sobre el flujo de trabajo

Durante la integración con el SDK, es posible que encuentres los siguientes errores:

Los vínculos directos se asocian con el nombre del paquete. Una buena forma de evaluar los vínculos directos es usar la herramienta adb.

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

Los vínculos directos son una excelente manera de hacer un seguimiento de la atribución. Las URLs de vínculo directo que dirigen a los usuarios a tu app se pueden incluir con parámetros de seguimiento adicionales. Por ejemplo: "http://xx/deeplink?source_tag=engagement".

Los desarrolladores pueden agregar sus propios parámetros de seguimiento y proporcionar atribución para calcular el impacto.

Preguntas frecuentes sobre Engage para TV 2.0

Preguntas generales

¿Qué es Seguir mirando 2.0?

La función Seguir mirando 2.0 (API de Video Discovery) lleva la experiencia de "reanudar desde donde lo dejaste" al siguiente nivel. Es una actualización significativa que permite a los usuarios reanudar su contenido sin problemas en una variedad más amplia de dispositivos. Imagina que comienzas una película en tu Google TV y, luego, la continúas sin esfuerzo en tu teléfono durante tu viaje diario. Esa es la potencia de Seguir mirando 2.0.

Este nuevo sistema está diseñado para aumentar la participación y la retención de los usuarios, ya que proporciona una experiencia fluida y sin interrupciones en todo el ecosistema de Google.

¿Cuáles son los beneficios de usar Seguir mirando 2.0?

Respuesta: La función Seguir mirando 2.0 permite que los usuarios retomen su contenido desde donde lo dejaron, sin importar el dispositivo que usen. Funciona de la siguiente manera:

  • Experiencia fluida en Google: Empieza a mirar contenido en Google TV y continúa sin problemas en tu teléfono o tablet Android o iPhone. Incluso funciona en dispositivos en los que aún no instalaste la app.
  • Mayor participación y retención: Seguir mirando 2.0 ayuda a que los usuarios vuelvan a tu app, incluso en dispositivos nuevos. Si permites que los usuarios reanuden sus programas favoritos, aumentarás las probabilidades de que sigan mirándolos.
  • Alcance más amplio: Además de Google TV, Seguir mirando 2.0 funciona en otras experiencias multimedia de Android, como Play Cubes y otras apps multimedia de Google.
  • Retrocompatible: Si ya usas la función "Mirar a continuación" anterior, no hay problema. Seguir mirando 2.0 es retrocompatible, por lo que tu integración existente seguirá funcionando.

Nota importante: Todas las integraciones nuevas de Seguir mirando deben usar Seguir mirando 2.0. El sistema anterior "Reproducir a continuación en todos los dispositivos" se eliminará gradualmente.

¿Qué plataformas admiten Seguir mirando 2.0?

  1. Google TV
  2. Android TV (solo integrado en el dispositivo, pero compatible con el SDK de Engage)
  3. App para dispositivos móviles de Google TV para Android
  4. App para dispositivos móviles de Google TV para iOS
  5. Cubes de Play
  6. Google Entertainment Space
  7. Dispositivos iOS (con integración de la API de REST)

¿El SDK de Engage es para Seguir mirando 2.0?

Sí, el SDK de Engage es para Seguir mirando 2.0. Es obligatorio integrarlo con Seguir mirando 2.0.

¿Sigue mirando 2.0 está disponible para todos?

Seguir mirando 2.0 se lanzará en fases.

  • Acceso anticipado: Inicialmente, otorgaremos acceso a un grupo selecto de socios a través de un programa de acceso anticipado (EAP).
  • Acceso ampliado: Estamos trabajando arduamente para que Continuar mirando 2.0 esté disponible para todos los desarrolladores pronto.

Para garantizar un lanzamiento sencillo y exitoso, contamos con protecciones para administrar el lanzamiento. Esto incluye una lista de entidades permitidas en el lado de Seguir mirando 2.0 y una verificación independiente dentro del SDK de Engage. Si eres socio del PAA o quieres incorporarte pronto, comunícate con nosotros para que podamos configurar los permisos de acceso antes de que comiences con la integración del SDK de Engage.

Se actualizaron los requisitos de las imágenes en la sección Crear entidades.

Con esta nueva documentación de la API, ¿el servidor de Google extraerá los datos de Seguir mirando del cliente y se reflejarán en todos los dispositivos?

La nueva API ofrece ventajas significativas para Seguir mirando, como las siguientes:

  • Experiencia fluida en Google TVs: Los usuarios pueden comenzar a mirar contenido en una Google TV y reanudarlo en cualquier otra Google TV a la que hayan accedido con la misma cuenta. Esta función también funciona con versiones anteriores de Android TV.

  • Integración en la app para dispositivos móviles: Sigue mirando está disponible en la app para dispositivos móviles de Google TV para Android y iOS, lo que permite a los usuarios cambiar sin problemas entre su TV y sus dispositivos móviles.

  • Retención de usuarios mejorada: Incluso en dispositivos sin la app instalada o en los que el usuario no accedió, la función Seguir mirando les solicita a los usuarios que vuelvan a interactuar con tu app, lo que aumenta la retención.

  • Expansión a otras plataformas: Esta integración extiende la función Seguir mirando a otras plataformas de contenido multimedia de Google, como Android, Play Cubes, tablets y otras apps y plataformas de contenido multimedia de Google en Android, lo que maximiza la participación de los usuarios en todos los dispositivos.

¿Cuál es el límite de la cantidad de entidades que puedo publicar en el clúster de Continuation?

Cada socio desarrollador tiene un límite de 5 entidades en el clúster de Continuation. Este límite garantiza una distribución justa del contenido en la fila “Seguir mirando” de Google TV, que es un espacio compartido para varios proveedores de contenido multimedia.

¿Qué sucede si intento publicar más de 5 entidades?

EngageSDK rechazará tu solicitud de publicación si supera el límite de 5 entidades. Deberás reducir la cantidad de entidades en tu solicitud para publicarla correctamente. Solo debes incluir las entidades en las que los usuarios dejaron de mirar, por lo que, en la mayoría de los casos, solo habrá algunas de esas entidades. Cuando haya más de 5 entidades de este tipo, puedes elegir las más recientes para publicarlas.

¿Por qué hay un límite en la cantidad de entidades?

La fila "Sigue mirando" en Google TV muestra contenido de varios proveedores de medios. Limitar la cantidad de entidades por proveedor garantiza que los usuarios vean una selección diversa de contenido de todas sus fuentes favoritas, lo que promueve una experiencia del usuario justa y equilibrada.

Preguntas sobre la app de verificación

¿Es obligatorio probar mi app con la app de verificación antes de enviarla?

Sí, es fundamental probar tu app con la app de verificación antes de enviar tu APK.

Si bien entendemos que podrías tener confianza en tu implementación, la integración de Seguir mirando 2.0 tiene muchos componentes complejos. La app de verificación actúa como una red de seguridad, detecta posibles problemas desde el principio y te ahorra tiempo y esfuerzo valiosos a largo plazo.

Piensa en ello como un chequeo rápido que ayuda a garantizar un lanzamiento fluido y una gran experiencia del usuario.

Si identificas y abordas los problemas de antemano, puedes evitar la frustración de los rechazos y los envíos posteriores.

Para enviar tu APK, deberás incluir una captura de pantalla que muestre que tu app aprobó el proceso de verificación.

#### ¿Cuáles son algunos errores comunes que debo tener en cuenta durante la integración?

La app de verificación está diseñada para detectar posibles problemas con tu integración de Seguir mirando 2.0. Estos son algunos errores comunes que los desarrolladores suelen encontrar:

Para todos los tipos de contenido (películas, episodios de TV, transmisiones en vivo y clips de video), sigue estos pasos:

  • Faltan vínculos: Asegúrate de proporcionar URIs (vínculos) válidos y específicos de la plataforma para tu contenido. Estos vínculos le indican al sistema dónde encontrar tu contenido en cada plataforma.
  • Faltan títulos: No olvides incluir títulos para todo tu contenido. Esto ayuda a los usuarios a identificar lo que estaban mirando.
  • Relaciones de aspecto de las imágenes: Asegúrate de que todas las imágenes asociadas con tu contenido tengan una relación de aspecto cercana a 16:9. Esto garantiza que tus imágenes se muestren correctamente en diferentes pantallas.

Para episodios de TV:

  • Información completa del episodio: Asegúrate de incluir el título del programa, el número del episodio y el número de la temporada. Esto ayuda a organizar los episodios y permite a los usuarios navegar dentro de una serie.
  • Posición de reproducción precisa: Verifica que la última posición de reproducción sea inferior o igual a la duración total del episodio. Esto garantiza que los usuarios reanuden desde el punto correcto.

Para películas:

  • Posición de reproducción precisa: Al igual que con los episodios de TV, asegúrate de que la última posición de reproducción sea precisa.

Para videos de transmisión en vivo:

  • Información del emisor: Incluye el nombre del emisor para las transmisiones en vivo.

Para los clips de video, sigue estos pasos:

  • Información del creador: Especifica el creador del clip de video.

Recuerda: La app de verificación marcará estos problemas, lo que te permitirá corregirlos antes de enviar la app. Esto te ahorrará tiempo y garantizará una experiencia más fluida para tus usuarios.

Preguntas sobre la cuenta y el perfil

Mi app usa accesos de usuarios anónimos. ¿Se sigue requiriendo AccountProfile para Seguir mirando 2.0?

AccountProfile está diseñado para apps que usan cuentas de usuario individuales. Sin embargo, sabemos que algunas apps, como la tuya, pueden depender de accesos anónimos. A continuación, te mostramos cómo funciona Seguir mirando 2.0 en esta situación:

  • Técnicamente, AccountProfile es obligatorio, pero puedes integrar Continuar reproducción 2.0 incluso si tu app no tiene un sistema de cuentas de usuario.
  • Se limita al uso en el dispositivo: Las capacidades multidispositivo de Seguir mirando 2.0 se basan en la identificación de usuarios en diferentes dispositivos. Como los accesos anónimos no proporcionan esta información, la función se limitará al dispositivo actual del usuario.
  • Cómo configurar: Para configurar esta opción, deberás inhabilitar la sincronización entre dispositivos. Esto garantiza que las entradas de Continuar mirando solo aparezcan en el dispositivo específico en el que se inició el contenido.

En resumen: Si bien puedes integrar Seguir mirando 2.0 con accesos anónimos, los usuarios solo podrán reanudar el contenido en el mismo dispositivo.

¿Puedo usar AccountProfile solo con accountId y sin profileId, incluso si mi app admite accountId y profileId?

AccountProfile requiere que accountId y profileId funcionen correctamente. Estos son los motivos:

  • Identificación coherente: accountId identifica al usuario, mientras que profileId distingue entre los diferentes perfiles dentro de la cuenta de ese usuario (si corresponde). Si proporcionas ambos, se garantiza que la función Seguir mirando haga un seguimiento y muestre con precisión el contenido de cada perfil individual.
  • Prevención de errores: El uso de accountId y profileId de forma incoherente en diferentes llamadas a la API puede generar errores y comportamientos inesperados. Por ejemplo, si incluyes ambos cuando agregas contenido a Seguir mirando, pero solo usas accountId cuando borras contenido, es posible que el sistema no pueda identificar ni quitar correctamente los elementos deseados.

¿Se requiere profileId para Seguir mirando 2.0?

  • accountId es obligatorio. Esto identifica al usuario en todos los dispositivos.
  • profileId es fundamental para una buena experiencia del usuario. Si bien es técnicamente opcional, se recomienda usar profileId si tu servicio admite varios perfiles (como lo hacen muchos servicios de transmisión). ¿Por qué es tan importante? Porque, sin profileId, es posible que la función Seguir mirando muestre contenido de otros perfiles en la misma cuenta. Esto puede generar una experiencia confusa y frustrante para los usuarios.
  • En resumen, proporcionar el profileId garantiza que la función Seguir mirando refleje con precisión el historial de reproducciones de cada persona. A menos que tu app no admita el concepto de perfil dentro de una cuenta, debes proporcionarlo.

¿Cómo usa Google el profileId?

Si el servicio ofrece diferentes perfiles para mirar contenido, se usarán accountId y profileId para asociar el contenido que se mira en el dispositivo con la Cuenta de Google a la que se accedió en el dispositivo. Google registraría los datos de ContinueWatching en la combinación de accountId-profileId. Cualquier dispositivo de Google que haya accedido con la misma Cuenta de Google recibirá los datos actualizados más recientes de los mismos IDs de cuenta y perfiles asociados en la fila de ContinueWatching.

¿Se requiere la vinculación de cuentas para implementar Seguir mirando 2.0?

No es necesario vincular una cuenta. Se le quitará prioridad, y la nueva API de Device Entitlements cubrirá todos los casos de uso relacionados.

Preguntas sobre la sincronización entre dispositivos

Con el consentimiento del usuario para "sincronizar contenido en todos los dispositivos", el contenido que está mirando se guardará en los servidores de Google TV, lo que le permitirá reanudar lo que estaba viendo sin problemas en cualquier dispositivo en el que haya accedido. Sin consentimiento, el historial de reproducción permanece local en el dispositivo actual.

¿Podemos establecer "Sincronizar dispositivos" como falso?

La marca UserConsentToSyncAcrossDevices controla si los datos de ContinuationCluster de un usuario se sincronizan en todos sus dispositivos (TV, teléfono, tablet, etcétera). Si esta marca se establece como falsa, la acción de seguir mirando solo se realiza en el mismo dispositivo.

Para aprovechar al máximo nuestra función multidispositivo, te recomendamos que tu app obtenga el consentimiento del usuario y establezca SyncAcrossDevices como verdadero.

dispositivos? ¿Qué datos se comparten con servidores de terceros desde dispositivos que no son Android?

El consentimiento se recopila a nivel del usuario (nivel del perfil o de la cuenta). Una vez que se obtiene el consentimiento, las cargas útiles de reproducción continua basadas en la participación se pueden enviar a cualquier lugar para que Google pueda reflejar el estado de reanudación de la ubiquidad de los usuarios en todas las entidades con las que tengan una participación parcial o próxima, en cualquier dispositivo (sin tener que volver a solicitar el consentimiento en todos los dispositivos o plataformas). Los socios enviarán el estado de reproducción continua más reciente del usuario (según las especificaciones) asociado con el ID de perfil (que se depositó en Android).

Preguntas sobre la API de REST

¿Hay documentación sobre la API de REST?

La fecha de llegada estimada de la API de REST es marzo de 2025, como se documenta en la documentación para desarrolladores de Seguir mirando 2.0.

Preguntas heredadas de Ver a continuación

¿La API de Video Discovery reemplazará a la API de Watch Next?

La API de Video Discovery será retrocompatible en todos los dispositivos Android TV que admitan la API de Watch Next. Todos los desarrolladores deben usar la API de Video Discovery (Sigue mirando 2.0) para publicar contenido en la fila Seguir mirando.

Preguntas sobre pruebas e integración

¿Cuál es la diferencia entre LastPlayBackPositionTimeMillis y duration?

LastPlayBackPositionTimeMillis debe reflejar la duración de la reproducción en milisegundos en la que el usuario dejó de mirar (p.ej., 605,000 ms para 10 minutos y 5 segundos). Nunca debe ser mayor que la duración total de la entidad.

Mientras que LastEngagementTime es la marca de tiempo de la última vez que el usuario interactuó con el contenido.

¿Cuáles son los casos de prueba que debemos realizar?

Los siguientes son casos de prueba de Google TV que realiza nuestro equipo de QA. También se pueden realizar casos de prueba similares en otras plataformas.

  1. Mira un video de más de 20 minutos durante unos 5 minutos. Sal de la app. La tarjeta de video debería mostrarse en la fila “Continuar mirando”. Nota: Solo mostramos 5 tarjetas por app de terceros en CW.
  2. Si seleccionas la tarjeta que apareció recientemente en la fila “Continuar reproduciendo”, el video debería seguir reproduciéndose desde el punto correcto. Nota: El contenido nuevo o anterior debería reanudar la reproducción desde donde se dejó la última vez.
  3. Si cambias de cuenta en el dispositivo de GTV, deberían cambiar las tarjetas de la fila Seguir viendo. Solo deberían aparecer los videos de la cuenta actual. Se ordenan de forma reciente. El CW del perfil de app de terceros se combinará. Nota: La CW de GoogleAccount2 mostrará el contenido de terceros que GoogleAccount2 estaba mirando.
  4. Sal de la app con el botón ATRÁS > Asegúrate de que la tarjeta se muestre en la fila “Continuar viendo”.
  5. Oculta el video en la fila "Seguir mirando". No debería volver a mostrarse. Prueba si el contenido oculto permanece oculto más allá de las 24 horas y, incluso, después de que la app se abra después de ese período. Confirma que ocultar un elemento no oculte varios.
    1. Disponibilidad del contenido en Seguir mirando con metadatos completos: imagen de la tarjeta, nombre de la app, título y número de episodio de la temporada para el contenido de TV
  6. La opción Verificar progreso se muestra en la barra de progreso.
  7. El usuario miró el contenido hasta los créditos finales; el contenido no se muestra en Continuar mirando
  8. Confirma que no aparezcan elementos sin mirar en la fila para seguir mirando
  9. Confirma que los elementos de CW estén organizados cronológicamente según el momento en que se produjo la actividad de reproducción y no según la última vez que se abrió la app o el último día
  10. Confirma que los detalles del episodio y la temporada en la tarjeta de CW coincidan con lo que se miró en el contenido de episodios.
  11. Confirma que los elementos completados (elementos en los créditos o más allá) no aparezcan en la opción para continuar mirando.
  12. Apaga el dispositivo a mitad de la reproducción del episodio, la película o el programa. "Apaga el dispositivo a mitad de la reproducción del episodio, la película o el programa. Verifica que, cuando se enciende el dispositivo y en otra TV, CW muestre la tarjeta correcta, en la posición correcta y la barra de progreso.
  13. Apaga el dispositivo después de mirar el episodio 1 por completo y verifica lo siguiente:
    1. El episodio 1 se cae y no vuelve a aparecer en la fila Seguir mirando [en el segundo dispositivo y cuando se enciende el dispositivo de prueba].
    2. El episodio 2 (si está disponible) debería aparecer en la fila Seguir mirando [en el segundo dispositivo y cuando se enciende el dispositivo de prueba].

  14. Primer escenario: TV1: Cuenta de Google: mamá, cuenta de terceros / perfil: cuenta 1/profile_1. Mira contenido y verifica que los datos de CW muestren el contenido que miró la cuenta_1/el perfil_1 de terceros

    1. TV2: Cuenta de Google: mamá. Verifica los datos de CW de la primera situación. Ahora accede a la app de terceros con otra cuenta. Cuenta o perfil de terceros: account_2/profile_2. Mira contenido y verifica que los datos de CW muestren el contenido que miró la cuenta_2 o el perfil_2 de terceros.

  15. GoogleAccount: mamá. No se instaló la nueva funda del dispositivo o la app de terceros. En un dispositivo nuevo(restablece la configuración de fábrica del dispositivo), Verify CW muestra los datos de la última app de terceros que usó la Cuenta de Google. Nota: La fila de CW no debe mostrar contenido de terceros si GAIA aún no está asociado con un perfil de terceros en otro dispositivo.

    1. GoogleAccount: mamá. Caso de dispositivo nuevo o app de terceros instalada, pero no se accedió a la cuenta. En un dispositivo nuevo(restablece la configuración de fábrica del dispositivo), Verify CW muestra los datos de la última app de terceros que usó la Cuenta de Google.
    2. Nota: Cuando la app esté instalada y se haya accedido a ella, el estado de CW reflejará al usuario externo activo que accedió a la app de terceros.
    3. Nota: La fila Seguir mirando no debe mostrar contenido de terceros si la Cuenta de Google aún no está asociada con un perfil de terceros.

No vemos la opción Seguir mirando en la app de Google TV para iOS. ¿Qué sucedió?

Deberás enviar vínculos directos de iOS para que la función Seguir mirando aparezca en los dispositivos iOS.

¿Con qué frecuencia debo actualizar la información de Seguir mirando? ¿Debo actualizar la información de Seguir mirando con frecuencia, por ejemplo, cada 15 segundos?

No, no se recomiendan las actualizaciones frecuentes. Estos son los motivos:

  • Impacto en el rendimiento: El envío continuo de actualizaciones genera una carga innecesaria en nuestros servidores, lo que podría ralentizar el sistema para todos.
  • Datos innecesarios: Mientras un usuario mira contenido de forma activa, su posición de reproducción cambia constantemente. El envío de actualizaciones cada pocos segundos crea muchos datos redundantes que no son útiles para reanudar la reproducción.

Cuándo actualizar la información de Seguir mirando:

Enfócate en capturar cambios significativos en el progreso de visualización del usuario. Estas son las situaciones clave:

  • Pausa o detención de la reproducción: Cuando un usuario pausa o detiene la reproducción, envía una actualización para almacenar su posición actual.
  • App cerrada o en segundo plano: Si un usuario sale de la app o cambia a otra mientras mira un video, envía una actualización para guardar su progreso.
  • Cuando el usuario quita un elemento de la fila Seguir mirando dentro de la app

Cómo actualizar de forma eficiente:

En lugar de actualizaciones cronometradas, usa eventos dentro del ciclo de vida de tu reproductor de video o app para activar las actualizaciones. Por ejemplo:

  • onPause, onStop: Cuando se pausa o detiene la reproducción de video.
  • onAppClose, onAppBackgrounded: Cuando la app se cierra o pasa a segundo plano.

Si sigues estos lineamientos, te asegurarás de usar los recursos de manera eficiente y, al mismo tiempo, de brindar a los usuarios una experiencia fluida de Seguir mirando.