Release Notes

Versão 1.3.0 (2025-07-18)

Novas Funcionalidades

  • Aprimorado endpoint /players/list com filtro por data: Adicionados parâmetros opcionais de consulta para melhores capacidades de filtragem de players:

    • Filtro por intervalo de datas: Adicionados parâmetros start_date e end_date para filtrar players por data de criação

    • Suporte a fuso horário: Adicionado parâmetro timezone para filtragem precisa de datas em diferentes fusos horários

    • Validação de parâmetros: Adicionada validação abrangente para parâmetros de data para garantir formato datetime adequado

    • Compatibilidade com versões anteriores: Todos os novos parâmetros são opcionais, garantindo que integrações existentes continuem funcionando sem alterações

Características Principais

O endpoint /players/list aprimorado agora suporta:

  • Filtro por data: Filtre players criados dentro de um intervalo específico de datas usando os parâmetros start_date e end_date

  • Consciência de fuso horário: Especifique fuso horário para cálculos precisos de data (padrão UTC se não fornecido)

Exemplo de Uso

# Requisição básica (inalterada)
GET /players/list

# Filtrar players criados nos últimos 30 dias
GET /players/list?start_date=2023-10-01&end_date=2023-10-31

# Filtrar com especificação de fuso horário
GET /players/list?start_date=2023-10-01 00:00:00&end_date=2023-10-31 23:59:59&timezone=America/Sao_Paulo

# Filtrar players criados após uma data específica
GET /players/list?start_date=2023-10-01&timezone=America/Sao_Paulo

Detalhes dos Parâmetros

  • start_date (opcional): Data de início do período para filtro de players. Usa comparação >=. Suporta formatos como "2023-10-26T18:24:05.000+00:00" ou "2023-10-26 18:24:05 UTC"

  • end_date (opcional): Data final do período para filtro de players. Usa comparação <=. Mesmos formatos de data que start_date

  • timezone (opcional): Fuso horário a ser usado para filtro de data. Padrão 'Etc/UCT' se não especificado

Formato de Resposta

O formato de resposta permanece inalterado, garantindo compatibilidade com versões anteriores:

[
  {
    "id": "player1",
    "name": "Meu Player",
    "pitch_time": 0,
    "duration": 3600,
    "created_at": "2025-07-18T10:00:00Z"
  }
]

Casos de Uso

Esta melhoria permite que você:

  • Análises baseadas em tempo: Filtre players criados dentro de campanhas específicas ou períodos de tempo

  • Relatórios: Gere relatórios para players criados durante períodos comerciais específicos

  • Auditoria: Acompanhe padrões de criação de players ao longo do tempo

  • Gerenciamento de dados: Consulte eficientemente players baseados em timestamps de criação

Versão 1.2.0 (2025-06-27)

Novas Funcionalidades

  • Novo endpoint /sessions/stats_by_day: Adicionado analytics diário abrangente de sessões que fornece estatísticas detalhadas divididas por dia dentro de um intervalo de datas especificado.

Características Principais

O endpoint /sessions/stats_by_day fornece:

  • Métricas diárias de sessão: Total de visualizações, inicializações, finalizações e cliques agregados por dia

  • Rastreamento de usuário único: Contagens separadas para sessões únicas e dispositivos únicos em todas as métricas

  • Análise de engajamento: Cálculos de taxa de engajamento baseados no tempo médio de visualização

  • Análise de limite de pitch: Rastreia usuários que assistiram acima/abaixo do limite de tempo de pitch

  • Rastreamento de conversão: Contagens diárias de conversão com valores em múltiplas moedas (USD, BRL, EUR)

  • Cálculo de taxa de reprodução: Percentual de visualizadores que começaram a reproduzir após visualizar

  • Filtro por intervalo de datas: Filtro flexível de datas com suporte a fuso horário

Exemplo de Requisição

{
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "timezone": "America/Sao_Paulo",
  "video_duration": 3600,
  "pitch_time": 30
}

Exemplo de Resposta

[
  {
    "date_key": "2023-01-01",
    "total_viewed": 200,
    "total_viewed_device_uniq": 180,
    "total_viewed_session_uniq": 190,
    "total_started": 250,
    "total_started_session_uniq": 230,
    "total_started_device_uniq": 220,
    "total_finished": 150,
    "total_finished_session_uniq": 140,
    "total_finished_device_uniq": 130,
    "engagement_rate": 75.56,
    "total_clicked": 50,
    "total_clicked_device_uniq": 45,
    "total_clicked_session_uniq": 40,
    "total_over_pitch": 30,
    "total_under_pitch": 10,
    "over_pitch_rate": 75.0,
    "total_conversions": 10,
    "overall_conversion_rate": 2.56,
    "total_amount_usd": 1000,
    "total_amount_brl": 1000,
    "total_amount_eur": 1000,
    "play_rate": 2.56
  },
  {
    "date_key": "2023-01-02",
    "total_viewed": 180,
    "total_viewed_device_uniq": 160,
    "total_viewed_session_uniq": 170,
    "total_started": 220,
    "total_started_session_uniq": 210,
    "total_started_device_uniq": 200,
    "total_finished": 130,
    "total_finished_session_uniq": 120,
    "total_finished_device_uniq": 110,
    "engagement_rate": 72.3,
    "total_clicked": 40,
    "total_clicked_device_uniq": 35,
    "total_clicked_session_uniq": 30,
    "total_over_pitch": 25,
    "total_under_pitch": 8,
    "over_pitch_rate": 75.76,
    "total_conversions": 8,
    "overall_conversion_rate": 2.27,
    "total_amount_usd": 800,
    "total_amount_brl": 800,
    "total_amount_eur": 800,
    "play_rate": 2.27
  }
]

Entendendo as Métricas Diárias

O endpoint /sessions/stats_by_day fornece detalhamentos diários detalhados de:

  • Métricas de Sessão: Visualização abrangente, contagens de início, fim e cliques para cada dia

  • Rastreamento Único: Contagens únicas separadas por sessão e dispositivo para entender o comportamento do usuário

  • Análise de Engajamento: Taxas de engajamento diárias mostrando quanto do vídeo os usuários estão assistindo

  • Performance de Pitch: Análise diária de quantos usuários assistem além do seu limite de pitch

  • Rastreamento de Conversão: Dados completos de conversão com valores monetários em múltiplas moedas

  • Análise de Tendências: Comparação dia-a-dia para identificar padrões e tendências

Casos de Uso

Este endpoint permite que você:

  • Acompanhe tendências de performance diárias: Monitore como o engajamento varia dia a dia

  • Identifique dias de pico de performance: Encontre quais dias geram mais engajamento e conversões

  • Analise padrões sazonais: Entenda como o comportamento do usuário muda ao longo do tempo

  • Rastreamento de performance de campanhas: Meça o impacto diário de campanhas de marketing

  • Otimização de conteúdo: Identifique quais dias têm taxas de engajamento mais altas para planejamento de conteúdo

  • Análise de conversão: Acompanhe padrões diários de conversão e tendências de receita

  • Insights de comportamento do usuário: Entenda padrões de visualização em diferentes dias da semana ou mês

Versão 1.1.0 (2025-06-25)

Novas Funcionalidades

  • Aprimorado o endpoint /custom_metrics/list com melhorias significativas:

    • Novo método POST: Adicionado endpoint POST em /custom_metrics/list para melhor manipulação de parâmetros

    • Cálculo de taxa de engajamento: Agora calcula e retorna taxas de engajamento para cada métrica personalizada

    • Filtro por intervalo de datas: Adicionados parâmetros opcionais start_date e end_date para filtrar métricas por período

    • Suporte a fuso horário: Adicionado parâmetro de timezone para filtragem precisa de datas em diferentes fusos horários

    • Análises de usuário aprimoradas: Retorna total_users, users_above e engagement_rate para cada métrica personalizada

Caminho de Migração

O endpoint GET original /custom_metrics/{player_id}/list está agora obsoleto e será removido em 25 de julho de 2025. Por favor, migre para o novo endpoint POST.

Exemplo de Requisição (Novo Método POST)

{
  "player_id": "64a5c8072e6fd10009828db2",
  "start_date": "2023-01-01 00:00:00",
  "end_date": "2023-12-31 23:59:59",
  "timezone": "America/Sao_Paulo"
}

Exemplo de Resposta (Aprimorada com Dados de Engajamento)

[
  {
    "id": "685acdfa39be67017b9be72d",
    "name": "Métrica Personalizada 1",
    "time": 600,
    "sequential_number": 1,
    "engagement_rate": 18.18,
    "total_users": 55,
    "users_above": 10
  },
  {
    "id": "685acdfa39be67017b9be72e",
    "name": "Métrica Personalizada 2",
    "time": 1200,
    "sequential_number": 2,
    "engagement_rate": 12.73,
    "total_users": 55,
    "users_above": 7
  }
]

Entendendo as Novas Métricas

O endpoint aprimorado agora fornece análises detalhadas de engajamento:

  • engagement_rate: Percentual de usuários que assistiram além do timestamp da métrica personalizada

  • total_users: Número total de usuários que assistiram ao vídeo no período especificado

  • users_above: Número de usuários que assistiram além do timestamp desta métrica personalizada

  • Filtro por data: Quando start_date e end_date são fornecidos, as análises são calculadas apenas para sessões dentro desse período

  • Consciência de fuso horário: As datas são adequadamente tratadas de acordo com o fuso horário especificado

Casos de Uso

Esta melhoria permite que você:

  • Analise retenção ao longo do tempo: Compare taxas de engajamento para as mesmas métricas personalizadas em diferentes períodos

  • Rastreie padrões sazonais: Use filtro por data para entender como o engajamento do usuário varia por temporada ou períodos de campanha

  • Calcule taxas de retenção precisas: Obtenha percentuais exatos de usuários atingindo cada marco personalizado

  • Gere relatórios baseados em tempo: Crie relatórios periódicos mostrando tendências de engajamento em momentos-chave do vídeo

  • Teste A/B: Compare taxas de engajamento para diferentes versões de vídeo ou campanhas de marketing

Mudanças Incompatíveis

  • Aviso de Obsolescência: O endpoint GET /custom_metrics/{player_id}/list está obsoleto e será removido em 25 de julho de 2025

  • Migração Necessária: Aplicações usando o endpoint GET devem migrar para o novo endpoint POST até a data de obsolescência

Versão 1.0.9 (2025-06-24)

Novas Funcionalidades

  • Adicionado novo endpoint /sessions/stats que fornece estatísticas abrangentes de sessão para um player específico:

    • Retorna métricas detalhadas de sessão incluindo total de visualizações, inicializações, finalizações e cliques

    • Fornece contagens únicas por sessão e dispositivo para cada tipo de métrica

    • Calcula taxas de engajamento e métricas de conversão

    • Inclui análise de tempo de pitch mostrando usuários que assistiram acima/abaixo do limite do pitch

    • Retorna dados de conversão com valores em múltiplas moedas (USD, BRL, EUR)

    • Suporte para filtro por intervalo de datas e configuração de fuso horário

Exemplo de Requisição

{
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "start_date": "2023-01-01",
  "end_date": "2024-01-31",
  "timezone": "America/Sao_Paulo",
  "video_duration": 3600,
  "pitch_time": 30
}

Exemplo de Resposta

{
  "total_viewed": 200,
  "total_viewed_device_uniq": 180,
  "total_viewed_session_uniq": 190,
  "total_started": 250,
  "total_started_session_uniq": 230,
  "total_started_device_uniq": 220,
  "total_finished": 150,
  "total_finished_session_uniq": 140,
  "total_finished_device_uniq": 130,
  "engagement_rate": 75.56,
  "total_clicked": 50,
  "total_clicked_device_uniq": 45,
  "total_clicked_session_uniq": 40,
  "total_over_pitch": 30,
  "total_under_pitch": 10,
  "over_pitch_rate": 75,
  "total_conversions": 10,
  "overall_conversion_rate": 2.56,
  "total_amount_usd": 1000,
  "total_amount_brl": 1000,
  "total_amount_eur": 1000,
  "play_rate": 2.56
}

Entendendo as Métricas

O endpoint /sessions/stats fornece várias métricas importantes:

  • Métricas de Visualização: Total de visualizações e visualizações únicas por sessão e dispositivo

  • Métricas de Engajamento: Taxas de início/fim e percentuais gerais de engajamento

  • Análise de Pitch: Mostra quantos usuários assistiram além do limite de tempo de pitch configurado

  • Dados de Conversão: Métricas completas de conversão com valores monetários em múltiplas moedas

  • Taxa de Reprodução: Percentual de visualizadores que começaram a reproduzir o vídeo após visualizar

Este endpoint é particularmente útil para:

  • Obter uma visão abrangente do desempenho do player

  • Analisar padrões de engajamento do usuário

  • Entender a eficácia das conversões

  • Rastrear retenção no limite do pitch

  • Comparar desempenho entre diferentes períodos de tempo

Version 1.0.8 (2025-06-17)

Melhorias

  • Corrigido um problema onde às vezes durante a busca da listagem de players (/players/list) alguns valores poderiam vir duplicados

Versão 1.0.7 (05/06/2025)

Melhorias

  • Aprimorado o endpoint /players/list com informações adicionais do player:

    • Adicionado campo pitch_time para mostrar a configuração de tempo de pitch do player

    • Adicionado campo duration para exibir a duração do vídeo associado

    • Mantém compatibilidade com implementações existentes

Exemplo de Resposta

[
  {
    "id": "player1",
    "name": "Meu Player",
    "pitch_time": 0,
    "duration": 3600,
    "created_at": "2025-06-05T10:00:00Z"
  }
]

Versão 1.0.6 (2025-05-30)

Novas Funcionalidades

  • Adicionado novo endpoint /custom_metrics/{player_id}/list que fornece uma lista de todas as métricas personalizadas de um player específico:

    • Retorna informações da métrica personalizada incluindo ID, nome, tempo e número sequencial

    • Permite rastrear pontos específicos de tempo do vídeo para análise de retenção

    • Possibilita o cálculo de percentuais de engajamento dos usuários em timestamps específicos do vídeo

Exemplo de Resposta

[
  {
    "id": "metric1",
    "name": "Primeiro Ponto Chave",
    "time": 30,
    "sequential_number": 1
  },
  {
    "id": "metric2",
    "name": "Segundo Ponto Chave",
    "time": 60,
    "sequential_number": 2
  }
]

Entendendo Métricas Personalizadas e Engajamento do Usuário

O endpoint de métricas personalizadas trabalha em conjunto com o endpoint /times/user_engagement para ajudar no cálculo das taxas de retenção em timestamps específicos do vídeo. Veja como usá-los juntos:

  1. Primeiro, liste suas métricas personalizadas para timestamps importantes do vídeo usando o endpoint /custom_metrics/{player_id}/list

  2. Em seguida, use o endpoint /times/user_engagement para obter o número de usuários em cada timestamp fornecendo:

    • player_id: O ID do seu player

    • video_duration: Duração total do vídeo em segundos

    • start_date e end_date: O período que você deseja analisar

    • timezone: Seu fuso horário preferido para filtragem de datas

Exemplo de requisição para /times/user_engagement:

{
  "start_date": "2023-10-26 18:24:05",
  "end_date": "2023-11-26 18:24:05",
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "video_duration": 3600,
  "timezone": "America/Sao_Paulo"
}

  1. O endpoint de engajamento do usuário retornará dados mostrando quantos usuários atingiram cada segundo do vídeo

  2. Você pode então calcular a retenção comparando o número de usuários em cada timestamp de métrica personalizada com o número total de usuários

Por exemplo, se você tem:

  • Total de usuários: 100

  • Usuários em 30 segundos (Primeiro Ponto Chave): 80

  • Usuários em 60 segundos (Segundo Ponto Chave): 50

As taxas de retenção seriam:

  • Primeiro Ponto Chave: 80% (80/100)

  • Segundo Ponto Chave: 50% (50/100)

Esta combinação permite que você:

  • Acompanhe o engajamento dos usuários em pontos específicos e significativos do seu vídeo

  • Calcule taxas de retenção para marcos personalizados

  • Analise quantos usuários estão atingindo seus momentos-chave do vídeo

  • Tome decisões baseadas em dados sobre o conteúdo e duração do vídeo

Versão 1.0.5 (28/05/2025)

Novas Funcionalidades

  • Adicionado novo endpoint /players/list que fornece uma lista de todos os players pertencentes à empresa do usuário autenticado:

    • Retorna informações básicas do player incluindo ID, nome e data de criação

    • Filtra automaticamente os players com base na empresa do usuário autenticado

    • Suporta formato de resposta JSON

Exemplo de Resposta

[
  {
    "id": "player1",
    "name": "Meu Player",
    "created_at": "2025-05-28T10:00:00Z"
  }
]

Versão 1.0.4 (27/05/2025)

Novas Funcionalidades

  • Adicionado novo endpoint /events/leaderboard que fornece rankings de players baseados em métricas de engajamento de vídeo:

    • Suporta múltiplos rankings com diferentes limites de players em uma única requisição

    • Permite filtrar por tipos de eventos (started, finished, viewed, clicked, paused)

    • Inclui métricas para total de reproduções, reproduções únicas por sessão e reproduções únicas por dispositivo

    • Suporta filtro por período com data final opcional

Exemplo de Requisição

{
  "company_id": "2b884cba-0b12-42ce-b3a1-7a3182d414df",
  "leaderboards": [
    {
      "leaderboard_limit": 10,
      "start_date": "2023-10-26",
      "end_date": "2023-11-26",
      "event": "finished"
    },
    {
      "leaderboard_limit": 5,
      "start_date": "2023-09-26",
      "event": "started"
    }
  ],
  "timezone": "America/Sao_Paulo"
}

Exemplo de Resposta

[
  {
    "leaderboard_name": "leaderboard_10",
    "event": "finished",
    "leaderboards": [
      {
        "player_id": "player1",
        "total_plays": 100,
        "uniq_plays": 50,
        "uniq_device_plays": 25
      }
    ]
  }
]

Version 1.0.3 (2025-05-15)

Melhorias

  • Melhorada a performance dos seguintes endopints:

    • /events/total_by_company_day

Detalhamento

Algumas vezes durante a requisição de alguns usuários, os mesmos estavam atingindo o limite de recurso permitido, porém, o request em questão não requisitava muitos dias de dados, isso foi um problema causado devido a maneira com a qual o endpoint agregava dados, todos os requests devem ser normalizados agora utilizando uma quantidade devida de recursos.

Versão 1.0.2 (2025-05-15)

Melhorias

  • Melhorias para lidar com exceções em requests que utilizam mais recursos do que o permitido considerando o plano da empresa:

    • Adicionado controles específicos para lidar com o erro AUTHENTICATION_FAILED

    • Adicionado controles específicos para lidar com o erro MEMORY_LIMIT_EXCEEDED

Exemplos de respostas de erro 401 - Não autorizado

Quando uma empresa não tem acesso ainda a API:

{
  "error": "This company does not have access to the public analytics API.",
  "code": 516
}

Quando a query ultrapassa o limite de recurso autorizado para o plano da empresa:

{
  "error": "Your api key tier is not enough to perform this query. Please contact support at contato@vturb.com.br",
  "code": 241
}

Versão 1.0.1 (15/05/2025)

Correções de Bugs

  • Corrigido o tratamento de fuso horário no endpoint /sessions/stats_by_field_by_day para garantir relatórios de data consistentes em diferentes fusos horários. Isso afeta como as datas são calculadas nas seguintes métricas:

    • Estatísticas de sessão por dia

    • Taxas de conversão

    • Timestamps de eventos

    • Agregações baseadas em data

Exemplo da Correção

Antes desta correção, ao usar o fuso horário "America/Sao_Paulo" (GMT-3), eventos que ocorreram no mesmo dia poderiam ser divididos em duas datas diferentes devido a problemas de conversão de fuso horário. Por exemplo:

// Antes da correção
{
    "grouped_field": "United States",
    "total_viewed": 100,
    "date_key": "2025-05-13"  // Alguns eventos de 14 de maio foram incorretamente agrupados aqui
},
{
    "grouped_field": "United States",
    "total_viewed": 200,
    "date_key": "2025-05-14"  // Apenas alguns eventos de 14 de maio estavam aqui
}

Agora, todos os eventos do mesmo dia são agrupados corretamente, independentemente do fuso horário especificado na requisição:

// Após a correção
{
  "grouped_field": "United States",
  "total_viewed": 300, // Todos os eventos de 14 de maio agora estão corretamente agrupados
  "date_key": "2025-05-14"
}

Nota: Esta versão inclui correções e melhorias na funcionalidade existente sem introduzir novos recursos ou alterações incompatíveis.

PreviousAnalytics

Last updated