# Analytics O analytics do Kinescope coleta dados sobre o número total de visualizações e carregamentos do player, profundidade de visualização, geografia do público, plataformas, sistemas operacionais e navegadores. Esses dados ajudam a entender como seu público interage com seu conteúdo e a otimizar suas estratégias de vídeo. ## Para quem é este artigo * **Profissionais de marketing** — precisam acompanhar o desempenho do conteúdo de vídeo e analisar o comportamento do público * **Gestores de conteúdo** — precisam entender quais vídeos são populares e por quê * **Desenvolvedores** — precisam integrar analytics em seus sistemas via API * **Criadores de cursos** — precisam acompanhar o progresso e o engajamento dos alunos ## **Acessando o analytics** O analytics está disponível tanto para vídeos individuais quanto para todo o workspace: * **Para um vídeo específico** * Abra o catálogo, encontre o vídeo que você precisa e clique duas vezes no nome. * Acesse a aba **"Analytics"**. ![Analytics para um vídeo específico](images/cvm-analytics-video-01.webp) * **Para todos os vídeos do workspace** * Clique no ícone **"Analytics"** no menu esquerdo — ele é acessível de qualquer lugar na plataforma. ![Analytics geral do workspace](images/cvm-analytics-workspace-01.webp) > **Информация:** Para ver dados em tempo real, use o modo **"Assistindo agora"** na linha acima do gráfico. Você também pode definir um intervalo de tempo personalizado usando o filtro **"Período"**. O analytics geral também inclui o **top 25 dos vídeos mais populares**. Você pode encontrá-lo na parte inferior da página. ![Top 25 dos vídeos mais populares](images/cvm-analytics-top-01.webp) ## **Métricas principais** **Visualizações** Mostra o número de inícios de vídeo. Uma visualização é contada após 5 segundos de reprodução contínua. ![Métrica de visualizações](images/cvm-analytics-views-01.webp) **Carregamentos do player** Mostra quantas vezes o player com o vídeo foi carregado em uma página. Se você abrir uma página com vídeo e depois atualizá-la, isso conta como dois carregamentos do player. **Taxa de visualização** Esta métrica reflete aproximadamente o interesse no vídeo, a eficácia do posicionamento do player ou a atratividade do poster. * **Gráfico**: a proporção de visualizações em relação a carregamentos do player. * **Porcentagem**: a proporção geral de todas as visualizações em relação a todos os carregamentos do player em todos os tempos. Na captura de tela acima: 20 visualizações / 85 carregamentos do player = 24% (arredondado). **Impressões únicas** O player memoriza a sessão do dispositivo e conta a unicidade por sessão. ![Métrica de impressões únicas](images/cvm-analytics-impressions-01.webp) **Engajamento ou profundidade de visualização** Mostra o tempo médio de visualização (quantos minutos um usuário assistiu do total do vídeo) e como esse valor mudou ao longo do período selecionado. Uma visualização é contada dentro de uma única sessão: em uma sessão um usuário pode assistir o vídeo várias vezes, mas é contado como uma visualização. Se dentro de uma sessão um usuário reassistir o mesmo segmento várias vezes, conta como uma visualização desse segmento. Esta métrica mostra o quão alto é a qualidade do conteúdo — e, portanto, quão bem ele pode manter a atenção do espectador. ![Métrica de engajamento e profundidade de visualização](images/cvm-analytics-engagement-01.webp) **Principais países, plataformas e SO** Dados de visualização divididos por país, plataforma (desktop, tablet, smartphone) e sistema operacional. ![Geografia, plataformas e sistemas operacionais](images/cvm-analytics-geography-01.webp) **Referenciadores (fontes de posicionamento)** Mostra quais páginas e domínios o player carrega e quão eficaz é cada posicionamento. Útil para comparar a qualidade do tráfego entre fontes e encontrar posicionamentos com baixa taxa de visualização. Abra a sub-aba **"Referenciador"** na aba "Analytics" — ela mostra uma tabela com as colunas: * **URL** — a página onde o player está incorporado * **Visualizações** — número de inícios de vídeo (uma visualização é contada após 5 segundos de reprodução) * **Carregamentos do player** — quantas vezes o player foi carregado na página * **Taxa de visualização** — proporção de visualizações em relação a carregamentos do player (`Visualizações / Carregamentos do player × 100%`) As linhas são agrupadas por domínio: o domínio aparece como uma linha pai com métricas totais, e páginas individuais são listadas abaixo dele. Os grupos podem ser recolhidos e expandidos. O período pode ser definido usando o filtro ("Últimas 24 horas", "Esta semana", "Este mês", "Todo o tempo" ou "Período"). Os dados podem ser exportados para CSV ou XLSX usando o botão **"Exportar"**. ![Referenciadores](images/cvm-analytics-referrers-01.png) ## Exportação de relatório Se houver muitos dados ou se você precisar levá-los para o seu próprio sistema de relatórios, exporte o analytics para um arquivo. O relatório é gerado em segundo plano no lado do Kinescope e, quando estiver pronto, chega ao e-mail informado como um arquivo ZIP contendo um arquivo CSV ou XLSX. Dentro do arquivo, cada linha corresponde a um vídeo, evento ao vivo ou gravação de stream — os dados são agrupados por identificador. ![Janela "Exportar relatório": formato, período, colunas e e-mail](images/cvm-analytics-export-01.png) ### Como gerar um relatório 1. Abra a seção **"Analytics"** → clique em **"Exportar relatório"**. 2. Escolha o **período** dos dados (veja a lista abaixo). 3. Marque as **pastas** que entram no relatório. Se uma pasta com subpastas estiver selecionada, os dados das subpastas também são incluídos. 4. Marque os **campos** que entram no arquivo (veja a tabela abaixo). 5. Indique o **formato do arquivo**: CSV ou XLSX. 6. Informe o **e-mail** para o qual enviar o relatório e clique em **"Gerar"**. A janela de configuração do relatório será fechada. Quando o relatório estiver pronto, um e-mail com o link para o arquivo ZIP será enviado ao endereço indicado. ### Período Estão disponíveis intervalos fixos e um período personalizado: * Todo o tempo * Hoje * Ontem * Esta semana * Semana passada * Este mês * Mês passado * Ano passado * **Período personalizado** — defina manualmente as datas de início e fim. ### Campos do relatório Os campos são divididos em três grupos. Alguns campos aparecem no relatório apenas para o tipo de conteúdo correspondente — por exemplo, o identificador do evento ao vivo é exportado apenas para streams. **Identificação do conteúdo** * **ID do projeto** (`project_id`) * **Nome do projeto** (`project_name`) * **ID do vídeo** (`video_id`) — campo obrigatório para linhas de vídeo. * **ID do stream** (`stream_id`) — campo obrigatório para linhas de stream. * **ID do evento** (`event_id`) — campo obrigatório para linhas de evento ao vivo. * **Título** (`title`) * **Duração** (`duration`) * **Pasta** (`folder_name`) — caminho até o arquivo, por exemplo `folder1/folder2`. * **ID da pasta** (`folder_id`) **Métricas de analytics** * **Carregamentos do player** (`player_loads`) — quantas vezes o player com o vídeo foi carregado em uma página. * **Impressões únicas** (`unique_views`) — sessões únicas em que o vídeo foi iniciado. * **Visualizações** (`views`) — número de inícios de vídeo; contado após 5 segundos de reprodução contínua. * **Tempo total de visualização** (`total_watch_time`) — quanto tempo, no total, os espectadores assistiram no período selecionado. * **Taxa de visualização** — calculada como `total_watch_time ÷ (views × duration) × 100%` e mostra a profundidade de visualização do conteúdo no período selecionado. **Métricas de transmissões** * **Pico de espectadores simultâneos** (`peak_concurrent_viewers`) — maior número de espectadores assistindo à transmissão ao mesmo tempo. ### O que vale a pena saber * O relatório é gerado **com base nas pastas selecionadas, incluindo as subpastas** — a lista corresponde ao que você vê no catálogo. * Se um conteúdo não tiver visualizações no período selecionado, a linha ainda entra no relatório com todas as métricas iguais a zero — útil para conferir a lista de conteúdo. * Um relatório — um e-mail. Para enviar uma cópia para colegas, encaminhe a mensagem manualmente ou gere o relatório novamente com outro endereço. * O link para o arquivo fica disponível por tempo limitado. Se o link expirar, gere o relatório novamente. ## Analytics avançado para desenvolvedores Para análise mais profunda e integração de analytics em seus sistemas, dois métodos estão disponíveis: ### IFrame Player API — para analytics do lado do cliente A IFrame Player API ajuda a coletar eventos do lado do cliente e enviá-los para sua plataforma de analytics junto com contexto (por exemplo, ID do usuário, curso, aula, dispositivo, navegador). Isso é normalmente usado quando você precisa: * **Em LMS** — rastrear progresso, tempo de visualização e retrocessos. * **Em cenários interativos** — entender como os usuários interagem com o vídeo (pausas, retrocessos, etc.). * **Em portais corporativos** — registrar a atividade dos funcionários em relação ao conteúdo de vídeo. * **Em integrações** — enviar eventos para seus sistemas de analytics, CRM ou LMS. Usando a IFrame Player API, você pode capturar não apenas visualizações, mas eventos detalhados (pausas, retrocessos, reproduções) e reagir a eles em tempo real. Saiba mais sobre os recursos da IFrame Player API no artigo [IFrame Player API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/). ### Analytics REST API Todos os dados de analytics também estão disponíveis via REST API. Os recursos incluem: * Classificação de dados por data, ID do vídeo * Agrupamento personalizado por campos e parâmetros * Recuperação de estatísticas para qualquer período de tempo > **Информация:** **Antes de começar:** Se você é novo na API do Kinescope, recomendamos revisar as [diretrizes gerais de API](https://docs-br.kinescope.com/developer-guides/api-general-rules/) — elas cobrem autorização, formato de token, paginação e tratamento de erros. **Analytics API (para desenvolvedores):** **Estatísticas gerais para um período:** ```bash curl -X GET "https://api.kinescope.io/v1/analytics/overview?from=2024-01-01&to=2024-01-31" \ -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" ``` **Parâmetros da solicitação:** - `from` (obrigatório) — início do período no formato `YYYY-MM-DD` ou `YYYY-MM-DDTHH:MM:SSZ` (RFC3339) - `to` (obrigatório) — fim do período no formato `YYYY-MM-DD` ou `YYYY-MM-DDTHH:MM:SSZ` (RFC3339) - `project_id` (opcional) — filtrar por projeto - `video_id` (opcional) — filtrar por vídeo **Estatísticas detalhadas com agrupamento:** ```bash curl -X GET "https://api.kinescope.io/v1/analytics?from=2024-01-01&to=2024-01-31&group_by=video_id&order=views.desc&per_page=10" \ -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" ``` **Parâmetros da solicitação:** - `from` (obrigatório) — início do período no formato `YYYY-MM-DD` ou `YYYY-MM-DDTHH:MM:SSZ` - `to` (obrigatório) — fim do período no formato `YYYY-MM-DD` ou `YYYY-MM-DDTHH:MM:SSZ` - `group_by` (obrigatório) — agrupamento de dados. Valores disponíveis: - `video_id` — por vídeo - `project_id` — por projeto - `date` — por dia - `country` — por país - `project_id` (opcional) — filtrar por projeto - `video_id` (opcional) — filtrar por vídeo - `page` (opcional) — número da página (padrão: 1) - `per_page` (opcional) — itens por página (padrão: 10) - `order` (opcional) — classificação no formato `campo.direção` (por exemplo, `views.desc`). Saiba mais sobre classificação nas [diretrizes gerais de API](https://docs-br.kinescope.com/developer-guides/api-general-rules/#sorting) **Tratamento de erros:** Se os parâmetros forem inválidos, a API retorna um erro de validação com código `400400`. Por exemplo, se os parâmetros obrigatórios `from` ou `to` estiverem ausentes, ou se um campo de classificação inválido for especificado (código `400216`). Saiba mais sobre tratamento de erros nas [diretrizes gerais de API](https://docs-br.kinescope.com/developer-guides/api-general-rules/#error-handling). Valor adicional pode ser obtido vinculando dados de visualização do player a sessões de usuário. Essa abordagem permite coletar analytics não apenas sobre vídeo, mas sobre espectadores específicos. Para personalizar o analytics, incorpore o player usando [IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api/), e ao [criar o player em uma página](https://docs-br.kinescope.com/player-docs/embedding/simple-iframe-embed/) passe o identificador do usuário (como e-mail ou ID) via parâmetro `externalId`. ## O que fazer a seguir? Depois de explorar o analytics, recomendamos: 1. **[Otimizar conteúdo](https://docs-br.kinescope.com/catalog-and-video-management/media-file-settings/)** — use dados de analytics para melhorar posters e descrições 2. **[IFrame Player API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/)** — use a IFrame Player API para analytics avançado enriquecido com dados contextuais 3. **[Configurar integração de analytics](https://docs-br.kinescope.com/developer-guides/)** — conecte o analytics aos seus sistemas via REST API 4. **[Incorporação](https://docs-br.kinescope.com/video-player/embedding/)** — configure o player para coleta de dados de analytics Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudá-lo!