A mensuração de performance web também remapeia mais valores de PID para nomes de exibição, por exemplo, iossearchads_int para Apple Search Ads, metweb_int para Facebook Ads, twitterweb_int para Twitter, tiktokweb_int para tiktokglobal_int e snapweb_int para snapchat_int. Relatórios criados com base nos valores brutos antigos precisam considerar os novos.

A PBA resolveu três IDs de clique: gclid para googleadwords_int, dclid para doubleclick_int e msclkid para bingsearch_int.

A mensuração de performance web resolve muitos outros: gclid/wbraid/gbraid para googleadwords_int, msclkid para bingsearch_int, twclid para Twitter, vmcid para yahoogemini_int, sccid para snapchat_int, li_fat_id para linkedin_int, ttclid para tiktokglobal_int, tbclid para taboola_int, ob_click_id/dicbo para outbrain_int, yclid para yandex_int e rdt_cid para reddit_int.

O mapeamento personalizado de utm_source + utm_medium é mais amplo na mensuração de performance web: inclui mais sinônimos de mídia (paid, paid_search, paid-search etc.) e adiciona cobertura para TikTok, Snapchat e Pinterest, além das regras restritas de mídia única da PBA. Quando nenhuma regra personalizada corresponde, ambos usam como fallback o valor bruto de utm_source.

Os valores do canal também mudam de formato, de Direct / Organic search / Social media / Email / Ad / Referral / Other da PBA para os novos DIRECT / ORGANIC_SEARCH / SOCIAL_MEDIA / EMAIL / AD / REFERRAL / OTHER. Os filtros e agrupamentos baseados nos rótulos antigos precisam ser atualizados.

Para facilitar essa transição, preparamos um prompt pronto para uso para seu agente de codificação com IA (Claude Code, Cursor ou similar). Dê ao agente acesso ao seu código de ETL existente e cole o prompt abaixo; ele contém o mapeamento completo dos campos e todas as diferenças de comportamento. Isso orientará o agente a aprender seu pipeline atual e reconstruí-lo para o novo relatório.

Você está migrando um pipeline de ETL dos relatórios de dados brutos do Data Locker de PBA legado da AppsFlyer (visitas ao site + eventos do site) para o relatório de Mensuração de performance web do Data Locker da AppsFlyer (eventos do usuário final). Tudo o que você precisa está neste prompt: as mudanças estruturais, o mapeamento completo campo a campo e as etapas de validação. Não presuma nada além do que está escrito aqui; se algo estiver ambíguo, pergunte-me.

## Etapa 1: Aprenda o pipeline atual

Antes de escrever qualquer código, explore a base de código existente e produza um inventário:
1. Quais relatórios de PBA consumimos (visitas ao site, eventos do site ou ambos) e onde eles são ingeridos.
2. Cada campo de PBA que lemos e onde cada um é usado mais adiante (transformações, joins, dashboards, alertas, exportações).
3. A cadência de carga e as premissas de agendamento (PBA entregue diariamente).
4. Qualquer lógica que separe ou una linhas de visita e linhas de evento.
5. Quaisquer filtros, agrupamentos ou valores codificados de forma fixa com base em valores de campos de PBA (por exemplo, nomes de media_source, rótulos de canal, event_type, valores de plataforma).

Apresente este inventário e aguarde minha confirmação antes de prosseguir.

## Etapa 2: Faça-me estas perguntas

1. O novo relatório de eventos do usuário final já está habilitado no Data Locker (habilitado pela IU da AppsFlyer)? Se não, preciso habilitá-lo primeiro.
2. Qual é o Unified App ID do nosso novo Aplicativo web? Formato: "website-{domain}" (por exemplo, website-www.example.com). Se eu não souber, vou obtê-lo no dashboard da AppsFlyer antes de continuarmos.
3. Queremos um período de execução paralela (pipelines antigo e novo lado a lado, comparando as saídas) ou uma migração direta? Recomendo a execução paralela.
4. O novo pipeline também deve consumir o relatório de conversões (instâncias únicas de atribuição, sem linhas duplicadas) ou o relatório de eventos do usuário final multiplataforma (deduplicado por CUID, em nível de usuário de web + mobile)? O escopo padrão é o relatório de eventos do usuário final em nível de plataforma, sucessor direto dos relatórios de PBA.

## Mudanças estruturais a serem consideradas no design

1. **Um relatório em vez de dois.** O PBA separava visitas e eventos em dois relatórios. O novo relatório de eventos do usuário final contém ambos: visitas são linhas com end_user_event_type = 'SESSION' e eventos são linhas com end_user_event_type = 'IN_APP'. Somente as linhas IN_APP têm um event_name válido; nas linhas SESSION, event_name fica vazio (o PBA registrava "website visit" ali).
2. **Um único esquema em todas as plataformas.** O relatório é compartilhado entre o site, o mobile, a CTV e o PC. Sempre filtre plataforma = 'WEBSITE' para isolar os dados da web.
3. **Crédito de Atribuição duplo: deduplique.** A mesma ação pode aparecer duas vezes: uma linha de crédito primário e uma linha de crédito secundário (fonte de UA original, para LTV na visualização de UA). Filtre is_primary_attribution = true por padrão para evitar contagem em dobro. Remova o filtro apenas para análises dedicadas de visualização de UA vs. visualização de retargeting usando conversion_type.
4. **Por hora, não por dia.** O novo relatório é entregue por hora, com atualização dos dados em aproximadamente 2 horas. Reestruture as cargas incrementais em torno de lotes por hora, em vez de uma entrega diária.
5. **Orgânico vs. pago.** O media_type ("Paid") do PBA não existe mais. Usar o booleano is_organic; nunca deduza orgânico/pago de media_source.
6. **Contagem de usuários.** Conte e relacione os usuários com COALESCE(customer_user_id, appsflyer_id_value): primeiro o ID estável do usuário cliente e, como fallback, o ID baseado em cookie.
7. **Valores vazios.** Campos STRING são '', campos NUMERIC são NULL.

## Mapeamento campo a campo (PBA → eventos do usuário final)

Legenda de status: Inalterado = mesmo nome e mesmos dados. Renomeado = mesmos dados, nova coluna. Redefinido = alterações no formato de dados ou de valor (trate com cuidado). Descontinuado = sem equivalente.

| Campo do PBA | Status | Novo campo / tratamento |
|---|---|---|
| advertising_id | Descontinuado | ID de mobile/dispositivo. Os relatórios entre plataformas são baseados em CUID; descarte-o. |
| af_web_id | Renomeado | appsflyer_id_value, mesmo cookie da web. |
| amazon_aid | Descontinuado | ID de mobile/dispositivo, não relevante para a web. |
| android_id | Descontinuado | ID de mobile/dispositivo, não relevante para a web. |
| app_id | Descontinuado | Campo mobile entre plataformas. O novo identificador do Aplicativo web é unified_app_id ("website-{domain}"), um conceito diferente, não uma renomeação. |
| app_name | Inalterado | app_name. |
| app_version | Descontinuado | Campo mobile entre plataformas. |
| appsflyer_id | Descontinuado | ID de instalação mobile. Observação: o novo appsflyer_id_value é o cookie web (af_web_id da PBA), NÃO ESTE campo. |
| attributed_touch_time | Renomeado | event_time__attribution. |
| attributed_touch_type | Descontinuado | Era uma constante. Visit-vs-event agora fica em end_user_event_type. |
| bundle_id | Descontinuado | Substituído pelo agrupamento de Linha de produto no relatório multiplataforma. |
| campaign | Renomeado | campaign_name. |
| campaign_id | Inalterado | campaign_id. |
| city | Inalterado | city. |
| country_code | Inalterado | country_code. |
| customer_user_id | Inalterado | customer_user_id. |
| device_type | Renomeado + alteração nos valores | device_category, os valores diferem (por exemplo, "Desktop" → "MOBILE_PHONE" / valores no estilo "TV"). Atualize qualquer lógica baseada em valor. |
| dma | Inalterado | dma. |
| event_name | Redefinido | Eventos: inalterado. Visitas: agora está vazio (a PBA registrava "website visit"). Use end_user_event_type = 'SESSION' para identificar visitas. |
| event_revenue | Renomeado | revenue_value_original. |
| event_revenue_currency | Renomeado | revenue_currency_original. |
| event_revenue_usd | Renomeado | revenue_usd. |
| event_source | Inalterado | event_source. |
| event_time | Inalterado | event_time. |
| event_type | Redefinido | A marcação de "evento de conversão" não existe mais. Visit-vs-event fica em end_user_event_type (SESSION / IN_APP). |
| event_url | Inalterado | event_url, agora também é o principal local de onde os parâmetros de consulta da URL principal (UTMs etc.) são lidos. |
| event_value | Inalterado | event_value. |
| idfa / idfv / imei / oaid | Obsoleto | IDs de mobile/dispositivo, não relevantes para web. |
| install_time | Obsoleto | Campo de mobile. A hora de aquisição de usuário na web é event_time__conversion, um conceito separado. |
| ip | Renomeado | ip_address_value (mais ip_address_type para o método de hashing). |
| language | Redefinido | language, o formato muda para ISO 639-1 + código do país (antes era, por exemplo, "English"). |
| media_channel | Obsoleto | Pode ser coberto por sub_param_1-5, se necessário. |
| media_source | Inalterado | media_source (mas veja abaixo as renomeações de valor). |
| media_type | Obsoleto | Use o booleano is_organic no lugar. |
| original_url | Renomeado | Consolidado em event_url (nas visitas, event_url é igual à URL original). A coluna independente foi removida. |
| platform | Redefinido | platform é sempre "WEBSITE". O SO foi movido para os_version / user_agent. |
| postal_code | Inalterado | postal_code. |
| query_params | Obsoleto | A string de consulta bruta fica em event_url; a coluna de JSON analisado foi removida. Reimplemente a análise a partir de event_url, se necessário. |
| referrer | Renomeado | http_referrer. |
| region | Renomeado | continente, código do continente (por exemplo, "NA"). |
| state | Inalterado | state. |

## Mudanças nos valores de atribuição (atualize filtros e agrupamentos)

O mecanismo de atribuição resolve as fontes de tráfego de forma diferente, então alguns VALORES mudam mesmo quando os nomes dos campos não mudam:
- renomeações de media_source: doubleclick_int → dv360_int (display/vídeo do Google via UTM); "X Ads" → "Twitter" (Twitter via UTM). Mais valores de PID agora são remapeados para nomes de exibição (por exemplo, iossearchads_int → Apple Search Ads, metweb_int → Facebook Ads, tiktokweb_int → tiktokglobal_int, snapweb_int → snapchat_int).
- Os rótulos de canal mudam de formato: Direct / Organic search / Social media / Email / Ad / Referral / Other passam a ser DIRECT / ORGANIC_SEARCH / SOCIAL_MEDIA / EMAIL / AD / REFERRAL / OTHER.
- A cobertura de Click-ID foi expandida (mais networks são resolvidas a partir de IDs de clique); dclid sozinho não é mais resolvido; fbclid não é usado.

Verifique a base de código em busca de qualquer filtro, CASE, chave de join ou agrupamento de dashboard baseado nesses valores antigos e atualize-os.

## Etapa 3: Criar

1. Proponha o novo design de ETL (ingestão, esquema, lógica incremental por hora, os filtros obrigatórios de "Mudanças estruturais").
2. Após minha aprovação, implemente, reutilizando nossas convenções e infraestrutura existentes.
3. Para cada campo obsoleto que o inventário encontrar em uso em sistemas downstream, liste o consumidor e proponha uma resolução (remover, substituir pela alternativa sugerida ou sinalizar para o responsável pelo negócio).

## Etapa 4: Validar

1. Execute ambos os pipelines no mesmo intervalo de datas e compare: visitas (linhas SESSION) vs. visitas do site do PBA, eventos (linhas IN_APP) vs. eventos do site do PBA e totais de receita.
2. Espere diferenças, não igualdade: a nova lógica de atribuição é mais avançada, então as dimensões atribuídas (media_source, campaign) não corresponderão exatamente ao PBA. A lógica de contagem de sessão permanece inalterada (30 minutos de atividade), então espere que os volumes de visita permaneçam na mesma faixa.
3. Verifique se o filtro is_primary_attribution é aplicado em todos os lugares; a ausência dele aparece como contagens infladas de eventos.
4. Produza um breve relatório de migração: o que foi mapeado, o que foi removido, o que mudou nos valores e quaisquer itens em aberto para o responsável pelo negócio.

• As visitas agora são do lado do servidor. A S2S da PBA aceitava apenas eventos; as visitas precisavam vir do SDK web. O novo endpoint /visits permite que o site funcione totalmente do lado do servidor.
• Chega de chamada setcuid. A PBA exigia o SDK web, então era necessária uma chamada separada para vincular um CUID a um usuário web. A nova API carrega a identidade em linha em todas as solicitações, então essa etapa foi eliminada.
• Janela de dados atrasados. Envie eventos e visitas em tempo real, de preferência até 30 minutos após a ocorrência do evento, em vez de agrupá-los em um único upload diário. Os dados que chegam mais de 30 minutos após o fim do dia UTC em que o evento ocorreu ainda são aceitos, mas o horário do evento é substituído pelo horário em que a AppsFlyer os recebeu.

Se você reporta eventos pela API servidor a servidor da PBA, preparamos um prompt pronto para uso para seu agente de codificação com IA (Claude Code, Cursor ou similar). Dê ao agente acesso ao serviço que envia eventos para a AppsFlyer e cole o prompt abaixo; ele contém o endpoint completo e o mapeamento do payload. Ele orientará o agente a entender sua implementação atual e criar a versão atualizada.

Você está migrando uma integração do lado do servidor da API legada de eventos PBA Web S2S da AppsFlyer (webs2s.appsflyer.com) para a nova API S2S da AppsFlyer para Mensuração de performance web (events.appsflyer.com). Tudo o que você precisa está neste prompt: endpoints, autenticação, o mapeamento completo do payload e as mudanças de comportamento. Não presuma nada além do que está escrito aqui; se algo estiver ambíguo, pergunte-me.

## Etapa 0: Faça estas perguntas antes de alterar o código

1. Devemos modificar o serviço existente no local ou criar um novo serviço/módulo em paralelo a ele (permitindo execução paralela e uma transição limpa)? Recomende um novo módulo em paralelo.
2. Sei qual é o Unified App ID do nosso novo aplicativo web? Formato: "website-{domain}" (por exemplo, website-www.example.com). Ele substitui o bundle ID do PBA no caminho da URL. Se eu não souber, vou obtê-lo no dashboard da AppsFlyer antes de continuarmos.
3. Temos a nova chave de API S2S? A autenticação foi movida do webDevKey no corpo da solicitação para um cabeçalho Authorization que carrega esta chave. Se eu não a tiver, vou recuperá-la no dashboard da AppsFlyer.
4. Queremos enviar apenas eventos (como no PBA) ou adotar também o novo endpoint de visitas? A nova API oferece suporte a visitas do lado do servidor, então o site pode ser executado totalmente no servidor; o PBA aceitava apenas eventos.
5. O SDK web da AppsFlyer ainda está em execução no nosso site? (Isso determina se as visitas vêm do SDK e se precisamos deduplicar eventos entre o SDK e o S2S.)

## Etapa 1: Conheça o serviço atual

Explore a base de código e produza um inventário:
1. Todos os pontos de chamada para webs2s.appsflyer.com, as chamadas para /event e quaisquer chamadas para /setcuid.
2. Os campos preenchidos em cada chamada (customerUserId, afUserId, eventName, eventValue, eventRevenue, timestamp, referrer, userAgent, ip etc.) e de onde vêm seus valores.
3. Tratamento de erros e monitoramento baseados na resposta 200 OK.
4. Comportamento de repetição, processamento em lote e enfileiramento.

Apresente esse inventário para mim e aguarde minha confirmação antes de prosseguir.

## O que mudou: endpoints e autenticação

|  | PBA Web-S2S (antigo) | Nova API S2S |
|---|---|---|
| URL base | https://webs2s.appsflyer.com | https://events.appsflyer.com |
| Chamada de evento | POST /v1/{bundleId}/event | POST /v2/s2s/inapps/app/web/{appId} |
| Chamada de visita | Não disponível | POST /v2/s2s/visits/app/web/{appId} |
| Chamada de identidade | POST /v1/{bundleId}/setcuid | Nenhuma; a identidade fica embutida no objeto user_id em todas as chamadas |
| Identificador do aplicativo no caminho | bundleId (ID do bundle da marca) | appId = o Unified App ID web ("website-{domain}") |
| Autenticação | webDevKey no corpo JSON | Cabeçalho Authorization com a chave de API S2S |
| Tipo de conteúdo | application/json | application/json (415 se estiver ausente) |
| Resposta de sucesso | 200 OK | 202 Accepted |

## Mapeamento de campos do payload

| Campo do PBA | Novo campo | Observação |
|---|---|---|
| customerUserId | user_id.customer_user_id | Aninhado no objeto user_id. |\n| afUserId | user_id.appsflyer_id | Aninhado no objeto user_id. Envie pelo menos um entre customer_user_id e appsflyer_id; envie ambos sempre que o usuário estiver identificado. |\n| webDevKey | (removido) | A autenticação foi movida para o cabeçalho Authorization; o aplicativo é identificado por appId no caminho. |\n| eventType (sempre "EVENT") | (removido) | O endpoint (/inapps vs /visits) determina o tipo. |\n| eventName | event_name | 1-64 caracteres; não pode conter os caracteres @ = + -. |\n| timestamp (Unix ms) | timestamp (Unix ms) | Mesmo formato. Recomendado em todas as chamadas; se omitido, a AppsFlyer usa o horário de recebimento. |
| eventValue | event_value | Forma livre; oferece suporte a um subobjeto custom_parameters personalizado. |
| eventRevenue | event_revenue | Agora é opcional (o PBA exigia isso para dashboards). |
| eventRevenueCurrency | event_revenue_currency | Agora é opcional (o PBA exigia isso para dashboards). |
| referrer | http_referrer | Renomeado. |
| userAgent | user_agent | Renomeado. |
| ip | ip | Sem alterações. |
| (new) | event_url | Obrigatório em visitas; opcional em eventos. |
| (new) | customer_dedup_id | Desduplica em relação ao mesmo evento que chega de outra fonte (por exemplo, o SDK web). |
| (new) | email_hashed, phone_number_hashed, phone_number_e164_hashed, first_name_hashed, last_name_hashed | SHA256 (hexadecimal minúsculo de 64 caracteres) de valores normalizados, para enriquecimento de identidade. |

## Mudanças de comportamento e pontos de atenção

1. **appId é o ID unificado do aplicativo, não o "ID do SDK web".** A página de configurações do aplicativo na AppsFlyer mostra um UUID de "ID do SDK web" (a antiga Web Dev Key, mantida para continuidade do SDK). O caminho S2S deve conter o ID unificado do aplicativo ("website-{domain}"), nunca esse UUID. Um 401 "app not found" normalmente significa um appId incorreto no caminho ou um cabeçalho Authorization ausente/inválido.
2. **Sucesso é 202, não 200.** Atualize as verificações de integridade, as novas tentativas e os alertas de acordo com isso.
3. **Não valide em relação ao endpoint antigo.** O endpoint legado ainda pode retornar 200, mas essa resposta não é prova de que os dados chegaram ao Web Performance Measurement. Sempre verifique se os eventos realmente aparecem nos dados do novo aplicativo web.
4. **Elimine totalmente o fluxo setcuid.** A identidade é transmitida inline no objeto user_id em cada evento e visita.
5. **Visitas antes de eventos.** O sistema espera uma visita antes de qualquer evento de um usuário; eventos de um usuário sem visita anterior são classificados como orgânicos. As visitas vêm do SDK web ou, agora, do endpoint /visits.
6. **Envie em tempo real; não agrupe em lote.** Envie cada evento e visita conforme acontecem, de preferência em até 30 minutos após a ocorrência do evento. Dados que chegam mais de 30 minutos após o fim do dia em UTC em que o evento ocorreu ainda são aceitos, mas o horário do evento é substituído pelo horário de recebimento, o que distorce a atribuição. Sempre envie um timestamp. Observe que o atraso de atribuição de aproximadamente 30 minutos sobre o qual você pode ler é uma retenção separada, no lado do servidor, do lado da AppsFlyer, e não algo que precisamos implementar.
7. **Opção totalmente server-side (se adotarmos visitas).** Sem o SDK web, nosso servidor controla o identificador do usuário web: gere um ID estável para visitantes de primeira viagem, persista-o como um cookie HTTP first-party definido pelo servidor (cabeçalho Set-Cookie, não JavaScript; cookies JS têm limite de aproximadamente 7 dias no Safari), reutilize-o em todas as solicitações e envie-o como user_id.appsflyer_id. O payload da visita deve incluir event_url, e recomendamos também incluir ip, user_agent e http_referrer para a qualidade da atribuição.
8. **SDK + S2S juntos.** Se ambos enviarem o mesmo evento, preencha customer_dedup_id para que a AppsFlyer mantenha uma cópia.

## Etapa 2: Criar

1. Proponha o design: novo cliente/módulo, configuração (URL base, appId, armazenamento da chave de API no nosso gerenciador de segredos, nunca hardcoded), builders de payload para eventos (e visitas, se estiverem no escopo) e o tratamento de resposta/novas tentativas para 202.
2. Após minha aprovação, implemente isso seguindo nossas convenções existentes.
3. Mapeie cada campo do inventário usando o mapeamento de payload acima; sinalize qualquer campo que enviamos atualmente e que não tenha equivalente novo.

## Etapa 3: Validar

1. Envie um evento de teste (e visita, se estiver no escopo) e confirme uma resposta 202.
2. Verifique se os dados de teste aparecem no novo aplicativo web no AppsFlyer (dashboard ou Data Locker); esse é o verdadeiro sinal de sucesso, não a resposta HTTP.
3. Confirme se os nomes dos eventos estão em conformidade com as novas restrições (1-64 caracteres, sem @ = + -).
4. Se estiver em execução em paralelo com o serviço antigo, compare os volumes de eventos entre o antigo e o novo por alguns dias antes da migração e, em seguida, desative as chamadas antigas, incluindo setcuid.