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

# useConversion()

> Hook avançado para rastrear conversões em múltiplos experimentos simultaneamente

<Warning>
  **Na maioria dos casos, você não precisa deste hook.**

  Use o `convert` que já vem do `useExperiment`:

  ```tsx theme={null}
  const { variant, convert } = useExperiment('meu-experimento');

  <button onClick={() => convert('cta_click')}>Confirmar</button>
  ```

  O `useConversion` é para cenários avançados onde uma única ação precisa ser creditada a **todos os experimentos ativos** na página ao mesmo tempo.
</Warning>

***

## O que é `useConversion`

O hook `useConversion` dispara uma conversão para **todos os experimentos que estão renderizados na página** no momento da chamada. É útil em eventos de negócio globais — como um checkout finalizado — onde você quer creditar qualquer experimento que pode ter influenciado a decisão do usuário.

***

## Quando usar

Use `useConversion` apenas quando:

* **Múltiplos experimentos** na mesma sessão devem ser creditados pelo mesmo evento
* O evento é um objetivo global de negócio (ex: compra, assinatura) que transcende qualquer variante específica
* Você não consegue chamar `convert` em cada experimento individualmente (ex: o evento acontece em uma página diferente da que exibiu os experimentos)

Para qualquer outro caso, use `useExperiment().convert` — é mais preciso e mais simples.

***

## Uso

```tsx theme={null}
import { useExperiment, useConversion } from '@testlyjs/react';

function CheckoutPage() {
  // Cada experimento ativo na sessão registra a conversão
  const track = useConversion();

  const handlePurchase = async () => {
    await processOrder();
    track('purchase_completed');
  };

  return (
    <button onClick={handlePurchase}>
      Finalizar Compra
    </button>
  );
}
```

***

## Assinatura

```typescript theme={null}
const track = useConversion();

// Chamar para registrar a conversão
track(eventName: string, metadata?: Record<string, any>): Promise<void>
```

O hook retorna uma função que, ao ser chamada, itera por todos os experimentos ativos no contexto e envia um evento de conversão para cada um.

***

## Comparação com `useExperiment().convert`

|                 | `useExperiment().convert`                           | `useConversion()`                                   |
| --------------- | --------------------------------------------------- | --------------------------------------------------- |
| **Escopo**      | Um experimento específico                           | Todos os experimentos ativos                        |
| **Precisão**    | Alta                                                | Menor (pode creditar experimentos não relacionados) |
| **Caso de uso** | Padrão — 95% dos casos                              | Eventos globais de negócio                          |
| **Código**      | `const { variant, convert } = useExperiment('key')` | `const track = useConversion()`                     |

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="useExperiment" icon="flask" href="/sdk/use-experiment">
    Hook principal — padrão recomendado
  </Card>

  <Card title="Exemplos" icon="code" href="/examples/hero-section">
    Veja implementações reais
  </Card>
</CardGroup>