Para facilitar esta transición, hemos preparado un prompt listo para usar para tu agente de programación con IA (Claude Code, Cursor o similar). Da al agente acceso a tu código ETL actual y pega el prompt que aparece a continuación; contiene la asignación completa de campos y todas las diferencias de comportamiento. Guiará al agente para que aprenda tu canalización actual y la reconstruya para el nuevo reporte.

Estás migrando una canalización de ETL desde los reportes heredados de datos sin procesar de PBA de Data Locker de AppsFlyer (visitas al sitio web + eventos del sitio web) al reporte de Data Locker de medición del rendimiento web de AppsFlyer (eventos de usuario final). En este prompt tienes todo lo que necesitas: los cambios estructurales, la asignación completa campo por campo y los pasos de validación. No supongas nada que no esté escrito aquí; si algo es ambiguo, pregúntamelo.

## Paso 1: Aprende la canalización actual

Antes de escribir código, explora el código existente y crea un inventario:
1. Qué reportes de PBA consumimos (visitas al sitio web, eventos del sitio web o ambos) y dónde se ingieren.
2. Todos los campos de PBA que leemos y dónde se usa cada uno posteriormente (transformaciones, uniones, dashboards, alertas, exportaciones).
3. La cadencia de carga y las hipótesis de programación (PBA se entrega a diario).
4. Cualquier lógica que separe o una filas de visitas y filas de eventos.
5. Cualquier filtro, agrupación o valor codificado de forma fija basado en valores de campos de PBA (p. ej., nombres de media_source, etiquetas de canal, event_type, valores de plataforma).

Preséntame este inventario y espera mi confirmación antes de continuar.

## Paso 2: Hazme estas preguntas

1. ¿Ya está habilitado en Data Locker el nuevo reporte de eventos de usuario final (habilitado desde la IU de AppsFlyer)? Si no, primero tengo que habilitarlo.
2. ¿Cuál es el Unified App ID de nuestra nueva aplicación web? Formato: "website-{domain}" (p. ej., website-www.example.com). Si no lo sé, lo obtendré del Dashboard de AppsFlyer antes de continuar.
3. ¿Queremos un periodo de ejecución en paralelo (pipelines antiguos y nuevos en paralelo, comparando resultados) o un cambio directo? Recomiendo una ejecución en paralelo.
4. ¿Debería el nuevo pipeline consumir también el reporte de conversiones (instancias de atribución únicas, sin filas duplicadas) o el reporte de eventos de usuario final multiplataforma (deduplicado por CUID, a nivel de usuario web+móvil)? El alcance predeterminado es el reporte de eventos de usuario final a nivel de plataforma, el sucesor directo de los reportes de PBA.

## Cambios estructurales que debes tener en cuenta

1. **Un reporte en lugar de dos.** PBA dividía las visitas y los eventos en dos reportes. El nuevo reporte de eventos de usuario final contiene ambos: las visitas son filas con end_user_event_type = 'SESSION' y los eventos son filas con end_user_event_type = 'IN_APP'. Solo las filas IN_APP tienen un event_name válido; en las filas SESSION, event_name está vacío (PBA escribía "website visit" ahí).
2. **Un esquema en todas las plataformas.** El reporte es común para website, móvil, CTV y PC. Filtra siempre platform = 'WEBSITE' para aislar los datos web.
3. **Crédito de atribución doble, deduplica.** La misma acción puede aparecer dos veces: una fila de crédito principal y una fila de crédito secundario (fuente de UA original, para LTV en vista de UA). Filtra is_primary_attribution = true de forma predeterminada para evitar el recuento doble. Quita el filtro solo para análisis específicos de vista de UA frente a vista de retargeting con conversion_type.
4. **Cada hora en lugar de a diario.** El nuevo reporte se entrega cada hora con aproximadamente 2 horas de frescura de datos. Rediseña las cargas incrementales en torno a lotes horarios en lugar de una carga diaria.
5. **Orgánico vs. pagado.** El media_type ("Paid") de PBA ya no existe. Usa el booleano is_organic; no infieras nunca si es orgánico o pagado a partir de media_source.
6. **Recuento de usuarios.** Cuenta y une usuarios con COALESCE(customer_user_id, appsflyer_id_value): primero el ID de usuario de cliente estable y, como alternativa, el ID basado en cookies.
7. **Valores vacíos.** Los campos STRING son '' y los campos NUMERIC son NULL.

## Mapeo campo por campo (PBA → End User Events)\n\nLeyenda de estados: Unchanged = mismo nombre y mismos datos. Renamed = mismos datos, columna nueva. Redefined = cambios en los datos o en el formato del valor (trátalo con cuidado). Deprecated = sin equivalente.

| Campo de PBA | Estado | Campo nuevo / gestión |\n|---|---|---|\n| advertising_id | Deprecated | ID de dispositivo móvil/de dispositivo. Los reportes multiplataforma se basan en CUID; elimínalo. |\n| af_web_id | Renamed | appsflyer_id_value, la misma cookie web. |
| amazon_aid | Deprecated | ID de dispositivo móvil, no relevante para la web. |
| android_id | Deprecated | ID de dispositivo móvil, no relevante para la web. |\n| app_id | Deprecated | Campo multiplataforma móvil. El nuevo identificador de la app web es unified_app_id ("website-{domain}"), un concepto distinto; no es un cambio de nombre. |
| app_name | Unchanged | app_name. |\n| app_version | Deprecated | Campo multiplataforma móvil. |
| appsflyer_id | Deprecated | ID de instalación móvil. Nota: el nuevo appsflyer_id_value es la cookie web (el af_web_id de PBA), NO este campo. |
| attributed_touch_time | Renamed | event_time__attribution. |
| attributed_touch_type | Deprecated | Era una constante. La distinción visita-vs-evento ahora está en end_user_event_type. |\n| bundle_id | Deprecated | Sustituido por la agrupación de línea de producto en el reporte multiplataforma. |
| campaign | Renamed | campaign_name. |
| campaign_id | Sin cambios | campaign_id. |
| city | Sin cambios | city. |
| country_code | Sin cambios | country_code. |
| customer_user_id | Sin cambios | customer_user_id. |
| device_type | Renombrado + cambio de valores | device_category, los valores son distintos (p. ej., "Desktop" → "MOBILE_PHONE" / valores de estilo "TV"). Actualiza cualquier lógica basada en claves de valor. |
| dma | Sin cambios | dma. |
| event_name | Redefinido | Eventos: sin cambios. Visitas: ahora está vacío (PBA escribió "website visit"). Usa end_user_event_type = 'SESSION' para identificar las visitas. |
| event_revenue | Renombrado | revenue_value_original. |
| event_revenue_currency | Renombrado | revenue_currency_original. |
| event_revenue_usd | Renombrado | revenue_usd. |
| event_source | Sin cambios | event_source. |
| event_time | Sin cambios | event_time. |
| event_type | Redefinido | La marca de «evento de conversión» ya no existe. La distinción entre visita y evento está en end_user_event_type (SESSION / IN_APP). |
| event_url | Sin cambios | event_url, ahora también es el lugar principal desde el que se leen los parámetros de consulta de la URL (UTM, etc.). |
| event_value | Sin cambios | event_value. |
| idfa / idfv / imei / oaid | Obsoleto | ID de dispositivo móvil, no relevante para web. |
| install_time | Obsoleto | Campo móvil. El tiempo de adquisición del usuario web es event_time__conversion, un concepto distinto. |
| ip | Renombrado | ip_address_value (más ip_address_type para el método de hashing). |
| language | Redefinido | language, el formato cambia a ISO 639-1 + código de país (antes, por ejemplo, "English"). |
| media_channel | Obsoleto | Se puede cubrir con sub_param_1-5 si es necesario. |
| media_source | Sin cambios | media_source (pero consulta los cambios de nombre de valores más abajo). |
| media_type | Obsoleto | Usa el booleano is_organic en su lugar. |
| original_url | Renombrado | Consolidado en event_url (en las visitas, event_url equivale a la URL original). La columna independiente ha desaparecido. |
| platform | Redefinido | platform siempre es "WEBSITE". El SO se ha trasladado a os_version / user_agent. |
| postal_code | Sin cambios | postal_code. |
| query_params | Obsoleto | La cadena de consulta sin procesar está en event_url; la columna de JSON analizado ha desaparecido. Vuelve a implementar el análisis desde event_url si es necesario. |
| referrer | Renombrado | http_referrer. |
| region | Renombrado | continente, código de continente (p. ej., "NA"). |
| state | Sin cambios | state. |

## Cambios en los valores atribuidos (actualiza filtros y agrupaciones)

El motor de atribución resuelve las fuentes de tráfico de forma diferente, por lo que algunos valores cambian incluso cuando los nombres de los campos no:
- cambios de nombre de media_source: doubleclick_int → dv360_int (display/vídeo de Google mediante UTM); "X Ads" → "Twitter" (Twitter mediante UTM). Ahora más valores de PID se reasignan a nombres para mostrar (p. ej., iossearchads_int → Apple Search Ads, metweb_int → Facebook Ads, tiktokweb_int → tiktokglobal_int, snapweb_int → snapchat_int).
- Las etiquetas de canal cambian de formato: Direct / Organic search / Social media / Email / Ad / Referral / Other pasan a ser DIRECT / ORGANIC_SEARCH / SOCIAL_MEDIA / EMAIL / AD / REFERRAL / OTHER.
- Se ha ampliado la cobertura de ID de clic (más redes se resuelven a partir de ID de clic); dclid por sí solo ya no se resuelve; fbclid no se usa.

Busca en el repositorio de código cualquier filtro, CASE, clave de join o agrupación de dashboard basada en estos valores antiguos y actualízalos.

## Paso 3: Compilar

1. Propón el nuevo diseño de ETL (ingesta, esquema, lógica incremental por hora y los filtros obligatorios de «Cambios estructurales»).
2. Tras mi aprobación, impleméntalo reutilizando nuestras convenciones e infraestructura existentes.
3. Para cada campo obsoleto que el inventario haya encontrado en uso downstream, indica el consumidor y propón una solución (eliminarlo, sustituirlo por la alternativa sugerida o marcarlo para el responsable de negocio).

## Paso 4: Validar

1. Ejecuta ambos pipelines en el mismo intervalo de días y compara: visitas (filas de SESSION) vs visitas web de PBA, eventos (filas de IN_APP) vs eventos web de PBA, e ingresos totales.
2. Espera diferencias, no igualdad: la nueva lógica de atribución es más avanzada, por lo que las dimensiones atribuidas (media_source, campaña) no coincidirán exactamente con PBA. La lógica de recuento de sesiones no cambia (30 minutos de actividad), por lo que los volúmenes de visitas deberían estar en el mismo orden de magnitud.
3. Verifica que el filtro is_primary_attribution se aplique en todas partes; si falta, aparecen recuentos de eventos inflados.
4. Genera un reporte breve de la migración: qué se asignó, qué se descartó, qué cambió en los valores y cualquier elemento pendiente para el responsable del negocio.

• Las visitas ahora son del lado servidor. El S2S de PBA solo aceptaba eventos; las visitas tenían que llegar desde el SDK web. El nuevo endpoint /visits permite que el sitio web funcione completamente del lado del servidor.
• Ya no hace falta la llamada setcuid. PBA requería el SDK web, por lo que hacía falta una llamada independiente para vincular un CUID a un usuario web. La nueva API incluye la identidad en línea en cada solicitud, por lo que se elimina ese paso.
• Ventana de datos tardíos. Envía los eventos y las visitas en tiempo real, preferiblemente en los 30 minutos posteriores a que se produzca el evento, en lugar de agruparlos en una única carga diaria. Los datos que llegan más de 30 minutos después del final del día UTC en el que se produjo el evento siguen aceptándose, pero su hora del evento se sustituye por la hora a la que AppsFlyer los recibió.

Si reportas eventos a través de la API de servidor a servidor de PBA, hemos preparado un prompt listo para usar para tu agente de programación con IA (Claude Code, Cursor o similar). Da al agente acceso al servicio que envía eventos a AppsFlyer y pega el prompt a continuación; contiene el endpoint completo y la asignación del payload. Guiará al agente para que aprenda tu implementación actual y cree la actualizada.

Estás migrando una integración del lado del servidor desde la API heredada de eventos PBA Web S2S de AppsFlyer (webs2s.appsflyer.com) a la nueva API S2S de AppsFlyer para la medición del rendimiento web (events.appsflyer.com). Todo lo que necesitas está en este prompt: endpoints, autenticación, el mapeo completo de la carga útil y los cambios de comportamiento. No des nada por supuesto más allá de lo que está escrito aquí; si algo es ambiguo, pregúntame.

## Paso 0: Hazme estas preguntas antes de modificar el código

1. ¿Debemos modificar el servicio actual directamente o crear un nuevo servicio/módulo en paralelo (para permitir una ejecución en paralelo y una transición limpia)? Recomienda un módulo nuevo en paralelo.
2. ¿Conozco el Unified App ID de nuestra nueva aplicación web? Formato: "website-{domain}" (p. ej., website-www.example.com). Sustituye al bundle ID de PBA en la ruta de la URL. Si no lo sé, lo obtendré del dashboard de AppsFlyer antes de continuar.
3. ¿Tengo la nueva clave de la API S2S? La autenticación pasó de la webDevKey en el cuerpo de la solicitud a una cabecera Authorization que incluye esta clave. Si no la tengo, la recuperaré del dashboard de AppsFlyer.
4. ¿Queremos enviar solo eventos (como PBA) o adoptar también el nuevo endpoint de visitas? La nueva API admite visitas del lado del servidor, por lo que el sitio web puede funcionar completamente del lado del servidor; PBA solo aceptaba eventos.
5. ¿El SDK web de AppsFlyer sigue en funcionamiento en nuestro sitio? (Esto determina si las visitas proceden del SDK y si necesitamos deduplicación de eventos entre el SDK y S2S.)

## Paso 1: Conoce el servicio actual

Explora la base de código y elabora un inventario:
1. Todos los puntos del código que llaman a webs2s.appsflyer.com, las llamadas a /event y cualquier llamada a /setcuid.
2. Los campos que se rellenan en cada llamada (customerUserId, afUserId, eventName, eventValue, eventRevenue, timestamp, referrer, userAgent, ip, etc.) y de dónde proceden sus valores.
3. Gestión de errores y monitorización basadas en la respuesta 200 OK.
4. Comportamiento de reintento, procesamiento por lotes y colas.

Preséntame este inventario y espera mi confirmación antes de continuar.

## Qué ha cambiado: endpoints y autenticación

|  | PBA Web-S2S (anterior) | Nueva API S2S |
|---|---|---|
| URL base | https://webs2s.appsflyer.com | https://events.appsflyer.com |
| Llamada de evento | POST /v1/{bundleId}/event | POST /v2.0/s2s/inapps/app/web/{appId} |
| Llamada de visita | No disponible | POST /v2.0/s2s/visits/app/web/{appId} |
| Llamada de identidad | POST /v1/{bundleId}/setcuid | Ninguna; la identidad va integrada en el objeto user_id en cada llamada |
| Identificador de la aplicación en la ruta | bundleId (bundle ID de la marca) | appId = el Unified App ID web ("website-{domain}") |
| Autenticación | webDevKey en el cuerpo JSON | Cabecera Authorization con la clave de la API S2S |
| Tipo de contenido | application/json | application/json (415 si falta) |
| Respuesta correcta | 200 OK | 202 Accepted |

## Mapeo de campos de la carga útil

| Campo de PBA | Campo nuevo | Nota |
|---|---|---|
| customerUserId | user_id.customer_user_id | Anidado en el objeto user_id. |
| afUserId | user_id.appsflyer_id | Anidado en el objeto user_id. Envía al menos uno de customer_user_id o appsflyer_id; envía ambos siempre que el usuario esté identificado. |
| webDevKey | (eliminado) | La autenticación se ha trasladado al encabezado Authorization; la app se identifica mediante appId en la ruta. |
| eventType (siempre "EVENT") | (eliminado) | El endpoint (/inapps vs /visits) determina el tipo. |
| eventName | event_name | 1-64 caracteres; no puede contener los caracteres @ = + -. |
| timestamp (Unix ms) | timestamp (Unix ms) | Mismo formato. Recomendado en cada llamada; si se omite, AppsFlyer usa la hora de recepción. |
| eventValue | event_value | Formato libre; admite un subobjeto custom_parameters. |
| eventRevenue | event_revenue | Ahora es opcional (PBA lo requería para los dashboards). |
| eventRevenueCurrency | event_revenue_currency | Ahora es opcional (PBA lo requería para los dashboards). |
| referrer | http_referrer | Renombrado. |
| userAgent | user_agent | Renombrado. |
| ip | ip | Sin cambios. |
| (nuevo) | event_url | Obligatorio en /visits; opcional en eventos. |
| (nuevo) | customer_dedup_id | Elimina duplicados del mismo evento cuando llega desde otra fuente (p. ej., el SDK web). |
| (nuevo) | email_hashed, phone_number_hashed, phone_number_e164_hashed, first_name_hashed, last_name_hashed | SHA256 (hexadecimal en minúsculas de 64 caracteres) de valores normalizados, para el enriquecimiento de identidad. |

## Cambios de comportamiento y aspectos a tener en cuenta

1. **appId es el Unified App ID, no el «Web SDK ID».** La página de configuración de la aplicación en AppsFlyer muestra un UUID «Web SDK ID» (el antiguo Web Dev Key, que se mantiene por la continuidad del SDK). La ruta S2S debe incluir el Unified App ID («website-{domain}»), nunca ese UUID. Un 401 «app not found» normalmente significa que hay un appId incorrecto en la ruta o que falta la cabecera Authorization, o bien que no es válida.
2. **El éxito es 202, no 200.** Actualiza las comprobaciones de estado, los reintentos y las alertas en consecuencia.
3. **No valides con el endpoint antiguo.** El endpoint heredado puede seguir devolviendo 200, pero esa respuesta no demuestra que los datos hayan llegado a Web Performance Measurement. Verifica siempre que los eventos aparezcan realmente en los datos de la nueva aplicación web.
4. **Elimina por completo el flujo setcuid.** La identidad viaja integrada en el objeto user_id en cada evento y visita.
5. **Las visitas deben ir antes que los eventos.** El sistema espera una visita antes de cualquier evento de un usuario; los eventos de un usuario sin ninguna visita previa se clasifican como orgánicos. Las visitas proceden del SDK web o, ahora también, del endpoint /visits.
6. **Envía en tiempo real; no agrupes en lotes.** Envía cada evento y visita a medida que se produzca, preferiblemente en un plazo de 30 minutos desde que ocurra el evento. Los datos que llegan más de 30 minutos después del final del día UTC en el que se produjo el evento siguen aceptándose, pero su hora del evento se sustituye por la hora de recepción, lo que distorsiona la Atribución. Envía siempre una marca de tiempo. Ten en cuenta que el retraso de Atribución de aproximadamente 30 minutos del que puedas leer es una retención independiente, del lado del Servidor, por parte de AppsFlyer; no hay nada que tengamos que implementar.
7. **Opción completa del lado del servidor (si adoptamos las visitas).** Sin Web SDK, nuestro servidor controla el identificador de usuario web: genera un ID estable para los visitantes que llegan por primera vez, consérvalo como una cookie HTTP propia establecida por el servidor (cabecera Set-Cookie, no JavaScript; las cookies de JS están limitadas a aproximadamente 7 días en Safari), reutilízalo en cada solicitud y envíalo como user_id.appsflyer_id. La carga útil de la visita debe incluir event_url (y debería incluir ip, user_agent y http_referrer para mejorar la calidad de la Atribución).
8. **SDK + S2S juntos.** Si ambos envían el mismo evento, rellena customer_dedup_id para que AppsFlyer conserve una sola copia.

## Paso 2: Compilar

1. Propón el diseño: nuevo cliente/módulo, configuración (URL base, appId, almacenamiento de la clave de API en nuestro gestor de secretos, nunca codificada de forma rígida), creadores de carga útil para eventos (y visitas, si entran en el alcance), y la gestión de respuestas/reintentos para 202.
2. Tras mi aprobación, impleméntalo siguiendo nuestras convenciones actuales.
3. Asigna todos los campos del inventario según la asignación de carga útil anterior; marca cualquier campo que enviemos actualmente y que no tenga un equivalente nuevo.

## Paso 3: Validar

1. Envía un evento de prueba (y una visita, si entra en el alcance) y confirma una respuesta 202.
2. Verifica que los datos de prueba aparezcan en la nueva aplicación web de AppsFlyer (en el dashboard o en Data Locker); esta es la señal real de éxito, no la respuesta HTTP.
3. Confirma que los nombres de los eventos cumplan las nuevas restricciones (1-64 caracteres, sin @ = + -).
4. Si funciona en paralelo con el servicio antiguo, compara durante unos días los volúmenes de eventos entre el sistema antiguo y el nuevo antes del cambio y, después, retira las llamadas antiguas, incluida setcuid.

Web Performance Measurement también reasigna más valores de PID a nombres para mostrar; por ejemplo, iossearchads_int a Apple Search Ads, metweb_int a Facebook Ads, twitterweb_int a Twitter, tiktokweb_int a tiktokglobal_int y snapweb_int a snapchat_int. Los reportes basados en los valores sin procesar antiguos deben contemplar los nuevos.

PBA resolvía tres ID de clic: gclid a googleadwords_int, dclid a doubleclick_int y msclkid a bingsearch_int.

Web Performance Measurement resuelve muchos más: gclid/wbraid/gbraid a googleadwords_int, msclkid a bingsearch_int, twclid a Twitter, vmcid a yahoogemini_int, sccid a snapchat_int, li_fat_id a linkedin_int, ttclid a tiktokglobal_int, tbclid a taboola_int, ob_click_id/dicbo a outbrain_int, yclid a yandex_int y rdt_cid a reddit_int.

La asignación personalizada de utm_source + utm_medium es más amplia en Web Performance Measurement: incluye más sinónimos de medio (paid, paid_search, paid-search, etc.) y añade cobertura para TikTok, Snapchat y Pinterest, más allá de las reglas de medio único limitadas de PBA. Si no coincide ninguna regla personalizada, ambos recurren al valor sin procesar de utm_source.

Los valores de canal también cambian de formato: de Direct / Organic search / Social media / Email / Ad / Referral / Other en PBA a los nuevos DIRECT / ORGANIC_SEARCH / SOCIAL_MEDIA / EMAIL / AD / REFERRAL / OTHER. Los filtros y las agrupaciones basados en las etiquetas antiguas deben actualizarse.