Fuentes de tráfico y UTMs

Compara campañas, fuentes y anuncios por visualizaciones, retención, pitch y ventas

Cada parámetro de la dirección de la página donde se vio el reproductor se registra con la sesión, siempre que tenga un valor: por lo general las UTM (utm_source, utm_medium, utm_campaign, utm_term, utm_content), src y sck, pero también cualquier otro parámetro. Agrupar las métricas por sus valores indica qué fuente, campaña o anuncio trae a los espectadores que se quedan y compran.

Necesitas el ID del reproductor, la duración del vídeo y el tiempo de pitch. GET /players/list devuelve los tres.

Mira qué parámetros trae tu tráfico

POST /traffic_origin/valid_utms cuenta cuántas veces se registró cada parámetro para el reproductor:

curl -X POST 'https://analytics.vturb.com/traffic_origin/valid_utms' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: mi-integracion/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "player_id": "64a5c8072e6fd10009828db2",
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-07 23:59:59",
    "timezone": "America/Sao_Paulo"
  }'

200 OK

[
  { "utm_source": 1520 },
  { "utm_campaign": 1488 },
  { "utm_content": 960 },
  { "src": 312 }
]

Cada elemento contiene un parámetro y su recuento. start_date es obligatorio; end_date es opcional.

Compara los valores de un parámetro

POST /traffic_origin/stats devuelve una fila por cada valor del parámetro de query_key:

curl -X POST 'https://analytics.vturb.com/traffic_origin/stats' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: mi-integracion/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "player_id": "64a5c8072e6fd10009828db2",
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-07 23:59:59",
    "timezone": "America/Sao_Paulo",
    "query_key": "utm_source",
    "video_duration": 2340,
    "pitch_time": 1260
  }'

Omite query_key para recibir todos los parámetros a la vez, cada fila con su propio query_key, o envía query_keys, una lista, para recibir solo esos parámetros.

video_duration y pitch_time, en segundos, no se leen del reproductor aquí: envíalos con los valores de GET /players/list. video_duration es obligatorio; envía pitch_time cuando el reproductor tenga uno, y déjalo fuera cuando la lista devuelva 0.

200 OK (una fila, campos principales)

[
  {
    "query_key": "utm_source",
    "grouped_field": "facebook",
    "total_viewed_device_uniq": 840,
    "total_started_device_uniq": 410,
    "play_rate": 48.8,
    "engagement_rate": 41,
    "total_over_pitch": 140,
    "total_under_pitch": 290,
    "over_pitch_rate": 32.55,
    "total_conversions": 22,
    "overall_conversion_rate": 5.36,
    "total_amount_brl": 437800
  }
]

grouped_field es el valor del parámetro. Los campos tienen los nombres y las fórmulas del informe diario, con estas diferencias:

total_over_pitch y total_under_pitch cuentan solo las sesiones que pulsaron play, y una sesión que pulsó play sin ningún progreso registrado cuenta por debajo del pitch.
Las ventas y sus importes se seleccionan por el momento en que se registró la venta, no por el momento del clic.
engagement_rate es un número entero, y play_rate nunca supera 100.

Síguelos día a día

POST /traffic_origin/stats_by_day recibe el mismo cuerpo con query_keys, una lista, en lugar de query_key, y devuelve una fila por día, parámetro y valor, cada una con su date_key. Un día sin tráfico vuelve como una fila con query_key y grouped_field vacíos, y ceros:

{
  "player_id": "64a5c8072e6fd10009828db2",
  "start_date": "2026-09-01 00:00:00",
  "end_date": "2026-09-07 23:59:59",
  "timezone": "America/Sao_Paulo",
  "query_keys": ["utm_source", "utm_campaign"],
  "video_duration": 2340,
  "pitch_time": 1260
}

Úsalo para ver si una campaña se sostiene a lo largo de la semana o se apaga después de los primeros días.

Compara dónde abandona el vídeo cada fuente

POST /times/user_engagement_by_traffic_origin devuelve los datos de retención separados por valor. values lista los valores que quieres comparar:

{
  "player_id": "64a5c8072e6fd10009828db2",
  "start_date": "2026-09-01 00:00:00",
  "end_date": "2026-09-07 23:59:59",
  "timezone": "America/Sao_Paulo",
  "query_key": "utm_source",
  "values": ["facebook", "google"]
}

200 OK (primeros elementos de cada valor)

[
  { "group_key": "facebook", "group_values": [{ "timed": 0, "totalUsers": 120 }, { "timed": 5, "totalUsers": 31 }] },
  { "group_key": "google", "group_values": [{ "timed": 0, "totalUsers": 64 }, { "timed": 5, "totalUsers": 12 }] }
]

Como en la curva de retención, cada elemento cuenta las sesiones que se detuvieron en ese segundo. Convierte cada group_values en una curva de la misma forma, renombrando totalUsers a total_users, y dibuja las fuentes en un mismo gráfico: la que mantiene la curva más alta hasta el pitch es la que trae a los espectadores que ven el vídeo.

Mantén los parámetros coherentes

Los valores se agrupan como llegan en la dirección, una vez decodificados de la URL: black%20friday y black friday son una sola fila, pero Facebook y facebook son dos. Una sesión cuenta una vez por parámetro, con el último valor que trajo. Estandariza cómo escriben sus parámetros tus campañas, y la comparación funciona sin limpiar los datos después.