Analytics API
A API de Analytics permite-te ler métricas de reprodução e de entrega do teu workspace. Todos os endpoints são pedidos GET só de leitura em /api/analytics/*.
A tua Chave API tem de ter a permissão analytics.read. Apenas read em vídeos não chega. Consulta Autenticação.
Endpoints
As métricas de reprodução vêm do player. As métricas de entrega vêm do CDN e do armazenamento.
| Endpoint | Path |
|---|---|
| Reproduções | GET /api/analytics/views |
| Fontes | GET /api/analytics/sources |
| Conteúdo | GET /api/analytics/content |
| Distribuição | GET /api/analytics/breakdown |
| Conclusão | GET /api/analytics/completion |
| Espetadores | GET /api/analytics/watching |
| Engagement | GET /api/analytics/engagement |
| Ao vivo | GET /api/analytics/live |
| Tráfego | GET /api/analytics/traffic |
| Pedidos | GET /api/analytics/requests[/:videoId] |
Autenticação
Passa a tua Chave API como Token Bearer:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/views?interval=day"O workspace é obtido a partir da Chave API. Não envies um parâmetro de consulta workspaceId.
Âmbito de categoria
Se a tua Chave API estiver limitada a categorias específicas:
- As chamadas de Analytics ao nível do workspace (sem
contentIdde vídeo nem:videoId) continuam a devolver agregados de todo o workspace. - As chamadas por vídeo que passam um
contentIdVOD ou:videoIdsó têm sucesso quando esse vídeo está dentro do âmbito de categoria da chave. - O conteúdo live (
contentType=live) não é filtrado pelo âmbito de categoria.
Parâmetros de consulta comuns
Muitos endpoints partilham estes parâmetros:
| Parâmetro | Tipo | Descrição |
|---|---|---|
contentType | string | vod (predefinição) ou live |
contentId | string | Id do vídeo ou id do evento live |
from | string | Hora de início ISO 8601. Predefinição: cerca de 30 dias atrás. |
to | string | Hora de fim ISO 8601. Predefinição: agora. |
minimumWatchSeconds | number | Tempo mínimo de visualização para uma view contar. Predefinição: 3. |
interval | string | Para plays: hour ou day (predefinição day) |
limit | number | Máx. de linhas para listas ordenadas. Predefinição: 100. |
Tráfego e Pedidos usam startDate e endDate em vez de from e to. Ambos são obrigatórios.
Intervalos maiores do que cerca de um ano são limitados ao ano mais recente nos endpoints de reprodução.
Erros
| Estado | Body | Significado |
|---|---|---|
400 | { "error": "..." } ou texto simples | Parâmetros de consulta inválidos |
403 | — | Falta analytics.read, chave desativada ou contentId VOD fora do âmbito |
500 | { "error": "analytics_not_configured" } | Analytics não está configurado no servidor |
502 | { "error": "analytics_upstream_error" } | Erro upstream de analytics |
504 | { "error": "analytics_timeout" } | Timeout upstream de analytics |
500 / 502 / 504 aplicam-se aos endpoints de reprodução. Tráfego e pedidos devolvem 400 como texto simples quando startDate ou endDate falta ou é inválido.
As respostas de reprodução incluem Cache-Control: private, no-store. Não armazenes em cache as respostas de analytics no navegador entre mudanças de workspace.