Origens de tráfego e UTMs

Cada parâmetro do endereço da página em que o player foi assistido é registrado com a sessão, desde que tenha um valor: em geral as UTMs (utm_source, utm_medium, utm_campaign, utm_term, utm_content), src e sck, mas também qualquer outro parâmetro. Agrupar as métricas pelos valores deles mostra qual origem, campanha ou anúncio traz os espectadores que ficam e compram.

Você precisa do ID do player, da duração do vídeo e do tempo de pitch. O GET /players/list devolve os três.

Veja quais parâmetros o seu tráfego traz

O POST /traffic_origin/valid_utms conta quantas vezes cada parâmetro foi registrado para o player:

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: minha-integracao/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"
  }'

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

Cada item traz um parâmetro e a contagem dele. start_date é obrigatório; end_date é opcional.

Compare os valores de um parâmetro

O POST /traffic_origin/stats devolve uma linha por valor do parâmetro em 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: minha-integracao/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
  }'

Deixe query_key de fora para receber todos os parâmetros de uma vez, cada linha com o seu query_key, ou envie query_keys, uma lista, para receber só esses parâmetros.

video_duration e pitch_time, em segundos, não são lidos do player aqui: envie-os com os valores do GET /players/list. video_duration é obrigatório; envie pitch_time quando o player tiver um, e deixe-o de fora quando a lista devolver 0.

[
  {
    "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 é o valor do parâmetro. Os campos têm os nomes e as fórmulas do relatório diário, com estas diferenças:

• total_over_pitch e total_under_pitch contam só as sessões que apertaram o play, e uma sessão que apertou o play sem nenhum progresso registrado conta como abaixo do pitch.
• As vendas e os seus valores são selecionados pelo momento em que a venda foi registrada, não pelo momento do clique.
• engagement_rate é um número inteiro, e play_rate nunca passa de 100.

Acompanhe dia a dia

O POST /traffic_origin/stats_by_day recebe o mesmo corpo com query_keys, uma lista, no lugar de query_key, e devolve uma linha por dia, parâmetro e valor, cada uma com o seu date_key. Um dia sem tráfego volta como uma linha com query_key e grouped_field vazios, e zeros:

{
  "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
}

Use-o para ver se uma campanha se sustenta ao longo da semana ou perde força depois dos primeiros dias.

Compare onde cada origem sai do vídeo

O POST /times/user_engagement_by_traffic_origin devolve os dados de retenção divididos por valor. values lista os valores a 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"]
}

[
  { "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 na curva de retenção, cada item conta as sessões que pararam naquele segundo. Transforme cada group_values em uma curva do mesmo jeito, renomeando totalUsers para total_users, e desenhe as origens em um só gráfico: aquela cuja curva fica mais alta até o pitch é a que está trazendo os espectadores que assistem.

Mantenha os parâmetros consistentes

Os valores são agrupados como chegam no endereço, depois de decodificados da URL: black%20friday e black friday são uma só linha, mas Facebook e facebook são duas. Uma sessão conta uma vez por parâmetro, com o último valor que trouxe. Padronize como as suas campanhas escrevem os parâmetros, e a comparação funciona sem limpar os dados depois.