> ## 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.

# Referência da API JavaScript de mensagens no aplicativo

> Métodos JavaScript para mensagens HTML interativas no aplicativo no OneSignal.

Este guia cobre a **API JavaScript** para mensagens HTML no aplicativo criadas com o [Editor HTML do OneSignal](./design-your-in-app-message-with-html).

Se você está procurando **métodos SDK** para definir gatilhos, lidar com eventos de clique no aplicativo ou gerenciar o ciclo de vida no aplicativo, veja a [Referência do SDK Móvel](./mobile-sdk-reference#in-app-messages).

***

## Requisitos

### 1. Use `data-onesignal-unique-label` para rastreamento de cliques

Todos os elementos clicáveis devem ter um atributo `data-onesignal-unique-label` com um valor **único**. Isso permite que o OneSignal:

* Rastreie análises de clique
* Acione corretamente as ações associadas

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

<Warning> Se dois elementos compartilharem o mesmo `data-onesignal-unique-label`, os cliques podem ser registrados incorretamente ou as ações podem não ser acionadas. </Warning>

### 2. Anexar event listeners

Você deve anexar explicitamente event listeners JavaScript para acionar ações no aplicativo do OneSignal.

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

**Exemplo:**

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

***

## Funções disponíveis

Todas as [ações de clique](./iam-click-actions) do [Editor de Blocos](./design-your-in-app-message) também estão disponíveis para mensagens HTML no aplicativo.

### Prompt de permissão push

Mostra o prompt de permissão de notificação push nativo. Eventos de clique são rastreados automaticamente.

Veja [Prompt para permissões push](./prompt-for-push-permissions).

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

### Prompt de permissão de localização

Mostra o prompt de permissão de localização nativo. Eventos de clique são rastreados automaticamente.

Veja [Prompts de permissão de localização](./location-opt-in-prompt).

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

### Fechar mensagem no aplicativo

Dispensa a mensagem no aplicativo atual. Eventos de clique são rastreados automaticamente.

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

### Marcar usuário com tag

Define uma [Tag](./add-user-data-tags). Eventos de clique são rastreados automaticamente.

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

### Abrir URL

Abre uma URL no navegador do dispositivo e fecha a mensagem no aplicativo. Eventos de clique são rastreados automaticamente.

Suporta [Deep Linking](./deep-linking).

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

### Nome do clique

Atribui um nome de clique que pode ser lido no [listener de clique de mensagem no aplicativo](./mobile-sdk-reference#addclicklistener-in-app). Eventos de clique são rastreados automaticamente.

Suporta [Deep Linking](./deep-linking).

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

### Rastrear clique

Rastreia um evento de clique quando você não está usando outros métodos de API clicáveis.

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

### Enviar Outcome

Rastreia um [Custom Outcome](./custom-outcomes) não atribuído e define uma [Tag](./add-user-data-tags) no usuário no formato `outcome name : true`. Eventos de clique são rastreados automaticamente.

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

***

## Personalizar mensagens HTML no aplicativo

Você pode usar substituição de tags em mensagens HTML no aplicativo assim como no Editor de Blocos.

<Warning> A substituição de tags **não funciona** dentro de tags `<script>`. </Warning>

A substituição de tags funciona para:

* Texto inline (`<h1>`, `<p>`, `<li>`, etc.)
* Regras `<style>`:
  ```css CSS theme={null}
  body { background-color: "{{ favorite_color | default: '#fff' }}"; }
  ```
* Atributos com URLs:
  * `href`
  * `src`
  * `<form action>`
  * `<object data>`

### Usando tags em `openUrl()` e `addClickName()`

Como tags `<script>` não suportam substituição, use um destes métodos:

**1. Acesse todas as tags com `liquidPlayerTags`**

Este objeto global fica disponível após `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) {
      // liquidPlayerTags becomes available afterthe DOMContentLoaded event confirm
      // by checking that the div with --replace with all tags-- is replaced with JSON
      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. Armazene uma tag no 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 passos

* Saiba mais sobre [usar sintaxe liquid para substituição de tags](./using-liquid-syntax)
* Explore [Deep Linking](./deep-linking) para manipulação de URLs
* [Projete mensagens no aplicativo com HTML](./design-your-in-app-message-with-html)

***