> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de API JavaScript de mensajes dentro de la aplicación

> Métodos JavaScript para mensajes HTML interactivos dentro de la aplicación en OneSignal.

Esta guía cubre la **API de JavaScript** para mensajes HTML dentro de la aplicación creados con el [Editor HTML de OneSignal](./design-your-in-app-message-with-html).

Si estás buscando **métodos SDK** para configurar disparadores, manejar eventos de clic dentro de la aplicación o gestionar el ciclo de vida dentro de la aplicación, consulta la [Referencia del SDK Móvil](./mobile-sdk-reference#in-app-messages).

***

## Requisitos

### Usar el atributo `data-onesignal-unique-label` para rastreo de clics

Todos los elementos clicables deben tener un atributo `data-onesignal-unique-label` con un valor **único**. Esto permite a OneSignal:

* Rastrear análisis de clics
* Disparar correctamente acciones asociadas

```html HTML theme={null}
<button id="tag-user-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Tag User
</button>
```

<Warning> Si dos elementos comparten el mismo `data-onesignal-unique-label`, los clics pueden registrarse incorrectamente o las acciones pueden no dispararse. </Warning>

### Adjuntar detectores de eventos

Debes adjuntar explícitamente detectores de eventos de JavaScript para disparar acciones dentro de la aplicación de OneSignal.

```javascript JavaScript theme={null}
document.getElementById("tag-user-button")
  .addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
```

**Ejemplo:**

```html HTML theme={null}
<button id="tag-user-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>
```

***

## Manejo del rastreo de clics en mensajes HTML dentro de la aplicación en entorno aislado

Debido a que los mensajes HTML dentro de la aplicación se ejecutan en un WebView aislado, el rastreo de clics y la navegación deben ocurrir dentro del mismo marco.
Los anclajes estándar (`<a href="...">`) y las llamadas `window.open()` no se rastrean y pueden desencadenar advertencias en la consola como:

```
SOAuthorizationCoordinator::tryAuthorize (2): Attempting to perform subframe navigation.
```

### Correcto: usar un botón y APIs de OneSignal

```html HTML theme={null}
<button id="shop-now" data-onesignal-unique-label="your-unique-label-for-this-button">
  Shop Now
</button>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    const btn = document.getElementById("shop-now");
    btn.addEventListener("click", function(e) {
      OneSignalIamApi.trackClick(e);
      OneSignalIamApi.openUrl(e, "https://shop.example.com/");
    });
  });
</script>
```

### Incorrecto: usar `<a>` o `window.open()`

```html HTML theme={null}
<a href="https://shop.example.com" target="_blank">
  Shop Now
</a>
```

Esta navegación ocurre fuera del entorno aislado dentro de la aplicación, impidiendo que OneSignal registre el evento de clic.

<Note>
  * Cada elemento clicable debe tener un `data-onesignal-unique-label` **único**.
  * Siempre llama a `OneSignalIamApi.trackClick(e)` **antes** de `openUrl()` o cualquier otro método de API de OneSignal.
  * Vincula detectores de eventos después de `DOMContentLoaded` para asegurar que los elementos existan.
  * OneSignal rastrea automáticamente clics solo para los métodos listados en esta referencia; cualquier navegación personalizada debe llamar `trackClick()` manualmente.
</Note>

### Problemas comunes

* **Clics no registrados:** No se llamó a `trackClick()` o al elemento le falta un `data-onesignal-unique-label`.
  * Llama a `trackClick(e)` y asegúrate de que cada elemento tenga una etiqueta única.
* **La consola muestra "Attempting to perform subframe navigation":**
  El código usa `window.open()` o un enlace `<a>` en lugar de `OneSignalIamApi.openUrl()`.
  * Usa `OneSignalIamApi.openUrl(e, "https://example.com/")` dentro del mismo manejador de clics.
* **Aparece la etiqueta incorrecta en los análisis:**
  Múltiples elementos comparten el mismo `data-onesignal-unique-label`.
  * Da a cada elemento clicable una etiqueta única.

***

## Funciones disponibles

Todas las [acciones de clic](./iam-click-actions) del [Editor de Bloques](./design-your-in-app-message) también están disponibles para mensajes HTML dentro de la aplicación.

### Solicitud de permiso de push

Muestra la solicitud de permiso de notificación push nativa. Los eventos de clic se rastrean automáticamente.

Ve [Solicitar permisos de push](./prompt-for-push-permissions).

```html HTML theme={null}
<button id="push-prompt-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Enable Push
</button>
<script>
  document.getElementById("push-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerPushPrompt(e);
  });
</script>
```

### Solicitud de permiso de ubicación

Muestra la solicitud de permiso de ubicación nativa. Los eventos de clic se rastrean automáticamente.

Ve [Solicitudes de permiso de ubicación](./location-opt-in-prompt).

```html HTML theme={null}
<button id="location-prompt-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Enable Location
</button>
<script>
  document.getElementById("location-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerLocationPrompt(e);
  });
</script>
```

### Cerrar mensaje dentro de la aplicación

Descarta el mensaje dentro de la aplicación actual. Los eventos de clic se rastrean automáticamente.

```html html theme={null}
<button id="close-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Close
</button>
<script>
  document.getElementById("close-button").addEventListener("click", function(e) {
    OneSignalIamApi.close(e);
  });
</script>
```

### Etiquetar usuario

Establece una [Etiqueta](./add-user-data-tags). Los eventos de clic se rastrean automáticamente.

```html HTML theme={null}
<button id="tag-user-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>
```

### Abrir URL

Abre una URL en el navegador del dispositivo y cierra el mensaje dentro de la aplicación. Los eventos de clic se rastrean automáticamente.

Soporta [Enlace Profundo](./deep-linking).

```html HTML theme={null}
<button id="open-url-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Visit Site
</button>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    OneSignalIamApi.openUrl(e, "https://example.com");
  });
</script>
```

### Nombre de clic

Asigna un nombre de clic que puede leerse en el [detector de clics de mensajes dentro de la aplicación](./mobile-sdk-reference#addclicklistener-in-app). Los eventos de clic se rastrean automáticamente.

Soporta [Enlace Profundo](./deep-linking).

```html HTML theme={null}
<button id="click-name-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Click Me
</button>
<script>
  document.getElementById("click-name-button").addEventListener("click", function(e) {
    OneSignalIamApi.addClickName(e, "test_click_name");
  });
</script>
```

### Rastrear clic

Rastrea un evento de clic cuando no estás usando otros métodos de API clicables.

```html HTML theme={null}
<button id="track-click-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Track Click
</button>
<script>
  document.getElementById("track-click-button").addEventListener("click", function(e) {
    OneSignalIamApi.trackClick(e);
  });
</script>
```

### Enviar Outcome

Rastrea un [Outcome Personalizado](./custom-outcomes) no atribuido y establece una [Etiqueta](./add-user-data-tags) en el usuario en el formato `nombre del outcome : true`. Los eventos de clic se rastrean automáticamente.

```html html theme={null}
<button id="send-outcome-button" data-onesignal-unique-label="your-unique-label-for-this-button">
  Claim Bonus
</button>
<script>
  document.getElementById("send-outcome-button").addEventListener("click", function(e) {
    OneSignalIamApi.sendOutcome(e, "bonus_claimed");
  });
</script>
```

***

## Personalizar mensajes HTML dentro de la aplicación

Puedes usar sustitución de etiquetas en mensajes HTML dentro de la aplicación al igual que en el Editor de Bloques.

<Warning> La sustitución de etiquetas **no funciona** dentro de etiquetas `<script>`. </Warning>

La sustitución de etiquetas funciona para:

* Texto en línea (`<h1>`, `<p>`, `<li>`, etc.)

* Reglas `<style>`:

  ```css CSS theme={null}
  body { background-color: "{{ favorite_color | default: '#fff' }}"; }
  ```

* Atributos con URLs:
  * `href`
  * `src`
  * `<form action>`
  * `<object data>`

### Usar etiquetas en `openUrl()` y `addClickName()`

Dado que las etiquetas `<script>` no soportan sustitución, usa uno de estos métodos:

**1. Acceder a todas las etiquetas con `liquidPlayerTags`**

Este objeto global se vuelve disponible después de `DOMContentLoaded`.

```html HTML theme={null}
<div class="my-tags">--test checking all tags--</div>
<button id="open-url-button" data-onesignal-unique-label="promo-link">
  Personalized Offer
</button>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    if (liquidPlayerTags) {
      document.querySelector(".my-tags").innerHTML = JSON.stringify(liquidPlayerTags);
    }
  });
  document.addEventListener("DOMContentLoaded", function() {
    document.getElementById("open-url-button").addEventListener("click", function(e) {
      OneSignalIamApi.openUrl(e, "https://shop.com?coupon=" + liquidPlayerTags["coupon"]);
    });
  });
</script>
```

**2. Almacenar una etiqueta en el atributo `href`**

```html HTML theme={null}
<a
  id="open-url-button"
  href="app://deeplink?code={{ coupon | default: '10OFF' }}"
  data-onesignal-unique-label="promo-link"
>
  Redeem Offer
</a>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    e.preventDefault();
    OneSignalIamApi.openUrl(e, e.currentTarget.href);
  });
</script>
```

***

## Próximos pasos

* Aprende más sobre [usar sintaxis liquid para sustitución de etiquetas](./using-liquid-syntax)
* Explora [Enlace Profundo](./deep-linking) para manejo de URLs
* [Diseñar mensajes dentro de la aplicación con HTML](./design-your-in-app-message-with-html)

***