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

# Aplicativo de exemplo: mensagens in-app

> Como o aplicativo de exemplo Clean Beans usa gatilhos de mensagens in-app e HTML personalizado para sobreposições de ajuda, uma pré-solicitação de permissão e avisos de atualização e avaliação.

Esta página faz parte de [Aplicativo de exemplo: uma integração completa do OneSignal](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-overview.md), que acompanha um aplicativo real do início ao fim. O aplicativo é o **Clean Beans**, uma escala de limpeza para casas compartilhadas, construído com Expo (React Native) e um backend Supabase.

As mensagens in-app aparecem enquanto alguém usa o aplicativo. O conteúdo, o público e o agendamento delas ficam no painel do OneSignal, então podem mudar sem uma nova versão. O Clean Beans as usa para cinco tarefas.

| Mensagem | Exibida quando | Como é direcionada |
| - | - | - |
| Sobreposições de ajuda | O usuário toca no botão de ajuda de uma tela | Um gatilho definido pelo aplicativo |
| Tutoriais guiados | O usuário precisa de um tour guiado por uma tela | O mesmo gatilho |
| Pré-solicitação de permissão de push | Antes do diálogo de permissão do sistema | Público e agendamento no painel |
| Aviso de atualização do aplicativo | O usuário está em uma versão antiga | Um segmento |
| Pedido de avaliação | O usuário atinge um marco de sequência | Um gatilho definido pelo aplicativo |

## Gatilhos: deixe o aplicativo decidir o momento \\

Um gatilho é uma chave e um valor que o aplicativo define. Qualquer mensagem in-app configurada para corresponder a ele é exibida. Toda tela do Clean Beans tem um botão de ajuda no cabeçalho que define um gatilho, com o nome da tela como valor.

```typescript src/components/HelpButton.tsx theme={null}
export function HelpButton({ triggerValue }: HelpButtonProps) {
  const handlePress = () => {
    OneSignal.InAppMessages.addTrigger('help_topic', triggerValue);
  };

  return (
    <TouchableOpacity onPress={handlePress} style={styles.button} hitSlop={8}>
      <Ionicons name="help-circle-outline" size={26} color={Colors.white} />
    </TouchableOpacity>
  );
}
```

```typescript app/(tabs)/_layout.tsx theme={null}
<Tabs.Screen
  name="index"
  options={{
    title: 'Dashboard',
    headerRight: () => <HeaderRight helpTopic="dashboard" />,
    tabBarIcon: ({ focused }) => <TabIcon name={focused ? 'home' : 'home-outline'} focused={focused} />,
  }}
/>
```

Uma única chave de gatilho atende treze telas. Adicionar ajuda para uma nova tela significa adicionar um botão com um novo valor e criar uma mensagem no painel.

![Uma mensagem in-app de sobreposição de ajuda exibida sobre o painel](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-help.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=521ce92f66d1df24e99790600813523a)

Tocar no botão de ajuda no painel mostra uma sobreposição de ajuda.

**Configuração do painel.** Em **Messages > In-App**, crie uma mensagem cujo gatilho seja `help_topic` **is** `dashboard` e repita para cada tela. Tutoriais guiados com várias etapas usam o mesmo gatilho com um layout de carrossel.

![Uma mensagem in-app de tutorial guiado formada por cards deslizáveis](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-walkthrough.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=c335375ee2bb79060e97aa945dea644e)

Um tutorial guiado com várias etapas criado como um carrossel de cards.

## Mensagens com HTML personalizado \\

As sobreposições de ajuda são escritas em HTML, então combinam exatamente com o design do aplicativo. Uma mensagem in-app em HTML se comunica com o SDK por meio do objeto `OneSignalIamApi`. Duas regras se aplicam a todo elemento clicável:

* Dê a ele um `data-onesignal-unique-label` exclusivo, para que os cliques sejam rastreados corretamente.
* Associe um listener que chame um método de `OneSignalIamApi`. Links simples não são rastreados.

```html docs/iam-html/help-dashboard.html theme={null}
<button id="got-it" class="cta-btn" data-onesignal-unique-label="dashboard-got-it">Got it</button>

<script>
  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("got-it").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

## Pré-solicitação de permissão de push \\

O diálogo de permissão do sistema só pode ser exibido uma vez. Uma mensagem in-app exibida antes pode explicar o que o usuário vai receber, e apenas quem toca em **Enable notifications** vê o diálogo do sistema.

![Uma mensagem in-app explicando os benefícios de ativar as notificações](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-push-prompt.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=18791e9af52a803d41048eba393109f6)

Uma pré-solicitação explica o benefício antes de o diálogo do sistema aparecer.

```html docs/iam-html/push-permission-prompt.html theme={null}
<script>
  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("enable-btn").addEventListener("click", function (e) {
      OneSignalIamApi.triggerPushPrompt(e);
    });
    document.getElementById("skip-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

> [!NOTE]
>
> Se você usar uma pré-solicitação, remova a chamada `requestPermission()` da inicialização do aplicativo. Caso contrário, o diálogo do sistema aparece primeiro e a pré-solicitação não tem mais nada a pedir.

## Aviso de atualização do aplicativo \\

Quando uma nova versão é lançada, quem está na versão antiga vê um aviso para atualizar. Essa mensagem não precisa de nenhum código no aplicativo. O público dela é um segmento de usuários em uma versão mais antiga do aplicativo.

![Uma mensagem in-app pedindo ao usuário que atualize o aplicativo](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-iam-app-version.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=f096ce85f566823331171e14312e534d)

O aviso de atualização, exibido apenas para quem está em uma versão mais antiga.

Uma única mensagem atende as duas plataformas. O script escolhe a loja de acordo com o dispositivo, e `openUrl` rastreia o clique, abre a loja e fecha a mensagem.

```html docs/iam-html/app-update-prompt.html theme={null}
<script>
  var IOS_URL = "https://apps.apple.com/app/id" + IOS_APP_STORE_ID;
  var ANDROID_URL = "https://play.google.com/store/apps/details?id=" + ANDROID_PACKAGE;

  // One message serves both platforms: pick the store from the device.
  var isAndroid = /android/i.test(navigator.userAgent);
  var storeUrl = isAndroid ? ANDROID_URL : IOS_URL;

  document.addEventListener("DOMContentLoaded", function () {
    document.getElementById("update-btn").addEventListener("click", function (e) {
      // openUrl tracks the click, opens the store and closes the message
      OneSignalIamApi.openUrl(e, storeUrl);
    });
    document.getElementById("later-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

A saudação usa uma tag, com um valor alternativo para usuários que não a têm.

```html docs/iam-html/app-update-prompt.html theme={null}
<p>Hey {{ user_name | default: "there" }}, you're on an older version</p>
```

**Configuração do painel.** Crie um segmento com o filtro **App version** menor que a sua versão atual e use-o como público da mensagem. Atualize o filtro a cada lançamento.

> [!NOTE]
>
> A substituição de tags funciona no texto e nos atributos de uma mensagem in-app em HTML, mas não dentro das tags `script`.

## Pedido de avaliação: devolver um clique ao aplicativo \\

Um bom momento para pedir uma avaliação na loja de aplicativos é logo depois de algo dar certo. O Clean Beans pede quando uma sessão de limpeza leva uma sequência a um múltiplo de sete dias.

Esta é a única mensagem in-app em que um toque precisa executar código no aplicativo, porque a tela de avaliação nativa só pode ser aberta pelo próprio aplicativo.

**1. O aplicativo define um gatilho em um marco de sequência**

Ele espera até a tela da sessão fechar, para que o aviso nunca interrompa a limpeza, e lembra o último marco em que pediu.

```typescript src/lib/reviewPrompt.ts theme={null}
export async function maybeAskForReview(streak: number): Promise<void> {
  try {
    if (streak <= 0 || streak % STREAK_MILESTONE_DAYS !== 0) return;

    // A second session on the same day leaves the streak unchanged —
    // don't ask twice for the same milestone.
    const lastPrompted = await AsyncStorage.getItem(LAST_PROMPTED_STREAK_KEY);
    if (lastPrompted === String(streak)) return;
    await AsyncStorage.setItem(LAST_PROMPTED_STREAK_KEY, String(streak));

    OneSignal.InAppMessages.addTrigger(REVIEW_TRIGGER_KEY, REVIEW_TRIGGER_VALUE);
    console.log('[reviewPrompt] Trigger set at streak', streak);
  } catch (e) {
    console.warn('[reviewPrompt] maybeAskForReview error:', e);
  }
}
```

**2. A mensagem envia um nome de clique de volta ao aplicativo**

`addClickName` passa um nome para o listener de clique do aplicativo. Ele não fecha a mensagem, então o script a fecha logo em seguida.

```html docs/iam-html/review-prompt.html theme={null}
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var autoCloseBtn = document.getElementById("auto-close-btn");

    document.getElementById("rate-btn").addEventListener("click", function (e) {
      // Passes the click name "review" to the app's In-App Message click
      // listener, which opens the native rating sheet. addClickName does not
      // close the message, so close it straight afterwards.
      OneSignalIamApi.addClickName(e, "review");
      setTimeout(function () { autoCloseBtn.click(); }, 300);
    });
    autoCloseBtn.addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
    document.getElementById("later-btn").addEventListener("click", function (e) {
      OneSignalIamApi.close(e);
    });
  });
</script>
```

**3. O aplicativo abre a tela de avaliação nativa**

O listener de clique verifica o nome e pede ao sistema que mostre a tela.

```typescript src/lib/reviewPrompt.ts theme={null}
export function handleReviewClick(event: InAppMessageClickEvent): void {
  if (event.result.actionId !== REVIEW_ACTION_ID) return;

  // Give the In-App Message a moment to close before presenting the sheet
  setTimeout(async () => {
    try {
      // false on TestFlight builds and on the web
      if (await StoreReview.isAvailableAsync()) {
        await StoreReview.requestReview();
      } else {
        console.log('[reviewPrompt] Store review not available on this build');
      }
    } catch (e) {
      console.warn('[reviewPrompt] requestReview error:', e);
    } finally {
      // Clear the trigger so the message is not re-evaluated this app session
      OneSignal.InAppMessages.removeTrigger(REVIEW_TRIGGER_KEY);
    }
  }, 800);
}
```

```typescript app/_layout.tsx theme={null}
OneSignal.InAppMessages.addEventListener('click', handleReviewClick);
```

![Uma mensagem in-app de pedido de avaliação](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-review-prompt.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=90dde058450240f49d42e76402ed28ce)

A mensagem in-app de pedido de avaliação.

**Configuração do painel.** Crie uma mensagem in-app em HTML com o gatilho `ask_for_review` **is** `show`. Agende-a para ser exibida no máximo uma vez a cada 17 semanas.

> [!WARNING]
>
> A Apple mostra a tela de avaliação no máximo três vezes por usuário em um ano, e o Google tem seu próprio limite, então tocar no botão não garante que algo seja exibido. A tela nunca aparece em compilações do TestFlight. Teste esse fluxo com uma compilação da App Store.

> [card] [Gatilhos in-app](https://documentation.onesignal.com/docs/pt-BR/iam-triggers.md)
>
> Tipos de gatilhos e como se combinam.

> [card] [Mensagens in-app em HTML](https://documentation.onesignal.com/docs/pt-BR/design-your-in-app-message-with-html.md)
>
> Crie mensagens com seu próprio HTML.

> [card] [API JavaScript in-app](https://documentation.onesignal.com/docs/pt-BR/in-app-message-api.md)
>
> Todos os métodos de `OneSignalIamApi`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.