Guia Rápido

Pré-requisitos

Conta criada em app.testly.com.br
Projeto React 16.8+ (Vite, CRA ou Next.js)
Node.js 14+

Instalação

npm
yarn
pnpm

npm install @testlyjs/react

yarn add @testlyjs/react

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 → 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>
  );
}

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:

.env

# Produção — chave real, usada no deploy
VITE_TESTLY_API_KEY=tk_live_...

.env.local

# 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 → 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

Acesse app.testly.com.br e clique em Novo Experimento
Preencha o nome — o slug é gerado automaticamente (ex: homepage-cta-test)
Defina o KPI de conversão (ex: cta_clicked)
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:

🤖 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ê 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';
   <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_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:

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.

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:

function PaginaPrincipal() {
  const heroTest    = useExperiment('hero-headline');
  const pricingTest = useExperiment('pricing-layout');

  return (
    <>
      <Hero variant={heroTest.variant} convert={heroTest.convert} />
      <Pricing variant={pricingTest.variant} convert={pricingTest.convert} />
    </>
  );
}

Cada experimento é independente. Um usuário pode estar no control do hero-headline e no variant-b do pricing-layout ao mesmo tempo.

Troubleshooting

variant retorna null e não muda

Causa mais comum: a API Key no TestlyProvider não corresponde à organização onde o experimento foi criado.Checklist:

Abra app.testly.com.br/settings → copie a API Key da seção API Key
Confirme que essa mesma key está no TestlyProvider do seu app
Verifique se o experimento está listado no seu dashboard (não no de outra conta)
Confirme que o slug no useExperiment('...') é idêntico ao slug exibido no dashboard

Ative o debug para ver o que o SDK está recebendo:

<TestlyProvider apiKey="..." config={{ debug: true }}>

variant retorna null mas o experimento existe

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.

Próximos Passos

useExperiment

Referência completa do hook principal

Exemplos práticos

Hero section, pricing, CTA — veja implementações reais

Configuração avançada

Debug mode, dedupConversions, userId customizado

Integração com IA

Use Claude Code ou Cursor para implementar experimentos automaticamente

Primeiros Passos

SDK

Guias

Pré-requisitos

Instalação

Passo 1 — Configure o Provider

Desenvolvendo localmente?

Passo 2 — Crie o experimento no dashboard

Passo 3 — Integre no seu app

Como funciona

Múltiplos experimentos

Troubleshooting

Próximos Passos

useExperiment

Exemplos práticos

Configuração avançada

Integração com IA

​Pré-requisitos

​Instalação

​Passo 1 — Configure o Provider

​Desenvolvendo localmente?

​Passo 2 — Crie o experimento no dashboard

​Passo 3 — Integre no seu app

​Como funciona

​Múltiplos experimentos

​Troubleshooting

​Próximos Passos

useExperiment

Exemplos práticos

Configuração avançada

Integração com IA

Pré-requisitos

Instalação

Passo 1 — Configure o Provider

Desenvolvendo localmente?

Passo 2 — Crie o experimento no dashboard

Passo 3 — Integre no seu app

Como funciona

Múltiplos experimentos

Troubleshooting

Próximos Passos