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

Você está migrando um pipeline de ETL dos relatórios de dados brutos do PBA legado do Data Locker da AppsFlyer (visitas ao site + eventos do site) para o relatório de Data Locker de Mensuração de Performance Web 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 suponha 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 PBA consumimos (visitas ao web, eventos do web ou ambos) e onde eles são ingeridos.
2. Todos os campos PBA que lemos e onde cada um é usado adiante (transformações, junções, 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 PBA (por exemplo, nomes de media_source, rótulos de canal, event_type, valores de plataforma).

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

## Etapa 2: Faça estas perguntas para mim

1. O novo relatório End User Events já está habilitado no Data Locker (habilitado pela interface do 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 do AppsFlyer antes de continuarmos.
3. Queremos um período de execução paralela (pipelines antiga e nova 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 Conversions (instâncias de atribuição únicas, sem linhas duplicadas) ou o relatório End User Events entre plataformas, deduplicado por CUID (nível de usuário em web+mobile)? O escopo padrão é o relatório End User Events no nível da plataforma, o sucessor direto dos relatórios PBA.

## Mudanças estruturais para considerar no design

1. **Um relatório em vez de dois.** O PBA dividia visitas e eventos em dois relatórios. O novo relatório End User Events contém ambos: as visitas são linhas com end_user_event_type = 'SESSION' e os 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 schema em todas as plataformas.** O relatório é compartilhado entre website, mobile, CTV e PC. Sempre filtre platform = 'WEBSITE' para isolar os dados 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). Por padrão, filtre is_primary_attribution = true para evitar contagem dupla. Remova o filtro apenas para análises dedicadas de visualização de UA vs. visualização de retargeting usando conversion_type.
4. **Por hora em vez de diariamente.** O novo relatório é entregue por hora, com aproximadamente 2 horas de defasagem na atualização dos dados. 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. Use o booleano is_organic; nunca infira orgânico/pago a partir de media_source.
6. **Contagem de usuários.** Conte e una os usuários com COALESCE(customer_user_id, appsflyer_id_value), usando primeiro o ID de usuário do cliente estável e, como fallback, o ID baseado em cookie.
7. **Valores vazios.** Os campos STRING são '', os 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 nos dados ou no formato do valor (trate com cuidado). Obsoleto = sem equivalente.

| Campo do PBA | Status | Novo campo / tratamento |
|---|---|---|
| advertising_id | Obsoleto | Device ID 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 | Obsoleto | ID de dispositivo/mobile, não relevante para web. |
| android_id | Obsoleto | ID de dispositivo/mobile, não relevante para web. |
| app_id | Obsoleto | 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 | Obsoleto | Campo mobile entre plataformas. |
| appsflyer_id | Obsoleto | ID de instalação mobile. Observação: o novo appsflyer_id_value é o cookie da web (o af_web_id do PBA), NÃO este campo. |
| attributed_touch_time | Renomeado | event_time__attribution. |
| attributed_touch_type | Obsoleto | Era uma constante. A distinção entre visita vs. evento agora está em end_user_event_type. |
| bundle_id | Obsoleto | Substituído pelo agrupamento de Linha de Produto no relatório entre plataformas. |
| 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 de valores | device_category, os valores são diferentes (por exemplo, "Desktop" → "MOBILE_PHONE" / valores no estilo "TV"). Atualize qualquer lógica baseada em valores. |
| dma | Inalterado | dma. |
| event_name | Redefinido | Eventos: inalterado. Visitas: agora vazio (o PBA escreveu "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. A distinção entre visita e evento está em end_user_event_type (SESSION / IN_APP). |
| event_url | Inalterado | event_url, agora também é o local principal de onde os parâmetros de consulta da URL (UTMs etc.) são lidos. |
| event_value | Inalterado | event_value. |
| idfa / idfv / imei / oaid | Descontinuado | IDs mobile/de dispositivo, não relevantes para web. |
| install_time | Descontinuado | Campo mobile. O momento de aquisição do 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 (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 valores). |
| media_type | Obsoleto | Use o booleano is_organic em vez disso. |
| original_url | Renomeado | Consolidado em event_url (em visitas, event_url é igual à URL original). A coluna independente foi removida. |
| platform | Redefinido | platform é sempre "WEBSITE". O SO foi movido para os campos 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 o parsing 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. |

## Alterações de valores atribuídos (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/video 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 IDs de clique foi ampliada (mais networks são resolvidas a partir de IDs de clique); dclid sozinho não é mais resolvido; fbclid não é usado.

Examine 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 "Structural changes").
2. Após minha aprovação, implemente-o reutilizando nossas convenções e infraestrutura existentes.
3. Para cada campo obsoleto que o inventário encontrar em uso downstream, liste o consumidor e proponha uma solução (remover, substituir pela alternativa sugerida ou sinalizar ao responsável de negócios).

## Etapa 4: Validar

1. Execute ambos os pipelines no mesmo intervalo de dias e compare: visitas (linhas SESSION) vs. visitas ao site no PBA, eventos (linhas IN_APP) vs. eventos do site no 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, campanha) não corresponderão exatamente ao PBA. A lógica de contagem de sessões permanece inalterada (30 minutos de atividade), portanto os volumes de visita devem ficar na mesma ordem de grandeza.
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 descartado, o que mudou nos valores e quaisquer itens pendentes para o responsável pela área de negócios.

• As visitas agora são do lado do servidor. O S2S do PBA aceitava apenas eventos; as visitas precisavam vir do SDK web. O novo endpoint /visits permite que o site opere totalmente do lado do servidor.
• Não é mais necessária a chamada setcuid. O PBA exigia o SDK web, então era necessária uma chamada separada para vincular um CUID a um usuário da web. A nova API carrega a identidade inline em todas as solicitações, então essa etapa foi removida.
• Janela para dados atrasados. Envie eventos e visitas em tempo real, de preferência em 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 do 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 da carga útil. 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 da carga útil 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 mexer no código

1. Devemos modificar o serviço existente no local ou criar um novo serviço/módulo em paralelo a ele (permitindo uma execução paralela e uma transição limpa)? Recomende um novo módulo em paralelo.
2. Eu sei o ID unificado do aplicativo do nosso novo aplicativo web? Formato: "website-{domain}" (por exemplo, website-www.example.com). Ele substitui o ID do pacote do PBA no caminho da URL. Se eu não souber, vou obtê-lo no dashboard da AppsFlyer antes de continuarmos.
3. Tenho a nova chave da API S2S? A autenticação passou da 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 do lado do 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 de desduplicação de 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 com base na resposta 200 OK.
4. Comportamento de tentativas, processamento em lote e enfileiramento.

Apresente este 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.0/s2s/inapps/app/web/{appId} |
| Chamada de visita | Não disponível | POST /v2.0/s2s/visits/app/web/{appId} |
| Chamada de identidade | POST /v1/{bundleId}/setcuid | Nenhuma; a identidade está embutida no objeto user_id em todas as chamadas |
| Identificador do aplicativo no caminho | bundleId (ID do pacote da marca) | appId = o ID unificado do aplicativo web ("website-{domain}") |
| Autenticação | webDevKey no corpo JSON | Cabeçalho Authorization com a chave da 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. |
| afUserId | user_id.appsflyer_id | Aninhado no objeto user_id. Envie pelo menos um entre customer_user_id ou appsflyer_id; envie ambos sempre que o usuário estiver identificado. |
| webDevKey | (removido) | A autenticação foi movida para o cabeçalho Authorization; o aplicativo é identificado pelo appId no caminho. |
| eventType (sempre "EVENT") | (removido) | O endpoint (/inapps vs /visits) determina o tipo. |
| eventName | event_name | 1-64 caracteres; não pode conter os caracteres @ = + -. |
| timestamp (Unix ms) | timestamp (Unix ms) | Mesmo formato. Recomendado em todas as chamadas; se omitido, o AppsFlyer usa o horário de recebimento. |
| eventValue | event_value | Formato livre; oferece suporte a um subobjeto custom_parameters. |
| 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 | Inalterado. |
| (novo) | event_url | Obrigatório em visitas; opcional em eventos. |
| (novo) | customer_dedup_id | Remove duplicatas em relação ao mesmo evento que chega de outra fonte (por exemplo, o SDK web). |
| (novo) | 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 no AppsFlyer mostra um UUID de "ID do SDK web" (a antiga Web Dev Key, mantida para continuidade do SDK). O caminho S2S deve incluir o ID unificado do Aplicativo ("website-{domain}"), nunca esse UUID. Um 401 "app not found" geralmente significa um appId incorreto no caminho ou um cabeçalho Authorization ausente/inválido.
2. **O sucesso é 202, não 200.** Atualize as verificações de integridade, as novas tentativas e os alertas adequadamente.
3. **Não valide em relação ao endpoint antigo.** O endpoint legado ainda pode retornar 200, mas essa resposta não prova que os dados chegaram à mensuração de performance web. Sempre verifique se os eventos realmente aparecem nos dados do novo Aplicativo web.
4. **Elimine totalmente o fluxo setcuid.** A identidade é enviada 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 acontecer, de preferência em até 30 minutos após a ocorrência do evento. 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 de recebimento, o que distorce a atribuição. Sempre envie um registro de data/hora. 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 AppsFlyer — não é algo que precisemos implementar.
7. **Opção completa do lado do servidor (se adotarmos visitas).** Sem o Web SDK, o nosso servidor controla o identificador do usuário na web: gere um ID estável para visitantes de primeira visita, persista-o como um cookie HTTP first-party definido pelo servidor (cabeçalho Set-Cookie, não JavaScript; cookies JS têm um limite de aproximadamente 7 dias no Safari), reutilize-o em todas as solicitações e envie-o como user_id.appsflyer_id. A carga útil da visita deve incluir event_url (e deve incluir ip, user_agent, http_referrer para a qualidade da atribuição).
8. **SDK + S2S juntos.** Se ambos enviarem o mesmo evento, preencha customer_dedup_id para que o AppsFlyer mantenha apenas 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 codificada diretamente), builders de carga útil para eventos (e visitas, se estiverem no escopo) e o tratamento de resposta/repetição para 202.
2. Após a minha aprovação, implemente isso seguindo nossas convenções existentes.
3. Mapeie todos os campos do inventário por meio do mapeamento de carga útil acima; sinalize qualquer campo que enviamos atualmente e que não tenha um novo equivalente.

## 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 na AppsFlyer (dashboard ou Data Locker); esse é o sinal real de sucesso, não a resposta HTTP.
3. Confirme se os nomes dos eventos estão em conformidade com as novas restrições (1 a 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 transição e, em seguida, desative as chamadas antigas, incluindo setcuid.

A mensuração de performance da 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, snapweb_int para snapchat_int. Relatórios criados com base nos valores brutos antigos precisam considerar os novos.

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

A web performance mensuração 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, rdt_cid para reddit_int.

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

Os valores de canal também mudam de formato, de Direct / Organic search / Social media / Email / Ad / Referral / Other do 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.