Analytics API
L’API Analytics ti consente di leggere le metriche di riproduzione 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
| Endpoint | Path |
|---|---|
| Riproduzioni | GET /api/analytics/plays |
| 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 |
Autenticazione
Passa la tua chiave API come Token Bearer:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/plays?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) restituiscono comunque aggregati dell’intero workspace. - Le chiamate per video che passano un
contentIdVOD hanno 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. |
Gli intervalli più ampi di circa un anno vengono limitati all’anno più recente.
Errori
| Stato | Body | Significato |
|---|---|---|
400 | { "error": "..." } | 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 |
Le risposte includono Cache-Control: private, no-store. Non memorizzare in cache le risposte analytics nel browser tra i cambi di workspace.