> ## Documentation Index
> Fetch the complete documentation index at: https://userepass.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracker client-side (script)

> Instale a tag da Repass, identifique visitantes e registre conversões direto do navegador.

O tracker client-side é uma tag JavaScript que você instala no seu site para capturar o clique do afiliado e registrar conversões **direto do navegador**, sem escrever código de backend. É uma **camada de conveniência** sobre o rastreamento [server-to-server](/docs/guias/conversoes-server-to-server) (S2S): o S2S continua sendo a fonte da verdade e [reconcilia](#reconcilia%C3%A7%C3%A3o-com-o-s2s) qualquer conversão client-side de mesmo `sourceEventId`.

A autenticação no navegador usa a **publishable key** (`pk_*`): pública, pode ficar visível no código do site. A chave secreta (`rstr_`) **nunca** vai ao client.

<Note>
  Quando usar o tracker client-side? Quando você quer adotar a Repass com o mínimo de integração de backend, ou complementar o S2S para capturar identidade e conversões mesmo quando o servidor não tem todos os identificadores. Se você já tem uma integração S2S robusta, o tracker é opcional.
</Note>

## Como funciona

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant V as Visitante
    participant API as API Repass
    participant Site as Seu site (tag)
    participant Back as Seu backend (S2S, opcional)

    V->>API: clica no link do afiliado (GET /t/{token})
    API-->>V: 302 destino?repass_cid=clk_…&repass_vid=vis_…
    V->>Site: navega; a tag persiste repass_cid/repass_vid
    Site->>API: POST /track/identify (e-mail hasheado, opcional)
    Site->>API: POST /track/conversion (X-Repass-Key: pk_…)
    Note over API: source: script + sinal client_side_unverified
    opt confirmação S2S (mesmo sourceEventId)
        Back->>API: POST /conversions
        Note over API: sobrescreve a conversão provisória → source: api
    end
```

## Instalação

<Steps>
  <Step title="Pegue sua publishable key">
    No painel da Repass, em **Configurações → Rastreamento**, copie a publishable key (`pk_…`). Pela API:

    ```bash theme={null}
    curl https://api.userepass.com/settings/tracker \
      -H "Authorization: Bearer rstr_..."
    # { "publishableKey": "pk_01J9Z...", "trustClientSide": false }
    ```

    <Warning>
      Use **somente** a publishable key (`pk_`) no navegador. A chave secreta (`rstr_`) autentica chamadas server-to-server e nunca deve aparecer no frontend.
    </Warning>
  </Step>

  <Step title="Instale a tag no seu site">
    Cole antes do fechamento do `</body>`, em todas as páginas (incluindo a de confirmação de compra). A base da API é derivada do próprio `src` do script.

    ```html theme={null}
    <script src="https://api.userepass.com/t.js" data-key="pk_01J9Z..."></script>
    ```

    A tag expõe `window.Repass` e, ao carregar, captura `repass_cid` e `repass_vid` da URL automaticamente (anexados pelo redirect do link do afiliado), persistindo-os em cookie first-party + `localStorage`.
  </Step>

  <Step title="Identifique o visitante (opcional, cross-device)">
    No cadastro/login, associe o visitante a um e-mail: o hash SHA-256 é calculado no navegador e permite atribuição entre dispositivos.

    ```js theme={null}
    Repass.identify("cliente@exemplo.com");
    ```
  </Step>

  <Step title="Dispare a conversão">
    Na página de obrigado (ou quando a venda se concretiza), registre a conversão. A tag mescla automaticamente o `clickId`/`visitorId` capturados.

    ```js theme={null}
    Repass.convert({
      type: "one_time_purchase",
      amountCents: 9900,
      customer: { id: "ID_DO_CLIENTE" },
      sourceEventId: "ID_DO_PEDIDO",
    });
    ```

    <Tip>
      Valores em centavos (inteiro): `9900` = R\$ 99,00. Use como `sourceEventId` um id estável do seu pedido: é a chave de idempotência **e** de reconciliação com o S2S.
    </Tip>
  </Step>
</Steps>

## Confiança no client-side

Conversões disparadas pelo navegador são, por natureza, menos confiáveis que o S2S (recebem o sinal de fraude `client_side_unverified`). Você controla, por organização, se elas contam sozinhas, em **Configurações → Rastreamento** (`trustClientSide`) ou via `PUT /settings/tracker`:

| `trustClientSide`                     | Comportamento da conversão client-side                                                                 |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `false` (padrão, recomendado com S2S) | Fica **provisória** (`status: pending`, sem comissão) até o S2S confirmar com o mesmo `sourceEventId`. |
| `true`                                | Conta sozinha e gera comissão (passa pelo antifraude normal); ainda é reconciliável pelo S2S.          |

<Warning>
  Sem S2S, mantenha `trustClientSide: true`, caso contrário as conversões ficam `pending` para sempre, aguardando uma confirmação que nunca chega.
</Warning>

## Reconciliação com o S2S

Se você envia **as duas coisas** (tag no site + S2S no backend), use o **mesmo `sourceEventId`** nos dois. Quando o evento S2S (`POST /conversions`) chega, ele **sobrescreve in-place** a conversão client-side provisória: reprocessa atribuição e fraude com os dados confiáveis, gera a comissão, troca a origem para `api` e emite `conversion.reconciled`. O S2S sempre vence.

<Note>
  A reconciliação cobre conversões client-side ainda **provisórias** (`pending`). Uma conversão client-side já aprovada (org com `trustClientSide: true`) não é sobrescrita por um S2S divergente posterior.
</Note>

## Instalação via npm (bundlers)

Para apps que usam bundler (React, Vue, etc.), o pacote `@repass/tracker` expõe uma API programática. Chame `initRepass` **apenas no client** (usa `window`/`document`/`crypto`).

<CodeGroup>
  ```bash npm theme={null}
  npm install @repass/tracker
  ```

  ```ts app.ts theme={null}
  import { initRepass } from "@repass/tracker";

  const repass = initRepass({
    publishableKey: "pk_01J9Z...",
    apiBaseUrl: "https://api.userepass.com",
  });

  await repass.identify("cliente@exemplo.com");
  await repass.convert({
    type: "one_time_purchase",
    amountCents: 9900,
    customer: { id: "ID_DO_CLIENTE" },
    sourceEventId: "ID_DO_PEDIDO",
  });
  ```
</CodeGroup>

## Referência da API

* `POST /track/conversion`: conversão client-side (autenticada pela publishable key). Veja a aba **Referência da API**.
* `GET` / `PUT /settings/tracker`: leia/rotacione a publishable key e ajuste `trustClientSide` (autenticado por sessão/API key).
* `POST /track/identify`: associa visitante a e-mail hasheado (cross-device).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Conversões server-to-server" icon="server" href="/docs/guias/conversoes-server-to-server">
    O contrato S2S que reconcilia e dá a palavra final sobre a conversão.
  </Card>

  <Card title="Tracking" icon="crosshairs" href="/docs/conceitos/tracking">
    Clique, visitante, janela de atribuição e fingerprint.
  </Card>

  <Card title="Atribuição" icon="diagram-project" href="/docs/conceitos/atribuicao">
    Modelos, janela e o conflito Cupom × Clique.
  </Card>

  <Card title="Conversões e fraude" icon="shield-halved" href="/docs/conceitos/conversoes-e-fraude">
    Pipeline de decisão, snapshots e o motor antifraude.
  </Card>
</CardGroup>