Curva de retención y pitch

Tres preguntas dan forma a un vídeo de ventas: dónde dejan de verlo las personas, cuántas siguen ahí cuando empieza el pitch y en qué momento hacen clic y compran. Cada una tiene su consulta, y juntas dibujan el vídeo segundo a segundo.

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

Curva de retención

POST /times/user_engagement devuelve dónde terminó cada visionado:

curl -X POST 'https://analytics.vturb.com/times/user_engagement' \
  -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",
    "video_duration": 2340,
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-07 23:59:59",
    "timezone": "America/Sao_Paulo"
  }'

video_duration, la duración del vídeo en segundos, es obligatorio aquí, igual que las dos fechas. Envía la duración real, el duration de GET /players/list: una sesión cuyo punto más lejano supera video_duration en más de 60 segundos queda fuera.

{
  "grouped_timed": [
    { "timed": 0, "total_users": 412 },
    { "timed": 5, "total_users": 96 },
    { "timed": 10, "total_users": 58 }
  ],
  "average_watched_time": 900.9,
  "engagement_rate": 38.5
}

• Cada elemento de grouped_timed cuenta las sesiones cuyo punto más avanzado en el vídeo fue exactamente ese segundo (timed): donde se detuvieron. Los segundos en los que nadie se detuvo no aparecen.
• El reproductor informa hasta dónde llegó cada espectador en pasos de cinco segundos, así que timed viene en múltiplos de 5.
• average_watched_time es hasta dónde llegó una sesión, en promedio, en segundos.
• engagement_rate es ese promedio como proporción de video_duration: average_watched_time ÷ video_duration × 100.

La curva es cuántas sesiones llegaron a cada segundo: todas las que se detuvieron en ese segundo o después. Suma los elementos desde el final:

function retentionCurve(groupedTimed, videoDuration) {
  const stoppedAt = new Map(groupedTimed.map(({ timed, total_users }) => [timed, total_users]));
  const total = groupedTimed.reduce((sum, { total_users }) => sum + total_users, 0);
  const curve = [];
  let reached = total;

  for (let second = 0; second <= videoDuration; second++) {
    curve.push({ second, reached, percent: total ? (reached / total) * 100 : 0 });
    reached -= stoppedAt.get(second) ?? 0;
  }

  return curve;
}

Una caída pronunciada en los primeros segundos apunta a la apertura; una caída justo antes del pitch, a la preparación que lleva hasta él.

Retención en el pitch

Cuántas sesiones llegaron al pitch viene ya calculado en POST /sessions/stats:

curl -X POST 'https://analytics.vturb.com/sessions/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"
  }'

En la respuesta, total_over_pitch cuenta las sesiones que llegaron a pitch_time, total_under_pitch las que salieron antes, y over_pitch_rate es la proporción que llegó. Sin pitch_time en el cuerpo, o con 0, la API usa el configurado en el reproductor; envíalo, en segundos, para probar otro momento, como un pitch que estás a punto de mover. Cuando el reproductor no tiene tiempo de pitch y no envías uno, el pitch es el segundo 0: todas las sesiones llegan a él, y over_pitch_rate es 100. Los demás campos son los mismos que en el informe diario.

Dónde compran

POST /conversions/video_timed sitúa cada venta en el segundo del vídeo en que el espectador hizo clic para comprar:

curl -X POST 'https://analytics.vturb.com/conversions/video_timed' \
  -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",
    "pitch_time": 1260
  }'

[
  {
    "timed": 1260,
    "timed_conversions": 9,
    "cumulative_conversions": 9,
    "timed_amount_usd": 0,
    "cumulative_amount_usd": 0,
    "timed_amount_brl": 179100,
    "cumulative_amount_brl": 179100,
    "timed_amount_eur": 0,
    "cumulative_amount_eur": 0
  },
  {
    "timed": 1305,
    "timed_conversions": 4,
    "cumulative_conversions": 13,
    "timed_amount_usd": 0,
    "cumulative_amount_usd": 0,
    "timed_amount_brl": 79600,
    "cumulative_amount_brl": 258700,
    "timed_amount_eur": 0,
    "cumulative_amount_eur": 0
  }
]

• timed_conversions cuenta las sesiones con una venta inicial cuyo clic ocurrió en timed; cumulative_conversions las suma hasta ese segundo.
• timed_amount_* suma, por moneda y como un entero en centavos, los importes de todas las compras cuyo clic ocurrió en ese segundo, order bumps incluidos; cumulative_amount_* los suma hasta ese segundo.
• start_date y end_date seleccionan las ventas por el momento del clic.
• Con pitch_time, una venta cuyo clic fue antes del pitch se cuenta en el segundo del pitch, así que la primera fila reúne todo hasta el pitch. Omítelo para ver cada clic en su propio segundo.

Dónde hacen clic

POST /clicks/total_by_company_timed recibe el reproductor, las fechas y timezone, y devuelve los clics en las llamadas a la acción del reproductor en cada segundo:

[
  { "timed": 1260, "total_users": 31 },
  { "timed": 1261, "total_users": 12 }
]

total_users es el número de clics registrados en ese segundo.

Júntalo todo

Dibuja la curva de retención, marca pitch_time en ella y superpón los clics y las ventas sobre los mismos segundos. La diferencia entre los clics y las ventas después del pitch muestra cuánto de ese interés convierte el checkout en ventas.

A continuación: descubre qué fuentes de tráfico traen a los espectadores que se quedan.