Configuração

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

Primeiros Passos

SDK

Guias

Configuração

Visão Geral

Opções de Configuração

debug

supabaseUrl

autoTrackImpressions

dedupConversions

onLog

Configurações por Ambiente

Desenvolvimento

Produção

Configuração Completa Recomendada

Next.js (App Router)

React (Vite)

Referência Completa

Próximos Passos

useExperiment

Exemplos práticos

Debugging

Boas Práticas

​Visão Geral

​Opções de Configuração

​debug

​supabaseUrl

​autoTrackImpressions

​dedupConversions

​onLog

​Configurações por Ambiente

​Desenvolvimento

​Produção

​Configuração Completa Recomendada

​Next.js (App Router)

​React (Vite)

​Referência Completa

​Próximos Passos

useExperiment

Exemplos práticos

Debugging

Boas Práticas

Visão Geral

Opções de Configuração

debug

supabaseUrl

autoTrackImpressions

dedupConversions

onLog

Configurações por Ambiente

Desenvolvimento

Produção

Configuração Completa Recomendada

Next.js (App Router)

React (Vite)

Referência Completa

Próximos Passos