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

# Introdução

> Testes A/B para quem constrói SaaS.

## O que é o Testly?

O **Testly** é uma ferramenta de **experimentação para produtos digitais** criada especialmente para **founders técnicos** e **pequenas equipes de SaaS** que precisam validar decisões de produto com dados reais, sem a complexidade das ferramentas tradicionais de marketing.

Diferente de plataformas focadas em campanhas publicitárias, o Testly foi projetado para quem **vive no código**.

Os experimentos são implementados via SDK, seguem princípios técnicos claros e não impactam a performance da sua aplicação.

<CardGroup cols={2}>
  <Card title="SDK-First" icon="code">
    Experimentos controlados diretamente no código, não em dashboards genéricos
  </Card>

  <Card title="Determinístico" icon="shuffle">
    O mesmo usuário sempre vê a mesma variante. Atribuição baseada no userId
  </Card>

  <Card title="Resiliente a Falhas" icon="shield-check">
    Conversões só são registradas quando o backend confirma o sucesso da chamada
  </Card>

  <Card title="Performance-Safe" icon="gauge">
    Zero bloqueio de render. Otimizado para não impactar Core Web Vitals
  </Card>
</CardGroup>

***

## Por que o Testly existe?

Instrumentar experimentos A/B é **chato, manual e repetitivo**.

A maioria das ferramentas foi feita para equipes de marketing com dashboards visuais complexos e não para devs que querem testar um título, um botão ou um fluxo rapidamente.

**O Testly resolve isso**: instale o SDK, crie um teste e veja o que performa melhor.

***

## Para quem o Testly foi criado?

O Testly **não é uma ferramenta de marketing**.

### Ele foi criado para:

<Check>
  Founders técnicos rodando SaaS independentes
</Check>

<Check>
  Pequenas equipes de produto (1-10 pessoas)
</Check>

<Check>
  Desenvolvedores que precisam de clareza técnica e código limpo
</Check>

<Check>
  Times enxutos sem recursos para ferramentas enterprise
</Check>

Se você tem um produto rodando, usuários ativos e quer entender o que converte melhor **sem gastar dias configurando dashboards** saiba que o Testly é pra você!

***

## Como funciona?

<Steps>
  <Step title="Instale o SDK">
    Adicione o Testly ao seu projeto React:

    ```bash theme={null}
    npm i @testlyjs/react
    ```
  </Step>

  <Step title="Configure o Provider">
    Envolva sua aplicação com o TestlyProvider:

    ```tsx theme={null}
    import { TestlyProvider } from '@testlyjs/react';

    function App() {
      return (
        <TestlyProvider apiKey="YOUR_API_KEY">
          <Main />
        </TestlyProvider>
      );
    }
    ```
  </Step>

  <Step title="Crie um experimento">
    Use o hook useExperiment para renderizar variantes:

    ```tsx theme={null}
    import { useExperiment } from '@testlyjs/react';

    export function HeroBanner() {
      const { variant, convert } = useExperiment('homepage-hero-v2');

      return (
        <div>
          {variant === 'variant-b' ? (
            <button onClick={() => convert('clicked_cta')}>
              Comece Grátis (Variante B)
            </button>
          ) : (
            <button onClick={() => convert('clicked_cta')}>
              Experimente Agora (Variante A)
            </button>
          )}
        </div>
      );
    }
    ```
  </Step>

  <Step title="Monitore os resultados">
    Acesse o dashboard do Testly para ver:

    * **Impressões**: quantos usuários viram cada variante
    * **Conversões**: quantos usuários realizaram a ação desejada
    * **Taxa de conversão**: qual variante está performando melhor
  </Step>

  <Step title="Tome decisões baseadas em dados">
    Quando tiver significância estatística, implemente a variante vencedora para 100% dos usuários
  </Step>
</Steps>

***

### Fluxo Detalhado

<Tabs>
  <Tab title="Primeira Visita">
    1. **Usuário acessa a página**: O visitante entra no seu app pela primeira vez
    2. **SDK executa**: Hook `useExperiment('experiment-id')` é executado
    3. **API consulta**: Verifica se o usuário já tem uma variante atribuída
    4. **Atribuição determinística**: Se não tem, atribui uma variante baseada no `userId`
    5. **Renderização**: SDK renderiza a variante
    6. **Impressão automática**: SDK registra a impressão automaticamente
    7. **Cache local**: Variante é salva no cache para próximas visitas
  </Tab>

  <Tab title="Visitas Subsequentes">
    1. **Usuário retorna**: O mesmo visitante volta ao app
    2. **SDK verifica cache**: Busca a variante armazenada localmente
    3. **Mesma experiência**: SDK renderiza a **mesma variante** anterior
    4. **Sem nova impressão**: Não registra impressão duplicada (dedupe automático)
    5. **Consistência**: Usuário vê sempre a mesma variante durante todo o experimento
  </Tab>

  <Tab title="Conversão">
    1. **Ação do usuário**: Visitante clica no elemento ou realiza ação
    2. **Chamada convert()**: Sua aplicação chama `convert('event_name')`
    3. **Validação**: API valida e registra a conversão
    4. **Atualização em tempo real**: Dashboard atualiza métricas instantaneamente
    5. **Cálculo automático**: Taxa de conversão é recalculada
  </Tab>
</Tabs>

***

## Principais Conceitos

### Experimento

Um **experimento** é o container onde você configura o teste A/B.

Cada experimento possui:

* **ID único**: Identificador do experimento (ex: `homepage-hero-v2`)
* **Variantes**: Versões diferentes que serão testadas (A, B, C...)
* **Status**: Ativo ou inativo

### Variante

Uma **variante** é cada versão testada no experimento:

* **Controle (A)**: Versão original
* **Tratamento (B, C, D...)**: Versões alternativas

No código, você decide o que renderizar baseado no valor de `variant`.

<Tip>
  O ideal é criar de 2 a 4 variantes por experimento. Muitas variantes podem diluir seus resultados e exigir muito mais tráfego para atingir significância estatística.
</Tip>

### Impressão (Auto-tracked)

Uma **impressão** é registrada **automaticamente** quando o hook `useExperiment` é executado pela primeira vez para aquele usuário.

Você não precisa fazer nada pois o nosso SDK cuida disso.

O SDK garante que:

* Apenas a primeira visualização é contada
* Recarregamentos de página não geram novas impressões
* Cada usuário é contado apenas uma vez

### Conversão

Uma **conversão** ocorre quando o usuário executa a ação desejada. Você decide **quando** chamar a função `convert()`:

```tsx theme={null}
const { convert } = useExperiment('pricing-test');

<button onClick={() => convert('plan_selected')}>
  Selecionar Plano
</button>
```

#### Conversões Globais vs Específicas

| Tipo           | Hook              | Quando usar                                                                    |
| -------------- | ----------------- | ------------------------------------------------------------------------------ |
| **Global**     | `useConversion()` | Ações genéricas que afetam todos os experimentos ativos (ex: cadastro, compra) |
| **Específica** | `useExperiment()` | Ações diretamente relacionadas ao experimento (ex: clique no botão testado)    |

<Accordion title="Exemplo de conversão global">
  ```tsx theme={null}
  import { useConversion } from '@testlyjs/react';

  function CheckoutButton() {
    const trackGlobal = useConversion();
    
    return (
      <button onClick={() => trackGlobal('purchase_completed')}>
        Finalizar Compra
      </button>
    );
  }
  ```
</Accordion>

### Taxa de Conversão

A **taxa de conversão** é calculada como:

```
Taxa de Conversão = (Conversões / Impressões) × 100%
```

Esta métrica indica qual variante está performando melhor.

***

## Casos de Uso Reais

O Testly é perfeito para testar diversos elementos do seu produto:

<CardGroup cols={2}>
  <Card title="CTAs e Botões" icon="hand-pointer">
    Teste textos, cores, tamanhos e posicionamento de call-to-actions
  </Card>

  <Card title="Headlines e Títulos" icon="heading">
    Descubra qual mensagem gera mais cliques e conversões
  </Card>

  <Card title="Hero Sections" icon="image">
    Compare diferentes imagens, vídeos e layouts de hero
  </Card>

  <Card title="Formulários" icon="list-check">
    Otimize número de campos, labels e copy dos formulários
  </Card>

  <Card title="Pricing e Planos" icon="dollar-sign">
    Teste diferentes estruturas de preço e ofertas
  </Card>

  <Card title="Social Proof" icon="users">
    Compare depoimentos, badges de confiança e reviews
  </Card>

  <Card title="Fluxos de Onboarding" icon="route">
    Teste sequências de etapas e copy do onboarding
  </Card>

  <Card title="Copy e Mensagens" icon="pen">
    Otimize textos de descrição e proposta de valor
  </Card>
</CardGroup>

***

## Configuração Avançada

### Debug Mode

Ative logs detalhados durante o desenvolvimento:

```tsx theme={null}
<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    debug: process.env.NODE_ENV === 'development'
  }}
>
```

Você verá logs como:

* `✅ Conversion recorded` — Conversão registrada com sucesso
* `❌ TRACKING BLOCKED: Missing experiment ID` — IDs ausentes (problema de configuração)
* `⚠️ API ERROR: Network timeout` — Detalhes sobre falhas de tracking

### Deduplicação de Conversões

Por padrão, o SDK evita registrar conversões duplicadas na mesma sessão:

```tsx theme={null}
config={{
  dedupConversions: true // Padrão
}}
```

### Fallback para Erros

Sempre implemente tratamento de erro para garantir uma experiência resiliente:

```tsx theme={null}
const { variant, loading, error } = useExperiment('hero-test');

if (loading) return <Skeleton />;
if (error) return <OriginalHero />; // Fallback seguro

return <div>{/* Renderiza variante */}</div>;
```

<Warning>
  Sempre implemente fallbacks. Isso garante que seu produto continue funcionando mesmo se a API do Testly estiver fora do ar.
</Warning>

***

## Requisitos Técnicos

<AccordionGroup>
  <Accordion title="Frameworks Suportados" icon="code">
    * ✅ React 16.8+ (com hooks)
    * ✅ Next.js
    * ✅ Remix
    * ✅ Gatsby
    * ⏳ Vue.js (em desenvolvimento)
    * ⏳ Svelte (em desenvolvimento)
  </Accordion>

  <Accordion title="Navegadores Suportados" icon="browser">
    * Chrome 90+
    * Firefox 88+
    * Safari 14+
    * Edge 90+
    * Opera 76+

    O SDK utiliza APIs modernas do JavaScript.
  </Accordion>

  <Accordion title="Hospedagem" icon="server">
    Funciona em qualquer tipo de hospedagem:

    * Vercel
    * Netlify
    * AWS
    * Custom servers
    * Single Page Applications (SPAs)
    * Server-Side Rendered (SSR)
  </Accordion>
</AccordionGroup>

***

## Segurança e Privacidade

<CardGroup cols={2}>
  <Card title="Dados Anônimos" icon="user-secret">
    Não coletamos informações pessoais dos visitantes
  </Card>

  <Card title="GDPR Compliant" icon="shield-check">
    Em conformidade com regulamentações de privacidade
  </Card>

  <Card title="API Keys Seguras" icon="key">
    Autenticação por chave única. Nunca exponha em código público
  </Card>

  <Card title="HTTPS Only" icon="lock">
    Todas as comunicações são criptografadas
  </Card>
</CardGroup>

<Warning>
  **Importante**

  Nunca exponha sua API Key em código público (GitHub, fóruns, etc.).
</Warning>

***

## Limitações Atuais

Queremos ser transparentes sobre as limitações da versão atual:

* **Tráfego mínimo recomendado**: 500+ visitantes/mês por experimento
* **Frameworks**: Apenas React no momento (Vue e Svelte em breve)
* **Eventos customizados**: Suportado via `convert('event_name')`
* **Segmentação avançada**: Não disponível ainda
* **Integração analytics**: Em desenvolvimento

<Note>
  Quer sugerir features? Entre em contato no Discord!
</Note>

***

## Pricing

### Free — R\$0/mês

* ✅ 1 experimento ativo
* ✅ Até 10.000 impressões/mês
* ✅ 2 variantes por experimento (Control + Variant B)
* ✅ Suporte via comunidade

### Pro — R\$79/mês

* ✅ Experimentos ilimitados
* ✅ Até 100.000 impressões/mês
* ✅ Tudo do plano Free
* ✅ Suporte prioritário

***

## Próximos Passos

Pronto para começar? Siga estes passos:

<Steps>
  <Step title="Crie sua conta">
    [Registre-se gratuitamente](https://app.testly.com.br) — leva menos de 1 minuto
  </Step>

  <Step title="Instale o SDK">
    ```bash theme={null}
    npm install @testlyjs/react
    ```
  </Step>

  <Step title="Configure seu primeiro experimento">
    Siga nosso [Guia de Quickstart](/quickstart) para ter um teste rodando em 5 minutos
  </Step>

  <Step title="Monitore os resultados">
    Acompanhe métricas em tempo real no dashboard
  </Step>
</Steps>

<Card title="Comece Agora" icon="rocket" href="/quickstart">
  Vá para o Guia Rápido e implemente seu primeiro teste A/B em 5 minutos
</Card>

***

## Precisa de Ajuda?

<CardGroup cols={3}>
  <Card title="Documentação" icon="book" href="/docs">
    Explore guias detalhados
  </Card>

  <Card title="Exemplos" icon="code" href="/examples">
    Veja implementações reais
  </Card>

  <Card title="Suporte" icon="life-ring" href="mailto:support@testly.com">
    Fale com nosso time
  </Card>
</CardGroup>

<Tip>
  Junte-se a [comunidade no Discord](https://discord.gg/SFwdTap4) para trocar experiências com outros founders devs!
</Tip>

***

**Feito para devs, por devs. 🚀**