Analytics API
L’API Analytics ti consente di leggere le metriche di riproduzione e di erogazione del tuo workspace. Tutti gli endpoint sono richieste GET in sola lettura sotto /api/analytics/*.
La tua chiave API deve avere il permesso analytics.read. Il solo read sui video non basta. Vedi Autenticazione.
Endpoint
Le metriche di riproduzione arrivano dal player. Le metriche di erogazione arrivano dal CDN e dallo storage.
| Endpoint | Path |
|---|---|
| Riproduzioni | GET /api/analytics/views |
| Fonti | GET /api/analytics/sources |
| Contenuto | GET /api/analytics/content |
| Suddivisione | GET /api/analytics/breakdown |
| Completamento | GET /api/analytics/completion |
| Spettatori | GET /api/analytics/watching |
| Engagement | GET /api/analytics/engagement |
| In diretta | GET /api/analytics/live |
| Traffico | GET /api/analytics/traffic |
| Richieste | GET /api/analytics/requests[/:videoId] |
Autenticazione
Passa la tua chiave API come Token Bearer:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/views?interval=day"Il workspace viene preso dalla chiave API. Non inviare un parametro di query workspaceId.
Ambito di categorie
Se la tua chiave API è limitata a categorie specifiche:
- Le chiamate Analytics a livello di workspace (senza
contentIdvideo né:videoId) restituiscono comunque aggregati dell’intero workspace. - Le chiamate per video che passano un
contentIdVOD o:videoIdhanno successo solo se quel video è all’interno dell’ambito di categorie della chiave. - I contenuti live (
contentType=live) non vengono filtrati per ambito di categorie.
Parametri di query comuni
Molti endpoint condividono questi parametri:
| Parametro | Tipo | Descrizione |
|---|---|---|
contentType | string | vod (predefinito) o live |
contentId | string | Id video o id evento live |
from | string | Ora di inizio ISO 8601. Predefinito: circa 30 giorni fa. |
to | string | Ora di fine ISO 8601. Predefinito: ora. |
minimumWatchSeconds | number | Tempo minimo di visione perché una view conti. Predefinito: 3. |
interval | string | Per plays: hour o day (predefinito day) |
limit | number | Max righe per elenchi classificati. Predefinito: 100. |
Traffico e Richieste usano startDate e endDate al posto di from e to. Entrambi sono obbligatori.
Gli intervalli più ampi di circa un anno vengono limitati all’anno più recente sugli endpoint di riproduzione.
Errori
| Stato | Body | Significato |
|---|---|---|
400 | { "error": "..." } o testo semplice | Parametri di query non validi |
403 | — | Manca analytics.read, chiave disabilitata o contentId VOD fuori ambito |
500 | { "error": "analytics_not_configured" } | Analytics non è configurato sul server |
502 | { "error": "analytics_upstream_error" } | Errore upstream di analytics |
504 | { "error": "analytics_timeout" } | Timeout upstream di analytics |
500 / 502 / 504 valgono per gli endpoint di riproduzione. Traffico e richieste restituiscono 400 come testo semplice quando startDate o endDate manca o non è valido.
Le risposte di riproduzione includono Cache-Control: private, no-store. Non memorizzare in cache le risposte analytics nel browser tra i cambi di workspace.