> For the complete documentation index, see [llms.txt](https://docs.agnosticdata.ai/agnosticdata.ai-or-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agnosticdata.ai/agnosticdata.ai-or-documentation/fundamentals/features/postbacks.md).
# Postbacks
Configurações do projeto
## Conceito
A funcionalidade de **postback** é crucial para garantir o rastreamento eficiente de eventos em campanhas de marketing e integração com terceiros.
Quando um evento específico, como uma conversão ou ação do usuário, ocorre, os dados relevantes — incluindo informações detalhadas como UTM parameters — são enviados automaticamente para uma URL pré-definida.
Os postbacks permitem que as equipes de marketing acompanhem com precisão o desempenho de campanhas, otimizem estratégias de aquisição e atribuam corretamente os resultados aos canais e campanhas corretos mesmo com ferramentas de hospedagem ou análise dos eventos diferentes, mas com a precisão da mesma ferramenta coleta.
### Como funciona, o básico.
A **funcionalidade de postback** permite que o sistema dispare uma requisição HTTP POST para uma URL específica sempre que um evento X ocorrer. Essa requisição inclui dados e parâmetros UTM, facilitando a integração com plataformas de análise e marketing. A implementação dessa funcionalidade garante que os dados de eventos sejam transmitidos de forma automática e em tempo real para a URL alvo, possibilitando o rastreamento preciso e a integração entre diferentes sistemas.
Processo de definição para os disparos Postback (útil para integração ou envio de eventos a terceiros)
### Entendendo as regras: Postback Rules (url)
Permite enviar um evento de volta (Postback) para um URL de destino baseado em:
1. rota
2. evento de página e
3. parâmetros de URL.
Vamos detalhar o que cada parte dessa configuração representa e como ela poderia ser utilizada em uma implementação prática.
**Exemplo de regras aplicadas em um payload JSON:**
```javascript
[
{
"url_target": "http://localhost:8080/test", // rota alvo para ação
"utm_case_strategy": "any", // pode ser 'any', 'now', 'before'
"utm_case_target": {
"utm_source": "agnostic", // Valores como 'utm_medium' e 'utm_campaign' também podem ser configurados
},
"triggedByEvent": "agScriptLoaded", // agScriptLoaded, popstate, load, etc.
"to_request": {
"type": "IMAGE", // Pode ser 'IMAGE', 'GET', 'POST', 'PUT', 'DELETE'
"url": "https://tracking.youragency.com/routeX",
"add_params": {
"offer_id": "40",
"aff_id": "1"
},
"pinch": [
{ "from": "utm_case", "item": "utm_source", "name": "utm_source" },
{ "from": "utm_case", "item": "my_name", "name": "customer" },
{ "from": "utm_case", "item": "abc", "name": "paramX" }
]
}
}
]
```
Então temos:
**Descrição dos componentes das Regras**
* **`url_target`**: URL alvo onde o postback deve ser iniciado ou a ação deve ser realizada. É o domínio mais o caminho relativo sem necessadade dos parâmetros de url (querystring).
* Exemplos:
* ou [www.uol.com.br/esportes](http://www.uol.com.br/esportes) (para ambos http ou https)
*
* **`utm_case_strategy`**: Define a estratégia de quando aplicar a regra consideranto as variáveis em [Histórico](/agnosticdata.ai-or-documentation/fundamentals/estrategias-de-atribuicao.md#estrategias) ou exatamente na URL.
* now: aplicado para utilizar apenas os parâmetros de URL quando estão realmente na URL.
* before: aplicado para utilizar apenas os parêmtros em histórico independentemente da URL. Lembrando todas as variáveis são armazenadas em histórico até o "reset" dos [determinantes](/agnosticdata.ai-or-documentation/fundamentals/estrategias-de-atribuicao.md).
* any: aplicado para ambos os casos, qualquer que seja os parâmetros disponíveis serão utilizados.
* **`utm_case_target`**: Especifica os parâmetros UTM que devem ser atendidos para que a regra seja aplicável.
* **`triggedByEvent`**: Especifica o(s) evento(s) que disparam a regra, como o carregamento de um script ou mudanças de visibilidade sendo eles: `DOMContentLoaded, load, popstate, visibilitychange, beforeunload.`
* **`to_request`**: Define como a requisição deve ser feita, incluindo o tipo (imagem, GET, POST, etc.), a URL e quaisquer parâmetros adicionais.
* **`type`**: Método da requisição.
* **`url`**: Endereço da requisição. É rota para onde deve ser enviado o postback,
* Exemplo: `https://tracking.youragency.com/aff_goal`
* **`add_params`**: Parâmetros adicionais que devem ser incluídos na requisição.
* **`pinch`**: Extração de dados de contexto do AgnosticData (ou "pinching") que são adicionados à requisição.
* **`from`**: De onde os dados devem ser extraídos (e.g., 'utm\_case').
* **`item`**: Qual item deve ser extraído.
* **`name`**: Nome sob o qual o item extraído deve ser incluído na requisição. (e pode ser renomeado)
