Analytics API
API Analytics pozwala odczytywać metryki odtwarzania i dostarczania w Twoim workspace. Wszystkie endpointy to żądania GET tylko do odczytu pod /api/analytics/*.
Twój klucz API musi mieć uprawnienie analytics.read. Samo read dla wideo nie wystarczy. Zobacz Uwierzytelnianie.
Endpointy
Metryki odtwarzania pochodzą z playera. Metryki dostarczania pochodzą z CDN i storage.
| Endpoint | Path |
|---|---|
| Odtworzenia | GET /api/analytics/views |
| Źródła | GET /api/analytics/sources |
| Treść | GET /api/analytics/content |
| Podział | GET /api/analytics/breakdown |
| Ukończenie | GET /api/analytics/completion |
| Widzowie | GET /api/analytics/watching |
| Engagement | GET /api/analytics/engagement |
| Na żywo | GET /api/analytics/live |
| Transfer | GET /api/analytics/traffic |
| Żądania | GET /api/analytics/requests[/:videoId] |
Uwierzytelnianie
Przekaż swój klucz API jako Token Bearer:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/views?interval=day"Workspace jest brany z klucza API. Nie wysyłaj parametru zapytania workspaceId.
Zakres kategorii
Jeśli Twój klucz API jest ograniczony do wybranych kategorii:
- Wywołania Analytics na poziomie workspace (bez
contentIdwideo ani:videoId) nadal zwracają agregaty całego workspace. - Wywołania per wideo, które przekazują VOD
contentIdlub:videoId, kończą się powodzeniem tylko wtedy, gdy to wideo jest w zakresie kategorii klucza. - Treści live (
contentType=live) nie są filtrowane według zakresu kategorii.
Wspólne parametry zapytania
Wiele endpointów korzysta z tych samych parametrów:
| Parametr | Typ | Opis |
|---|---|---|
contentType | string | vod (domyślnie) lub live |
contentId | string | Id wideo lub id wydarzenia na żywo |
from | string | Czas rozpoczęcia ISO 8601. Domyślnie około 30 dni wstecz. |
to | string | Czas zakończenia ISO 8601. Domyślnie teraz. |
minimumWatchSeconds | number | Minimalny czas oglądania, aby wyświetlenie się liczyło. Domyślnie 3. |
interval | string | Dla plays: hour lub day (domyślnie day) |
limit | number | Maks. liczba wierszy w rankingach. Domyślnie 100. |
Transfer i Żądania używają startDate i endDate zamiast from i to. Oba są wymagane.
Zakresy dłuższe niż około roku są ograniczane do najnowszego roku na endpointach odtwarzania.
Błędy
| Status | Body | Znaczenie |
|---|---|---|
400 | { "error": "..." } lub zwykły tekst | Nieprawidłowe parametry zapytania |
403 | — | Brak analytics.read, wyłączony klucz lub contentId VOD poza zakresem |
500 | { "error": "analytics_not_configured" } | Analytics nie jest skonfigurowane na serwerze |
502 | { "error": "analytics_upstream_error" } | Błąd upstream analytics |
504 | { "error": "analytics_timeout" } | Timeout upstream analytics |
500 / 502 / 504 dotyczą endpointów odtwarzania. Transfer i żądania zwracają 400 jako zwykły tekst, gdy brakuje startDate lub endDate albo wartość jest nieprawidłowa.
Odpowiedzi odtwarzania zawierają Cache-Control: private, no-store. Nie zapisuj w cache odpowiedzi analytics w przeglądarce przy przełączaniu workspace.