Este artículo también está disponible en:

Integración avanzada del código de integración HTML (widget) a través de la API

<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 de Opciones a la función Create:

var widget = DigitaService.Widget.Create(options);

Opciones de Configuración

Obligatorias

Opción	Tipo	Descripción
options.element	string - HTMLElement	El widget se inyectará en este HTMLElement. Puedes pasar acceso directo a un HTMLElement existente o proporcionar el ID en cadena de 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.

Opcionales

Opción	Tipo	Valor por Defecto	Descripción
options.height	string	auto	El widget tiene una altura predeterminada de cero antes de ser cargado. Puedes sobrescribirlo con un valor de marcador de posición para evitar saltos de página dependiendo de dónde se use el widget en la página principal. El valor es en píxeles, como “600px”. Cuando se usa options.fixed = true, el valor de altura quedará bloqueado en el valor proporcionado, introduciendo barras de desplazamiento.
options.autoscroll	boolean	true	Dependiendo de la longitud del contenido del widget y la visualización del usuario, puede ser necesario que la página que contiene el widget requiera desplazamiento. El comportamiento predeterminado al usar el Widget es desplazar la página anfitriona hacia la parte superior del widget para mejorar la usabilidad. Para desactivar esto, configura autoscroll en false. Esta propiedad será falsa si options.fixed es true.
options.sharingurl	string	La URL anfitriona que contiene el widget	Al usar Compartir en Redes Sociales, esta es la URL que las personas compartirán para llevarlas a tu campaña. Si sharing está vacío, se utilizará la página anfitriona (que contiene el widget) como URL.
options.fixed	boolean	false	Normalmente, el widget cambiará de tamaño automáticamente para ajustarse al contenido del motor y evitar barras de desplazamiento. Si esto está configurado en true, entonces la altura del widget será persistente y no cambiará. Al usar esta opción, el valor de options.height debe establecerse en cualquier cosa diferente de “auto”. Si la altura del motor es mayor que el valor de altura, se usarán barras de desplazamiento para navegar.
options.width	string	“100%”	El ancho del widget. Puede configurarse como una medida CSS como “%” o “px”, por ejemplo.

Cargar

Una vez que un Widget está configurado, debes cargarlo. Puedes cargar el widget en cualquier momento.

Nota: Asegúrate de configurar cualquiera de los callbacks a continuación antes de cargar para poder capturar todos los eventos.

widget.load();

Event Callbacks

onReady

Cuando se llama a widget.load(), este cargará e inicializará el widget. Una vez que el widget haya completado este proceso, se invocará un callback opcional onReady.

widget.onReady = function (event) {
   // cargado y listo para usar
   console.log(event.type); // “ready”
   console.log(event.data); // {}
};

onError

Una vez se llama a widget.load(), este cargará e inicializará el widget. Cualquier error fatal que ocurra después de ese punto invocará un callback opcional onError.

widget.onError = function (event) {
   throw new Error(event.message);
};

onComplete

Una vez 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 en esto, puede que quieras dar un tiempo de espera 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);
};

onClose

La aplicación puede configurarse con un botón dedicado a cerrar que permite al usuario cerrar implícitamente la experiencia. Si este botón está configurado y el usuario interactúa con él, se enviará el evento de cerrar. Este es un buen momento para destruir el widget desde tu página y finalizar el ciclo de vida del widget.

widget.onClose = function () {
   DigitaService.Widget.Destroy();
};

onFirstInteraction

Cuando el usuario interactúa (toca/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 contener o no 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ó hacia una nueva pantalla");
};

onScrollToTop

Ocurre cuando la Aplicación intenta 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 active (CORS) o necesite ser ajustado. El evento no contiene un objeto de datos.

widget.onScrollToTop = function () {
   console.log("Desplazarse hasta la parte superior");
};

Métricas

Aquí tienes una lista de las métricas clave que se pueden utilizar según el tipo de juego:

Clave	Descripción
data.gameMetrics.CurrentAttempt	Los intentos cuando el usuario completa 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 según el estado del usuario.
data.gameMetrics.score	La cantidad total de puntos acumulados con los que el usuario completa el juego.

Credenciales

Clave	Descripción
data.credentials.isPreviewMode	Verifica si el juego está en modo vista previa.
data.credentials.projectID	El ID de la App actual.
data.credentials.projectLanguage	El idioma del proyecto dentro del widget (en, fr).
data.credentials.projectName	El nombre de la aplicación.
data.credentials.projectType	El tipo de aplicación (quiz, memory...).
data.credentials.publisherID	El ID del editor.
data.credentials.sessionID	El ID de la sesión del jugador actual.

Manejo de Errores

Existen dos formas principales para detectar errores y recopilar información sobre problemas que ocurren dentro del widget:

Callback onError

El onError callback captura cualquier error fatal que se produzca después de que el widget se haya cargado. Esto puede ser útil para identificar cuándo una página no existe o si ocurre 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;
        }
    }
};

Callback onRouteChange

El onRouteChange callback 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 de 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("No se detectó el Uid de la sesión");
                break;
            case 'ERR_10':
                console.log("El Uid de la sesión ya se ha utilizado");
                break;
            case 'ERR_11':
                console.log("Plan no activado");
                break;
            case 'ERR_12':
                console.log("Datos recibidos incorrectos");
                break;
            case 'ERR_13':
                console.log("La llamada de SSO ha fallado");
                break;
            case 'ERR_14':
                console.log("Idioma no disponible");
                break;
        }
    }
};

Al usar tanto onError como onRouteChange, puedes rastrear y manejar eficazmente los problemas que puedan surgir dentro del widget, asegurando una mejor experiencia para el usuario.

Actualizado el: 05/03/2025

¿Este artículo te resultó útil?

¡Gracias!