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 → 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.
React / Vite
Next.js (App Router)
Next.js (Pages Router)
App.tsx
import { TestlyProvider } from '@testlyjs/react';export default function App() { return ( <TestlyProvider apiKey={import.meta.env.VITE_TESTLY_API_KEY}> <MinhaApp /> </TestlyProvider> );}
.env
VITE_TESTLY_API_KEY=tk_live_...
app/layout.tsx
import { TestlyProvider } from '@testlyjs/react';export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="pt-BR"> <body> <TestlyProvider apiKey={process.env.NEXT_PUBLIC_TESTLY_API_KEY}> {children} </TestlyProvider> </body> </html> );}
.env.local
NEXT_PUBLIC_TESTLY_API_KEY=tk_live_...
pages/_app.tsx
import type { AppProps } from 'next/app';import { TestlyProvider } from '@testlyjs/react';export default function App({ Component, pageProps }: AppProps) { return ( <TestlyProvider apiKey={process.env.NEXT_PUBLIC_TESTLY_API_KEY}> <Component {...pageProps} /> </TestlyProvider> );}
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:
.env
# Produção — chave real, usada no deployVITE_TESTLY_API_KEY=tk_live_...
.env.local
# Desenvolvimento local — sobrescreve .env localmente# Adicione .env.local ao .gitignore para não comitar a chaveVITE_TESTLY_API_KEY=tk_test_...
Pegue ambas as chaves em 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.
Você tem duas opções para integrar o experimento. Escolha a que preferir:
🤖 Pedir pra IA (mais rápido)
✍️ Manual
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ê definiuPASSOS QUE VOCÊ DEVE EXECUTAR:1. Verifique se @testlyjs/react está no package.json. Se não estiver, instale: npm install @testlyjs/react2. 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'; <TestlyProvider apiKey={import.meta.env.VITE_TESTLY_API_KEY || "tk_live_xxx"}> {/* conteúdo atual */} </TestlyProvider> Adicione ao .env: VITE_TESTLY_API_KEY=tk_live_xxx3. 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:
components/HeroSection.tsx
import { useExperiment } from '@testlyjs/react';export function HeroSection() { const { variant, loading, error, convert } = useExperiment('homepage-cta-test'); if (loading) return <div className="skeleton-button" />; if (error) { // Fallback — nunca deixe o experimento quebrar o app return <button onClick={() => window.location.href = '/signup'}>Comece Grátis</button>; } return ( <button onClick={() => { convert('cta_clicked'); window.location.href = '/signup'; }} > {variant === 'variant-b' ? 'Experimente Agora' : 'Comece Grátis'} </button> );}
Sempre implemente loading e error. Se o SDK falhar, o usuário vê a versão original — sem quebrar o app.
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)
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.
Variante muda a cada refresh
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.
Conversões não aparecem no dashboard
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?
// Teste manual no console do navegador:convert('cta_clicked').then(() => console.log('✅ Conversão registrada'));
Atingi o limite do plano gratuito
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 — R$79/mês, experimentos ilimitados, 100k impressões.
