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

# Criando Componentes

> Guia completo para criar e configurar componentes visuais na UserIn: cards, modais, smart blocks e mini games.

**Nesta página:**

* [O que são componentes](#o-que-são-componentes)
* [Quando usar cada tipo](#quando-usar-cada-tipo)
* [Estrutura de um componente](#estrutura-de-um-componente)
* [Controle quem vê cada componente](#controle-quem-vê-cada-componente)
* [Defina quando e quantas vezes exibir](#defina-quando-e-quantas-vezes-exibir)
* [Conecte componentes às suas automações](#conecte-componentes-às-suas-automações)
* [Teste antes de publicar](#teste-antes-de-publicar)
* [Boas práticas para componentes eficazes](#boas-práticas-para-componentes-eficazes)

***

## O que são componentes

Componentes são **elementos visuais interativos** que a UserIn injeta diretamente no seu site para engajar visitantes em tempo real. Diferente de conteúdo estático, cada componente se adapta ao perfil e ao comportamento do visitante, exibindo a mensagem certa para a pessoa certa no momento certo.

A plataforma organiza componentes em quatro tipos, cada um projetado para um contexto de interação diferente:

| Tipo             | Formato                                          | Exemplo de uso                               |
| ---------------- | ------------------------------------------------ | -------------------------------------------- |
| **Cards**        | Elementos visuais compactos, fixos ou flutuantes | Destaques, promoções, CTAs contextuais       |
| **Modais**       | Janelas sobrepostas ao conteúdo da página        | Ofertas, captação de leads, comunicados      |
| **Smart Blocks** | Blocos embutidos diretamente na página           | Banners personalizados, recomendações inline |
| **Mini Games**   | Mecânicas interativas de gamificação             | Engajamento, recompensas, retenção           |

<div className="callout-blue">
  Componentes são sempre acionados via **Construtor de Fluxos** ou **regras da plataforma**. Isso garante que você controle a segmentação, frequência e prioridade de cada exibição com base em dados reais do visitante.
</div>

***

## Quando usar cada tipo

Escolher o componente certo depende do objetivo da interação e do contexto em que o visitante se encontra. Abaixo, cada tipo com seus cenários ideais.

<AccordionGroup>
  <Accordion title="Cards" icon="cards-blank" defaultOpen>
    Cards são componentes visuais compactos que aparecem no site do visitante em formato de cartão. Podem ser fixos em uma posição da página ou flutuantes (acompanhando o scroll).

    **Cenários ideais:**

    * Destacar uma oferta ou promoção contextual sem interromper a navegação
    * Exibir CTAs personalizados em áreas estratégicas da página
    * Mostrar notificações ou alertas visuais com base no comportamento
    * Recomendar conteúdo ou produtos de forma discreta

    Cards funcionam bem quando você quer chamar a atenção do visitante **sem bloquear a experiência**. O formato compacto mantém a navegação fluida.

    [Guia completo de Cards →](/componentes/cards)
  </Accordion>

  <Accordion title="Modais" icon="window-maximize">
    Modais são janelas sobrepostas que aparecem sobre o conteúdo da página. São o formato mais direto de comunicação: capturam a atenção total do visitante por alguns segundos.

    **Cenários ideais:**

    * Ofertas de conversão com senso de urgência (ex: desconto por tempo limitado)
    * Captação de leads com formulário (email, telefone)
    * Comunicados importantes que precisam de confirmação
    * Intervenção em momentos de intenção de saída (exit intent)
    * Boas-vindas personalizadas para novos visitantes

    Modais têm alto impacto, mas precisam de controle de frequência para não se tornarem intrusivos.

    [Guia completo de Modais →](/componentes/modais)
  </Accordion>

  <Accordion title="Smart Blocks" icon="puzzle-piece">
    Smart Blocks são blocos de conteúdo embutidos diretamente na estrutura da página. Eles se integram ao layout existente, ocupando um espaço pré-definido no HTML do site.

    **Cenários ideais:**

    * Banners personalizados que mudam de acordo com o perfil do visitante
    * Recomendações inline dentro de páginas de conteúdo ou produto
    * CTAs contextuais que se adaptam ao estágio do funil
    * Seções dinâmicas que mudam com base em segmentos

    Smart Blocks são a opção mais discreta: o visitante vê conteúdo personalizado sem perceber que é um elemento dinâmico.

    [Guia completo de Smart Blocks →](/componentes/smart-blocks)
  </Accordion>

  <Accordion title="Mini Games" icon="dice">
    Mini Games são mecânicas interativas de gamificação que transformam a experiência do visitante em algo divertido e recompensador. A plataforma oferece seis formatos prontos:

    * **Roleta de prêmios**: o visitante gira a roleta para revelar recompensas
    * **Raspadinha**: revela ofertas ao "raspar" a tela
    * **Flip Card**: cartas que o visitante vira para descobrir o prêmio
    * **Gift Box**: caixas surpresa com animação de abertura
    * **Prize Drop**: mecânica estilo plinko onde o prêmio cai por obstáculos
    * **Slot Machine**: colunas giratórias que sorteiam combinações

    **Cenários ideais:**

    * Aumentar tempo de permanência e engajamento no site
    * Captar leads oferecendo recompensas em troca de dados
    * Reativar visitantes inativos com mecânicas lúdicas
    * Criar campanhas promocionais com alto fator de viralização

    [Guia completo de Mini Games →](/componentes/mini-games)
  </Accordion>
</AccordionGroup>

***

## Estrutura de um componente

Todo componente na UserIn, independentemente do tipo, compartilha uma estrutura base com propriedades comuns. Entender essa estrutura facilita a criação de qualquer componente.

| Propriedade     | Descrição                             | Exemplo                                       |
| --------------- | ------------------------------------- | --------------------------------------------- |
| **Nome**        | Identificador interno do componente   | "Banner Black Friday VIP"                     |
| **Tipo**        | Categoria do componente               | Card, Modal, Smart Block ou Mini Game         |
| **Conteúdo**    | O que o visitante vê (visual + texto) | Template pré-definido ou HTML/CSS customizado |
| **Segmentação** | Quem pode ver o componente            | Visitantes do segmento "alta intenção"        |
| **Gatilho**     | Evento que aciona a exibição          | Entrada em segmento, scroll, tempo na página  |
| **Frequência**  | Quantas vezes o visitante vê          | Uma vez por sessão, máximo 3 vezes no total   |
| **Status**      | Estado atual do componente            | Rascunho, Ativo ou Pausado                    |

<Tip>
  Nomeie seus componentes com um padrão claro. Uma boa prática: **\[Tipo] - \[Objetivo] - \[Audiência]**. Exemplo: "Modal - Oferta 20% - Novos Visitantes". Isso facilita encontrar e gerenciar componentes quando a lista cresce.
</Tip>

Cada tipo de componente adiciona propriedades específicas sobre essa base. Cards incluem configuração de posição, Modais incluem tipo de overlay, Smart Blocks incluem o seletor CSS do container, e Mini Games incluem mecânica e configuração de prêmios. Consulte o guia específico de cada tipo para detalhes.

***

## Controle quem vê cada componente

A segmentação determina **quem** é elegível para ver o componente. Você combina critérios para garantir que cada visitante receba a experiência mais relevante.

### Segmentação por segmentos

A forma mais comum de segmentar componentes é usar os **segmentos dinâmicos** que você já criou na plataforma. O componente só aparece para visitantes que pertencem ao segmento selecionado.

Exemplos práticos de segmentação:

| Segmento                             | Componente sugerido        | Objetivo                       |
| ------------------------------------ | -------------------------- | ------------------------------ |
| Novos visitantes (primeira sessão)   | Modal de boas-vindas       | Captação de lead               |
| Visitantes recorrentes sem conversão | Card com oferta            | Incentivo à primeira conversão |
| Clientes inativos há 30+ dias        | Mini Game com recompensa   | Reativação                     |
| Visitantes de alta intenção          | Smart Block com CTA direto | Aceleração de conversão        |

### Segmentação por atributos

Além de segmentos, você pode usar **atributos individuais** do perfil do visitante como critério. Isso permite condições mais granulares:

* `deposits.total > 1000` para exibir componentes exclusivos para clientes de alto valor
* `contact.email != null` para filtrar apenas visitantes identificados
* `behavior.sessionsPerWeek >= 3` para alcançar visitantes engajados

### Combinando condições

Condições podem ser empilhadas com operadores lógicos para criar segmentações precisas:

* **E (AND)**: o visitante deve atender a **todas** as condições simultaneamente
* **OU (OR)**: basta atender a **pelo menos uma** das condições

```
Segmento = "alta intenção"
E atributo deposits.total > 500
E atributo behavior.sessionsPerWeek >= 2
```

Neste exemplo, o componente só aparece para visitantes que pertencem ao segmento "alta intenção", já gastaram mais de R\$ 500 e acessam o site pelo menos 2 vezes por semana.

***

## Defina quando e quantas vezes exibir

Além de controlar **quem** vê, você controla **quando** e **com qual frequência** o componente aparece. Isso evita experiências repetitivas e garante que cada exibição tenha impacto.

### Frequência por visitante

A configuração de frequência define quantas vezes um mesmo visitante pode ver o componente:

| Opção                  | Comportamento                                                    |
| ---------------------- | ---------------------------------------------------------------- |
| **Uma única vez**      | O visitante vê o componente uma vez e nunca mais                 |
| **Uma vez por sessão** | Aparece no máximo uma vez cada vez que o visitante acessa o site |
| **X vezes no total**   | Limite máximo de exibições por visitante (ex: 3 vezes)           |
| **Sem limite**         | Aparece sempre que as condições forem atendidas                  |

<div className="callout-blue">
  A frequência é rastreada por visitante individual. Se um visitante já viu o componente o número máximo de vezes, ele não será exibido novamente, mesmo que o fluxo seja reativado.
</div>

### Agendamento

Você pode restringir a exibição do componente a um período ou horário específico:

* **Data de início e fim**: ideal para campanhas com prazo definido (ex: Black Friday de 20/11 a 30/11)
* **Janela de horário**: exiba componentes apenas em horários estratégicos (ex: entre 18h e 23h quando o tráfego é mais qualificado)
* **Dias da semana**: restrinja a exibição a dias específicos

### Prioridade entre componentes

Quando múltiplos componentes são elegíveis para o mesmo visitante no mesmo momento, a UserIn usa um sistema de **prioridade**. Componentes com prioridade mais alta são exibidos primeiro. Isso evita conflitos visuais (como dois modais tentando aparecer ao mesmo tempo).

<Tip>
  Configure prioridades pensando na jornada do visitante. Componentes de conversão direta (como ofertas) devem ter prioridade sobre componentes informativos (como banners de conteúdo).
</Tip>

***

## Conecte componentes às suas automações

Componentes não funcionam de forma isolada. Eles são **acionados pelo Construtor de Fluxos**, que controla toda a lógica de quando e como exibir cada elemento no site do visitante.

### Como o fluxo aciona um componente

O Construtor de Fluxos funciona com blocos encadeados. Para exibir um componente, você usa um bloco de ação do tipo **Insite**. O fluxo típico segue esta estrutura:

```mermaid theme={null}
flowchart TD
    A["Gatilho"] --> B["Condição"]
    B --> C["Ação Insite"]
    C --> D["Exibir Componente"]
```

1. **Gatilho**: define o evento que inicia o fluxo (regra da plataforma, agendamento, trigger manual)
2. **Condição**: verifica se o visitante atende aos critérios (segmento, atributo, regra)
3. **Ação Insite**: seleciona qual componente exibir (modal, card, smart block ou mini game)

### Teste A/B com componentes

O Construtor de Fluxos suporta blocos de **Teste A/B**, que permitem dividir visitantes em variantes aleatórias. Você pode usar isso para testar diferentes versões de um componente:

* **Variante A** (50%): Modal com desconto de 10%
* **Variante B** (50%): Modal com frete grátis

Cada variante pode apontar para um componente diferente, e os resultados são rastreados separadamente. Isso permite identificar qual abordagem gera mais conversão.

### Caminhos paralelos

Se você precisa exibir componentes diferentes dependendo de condições, use **caminhos paralelos** no fluxo. Exemplo:

* Visitantes do segmento "premium" → exibir Card exclusivo
* Demais visitantes → exibir Smart Block genérico

Caminhos paralelos executam ações simultaneamente, cada um com suas próprias condições.

***

## Teste antes de publicar

Validar o componente antes de ativar para todos os visitantes evita erros e garante a experiência esperada.

### Checklist de validação

Antes de ativar um componente, passe por estes pontos:

| Item                | Verificação                                             |
| ------------------- | ------------------------------------------------------- |
| **Visual desktop**  | O componente renderiza corretamente em telas grandes?   |
| **Visual mobile**   | O layout se adapta bem a telas menores?                 |
| **Variáveis**       | Todas as variáveis Liquid têm valor padrão configurado? |
| **Segmentação**     | A audiência-alvo está corretamente definida?            |
| **Frequência**      | O limite de exibições por visitante está adequado?      |
| **CTA funcional**   | Links e botões apontam para as URLs corretas?           |
| **Fluxo vinculado** | O componente está conectado a um fluxo ativo?           |

<div className="callout-blue">
  Se o componente usa **variáveis Liquid**, teste com perfis que tenham dados preenchidos e perfis sem dados. Verifique se os valores padrão (fallback) aparecem corretamente nos dois cenários.
</div>

***

## Boas práticas para componentes eficazes

<AccordionGroup>
  <Accordion title="Menos é mais: não sobrecarregue o visitante" icon="scale-balanced">
    Evite exibir múltiplos componentes ao mesmo tempo. Dois modais simultâneos ou um modal sobre um smart block prejudicam a experiência. Use o sistema de **prioridade** para garantir que apenas o componente mais relevante apareça a cada momento.

    Regra prática: limite-se a **um componente de alta visibilidade** (modal ou mini game) e no máximo **dois de baixa visibilidade** (cards ou smart blocks) por sessão.
  </Accordion>

  <Accordion title="Personalize sempre que possível" icon="user-pen">
    Componentes personalizados convertem significativamente mais do que mensagens genéricas. Use variáveis Liquid para incluir o nome do visitante, dados relevantes do perfil e informações contextuais.

    Compare: "Confira nossa promoção" vs. "João, você tem 2.500 pontos acumulados. Resgate agora com 20% de bônus!"
  </Accordion>

  <Accordion title="Teste variações com A/B" icon="vials">
    Nunca assuma que a primeira versão é a melhor. Use o bloco de Teste A/B no Construtor de Fluxos para comparar variações de copy, design, oferta ou formato de componente. Deixe os dados indicarem o vencedor.

    Sugestões de variáveis para testar:

    * **Copy do CTA**: "Quero meu desconto" vs. "Resgatar agora"
    * **Formato**: Modal vs. Card para a mesma oferta
    * **Momento**: exibir ao entrar na página vs. após 30 segundos
  </Accordion>

  <Accordion title="Respeite a frequência" icon="clock">
    Um componente que aparece com frequência excessiva se torna invisível (banner blindness) ou irritante. Configure limites de frequência conservadores e aumente gradualmente conforme os resultados.

    Ponto de partida sugerido:

    * **Modais**: uma vez por sessão, máximo 3 vezes no total
    * **Cards**: uma vez por sessão
    * **Smart Blocks**: sem limite (são integrados ao layout)
    * **Mini Games**: uma vez por dia
  </Accordion>

  <Accordion title="Alinhe o componente ao momento da jornada" icon="map-location-dot">
    O mesmo visitante tem necessidades diferentes em cada estágio. Um modal de boas-vindas faz sentido na primeira visita, mas seria estranho na décima. Use segmentos comportamentais para exibir o componente certo no momento certo:

    * **Primeira visita**: modal de boas-vindas ou captação de email
    * **Visitante recorrente sem conversão**: card com oferta ou incentivo
    * **Cliente ativo**: smart block com recomendação personalizada
    * **Cliente inativo**: mini game com recompensa de reativação
  </Accordion>

  <Accordion title="Monitore e itere continuamente" icon="arrows-spin">
    Componentes não são "configure e esqueça". Revise as métricas semanalmente, identifique componentes com baixa performance e teste novas abordagens. Pause componentes que não estão entregando resultado e redirecione o tráfego para versões otimizadas.
  </Accordion>
</AccordionGroup>

***

## Guias por tipo de componente

Cada tipo de componente tem seu próprio guia com instruções detalhadas de criação, configuração visual, analytics e boas práticas específicas:

<CardGroup cols={2}>
  <Card title="Cards" icon="cards-blank" href="/componentes/cards">
    Crie cards visuais compactos para destaques e CTAs contextuais.
  </Card>

  <Card title="Modais" icon="window-maximize" href="/componentes/modais">
    Configure modais com gatilhos inteligentes e controle de frequência.
  </Card>

  <Card title="Smart Blocks" icon="puzzle-piece" href="/componentes/smart-blocks">
    Embutir blocos personalizados diretamente na estrutura da página.
  </Card>

  <Card title="Mini Games" icon="dice" href="/componentes/mini-games">
    Engaje visitantes com mecânicas de gamificação interativas.
  </Card>
</CardGroup>