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

# Atribuição

> Classifique o tráfego em canais com regras que você controla e reescreva o histórico quando alterá-las.

![Seção Filtros com as regras de atribuição listadas por prioridade, com suas condições, operações e tags](https://www.notifuse.com/docs/assets/screenshots/web_analytics/filters.png)

Toda visita chega com sinais brutos: um referenciador, alguns parâmetros UTM, talvez um ID de clique de anúncio. As regras de atribuição transformam esses sinais em um **Canal** e um **Grupo de canais** que você pode usar nos relatórios.

O seu próprio site nunca é um desses sinais: um referenciador no mesmo host da página de destino é descartado, e a visita é registrada como **direto**. Uma sessão termina após 30 minutos de inatividade. Assim, um visitante que volta a uma aba, ou que clica em algo depois de uma leitura longa, abre uma nova sessão com uma das suas próprias páginas como referenciador. Outro host é um referenciador de verdade e é mantido: `docs.example.com` com um link para `www.example.com` aparece nos seus relatórios.

## Regras padrão

Um workspace novo começa com 40 regras que cobrem busca paga, social pago, vídeo pago, display, busca orgânica, social orgânico, email e tráfego direto. São regras comuns: você pode editar ou excluir qualquer uma delas.

| Prioridade | Família                                                                    |
| ---------- | -------------------------------------------------------------------------- |
| 900 a 831  | Pago, identificado pelo ID de clique do anúncio                            |
| 830 a 770  | Pago, identificado por uma origem UTM conhecida junto com um meio UTM pago |
| 760        | Display pago, identificado pelo referenciador                              |
| 750        | Direto, declarado por `utm_source=direct` e `utm_medium=none`              |
| 745        | Email                                                                      |
| 740        | Tráfego direto: sem referenciador _e_ sem parâmetros de campanha           |
| 705 a 650  | Busca orgânica                                                             |
| 600 a 510  | Social orgânico                                                            |
| 10         | Regra de último recurso (`not-mapped`)                                     |

> [!NOTE]
>
> O Email fica acima do Tráfego direto de propósito. Muitos clientes de email removem o referenciador, e um clique vindo de um email pareceria alguém digitando o seu endereço. Por isso os seus broadcasts devem levar parâmetros UTM.

> [!WARNING]
>
> Não existe regra pré-configurada para tráfego de **referência**. Um clique simples em um link de outro site não corresponde a nenhuma regra e cai em `not-mapped`, de propósito: ele aparece na aba Filtros, onde você classifica esses referenciadores uma única vez, em vez de ficar arquivado sem que ninguém perceba. Adicione a sua própria regra sobre Referrer Domain quando quiser um canal de referência.
>
> Pelo mesmo motivo, as regras de UTM pago exigem uma origem _conhecida_ além de um meio pago: `utm_medium=cpc` vindo de uma rede para a qual o Notifuse não traz regra cai em `not-mapped` em vez de ser classificado como pago.

## Como as regras são aplicadas

As regras rodam por prioridade, da mais alta para a mais baixa, e **toda regra que corresponde contribui**: a avaliação não para na primeira correspondência.

A precedência vale por alvo, não por regra:

- Para cada alvo, vence a regra de maior prioridade que o grava.
- Uma regra de prioridade menor ainda pode gravar um alvo que nenhuma regra de prioridade maior reivindicou. Por isso, uma regra que só define `custom_3` se aplica mesmo quando uma regra de prioridade maior já definiu o canal.
- Duas regras que correspondem com a _mesma_ prioridade rodam as duas, e a última sobrescreve: um empate fica com a última regra, não com a primeira.
- `set as default` nunca reivindica um alvo, então um `set` de prioridade menor ainda substitui um valor padrão gravado antes. É assim que funciona a regra de último recurso de prioridade 10.

## Como escrever uma regra

Uma regra é um conjunto de condições e os valores a gravar quando todas elas correspondem. Uma regra sem condições sempre corresponde, como a Default Channel pré-configurada, e pode ser salva assim.

![Edição da regra iPhone General: detalhes, uma condição regex em Landing Path ao lado de uma operação que define Product line, a ordem das regras, as verificações, um Teste rápido que corresponde e o card Quando se aplica](https://www.notifuse.com/docs/assets/screenshots/web_analytics/edit_rule.png)

- **Condições** testam qualquer sinal rastreado: o referenciador, o domínio e o caminho do referenciador, is-direct, a página, o domínio e o caminho de destino, o caminho atual, todos os parâmetros UTM e o ID de clique do anúncio, além de dispositivo, navegador, tipo de navegador, sistema operacional, user agent, tipo de conexão, idioma e fuso horário.
- **Operadores** são `equals`, `not equals`, `contains`, `not contains`, `is empty`, `is not empty` e `regex`.
- **Operações** então aplicam `set` a um valor, aplicam `set` apenas como _padrão_, onde nada mais gravou um valor, ou aplicam `unset`.
- **Alvos** são Channel, Channel Group, qualquer um dos cinco campos UTM, Referrer Domain, Is Direct e de `custom_1` a `custom_10`.

Uma regra que grava uma dimensão personalizada classifica um tráfego que você não conseguiu marcar na origem: o referenciador de um parceiro pode virar o nome desse parceiro, sem pedir que ele adicione parâmetros.

### O editor de regras

**Adicionar**, ou o botão de edição de uma regra na aba Filtros, abre o editor em largura total. A barra mostra o nome e a prioridade da regra, **Alterações não salvas** assim que você a edita, e os botões **Descartar** e **Salvar alterações** (**Criar regra** para uma regra nova).

- **Detalhes**: nome, prioridade de 0 a 1000, ativação e tags.
- **Condições** e **Operações** ficam lado a lado em uma tela larga.
- **Ordem das regras** lista as regras que também gravam as dimensões que esta regra grava, na ordem em que rodam (maior prioridade primeiro; prioridades iguais na ordem da lista), com o que cada uma lê e grava, duas de cada lado desta regra. **Mostrar todas as regras** lista todas.
- **Verificações** se atualizam enquanto você digita:
  - se toda condição e toda operação "set" têm um valor, e **Sempre corresponde** para uma regra sem condições;
  - cada expressão regular: válida, recusada pelo servidor (um lookaround ou uma referência retroativa), inválida e talvez recusada ao salvar, ou escrita em uma sintaxe que só o mecanismo RE2 do servidor lê, como `\A`, `\z`, `\Q…\E`, `\p{…}`, `[[:alpha:]]` ou `(?U)`. O navegador não consegue testar esse último tipo; o servidor o verifica ao salvar;
  - as regras ativadas que **rodam antes** e podem impedir esta regra de gravar uma dimensão, e as que **rodam depois** e podem sobrescrevê-la. Para uma regra desativada, a verificação diz que ela não roda e não grava nada.
- **Teste rápido** pede apenas os campos que a regra lê e mostra o resultado de cada condição para essa visita, além dos valores que a regra grava quando corresponde. Nada é salvo nem enviado. **Abrir testador** leva a visita para o [testador de regras](#test-your-rules).
- **Quando se aplica**: às sessões novas a partir do momento em que você salva, às sessões anteriores depois de um [reprocessamento](#changing-rules-later), e o status do último reprocessamento.

A tecla Esc não fecha o editor, e fechá-lo com alterações não salvas pede confirmação antes de descartá-las. Membros sem permissão de escrita no Web Analytics abrem as regras somente para leitura: o formulário fica desativado, o botão de salvar explica o motivo, e o Teste rápido continua funcionando.

## Teste suas regras

![Testar todas as regras, preenchido a partir de uma URL de destino com parâmetros UTM e um gclid: os campos UTM e Páginas preenchidos, e as regras que correspondem com os valores que cada uma grava](https://www.notifuse.com/docs/assets/screenshots/web_analytics/rule_tester.png)

O testador passa uma visita que você descreve pelas regras, no seu navegador, e atualiza os resultados enquanto você digita. Nada é salvo nem enviado. **Testar** na aba Filtros roda todas as regras salvas; **Abrir testador** no editor roda a regra que você está editando, incluindo as alterações não salvas, partindo dos valores do Teste rápido.

Os campos da visita ficam agrupados por tipo, com a quantidade preenchida em cada grupo. Campos vazios contam como valores vazios. **Limpar visita** esvazia os campos, e fechar o testador descarta a visita.

**Começar a partir de um link** preenche os campos a partir de uma URL de destino: Landing Page, Landing Domain, Landing Path e Current Path, os cinco parâmetros UTM, e UTM ID e UTM ID From a partir do primeiro [ID de clique de anúncio](#ad-click-ids) presente. Os campos de referenciador e de dispositivo ficam como você os digitou.

- Um link sem esquema é lido como `https://`. Qualquer endereço que não seja http ou https é recusado.
- Só os treze IDs de clique padrão são reconhecidos. Um link com um ID de clique que você adicionou com `extraAdClickIds` deixa UTM ID vazio aqui, e você precisa digitá-lo.
- Um `%` que não é seguido de dois dígitos hexadecimais no caminho ou no fragmento, como em `/50%off`, torna o link malformado: o servidor não consegue lê-lo e registra um domínio e um caminho de destino vazios. O testador também os deixa vazios e explica o motivo.

Ao testar todas as regras, o testador as distribui em abas, da maior prioridade para a menor, cada uma com o resultado de cada condição para a visita:

| Aba                  | Regras                                                                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Correspondem**     | Regras ativadas cujas condições correspondem todas, com os valores que cada uma grava.                                                      |
| **Não correspondem** | Regras ativadas com uma condição que falha.                                                                                                 |
| **Não testáveis**    | Regras ativadas que nenhuma condição exclui, mas com uma expressão regular que só o servidor lê. A aba só aparece quando há uma regra nela. |
| **Desativado**       | Regras que nunca rodam, seja qual for a correspondência.                                                                                    |

> [!NOTE]
>
> O testador mostra o que cada regra que corresponde grava por conta própria. Ele não aplica a [precedência](#how-rules-are-applied) para chegar aos valores finais de Channel ou das dimensões: quando a regra de último recurso diz "default to `not-mapped`" ao lado de uma regra que define `google-ads`, a visita termina como `google-ads`.

## IDs de clique de anúncio

O rastreador reconhece treze IDs de clique de anúncio na URL de destino, nesta ordem:
`gclid` (Google Ads), `fbclid` (Meta), `msclkid` (Microsoft), `dclid` (Google
Display), `twclid` (X), `ttclid` (TikTok), `li_fat_id` (LinkedIn), `wbraid` e
`gbraid` (Google Ads), `epik` (Pinterest), `ScCid` (Snapchat), `rdt_cid` (Reddit)
e `qclid` (Quora).

O primeiro presente vai para `utm_id`, e o parâmetro de onde ele veio vai para
`utm_id_from`. Assim, um clique pago pode ser atribuído mesmo quando a campanha
esqueceu os UTMs. "Primeiro" quer dizer primeiro nessa lista, não primeiro na URL:
um link com `gclid` e `fbclid` é atribuído ao Google.

A correspondência ignora maiúsculas e minúsculas: `?sccid=`, `?ScCid=` e `?SCCID=`
são todos reconhecidos, e `utm_id_from` sempre registra a grafia canônica acima,
que é a usada pelas regras integradas.

> [!NOTE]
>
> Para capturar um ID de clique próprio **além** desses treze, defina
> `extraAdClickIds: ['myclid']` em `NotifuseAnalyticsConfig`. `adClickIds` também
> existe, mas **substitui** a lista inteira, e `adClickIds: []` não captura nenhum.
> Use essa opção só quando for isso que você quer. Uma regra que testa `utm_id_from`
> só dispara para um parâmetro que o rastreador foi configurado para capturar.

## Alterar as regras depois

As regras são aplicadas quando uma visita é registrada. Editá-las muda o que acontece daqui em diante, não o que já aconteceu. Para aplicá-las ao tráfego existente, execute um **reprocessamento** na aba Filtros.

Um reprocessamento reescreve as colunas de atribuição das linhas históricas de **sessão e meta**, o que atualiza a "receita por canal" do tráfego passado. Ele nunca adiciona, remove ou muda o horário do tráfego, e as linhas de visualização de página não são tocadas.

> [!WARNING]
>
> Um reprocessamento **apaga** Channel e Channel Group em toda linha que as suas regras não gravam.
> Esses dois só existem porque uma regra os definiu, então "nenhuma regra corresponde" quer dizer vazio.
>
> As dimensões personalizadas não são tocadas, porque o seu rastreador pode defini-las sem
> nenhuma regra. Uma regra que tem uma delas como alvo ainda reescreve as linhas que
> correspondem, e uma regra `unset_value` ainda as apaga, mas uma linha sem regra
> correspondente mantém o que o seu site enviou. Por isso, um valor personalizado gravado
> por uma regra continua lá depois que a regra é excluída, já que nada permite distingui-lo
> de um valor enviado pelo rastreador. Apague-o com uma regra `unset_value` temporária.

> [!WARNING]
>
> Só um reprocessamento roda por vez em cada workspace. Cancelar o interrompe onde ele está. As partições já reescritas mantêm os novos valores, então uma execução cancelada deixa os seus dados em um estado misto até você executá-la de novo.

## De onde vem o tráfego

Os broadcasts adicionam parâmetros UTM aos seus links (veja [Campanhas de broadcast → Rastreamento UTM](https://www.notifuse.com/pt/docs/features/broadcast-campaigns.md#utm-tracking)). A regra Email pré-configurada procura esses parâmetros, e o tráfego das campanhas é classificado sem trabalho extra.

## Observações

- A atribuição é definida por sessão, a partir da página de destino. Um visitante que chega por uma busca e depois clica em um dos seus emails abre uma nova sessão, com atribuição própria, quando a primeira termina.
- As metas partem da atribuição da sua sessão e depois rodam as regras de novo com o caminho da _própria_ página da meta. Uma meta corresponde à sua sessão, a menos que uma das suas regras teste o caminho atual.
- O conjunto de regras é versionado por um hash que o servidor recalcula a cada vez que você salva. O console o compara com a versão do último reprocessamento concluído para avisar quando o seu histórico foi atribuído com outro conjunto de regras. Um reprocessamento reescreve todas as linhas históricas, não só as desatualizadas.
- [Referência da API](https://www.notifuse.com/docs/api-reference.md)
