> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.drimify.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

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

# Widget código de muestra

```
<html>
<head>
   <!-- Incluir los bundles -->
   <script src="https://cdn-apps.drimify.com/prod/widget/index.js" type="text/javascript"></script>

   <!-- Configurar el widget al cargar la página -->
   <script>
       window.addEventListener('load', function () {
           var widget = DigitaService.Widget.Create({
               autoscroll: true,
               element: 'gamification-widget',
               engine: 'https://apps.drimify.com/Rf6aGmBR/',
               fixed: false,
               altura:['auto'],
               sharingurl: 'https://apps.drimify.com/Rf6aGmBR/',
               ancho: '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

### Requerido

| 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 de string 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 cargue. Puedes anular esto 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 está en píxeles como “600px”. Al usar *options.fixed = true*, el valor de la altura se bloqueará al valor proporcionado, introduciendo barras de desplazamiento. |
| **options.autoscroll** | boolean | true | Dependiendo de la longitud del contenido del widget y la pantalla del usuario, puede requerir que la página que contiene el widget necesite desplazamiento de la página de alojamiento. El comportamiento predeterminado cuando un usuario está usando el Widget es desplazar la página de alojamiento hasta la parte superior del widget para mejorar la usabilidad. Para desactivar esto, establece autoscroll en false. Esta propiedad será falsa si *options.fixed* es true. |
| **options.sharingurl** | string | La URL de alojamiento que contiene el widget | Al utilizar el Compartir en Redes Sociales, esta es la URL que las personas compartirán en medios 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 URL. |
| **options.fixed** | boolean | false | Generalmente, el widget cambiará de tamaño automáticamente para ajustarse al contenido del engine y evitar barras de desplazamiento. Si esto se configura en true, entonces la altura del widget será persistente y no cambiará. Al utilizar esta opción, el valor de *options.height* debe configurarse en algo distinto de “auto”. Si la altura del engine es mayor que el valor de height, se utilizarán barras de desplazamiento para navegar. |
| **options.width** | string | “100%” | El ancho del widget. Se puede configurar como una medida CSS como “%” o “px”, por ejemplo. |

### Cargar

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

*Nota: Asegúrate de configurar cualquier de los callbacks a continuación antes de cargar para que puedas capturar todos los eventos.*

```
widget.load();
```

# Callbacks de Evento

###### onReady

Una vez que se ha llamado a *widget.load()*, esto cargará e inicializará el widget. Cuando el widget haya completado este proceso, 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 que se ha llamado a *widget.load()*, esto 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 nuevo Error(event.message);
};
```

###### onComplete

Una vez que el juego ha sido completado y el usuario está viendo en la última pantalla. También proporciona un *objeto de datos* describiendo lo que ocurrió en el juego.

*Nota: si deseas actuar en esto, puedes querer 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 Engine ha sido redimensionado, proporciona 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/click) con la aplicación cargada por primera vez.

```
widget.onFirstInteraction = function () {
   console.log("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 event 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 undefined
   console.log("Usuario navegó a una nueva pantalla");
};
```

###### onScrollToTop

Ocurre cuando la aplicación está tratando de desplazarse de nuevo a la parte superior de la página. Puede utilizarse en la página de origen para asegurar que el desplazamiento no se dispara (CORS) o necesita ser ajustado. El event no contiene un objeto de datos.

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

# Métricas

Aquí hay una lista de las métricas clave que pueden ser utilizadas dependiendo del tipo de juego:

| Clave | Descripción |
| ---- | ---- |
| **data.gameMetrics.CurrentAttempt** | Los intentos del usuario una vez que ha completado 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** | true/false dependiendo del estado del usuario. |
| **data.gameMetrics.score** | La cantidad total de puntos acumulados que este usuario completa el juego. |

###### Credenciales

| Clave | Descripción |
| ---- | ---- |
| **data.credentials.isPreviewMode** | Verificar si el juego está en modo de vista previa. |
| **data.credentials.projectID** | El id de la aplicación actual jugada. |
| **data.credentials.projectLanguage** | El idioma del proyecto en el 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 publicador. |
| **data.credentials.sessionID** | El id de sesión del jugador actual. |

# Manejo de Errores

Hay dos formas principales de detectar errores y recuperar información sobre problemas que ocurren dentro del widget:

## Callback onError

El callback `onError` captura cualquier error fatal que ocurra después de que se cargue el widget. Esto puede ser útil para identificar cuando una página no existe o si ocurre una falla crítica.
```
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 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 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 más visualizaciones");
                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("Uid de sesión no detectado");
                break;
            case 'ERR_10':
                console.log("Uid de sesión ya utilizado");
                break;
            case 'ERR_11':
                console.log("Plan no activado");
                break;
            case 'ERR_12':
                console.log("Datos incorrectos recibidos");
                break;
            case 'ERR_13':
                console.log("La llamada SSO ha fallado");
                break;
            case 'ERR_14':
                console.log("Idioma no disponible");
                break;
        }
    }
};
```

Al usar ambos `onError` y `onRouteChange`, puedes rastrear y manejar efectivamente problemas que puedan ocurrir dentro del widget, asegurando una mejor experiencia de usuario.

# Recuperación de Información del Usuario en la Pantalla Final (`onRouteChange`)

Al usar **Dynamic Path™**, **Advent Calendar** o **Combo™**, puedes recuperar información del usuario al final de cualquier juego a través del callback `onRouteChange`.

Este método es requerido porque el evento estándar `onComplete` solo se activa **una vez que toda la experiencia multi-paso ha finalizado**, no cuando cada juego incrustado termina.

Esto permite que tu sistema reciba los resultados del juego completo (vía `gameInfo`) cuando el usuario llega al fin de la pantalla de la experiencia.

# Configuración

Después de crear tu widget:

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

```

Añadir el listener `onRouteChange`:

```
widget.onRouteChange = function (event) {
    console.log(event.type);   // "routechange"
    console.log(event.data);   // { ... } o undefined
    console.log("Usuario navegó a una nueva pantalla");
};

```

# Detectando la Pantalla Final

Cuando el usuario llega al fin de la pantalla del juego, el widget devolverá una ruta que coincide con:

```
event.data.screen === 'screen_end-YOUR_APP_ID'

```

Reemplazar `YOUR_APP_ID` con tu actual ID de aplicación.

# Recuperando la Información del Usuario (`gameInfo`)

Una vez que se detecta la pantalla final, 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 recogidos durante la experiencia

Este payload solo está disponible en la pantalla final 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 de la pantalla final:", datos);
        // Procesar o reenviar esta información según sea necesario
    }
};

```