> ## 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.
# Guia Rápido
> Implemente seu primeiro teste A/B em 5 minutos com o Testly React SDK
## Pré-requisitos
* Conta criada em [app.testly.com.br](https://app.testly.com.br)
* Projeto React 16.8+ (Vite, CRA ou Next.js)
* Node.js 14+
***
## Instalação
```bash theme={null}
npm install @testlyjs/react
```
```bash theme={null}
yarn add @testlyjs/react
```
```bash theme={null}
pnpm add @testlyjs/react
```
***
## Passo 1 — Configure o Provider
Envolva sua aplicação com o `TestlyProvider` no arquivo raiz. Você configura isso **uma única vez**.
**API Key**: Pegue a sua em [app.testly.com.br/settings](https://app.testly.com.br/settings) → seção **API Key**. Ela tem o formato `tk_live_...`.
A API Key identifica sua organização. O experimento que você criou no dashboard **só funciona com a API Key da mesma conta**. Se usar a key errada, o SDK retorna `variant: null`.
```tsx App.tsx theme={null}
import { TestlyProvider } from '@testlyjs/react';
export default function App() {
return (
);
}
```
```bash .env theme={null}
VITE_TESTLY_API_KEY=tk_live_...
```
```tsx app/layout.tsx theme={null}
import { TestlyProvider } from '@testlyjs/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
```bash .env.local theme={null}
NEXT_PUBLIC_TESTLY_API_KEY=tk_live_...
```
```tsx pages/_app.tsx theme={null}
import type { AppProps } from 'next/app';
import { TestlyProvider } from '@testlyjs/react';
export default function App({ Component, pageProps }: AppProps) {
return (
);
}
```
***
## Desenvolvendo localmente?
O Testly tem duas chaves por organização para você nunca misturar dados de teste com dados reais:
| Chave | Formato | Quando usar |
| ------------------- | ------------- | ----------------------------------------------------- |
| **Produção** | `tk_live_...` | App em produção — eventos contam nas suas métricas |
| **Desenvolvimento** | `tk_test_...` | Ambiente local — eventos ficam completamente isolados |
Configure as duas no seu projeto:
```bash .env theme={null}
# Produção — chave real, usada no deploy
VITE_TESTLY_API_KEY=tk_live_...
```
```bash .env.local theme={null}
# Desenvolvimento local — sobrescreve .env localmente
# Adicione .env.local ao .gitignore para não comitar a chave
VITE_TESTLY_API_KEY=tk_test_...
```
Pegue ambas as chaves em [app.testly.com.br/settings](https://app.testly.com.br/settings) → **Chave de API** → abas "Produção" e "Desenvolvimento".
**Dev Mode**: quando você usa a chave `tk_test_`, o dashboard do Testly filtra os experimentos e métricas para mostrar apenas dados de teste — suas métricas reais ficam protegidas. Ative o Dev Mode no toggle da sidebar para ver esses experimentos.
***
## Passo 2 — Crie o experimento no dashboard
1. Acesse [app.testly.com.br](https://app.testly.com.br) e clique em **Novo Experimento**
2. Preencha o nome — o **slug** é gerado automaticamente (ex: `homepage-cta-test`)
3. Defina o KPI de conversão (ex: `cta_clicked`)
4. O experimento é criado já em estado **ativo** (running)
O dashboard mostra o código pronto para copiar em cada experimento — incluindo a API Key e o slug correto.
***
## Passo 3 — Integre no seu app
Você tem duas opções para integrar o experimento. Escolha a que preferir:
Depois de criar o experimento, o dashboard mostra a aba **"Pedir pra IA"** com um prompt pronto — sua API Key, slug e evento de conversão já preenchidos.
Cole no **Claude Code**, **Cursor**, **Windsurf** ou qualquer IA do seu editor. Ela faz tudo:
```
Preciso integrar um teste A/B no meu projeto React usando o Testly SDK.
Faça tudo do zero — assuma que ainda não configurei nada.
INFORMAÇÕES DO EXPERIMENTO:
SDK: @testlyjs/react
API Key: tk_live_xxx ← pré-preenchida com a sua key
Experimento: 'homepage-cta-test' ← slug do seu experimento
Conversão: 'cta_clicked' ← evento que você definiu
PASSOS QUE VOCÊ DEVE EXECUTAR:
1. Verifique se @testlyjs/react está no package.json.
Se não estiver, instale: npm install @testlyjs/react
2. Encontre o arquivo raiz do app (App.tsx, layout.tsx, _app.tsx).
Adicione o TestlyProvider envolvendo TODA a aplicação:
import { TestlyProvider } from '@testlyjs/react';
{/* conteúdo atual */}
Adicione ao .env:
VITE_TESTLY_API_KEY=tk_live_xxx
3. Encontre o componente certo e implemente o hook:
const { variant, convert } = useExperiment('homepage-cta-test');
- variant === 'control' → versão original
- variant === 'variant-b' → nova variante
- Conversão: convert('cta_clicked')
Se não tiver certeza de qual componente usar, mostre as opções antes.
```
O prompt completo com sua API Key real está disponível na aba **"Pedir pra IA"** após criar o experimento no dashboard.
Implemente você mesmo no componente certo:
```tsx components/HeroSection.tsx theme={null}
import { useExperiment } from '@testlyjs/react';
export function HeroSection() {
const { variant, loading, error, convert } = useExperiment('homepage-cta-test');
if (loading) return ;
if (error) {
// Fallback — nunca deixe o experimento quebrar o app
return ;
}
return (
);
}
```
Sempre implemente `loading` e `error`. Se o SDK falhar, o usuário vê a versão original — sem quebrar o app.
***
## Como funciona
```
useExperiment('homepage-cta-test')
1. Verifica cache local (localStorage)
2. Cache vazio → GET /get-variant com sua API Key
3. Retorna variant: 'control' ou 'variant-b'
4. Registra impressão automaticamente (uma vez por sessão)
convert('cta_clicked')
→ POST /track-event (conversão registrada no dashboard)
```
***
## Múltiplos experimentos
Você pode usar vários `useExperiment` no mesmo componente ou em componentes diferentes:
```tsx theme={null}
function PaginaPrincipal() {
const heroTest = useExperiment('hero-headline');
const pricingTest = useExperiment('pricing-layout');
return (
<>
);
}
```
Cada experimento é independente. Um usuário pode estar no `control` do `hero-headline` e no `variant-b` do `pricing-layout` ao mesmo tempo.
***
## Troubleshooting
**Causa mais comum**: a API Key no `TestlyProvider` não corresponde à organização onde o experimento foi criado.
**Checklist**:
1. Abra [app.testly.com.br/settings](https://app.testly.com.br/settings) → copie a API Key da seção **API Key**
2. Confirme que essa mesma key está no `TestlyProvider` do seu app
3. Verifique se o experimento está listado no seu dashboard (não no de outra conta)
4. Confirme que o slug no `useExperiment('...')` é idêntico ao slug exibido no dashboard
Ative o debug para ver o que o SDK está recebendo:
```tsx theme={null}
```
O SDK retorna `null` quando o experimento não está em estado **running**. Isso acontece quando:
* O experimento foi pausado ou arquivado no dashboard
* O experimento foi concluído automaticamente (winner encontrado)
* A API Key usada pertence a uma organização diferente da que criou o experimento
**Solução**: Verifique o status do experimento no dashboard. Se estiver `draft` ou `paused`, ative-o.
Isso **não deveria acontecer** — o SDK usa cache local para manter consistência.
**Causas possíveis**:
* Código limpando o `localStorage` em algum lugar
* Navegação privada (sem persistência entre abas)
* `userId` diferente sendo gerado a cada render
Para testar, use `config={{ debug: true }}` e verifique os logs no console.
**Checklist**:
* ✅ `convert('nome_do_evento')` está sendo chamado?
* ✅ O nome do evento usa snake\_case (ex: `cta_clicked`, não `CTA Clicked`)?
* ✅ A impressão foi registrada antes? (automático, mas verifique com `debug: true`)
* ✅ O experimento está em estado **running**?
```tsx theme={null}
// Teste manual no console do navegador:
convert('cta_clicked').then(() => console.log('✅ Conversão registrada'));
```
O plano gratuito permite **1 experimento ativo** e **10.000 impressões/mês**.
Se você atingiu o limite de impressões, o SDK continua funcionando — mas novas impressões não são registradas (conversões nunca são bloqueadas).
Para criar mais experimentos sem afetar seus limites, ative o **Dev Mode** no painel lateral e use a chave `tk_test_` — experimentos de teste são ilimitados.
Para aumentar os limites de produção, [faça upgrade para o Pro](https://app.testly.com.br/settings) — R\$79/mês, experimentos ilimitados, 100k impressões.
***
## Próximos Passos
Referência completa do hook principal
Hero section, pricing, CTA — veja implementações reais
Debug mode, dedupConversions, userId customizado
Use Claude Code ou Cursor para implementar experimentos automaticamente