# Postbacks
## 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)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.agnosticdata.ai/agnosticdata.ai-or-documentation/fundamentals/features/postbacks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.