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

# Conectando Dados

> Transforme visitantes anônimos em perfis completos. Identifique usuários, capture formulários e rastreie eventos do seu negócio.

O tracker já está capturando comportamento, mas visitantes são **anônimos** por padrão. Nesta etapa, você conecta esses dados a pessoas reais: quando um visitante faz login ou se cadastra, a UserIn unifica todo o histórico anônimo com o perfil identificado automaticamente.

<CardGroup cols={3}>
  <Card title="Identificar" icon="user-check">
    Conecte visitantes a perfis reais quando fizerem login ou se cadastrarem.
  </Card>

  <Card title="Capturar" icon="rectangle-list">
    Colete dados de formulários automaticamente ou com controle total.
  </Card>

  <Card title="Rastrear" icon="bullseye">
    Envie eventos customizados para ações específicas do seu negócio.
  </Card>
</CardGroup>

***

## 1. Identificar usuários

Quando um visitante fizer login, se cadastrar ou preencher um formulário com dados de contato, identifique-o com:

```javascript theme={null}
__SmartTrack.setExternalUserContext('id_do_usuario', {
  email: 'maria@empresa.com',
  name: 'Maria Silva',
  plan: 'premium'
});
```

### Parâmetros

<ParamField body="userId" type="string" required>
  Identificador único do usuário no **seu** sistema (ID do banco, UUID, etc.)
</ParamField>

<ParamField body="properties" type="object">
  Objeto com propriedades do usuário. Campos comuns:

  | Campo     | Tipo   | Descrição        |
  | --------- | ------ | ---------------- |
  | `email`   | string | Email do usuário |
  | `name`    | string | Nome completo    |
  | `phone`   | string | Telefone         |
  | `plan`    | string | Plano/assinatura |
  | `company` | string | Nome da empresa  |
  | `role`    | string | Cargo ou função  |

  <Tip>Você pode enviar **qualquer propriedade customizada**. Elas serão salvas no perfil e podem ser usadas para segmentação.</Tip>
</ParamField>

### Exemplos práticos

<CodeGroup>
  ```javascript Após login theme={null}
  function onLoginSuccess(user) {
    __SmartTrack.setExternalUserContext(user.id, {
      email: user.email,
      name: user.name,
      plan: user.subscription?.plan,
      createdAt: user.createdAt
    });
  }
  ```

  ```javascript Após cadastro theme={null}
  function onSignupComplete(newUser) {
    __SmartTrack.setExternalUserContext(newUser.id, {
      email: newUser.email,
      name: newUser.fullName,
      source: 'organic',
      trial: true
    });
  }
  ```

  ```javascript E-commerce theme={null}
  function onCheckout(customer) {
    __SmartTrack.setExternalUserContext(customer.id, {
      email: customer.email,
      name: customer.name,
      totalOrders: customer.orderCount,
      ltv: customer.lifetimeValue,
      lastPurchase: new Date().toISOString()
    });
  }
  ```
</CodeGroup>

<div className="callout-blue">
  Chame `setExternalUserContext` **uma vez** por sessão (após login ou cadastro). Chamadas repetidas atualizam o perfil, não criam duplicatas.
</div>

<Tip>
  **Quando identificar?** O melhor momento é logo após a autenticação. Se o usuário já está logado ao entrar no site (sessão persistente), chame o método no carregamento da página.
</Tip>

***

## 2. Capturar formulários

O tracker captura envios de formulários automaticamente. Nenhum código extra é necessário para a captura padrão.

### Configurar estratégia de captura

Se você precisa de controle sobre quais formulários são capturados:

```javascript theme={null}
__SmartTrack.forms({
  strategy: 'auto',
  trigger: 'submit',
  excludeFields: [
    'password',
    'credit-card',
    'cvv',
    'ssn'
  ]
});
```

### Estratégias disponíveis

| Estratégia  | Comportamento                                         |
| ----------- | ----------------------------------------------------- |
| `auto`      | Captura todos os formulários automaticamente (padrão) |
| `whitelist` | Captura **apenas** formulários específicos            |
| `blacklist` | Captura todos, **exceto** os especificados            |
| `disabled`  | Desativa captura de formulários                       |

### Exemplo: apenas formulários específicos

```javascript theme={null}
__SmartTrack.forms({
  strategy: 'whitelist',
  include: ['#form-contato', '#form-newsletter', '.form-lead'],
  trigger: 'submit'
});
```

<div className="callout-blue">
  **Privacidade primeiro:** campos sensíveis como `password`, `credit-card` e `cvv` são **excluídos automaticamente** por padrão, independente da estratégia escolhida.
</div>

***

## 3. Rastrear eventos customizados

Envie eventos específicos do seu negócio para a UserIn:

```javascript theme={null}
__SmartTrack.customEvent('nome_do_evento', {
  // propriedades opcionais
});
```

### Exemplos por vertical

<Tabs>
  <Tab title="E-commerce">
    ```javascript theme={null}
    // Produto visualizado
    __SmartTrack.customEvent('product_viewed', {
      productId: 'SKU-123',
      productName: 'Camiseta Premium',
      category: 'Vestuário',
      price: 89.90
    });

    // Adicionou ao carrinho
    __SmartTrack.customEvent('add_to_cart', {
      productId: 'SKU-123',
      quantity: 2,
      cartTotal: 179.80
    });

    // Compra finalizada
    __SmartTrack.customEvent('purchase_completed', {
      orderId: 'ORD-456',
      total: 179.80,
      items: 2,
      paymentMethod: 'credit_card'
    });
    ```
  </Tab>

  <Tab title="SaaS">
    ```javascript theme={null}
    // Feature utilizada
    __SmartTrack.customEvent('feature_used', {
      feature: 'export_report',
      plan: 'pro'
    });

    // Upgrade de plano
    __SmartTrack.customEvent('plan_upgraded', {
      from: 'free',
      to: 'pro',
      mrr: 99.00
    });

    // Onboarding completado
    __SmartTrack.customEvent('onboarding_completed', {
      steps: 5,
      durationMinutes: 12
    });
    ```
  </Tab>

  <Tab title="Lead Generation">
    ```javascript theme={null}
    // Lead qualificado
    __SmartTrack.customEvent('lead_qualified', {
      score: 85,
      source: 'landing_page',
      interest: 'plano_enterprise'
    });

    // Demo agendada
    __SmartTrack.customEvent('demo_scheduled', {
      date: '2026-03-15',
      salesRep: 'joao@empresa.com'
    });

    // Proposta enviada
    __SmartTrack.customEvent('proposal_sent', {
      value: 4500.00,
      plan: 'enterprise'
    });
    ```
  </Tab>

  <Tab title="Conteúdo / Blog">
    ```javascript theme={null}
    // Artigo lido
    __SmartTrack.customEvent('article_read', {
      title: 'Como aumentar conversões',
      category: 'Marketing',
      readTimeSeconds: 240
    });

    // Newsletter assinada
    __SmartTrack.customEvent('newsletter_subscribed', {
      source: 'blog_sidebar'
    });

    // Conteúdo compartilhado
    __SmartTrack.customEvent('content_shared', {
      platform: 'linkedin',
      url: window.location.href
    });
    ```
  </Tab>
</Tabs>

***

## 4. Eventos comportamentais avançados

Além dos eventos padrão, você pode ativar rastreamento comportamental avançado:

```javascript theme={null}
__SmartTrack.events({
  idle: true,
  rageClick: true,
  keyboardUsage: true,
  hoverFrequency: true,
  clipboardUsage: true
});
```

| Evento           | O que detecta                                                 |
| ---------------- | ------------------------------------------------------------- |
| `idle`           | Visitante ficou inativo na página                             |
| `rageClick`      | Cliques frustrados (muitos cliques rápidos no mesmo elemento) |
| `keyboardUsage`  | Padrões de uso do teclado                                     |
| `hoverFrequency` | Frequência de hover sobre elementos                           |
| `clipboardUsage` | Uso de copiar/colar                                           |

<Tip>
  **Para ativar todos os eventos de uma vez:**

  ```javascript theme={null}
  __SmartTrack.events('all');
  ```
</Tip>

***

## Métodos úteis

Referência rápida de métodos disponíveis no objeto `__SmartTrack`:

| Método                | Retorno          | Descrição                       |
| --------------------- | ---------------- | ------------------------------- |
| `getLocalStorageId()` | `string`         | ID persistente do visitante     |
| `getSessionId()`      | `string`         | ID da sessão atual              |
| `getExternalId()`     | `string \| null` | ID externo (após identificação) |
| `getCompanyId()`      | `string`         | ID do projeto na UserIn         |

***

## Próximo passo

Com os dados conectados, verifique se tudo está funcionando corretamente.

<Card title="Verificar Integração" icon="circle-check" href="/onboarding/verificar-integracao">
  Confirme que os dados estão chegando e veja seus primeiros visitantes na plataforma.
</Card>