Skip to main content

​
Visão Geral

O TestlyProvider aceita um objeto config opcional que permite customizar o comportamento do SDK. 
<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    debug: boolean,
    supabaseUrl: string,
    autoTrackImpressions: boolean,
    dedupConversions: boolean,
    onLog: (log) => void,
  }}
>
  {children}
</TestlyProvider>

​
Opções de Configuração

​
debug

Tipo: boolean
Padrão: false
Descrição: Ativa logs detalhados no console para facilitar debugging. 
<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    debug: process.env.NODE_ENV === 'development'
  }}
>
Logs que você verá: 
[Testly] ✅ Conversion recorded for homepage-hero-test
[Testly] ❌ API ERROR: Failed to track impression. Status: 401
[Testly] ❌ TRACKING BLOCKED: Missing critical IDs for experiment "my-test"
Recomendação: Sempre ative em desenvolvimento e desative em produção para não poluir o console dos usuários.

​
supabaseUrl

Tipo: string
Padrão: URL do projeto Supabase do Testly
Descrição: URL customizada do projeto Supabase. Útil apenas se você estiver usando uma instância self-hosted do Testly. 
<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    supabaseUrl: 'https://seu-projeto.supabase.co'
  }}
>
Na grande maioria dos casos, você não precisa configurar este campo. O SDK já aponta para o projeto correto por padrão.

​
autoTrackImpressions

Tipo: boolean
Padrão: true
Descrição: Registra automaticamente uma impressão quando useExperiment é executado pela primeira vez para um usuário em uma sessão. 
<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    autoTrackImpressions: true // Padrão
  }}
>
Comportamento com true (padrão):
  • Impressão registrada automaticamente no primeiro render
  • Deduplicada por sessionStorage — uma impressão por sessão por experimento
  • Você não precisa fazer nada
Quando usar false: 
config={{
  autoTrackImpressions: false // Controle manual de impressões
}}
Use false apenas se você precisa controlar exatamente quando a impressão é contada.

​
dedupConversions

Tipo: boolean
Padrão: true
Descrição: Previne que o mesmo tipo de conversão seja registrado mais de uma vez por experimento. 
<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    dedupConversions: true // Padrão
  }}
>
Comportamento: 
const { convert } = useExperiment('pricing-test');

// Primeira chamada: ✅ Registrada
await convert('plan_selected');

// Segunda chamada (mesma sessão): ❌ Ignorada automaticamente
await convert('plan_selected');
Quando desativar: 
config={{
  dedupConversions: false // Permite conversões do mesmo tipo repetidas
}}
Use false apenas se você precisa rastrear eventos repetíveis (ex: múltiplos cliques em “adicionar ao carrinho”).
Cuidado: Desativar deduplicação pode inflar artificialmente suas métricas. Use com cautela.

​
onLog

Tipo: (log: object) => void
Padrão: undefined
Descrição: Callback personalizado para cada chamada de API. Recebe um objeto com detalhes da requisição. Útil para integrar com seu sistema de observabilidade. 
<TestlyProvider 
  apiKey="YOUR_API_KEY"
  config={{
    onLog: (log) => {
      console.table(log);
      // ou envie para seu sistema de logs
      myLogger.track('testly_api_call', log);
    }
  }}
>
Estrutura do objeto log: 
{
  method: 'GET' | 'POST',
  url: string,
  status: number,
  timestamp: number,
  body?: object,    // apenas em POSTs
  response: object
}

​
Configurações por Ambiente

​
Desenvolvimento

<TestlyProvider 
  apiKey={import.meta.env.VITE_TESTLY_API_KEY}
  config={{
    debug: true,
    dedupConversions: true,
    autoTrackImpressions: true,
  }}
>

​
Produção

<TestlyProvider 
  apiKey={import.meta.env.VITE_TESTLY_API_KEY}
  config={{
    debug: false,
    dedupConversions: true,
    autoTrackImpressions: true,
  }}
>

​
Configuração Completa Recomendada

​
Next.js (App Router)

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!}
          config={{
            debug: process.env.NODE_ENV === 'development',
            dedupConversions: true,
            autoTrackImpressions: true,
          }}
        >
          {children}
        </TestlyProvider>
      </body>
    </html>
  );
}

​
React (Vite)

src/App.tsx
import { TestlyProvider } from '@testlyjs/react';

function App() {
  return (
    <TestlyProvider 
      apiKey={import.meta.env.VITE_TESTLY_API_KEY}
      config={{
        debug: import.meta.env.DEV,
        dedupConversions: true,
        autoTrackImpressions: true,
      }}
    >
      <Routes />
    </TestlyProvider>
  );
}

​
Referência Completa

interface TestlyConfig {
  /**
   * Chave de API do Testly (obrigatória, passada diretamente na prop apiKey)
   */
  apiKey: string;

  /**
   * URL do projeto Supabase. Não precisa configurar na maioria dos casos.
   */
  supabaseUrl?: string;

  /**
   * Ativa logs detalhados no console
   * @default false
   */
  debug?: boolean;

  /**
   * Registra impressão automaticamente no primeiro render do useExperiment
   * @default true
   */
  autoTrackImpressions?: boolean;

  /**
   * Previne registrar o mesmo tipo de conversão mais de uma vez
   * @default true
   */
  dedupConversions?: boolean;

  /**
   * Callback chamado a cada requisição à API (para observabilidade)
   */
  onLog?: (log: any) => void;
}

​
Próximos Passos

useExperiment

Hook principal para experimentos

Exemplos práticos

Veja implementações reais

Debugging

Troubleshooting detalhado

Boas Práticas

Padrões recomendados