Construir um carrossel de onboarding com botões

Visão geral

Este tutorial mostra como criar um carrossel de onboarding de várias etapas usando uma única Mensagem In-App HTML. Ao contrário dos carrosséis tradicionais que dependem de gestos de deslizar, esta abordagem usa navegação por botões e mantém todas as etapas dentro de uma única mensagem. O que você vai construir:

Um fluxo de onboarding de duas etapas com imagens, texto e botões
Navegação por botões (toque em “Próximo” para avançar, toque em “Começar” para fechar)
Pontos indicadores de progresso
Transições suaves de fade entre as etapas

Carrossel de onboarding mostrando tela de boas-vindas com imagem, texto e botão Próximo — Exemplo de carrossel de onboarding com navegação por botões

Use esta abordagem quando quiser:

Guiar os usuários através de um fluxo curto de onboarding ou educação (2-5 etapas)
Exigir que os usuários toquem explicitamente em um botão para continuar (sem gestos de deslizar)
Manter tudo dentro de uma única Mensagem In-App HTML para simplificar
Fechar a mensagem automaticamente quando o fluxo for concluído

Este guia usa uma Mensagem In-App HTML para controle total. Você também pode construir fluxos de onboarding baseados em cards com o editor de arrastar e soltar—esses cards são deslizáveis, mas oferecem menos personalização.

Pré-requisitos

Antes de começar, certifique-se de ter:

Um aplicativo OneSignal ativo com Mensagens In-App habilitadas
Permissão para criar ou editar Mensagens In-App HTML
Mobile SDK instalado em seu aplicativo móvel
Conhecimento básico de HTML, CSS e JavaScript

Como funciona o fluxo de várias etapas

Antes de mergulhar no código, é importante entender a abordagem técnica. Esta implementação usa uma única Mensagem In-App HTML que alterna entre etapas mostrando e ocultando conteúdo, não carregando múltiplas mensagens separadas. A arquitetura depende de quatro componentes principais:

Contêineres de card para cada etapa

Cada etapa é envolvida em um <div> com a classe card e um ID único:

<div id="card-0" class="card active">...</div>
<div id="card-1" class="card">...</div>

Todos os cards existem simultaneamente no DOM
Apenas um card é visível por vez (controlado pela classe active)

Controle de visibilidade CSS

O CSS lida com a lógica de mostrar/ocultar usando opacidade e eventos de ponteiro:

.card {
  opacity: 0;
  pointer-events: none;  /* Impede interação com cards ocultos */
  transition: opacity .25s ease;
}

.card.active {
  opacity: 1;
  pointer-events: auto;  /* Permite interação com card visível */
}

Por que isso importa:

opacity: 0 oculta o card visualmente, mas o mantém no layout
pointer-events: none impede cliques acidentais em cards ocultos
transition cria efeitos de fade suaves

Gerenciamento de estado JavaScript

A função setActive(i) controla qual card está visível:

function setActive(i) {
  // Atualizar visibilidade dos cards
  document.getElementById("card-0").className = i === 0 ? "card active" : "card";
  document.getElementById("card-1").className = i === 1 ? "card active" : "card";

  // Atualizar pontos de progresso
  var dots = document.getElementById("dots").children;
  dots[0].classList.toggle("active", i === 0);
  dots[1].classList.toggle("active", i === 1);
}

Esta função:

Remove active de todos os cards
Adiciona active ao card de destino
Atualiza os pontos indicadores de progresso

Listeners de eventos dos botões

Os botões disparam navegação ou fechamento:

// Avançar para próxima etapa
document.getElementById("next-0").addEventListener("click", function () {
  setActive(1);
});

// Fechar a Mensagem In-App
document.getElementById("done").addEventListener("click", function (e) {
  if (window.OneSignalIamApi && OneSignalIamApi.close) {
    OneSignalIamApi.close(e);
  }
});

Importante: OneSignalIamApi.close(e) é o método do SDK OneSignal que fecha a Mensagem In-App de dentro do HTML.

Ponto-chave: Este é um padrão de aplicação de página única (SPA) dentro de uma Mensagem In-App. Todo o conteúdo é carregado uma vez, e o JavaScript gerencia as mudanças de estado sem recarregar.

Etapa 1: Criar uma nova Mensagem In-App HTML

No painel do OneSignal, vá para Messages → In-App Messages
Clique em New In-App Message
Selecione HTML como tipo de mensagem
Escolha o layout Full Screen ou Large (recomendado para onboarding para maximizar o impacto visual)
Continue para o editor HTML

A visualização do editor HTML pode não refletir totalmente o comportamento em tempo de execução. Sempre teste em um dispositivo real ou usuário de teste para verificar animações, comportamento dos botões e a ação de fechar.

Etapa 2: Adicionar o template HTML

Substitua o conteúdo do editor pelo template abaixo. Este template inclui:

Código autocontido: Todo HTML, CSS e JavaScript em um arquivo
Navegação por botões: Sem gestos de deslizar (mais confiável em diferentes dispositivos)
Transições de fade: Mudanças suaves de opacidade entre etapas
Integração com SDK OneSignal: Usa OneSignalIamApi.close(e) para fechar a mensagem
Otimizado para mobile: Layout responsivo com meta tag viewport

Ver template HTML completo

<!doctype html>
<html>
<head>
  <meta charset="UTF-8" />
  <!-- viewport-fit=cover garante cobertura da área segura em dispositivos com notch -->
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
  <style>
    /* Estilos base - reset e fonte do sistema */
    html, body {
      margin: 0;
      padding: 0;
      background: #ffffff;
      font-family: -apple-system, system-ui;
    }

    /* Contêiner principal com padding */
    .wrap {
      padding: 28px 22px 24px;
    }

    /* Contêiner de palco - mantém todos os cards na mesma posição */
    .stage {
      position: relative;
      min-height: 74vh;  /* Garante espaço vertical suficiente */
    }

    /* Card - cada etapa do fluxo de onboarding */
    .card {
      position: absolute;  /* Todos os cards se sobrepõem na mesma posição */
      inset: 0;            /* Cobertura total do palco */
      display: flex;
      flex-direction: column;
      align-items: center;
      opacity: 0;               /* Oculto por padrão */
      pointer-events: none;     /* Impede cliques quando oculto */
      transition: opacity .25s ease;  /* Efeito de fade suave */
    }

    /* Card ativo é visível e interativo */
    .card.active {
      opacity: 1;
      pointer-events: auto;
    }

    /* Tipografia */
    h1 {
      margin: 44px 0 12px;
      font-size: 26px;
      text-align: center;
    }

    p {
      margin: 0;
      color: #6b7280;
      text-align: center;
      max-width: 260px;
      line-height: 1.35;
    }

    /* Contêiner de imagem - quadrado com cantos arredondados */
    .image {
      width: 240px;
      height: 240px;
      border-radius: 16px;
      margin: 24px 0 12px;
      background-size: cover;
      background-position: center;
    }

    /* Botão principal */
    .btn {
      margin-top: auto;  /* Empurra o botão para o final do card */
      width: 100%;
      max-width: 260px;
      height: 52px;
      border: 0;
      border-radius: 12px;
      background: #3b82f6;  /* Azul - personalize para sua marca */
      color: #fff;
      font-size: 18px;
      font-weight: 600;
    }

    /* Pontos indicadores de progresso */
    .dots {
      display: flex;
      justify-content: center;
      gap: 8px;
      padding: 12px 0 8px;
    }

    .dot {
      width: 8px;
      height: 8px;
      border-radius: 999px;
      background: #d1d5db;  /* Cor do ponto inativo */
    }

    .dot.active {
      background: #6b7280;  /* Cor do ponto ativo */
      transform: scale(1.15);  /* Ligeiramente maior quando ativo */
    }
  </style>
</head>

<body>
  <div class="wrap">
    <div class="stage">

      <!-- ETAPA 1: Card de boas-vindas (começa visível com classe "active") -->
      <div id="card-0" class="card active">
        <h1>Bem-vindo</h1>
        <div
          class="image"
          style="background-image: url('https://images.pexels.com/photos/6153129/pexels-photo-6153129.jpeg');">
        </div>
        <p>Construa um hábito diário tranquilo em minutos.</p>
        <button
          id="next-0"
          class="btn"
          data-onesignal-unique-label="onboarding_next_0">
          Próximo
        </button>
      </div>

      <!-- ETAPA 2: Card de respiração (começa oculto, aparece quando usuário toca em "Próximo") -->
      <div id="card-1" class="card">
        <h1>Respire</h1>
        <div
          class="image"
          style="background-image: url('https://images.pexels.com/photos/417173/pexels-photo-417173.jpeg');">
        </div>
        <p>Respiração guiada sempre que você precisar de um reset.</p>
        <button
          id="done"
          class="btn"
          data-onesignal-unique-label="onboarding_done">
          Começar
        </button>
      </div>

    </div>

    <!-- Indicador de progresso: 2 pontos, primeiro começa ativo -->
    <div class="dots" id="dots">
      <div class="dot active"></div>
      <div class="dot"></div>
    </div>
  </div>

  <script>
    (function () {
      /**
       * Alternar entre cards usando a classe "active"
       * @param {number} i - Índice do card a exibir (0 ou 1)
       */
      function setActive(i) {
        // Atualizar visibilidade dos cards
        document.getElementById("card-0").className = i === 0 ? "card active" : "card";
        document.getElementById("card-1").className = i === 1 ? "card active" : "card";

        // Atualizar pontos de progresso
        var dots = document.getElementById("dots").children;
        dots[0].classList.toggle("active", i === 0);
        dots[1].classList.toggle("active", i === 1);
      }

      // Botão: Próximo (card 0 → card 1)
      document.getElementById("next-0").addEventListener("click", function () {
        setActive(1);
      });

      // Botão: Começar (fecha a Mensagem In-App)
      document.getElementById("done").addEventListener("click", function (e) {
        // Verificar se a API IAM do OneSignal está disponível
        if (window.OneSignalIamApi && OneSignalIamApi.close) {
          OneSignalIamApi.close(e);  // Fechar a mensagem
        }
      });
    })();
  </script>
</body>
</html>

Etapa 3: Personalizar seu conteúdo

Seguro para personalizar

Você pode modificar estes elementos sem quebrar a funcionalidade: Conteúdo:

Texto do título nas tags <h1>
Texto do corpo nas tags <p>
Rótulos dos botões (Próximo, Começar)
URLs de imagens nos estilos background-image: url('...')

Estilo visual:

Cores: Altere o fundo do .btn, cor do texto ou cores dos pontos
Espaçamento: Ajuste padding e margens
Tipografia: Modifique font-family, font-size, font-weight
Raio de borda: Atualize valores de border-radius para botões e imagens

Adicionar mais etapas

Para adicionar uma terceira etapa, siga este padrão:

Adicionar o card HTML:

<div id="card-2" class="card">
  <h1>Seu Título</h1>
  <div class="image" style="background-image: url('sua-url-de-imagem');"></div>
  <p>Sua descrição</p>
  <button id="next-2" class="btn">Próximo</button>
</div>

Adicionar um ponto de progresso:

<div class="dots" id="dots">
  <div class="dot active"></div>
  <div class="dot"></div>
  <div class="dot"></div> <!-- Novo ponto -->
</div>

Atualizar a função setActive():

function setActive(i) {
  document.getElementById("card-0").className = i === 0 ? "card active" : "card";
  document.getElementById("card-1").className = i === 1 ? "card active" : "card";
  document.getElementById("card-2").className = i === 2 ? "card active" : "card"; // Novo card

  var dots = document.getElementById("dots").children;
  dots[0].classList.toggle("active", i === 0);
  dots[1].classList.toggle("active", i === 1);
  dots[2].classList.toggle("active", i === 2); // Novo ponto
}

Atualizar o ID do botão da etapa anterior: Altere id="done" para id="next-1" no botão do card 1, então adicione um listener de clique:

document.getElementById("next-1").addEventListener("click", function () {
  setActive(2);
});

Adicionar o botão de fechar ao novo último card (card-2):

document.getElementById("done").addEventListener("click", function (e) {
  if (window.OneSignalIamApi && OneSignalIamApi.close) {
    OneSignalIamApi.close(e);
  }
});

Mantenha os fluxos de onboarding curtos (máximo de 2-4 etapas). Os usuários desistem rapidamente em fluxos mais longos. Teste as taxas de conclusão com rastreamento de cliques.

Etapa 4: Testar a Mensagem In-App

Lista de verificação de testes

Salve a mensagem no painel do OneSignal
Configure os ajustes de entrega:
- Defina condições de gatilho (ex.: início de sessão, visualização de página específica)
- Escolha seu público-alvo ou selecione um usuário de teste
Envie para um dispositivo de teste:
- Use Usuários de Teste para visualizar sem afetar usuários de produção
- Instale seu app em um dispositivo físico (recomendado em vez de simuladores para comportamento preciso)
Verifique a funcionalidade:
- ✓ O primeiro card aparece com o conteúdo correto
- ✓ O botão “Próximo” avança para o card 2
- ✓ Os pontos de progresso atualizam corretamente
- ✓ As transições de fade são suaves
- ✓ O botão “Começar” fecha a mensagem
- ✓ A mensagem não reaparece imediatamente (verifique as configurações de limite de frequência)

Simuladores/emuladores podem não refletir com precisão o comportamento do dispositivo real, especialmente para interações de toque e integrações de SDK. Sempre teste em dispositivos físicos antes de lançar em produção.

Resolução de problemas comuns

Problema	Causa provável	Solução
Mensagem não aparece	Condições de gatilho não atendidas	Verifique os Gatilhos de Mensagens In-App e confirme que seu usuário de teste atende aos critérios
Botões não funcionam	Erros de JavaScript ou incompatibilidade de ID	Verifique o console do navegador por erros; confirme que os IDs dos botões correspondem aos IDs dos listeners de eventos
Imagens não carregam	Problemas de CORS ou URLs inválidas	Use URLs HTTPS; teste as URLs das imagens em um navegador primeiro
Mensagem aparece mas não fecha	SDK do OneSignal não carregado	Verifique se a configuração do Mobile SDK está completa

Próximos passos

Rastrear engajamento dos usuários:

Adicione rastreamento de cliques usando atributos data-onesignal-unique-label (já incluídos no template) para medir desistência entre etapas
Veja análises de cliques em Messages → In-App Messages → [Sua Mensagem] → Analytics

Personalizar a experiência:

Marque usuários que completam o onboarding (ex.: onboarding_completed: true)
Use tags para segmentar usuários e evitar reexibir o fluxo de onboarding
Adicione dados de usuário para personalizar conteúdo em mensagens futuras

Personalização avançada:

Deep link usuários para uma tela específica após o fechamento
Use sintaxe Liquid para personalizar títulos com nomes de usuários ou atributos
Implemente testes A/B com diferentes fluxos de onboarding para otimizar taxas de conclusão

Tutoriais

Por setor

Aumentar a engajamento e a retenção

Entregar mensagens críticas ou de alta prioridade

Aprimorar o targeting e a personalização

Aprimorar a experiência do usuário e o onboarding

Construir um carrossel de onboarding com botões

Visão geral

Pré-requisitos

Como funciona o fluxo de várias etapas

Etapa 1: Criar uma nova Mensagem In-App HTML

Etapa 2: Adicionar o template HTML

Etapa 3: Personalizar seu conteúdo

Seguro para personalizar

Adicionar mais etapas

Etapa 4: Testar a Mensagem In-App

Lista de verificação de testes

Resolução de problemas comuns

Próximos passos

​Visão geral

​Pré-requisitos

​Como funciona o fluxo de várias etapas

​Etapa 1: Criar uma nova Mensagem In-App HTML

​Etapa 2: Adicionar o template HTML

​Etapa 3: Personalizar seu conteúdo

​Seguro para personalizar

​Adicionar mais etapas

​Etapa 4: Testar a Mensagem In-App

​Lista de verificação de testes

​Resolução de problemas comuns

​Próximos passos

Visão geral

Pré-requisitos

Como funciona o fluxo de várias etapas

Etapa 1: Criar uma nova Mensagem In-App HTML

Etapa 2: Adicionar o template HTML

Etapa 3: Personalizar seu conteúdo

Seguro para personalizar

Adicionar mais etapas

Etapa 4: Testar a Mensagem In-App

Lista de verificação de testes

Resolução de problemas comuns

Próximos passos