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

# Metas

> Registre as conversões do seu site e use-as em segmentos e automações.

![Seção Metas com um card por meta, mostrando contagem, taxa de conversão, valor total e valor mediano em relação ao período anterior](https://www.notifuse.com/docs/assets/screenshots/web_analytics/goals.png)

Uma meta é algo que vale a pena contar: um cadastro, uma compra, um pedido de demonstração. O seu site a informa, e o Web Analytics a registra na visita que a gerou.

## Registrar uma meta

```javascript
NotifuseAnalytics.trackGoal({ action: 'purchase', type: 'purchase', value: 49.9 })
```

| Campo        | Obrigatório | Observações                                                                                                         |
| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `action`     | Sim         | O nome da meta, com até 100 bytes (100 caracteres ASCII, menos para texto com acentos ou não latino).               |
| `type`       | Sim         | O tipo de conversão: `purchase`, `subscription`, `lead`, `signup`, `booking`, `trial` ou `other`.                   |
| `value`      | Não         | Um número não negativo: a receita, ou o que você estiver somando.                                                   |
| `properties` | Não         | Até 50 valores seus, com 1024 bytes por valor e 8 KB no total, chaves incluídas. Eles são armazenados como strings. |

`type` é obrigatório porque só o seu site sabe se uma conversão é uma venda ou
um lead, e as condições de segmento baseadas em metas filtram por ele. `trackGoal`
rejeita a chamada quando `type` está ausente ou não é um desses valores, em
minúsculas. Por isso, capture o erro se você espera `trackGoal` antes de
redirecionar. Use `other` quando nenhum dos outros servir.

O caminho da página atual e a posição dela na visita são anexados automaticamente, então uma meta sempre sabe onde aconteceu.

> [!NOTE]
>
> As metas são enviadas na hora, sem esperar o próximo heartbeat. Uma conversão em uma página que o visitante está prestes a deixar ainda chega.

> [!WARNING]
>
> Um `value` negativo invalida a meta inteira: a meta é descartada, com nome e tudo, e não só o número. A API de [eventos personalizados](https://www.notifuse.com/pt/docs/features/custom-events.md) funciona de outro jeito aqui: ela aceita valores negativos de propósito, para reembolsos e estornos.

Você não precisa declarar as metas antes em lugar nenhum. A aba Metas lista os nomes que o seu site enviou, ordenados por conversões, e mostra até as 30 metas com mais conversões no período e com os filtros que você aplicou.

### Valores vindos de um gerenciador de tags ou de JavaScript puro

Um snippet ou um gerenciador de tags costuma passar valores lidos da página, por isso `trackGoal` converte os tipos mais comuns para você:

- Um `value` passado como string escrita como um número JSON, como `'49.90'` ou `'120'`, é armazenado como número. `'49,90'`, `'1,299.00'`, `'€49.90'` e `'.5'` não são, e uma meta assim fica de fora, como descrito abaixo.
- Um `value` igual a `NaN` (o que `parseFloat('€49.90')` retorna), a um número infinito, a `null` ou a uma string vazia registra a meta sem valor e sem aviso. A aba Metas e os relatórios contam uma meta assim como 0 nos valores médio e mediano.
- Números e booleanos em `properties` são armazenados como strings, e um `Date` como a sua string ISO. `null`, `NaN`, um número infinito e um `Date` inválido são armazenados como string vazia, e uma entrada `undefined` fica de fora.
- Quando `properties` é `false`, `''` ou `0`, como `coupon && { coupon }` retorna quando não há cupom, a meta é registrada sem propriedades.

Uma meta cujos dados ainda não podem ser registrados fica de fora, com um aviso no console do navegador. A chamada ainda é resolvida, então uma página que espera `trackGoal` antes de redirecionar continua redirecionando. Isso vale para um `action` ausente, em branco, que não é string ou que passa de 100 bytes; um `value` que não é número ou está fora do intervalo de 0 a 1e12; e `properties` que são um array, uma string não vazia, `true` ou um número diferente de `0` e `NaN`, que contêm um objeto ou um array, ou que passam dos limites acima. O resto da visita continua sendo registrado.

Um `Map`, um `FormData` ou um `URLSearchParams` não tem campos próprios. Uma meta que recebe um deles em `properties` é registrada sem propriedades e sem aviso: passe `Object.fromEntries(…)` dele, deixando de fora qualquer campo de arquivo, cujo valor é um objeto.

## O que uma meta produz

O ícone de olho no card de uma meta abre o dashboard dela em largura total. Todos os números nele contam apenas as conversões dessa meta.

![Dashboard da meta add_to_cart: botões de meta anterior e seguinte, o período comparado, a faixa Contagem, Taxa de conv., Valor Total e Valor Mediano, um gráfico diário com anotações, um mapa de calor por dia e hora, e os cards Principais Origens, Principais Campanhas e Dispositivos](https://www.notifuse.com/docs/assets/screenshots/web_analytics/goal_dashboard.png)

- **A barra** volta para Metas, passa para a meta anterior ou seguinte da grade com as setas ou com **K** e **J**, e mostra o período e o período com que ele é comparado. Os dois são definidos na aba Metas.
- **Filtrado por** lista os filtros aplicados, e cada um pode ser removido. São os filtros de toda a seção Web Analytics: clicar em uma linha ou em um país no dashboard também adiciona um filtro lá.
- **A faixa de KPIs** mostra Contagem, Taxa de conv., Valor Total e Valor Mediano em relação ao período de comparação. Clicar em Contagem, Valor Total ou Valor Mediano exibe o gráfico desse número.
- **Taxa de conv.** é o número de conversões da meta dividido pelas sessões do período, como no card da meta. Ela conta eventos de meta, não sessões com conversão: uma meta atingida duas vezes em uma sessão conta duas vezes, e a taxa pode passar de 100%. A dica de ferramenta avisa que ela inclui todo o tráfego, seja qual for o motivo da visita.
- **O gráfico** segue a granularidade que você escolhe nele e mostra as suas [anotações](https://www.notifuse.com/pt/docs/web-analytics/annotations.md), ao lado de um mapa de calor da meta por dia e hora.
- **Os cards** detalham as conversões e o valor delas: Principais Origens (referenciadores, canais, grupos de canais), Principais Campanhas (campanhas, origens, meios, sem as conversões que não têm campanha), Dispositivos (dispositivos, navegadores, sistemas operacionais), Países (mapa e lista), Páginas de destino (páginas de destino e páginas de meta), e um card para as suas dimensões personalizadas que têm nome.

Nos relatórios, as metas oferecem as medidas Goals, Total Goal Value, Avg Goal Value, Median Goal Value e Converting Sessions, e as dimensões Goal Name, Goal Path e Goal Value. No nível da sessão, Sessions with Goals e Goal Value permitem comparar canais por conversões em vez de tráfego.

Para um visitante **identificado**, uma meta também vira um evento personalizado na linha do tempo do contato, o que a torna acessível a segmentos e automações. Veja [Identificar visitantes](https://www.notifuse.com/pt/docs/web-analytics/identifying-visitors.md).

## Nomes de meta na linha do tempo do contato

Uma meta que chega à linha do tempo de um contato é normalizada antes: passa para minúsculas, cada sequência de caracteres fora de `a–z`, `0–9`, `.` e `/` em ASCII vira um único `_`, os `_` do início e do fim são removidos, e o resultado é cortado em 100 caracteres. Assim, `Trial Started` chega como `trial_started`, e é com esse nome que uma automação ou um segmento faz a correspondência.

> [!WARNING]
>
> O conjunto mantido é só ASCII, então letras acentuadas e não latinas são removidas em vez de transliteradas: `Café` chega como `caf`. Um nome sem nenhuma letra ou dígito ASCII, como `購入`, fica vazio depois da normalização e nunca chega à linha do tempo. A meta continua sendo registrada e aparece nos relatórios; só a cópia na linha do tempo é pulada. Use nomes de meta em ASCII se você segmenta ou automatiza com base neles.
>
> Essa regra também é mais restrita que a regra de nomes dos eventos enviados pela API de [eventos personalizados](https://www.notifuse.com/pt/docs/features/custom-events.md), que permite hífens: `black-friday` enviado por uma meta web vira `black_friday`.

## Usar metas web em segmentos

Uma meta web traz as mesmas três informações que um evento personalizado criado pela
API: um nome, um valor e um tipo.

- A condição **Custom Events Goal** corresponde às metas web, de um tipo específico ou
  de **All types**, e conta, soma e calcula a média do valor delas.
- Uma **automação** pode ser disparada por um evento personalizado com o nome normalizado da meta.

> [!NOTE]
>
> O tipo é declarado pelo seu site, não verificado pelo Notifuse, e a mesma página
> também escolhe o nome e o valor da meta. Leia os relatórios de receita com isso em mente,
> como faria com eventos enviados pela API.

## Limites

- Até 100 metas de uma sessão são levadas para a linha do tempo do contato por lote de gravação. As metas além disso no mesmo lote ficam fora da linha do tempo para sempre, e o contador recomeça a cada lote. Uma visita longa que continua convertendo pode, assim, acabar com mais de 100 entradas na linha do tempo no total. A visita em si continua sendo registrada; o limite só afeta a cópia na linha do tempo.
- Uma meta com mais de 24 horas não é levada para a linha do tempo. Um visitante cujo navegador ficou offline por um dia volta com a visita intacta, sem disparar com um dia de atraso automações do tipo "você acabou de fazer isto".
- Uma meta com valor acima de 1e12, nome com mais de 100 bytes, propriedades com mais de 50 chaves, 1024 bytes em um valor ou 8 KB no total com as chaves, uma propriedade que contém um objeto ou um array, ou um caractere NUL (`\u0000`) no nome ou nas propriedades é descartada: só a meta, nunca o resto da visita.

## Observações

- As metas de visitantes anônimos são registradas e aparecem nos relatórios normalmente. Só a cópia na linha do tempo precisa de uma identidade.
- Os eventos levados para a linha do tempo trazem o contexto da visita como propriedades (ID da sessão, caminho, caminho de destino, origem, meio e campanha UTM, dispositivo e país), ao lado das suas. Essas chaves são definidas pelo Notifuse e sobrescrevem as propriedades com o mesmo nome.
- Uma moeda, um ID de pedido ou qualquer outra informação da conversão vai em `properties`, que são enviadas e armazenadas. Não existe um campo `currency` dedicado: `goal_value` é um número simples. Se você registra mais de uma moeda, agrupe os relatórios pela propriedade de moeda em vez de somar valores de moedas diferentes.
- [Referência da API](https://www.notifuse.com/docs/api-reference.md)
