Integración avanzada del código de integración HTML (widget) a través de la API
Código de ejemplo del widget
<html>
<head>
<!-- Include the bundles -->
<script src="https://cdn-apps.drimify.com/prod/widget/index.js" type="text/javascript"></script>
<!-- Setup the widget on page load -->
<script>
window.addEventListener('load', function () {
var widget = DigitaService.Widget.Create({
autoscroll: true,
element: 'gamification-widget',
engine: 'https://apps.drimify.com/XBs15jKF/',
fixed: false,
height:['auto'],
sharingurl: 'https://apps.drimify.com/XBs15jKF/',
width: '100%',
});
widget.onReady = function (event) {};
widget.onComplete = function (event) {};
widget.onFirstInteraction = function () {};
widget.onRouteChange = function (event) {};
widget.onScrollToTop = function () {};
widget.onClose = function () {};
widget.onError = function (errorEvent) {};
widget.load();
});
</script>
</head>
<body>
<div id="gamification-widget"></div>
</body>
</html>
Configuración
Crea un Widget pasando un objeto Options a la función Create:
var widget = DigitaService.Widget.Create(options);
Opciones de Configuración
Requerido
Opción | Tipo | Descripción |
|---|---|---|
options.element | string - HTMLElement | El widget será inyectado en este HTMLElement. Puedes pasar acceso directo a un HTMLElement existente o proporcionar el ID de cadena para ese elemento. Si no proporcionas esta propiedad, intentará encontrar un id “digitaservice-widget” en la página. |
options.engine | string | La URL absoluta de la aplicación que se cargará en el widget. |
Opcional
Opción | Tipo | Predeterminado | Descripción |
|---|---|---|---|
options.height | string | auto | El widget tiene una altura predeterminada de cero antes de que se haya cargado. Puedes sobrescribir esto con un valor de marcador de posición para evitar saltos de página dependiendo de dónde se utilice el widget en la página principal. El valor está en píxeles como “600px”. Al usar options.fixed = true, el valor de altura se bloqueará al valor proporcionado introduciendo barras de desplazamiento. |
options.autoscroll | booleano | true | Dependiendo de la longitud del contenido del widget y la visualización del usuario, puede requerir que la página que contiene el widget necesite desplazarse. El comportamiento predeterminado cuando un usuario está utilizando el Widget, es desplazar la página de alojamiento hasta la parte superior del widget para facilitar el uso. Para desactivar esto, establece autoscroll en false. Esta propiedad será false si options.fixed es true. |
options.sharingurl | string | La URL de la página que contiene el widget | Al utilizar Compartición en Redes Sociales, esta es la URL que las personas compartirán en las Redes Sociales para llevarlas a tu campaña. Si sharing es una cadena vacía, utilizará la página de alojamiento (que contiene el widget) como la URL. |
options.fixed | booleano | false | Normalmente el widget cambiará de tamaño automáticamente para ajustarse al contenido del motor y evitar barras de desplazamiento. Si esto se establece en true, entonces la altura del widget será persistente y no cambiará. Al utilizar esta opción, el valor de options.height debe establecerse en cualquier cosa que no sea “auto”. Si la altura del motor es mayor que el valor de altura, se utilizarán barras de desplazamiento para navegar. |
options.width | string | “100%” | El ancho del widget. Se puede establecer hasta una medida CSS como “%” o “px” por ejemplo. |
Carga
Una vez que un Widget está configurado, debes cargarlo. Puedes cargar el widget en cualquier momento.
Nota: Asegúrate hasta de configurar cualquiera de las devoluciones de llamada a continuación antes de cargar para que puedas capturar todos los eventos.
widget.load();
Callbacks de Eventos
onReady
Una vez que widget.load() ha sido llamado, esto cargará e inicializará el widget. Cuando el widget haya completado este proceso, invocará una función opcional de callback onReady.
widget.onReady = function (event) {
// cargado y listo para usar
console.log(event.type); // “ready”
console.log(event.data); // {}
};
onError
Una vez que widget.load() ha sido llamado, esto cargará e inicializará el widget. Cualquier error fatal que ocurra a partir de ese punto invocará una función opcional de callback onError.
widget.onError = function (event) {
throw nuevo Error(event.message);
};
onComplete
Cuando el juego se ha completado y el usuario está viendo la última pantalla. También proporciona un objeto de datos que describe lo que ocurrió en el juego.
Nota: si deseas actuar sobre esto, quizás quieras agregar un retraso dentro del callback para que el usuario tenga tiempo de leer la pantalla final, ya que ocurre instantáneamente al llegar a la última pantalla. También puedes usar onClose.
widget.onComplete = function (event) {
console.log(event.type); // “complete”
console.log(event.data); // {}
console.log("La puntuación del usuario fue " + event.data.gameMetrics.score);
};
onResize
Ocurre cuando el Motor ha cambiado de tamaño, proporcionando la altura como un valor en píxeles.
widget.onResize = function (event) {
console.log(event.type); // “resize”
console.log(event.data); // {}
console.log("Altura de la Aplicación: " + event.data.height);
};
onFirstInteraction
Cuando el usuario interactúa (tocar/clic) con la aplicación cargada por primera vez.
widget.onFirstInteraction = function () {
console.log("El usuario interactuó con la Aplicación por primera vez");
};
onRouteChange
Ocurre cuando la Aplicación ha cambiado de ruta dentro del widget. (Navega entre pantallas). El evento puede o no contener un objeto de datos dependiendo del contexto.
widget.onRouteChange = function (event) {
console.log(event.type) // “routechange”
console.log(event.data) // {} o indefinido
console.log("El usuario navegó a una nueva pantalla");
};
onScrollToTop
Ocurre cuando la Aplicación está tratando de desplazarse de vuelta hasta la parte superior de la página. Puede ser usado en la página principal para asegurarse de que el desplazamiento no se dispare (CORS) o necesite ajustarse. El evento no contiene un objeto de datos.
widget.onScrollToTop = function () {
console.log("Desplazarse hacia la parte superior");
};
Métricas
Aquí está una lista de las métricas clave que pueden ser usadas dependiendo del tipo de juego:
Clave | Descripción |
|---|---|
data.gameMetrics.CurrentAttempt | Los intentos del usuario una vez que completó el juego. |
data.gameMetrics.prizeID | El ID del premio. |
data.gameMetrics.prizeImage | La imagen del premio. |
data.gameMetrics.prizeName | El nombre del premio. |
data.gameMetrics.prizeRef | La referencia del premio. |
data.gameMetrics.totalPossibleAttempts | La cantidad total de intentos posibles. |
data.gameMetrics.userWon | verdadero/falso dependiendo del estado del usuario. |
data.gameMetrics.score | La cantidad total de puntos obtenidos que el usuario completa el juego. |
Credenciales
Clave | Descripción |
|---|---|
data.credentials.isPreviewMode | Verifica si el juego está en modo de vista previa. |
data.credentials.projectID | El ID de la App del juego actual. |
data.credentials.projectLanguage | El idioma del proyecto en el widget (en, fr). |
data.credentials.projectName | El nombre de la app. |
data.credentials.projectType | El tipo de app (quiz, memoria...). |
data.credentials.publisherID | El ID del publicador. |
data.credentials.sessionID | El ID de la sesión del jugador actual. |
Manejo de Errores
Existen dos formas principales para detectar errores y recuperar información sobre problemas que ocurren dentro del widget:## onError Callback
El callback onError captura cualquier error fatal que ocurra después de que el widget esté cargado. Esto puede ser útil para identificar cuándo una página no existe o si sucede un fallo crítico.
widget.onError = function (event) {
if (typeof event.data.message !== 'undefined') {
switch (event.data.message) {
default:
// No hacer nada
break;
case 'ERR_15':
console.log("La página no existe");
break;
}
}
};
onRouteChange Callback
El callback onRouteChange se activa cuando la aplicación navega entre diferentes pantallas dentro del widget. Esto es útil para rastrear errores relacionados con el estado de la aplicación y la disponibilidad del contenido.
widget.onRouteChange = function (event) {
if (typeof event.data.errorCode !== 'undefined') {
switch (event.data.errorCode) {
default:
// No hacer nada
break;
case 'ERR_01':
console.log("No hay plan disponible");
break;
case 'ERR_02':
console.log("El contenido aún no está disponible");
break;
case 'ERR_03':
console.log("El contenido ha expirado");
break;
case 'ERR_04':
console.log("No hay más vistas");
break;
case 'ERR_05':
console.log("Error de seguridad");
break;
case 'ERR_07':
console.log("Aplicación no publicada");
break;
case 'ERR_08':
console.log("Aplicación Premium no disponible");
break;
case 'ERR_09':
console.log("Session Uid no detectado");
break;
case 'ERR_10':
console.log("Session Uid ya usado");
break;
case 'ERR_11':
console.log("Plan no activado");
break;
case 'ERR_12':
console.log("Datos incorrectos recibidos");
break;
case 'ERR_13':
console.log("Falló la llamada SSO");
break;
case 'ERR_14':
console.log("Idioma no disponible");
break;
}
}
};
Utilizando onError y onRouteChange, puedes seguir y manejar efectivamente los problemas que puedan surgir dentro del widget, asegurando una mejor experiencia de usuario.
Recuperando Información del Usuario al Final de la Pantalla (onRouteChange)
Al usar Dynamic Path, Advent Calendar o Combo, puedes recuperar la información del usuario al final de cualquier juego a través del callback onRouteChange.
Este método es necesario porque el evento estándar onComplete solo se activa una vez que toda la experiencia de varios pasos ha terminado, no cuando acaba cada juego embebido.
Esto permite que tu sistema reciba los resultados completos del juego (mediante gameInfo) cuando el usuario llega al final de la pantalla de la experiencia.
Configuración
Después de crear tu widget:
var widget = DigitaService.Widget.Create(options);
Añade el escucha onRouteChange:
widget.onRouteChange = function (event) {
console.log(event.type); // "routechange"
console.log(event.data); // { ... } o undefined
console.log("El usuario ha navegado a una nueva pantalla");
};
Detectar el Fin de la Pantalla
Cuando el usuario llega al final de la pantalla del juego, el widget devolverá una ruta coincidente:
event.data.screen === 'screen_end-YOUR_APP_ID'
Reemplaza YOUR_APP_ID con tu ID real de la aplicación.# Recuperación de la Información del Usuario (gameInfo)
Una vez detectado el final de la pantalla, puedes extraer los datos:
event.data.gameInfo
gameInfo contiene un array de información del usuario, que puede incluir:
- Datos de entrada del usuario
- Resultados o puntuaciones del juego
- Campos recopilados durante la experiencia
Este conjunto de datos solo está disponible al final de la pantalla para experiencias utilizadas dentro de Dynamic Path, Advent Calendar o Combo.
Ejemplo
widget.onRouteChange = function (event) {
if (event.data && event.data.screen === 'screen_end-12345') {
const datos = event.data.gameInfo;
console.log("Información al finalizar la pantalla:", datos);
// Procesa o reenvía esta información según sea necesario
}
};
Actualizado el: 25/11/2025
¡Gracias!