Analytics-API

Verfolgen Sie das Leser-Engagement und rufen Sie Analysedaten ab, einschließlich Seitenaufrufe, eindeutiger Besucher, Lesezeit, geografischer Verteilung und Gerätestatistiken.

On this page

Analytics-API

Die Analytics-API ermöglicht es Ihnen, Betrachterinteraktionen mit Ihren Publikationen zu verfolgen und Engagement-Metriken abzurufen. Die Analysedaten umfassen Seitenaufrufe, eindeutige Besucher, Lesezeit, seitenbasierte Heatmaps, geografische Verteilung und Geräte-Aufschlüsselungen.

Basis-URL: https://api.zenflip.io/v1/analytics

Ein Ereignis erfassen

Zeichnet eine Betrachterinteraktion auf. Dies ist ein öffentlicher Endpunkt, der vom eingebetteten Flipbook-Viewer verwendet wird --- eine Authentifizierung ist nicht erforderlich.

` POST /analytics/track `

Ratenlimit: 30 Ereignisse pro Sekunde pro IP-Adresse (um schnelles Seitenblättern zu ermöglichen).

Anfragekörper

Feld

Typ

Erforderlich

Beschreibung

publicationId

string

Ja

UUID der betrachteten Publikation

eventType

string

Ja

Ereignistyp (max. 30 Zeichen): page_view, session_start, session_end, download, share

sessionId

string

Nein

Sitzungskennung des Betrachters (max. 100 Zeichen)

viewerId

string

Nein

Anonyme Betrachterkennung (max. 100 Zeichen)

pageNumber

integer

Nein

Angezeigte Seitennummer

duration

integer

Nein

Verweildauer auf der Seite in Sekunden

deviceType

string

Nein

Gerätekategorie: desktop, tablet, mobile

browser

string

Nein

Browsername (z.B. Chrome, Safari)

os

string

Nein

Betriebssystem (z.B. macOS, Windows, iOS)

country

string

Nein

ISO 3166-1 Alpha-2 Ländercode (z.B. US, GB)

city

string

Nein

Stadtname (max. 100 Zeichen)

referrer

string

Nein

Referrer-URL (max. 500 Zeichen)

metadata

object

Nein

Beliebige Schlüssel-Wert-Metadaten

Beispielanfrage

`bash curl -X POST https://api.zenflip.io/v1/analytics/track \ -H "Content-Type: application/json" \ -d '{ "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "eventType": "page_view", "sessionId": "sess_abc123", "viewerId": "anon_xyz789", "pageNumber": 5, "duration": 12, "deviceType": "desktop", "browser": "Chrome", "os": "macOS", "country": "US", "city": "San Francisco" }' `

Beispielantwort

`json { "message": "Event tracked" } `

Organisationsübersicht

Ruft eine übergeordnete Analysezusammenfassung über alle Publikationen in Ihrer Organisation ab.

` GET /analytics/overview `

Abfrageparameter

Parameter

Typ

Erforderlich

Beschreibung

start

string

Nein

Startdatum im ISO 8601-Format (z.B. 2026-01-01T00:00:00Z)

end

string

Nein

Enddatum im ISO 8601-Format

range

string

Nein

Kurzform-Zeitraum: 7d, 30d, 90d (wird durch start/end überschrieben)

Beispielanfrage

`bash curl "https://api.zenflip.io/v1/analytics/overview?range=30d" \ -H "Authorization: Bearer YOUR_TOKEN" `

Beispielantwort

`json { "data": { "totalViews": 12450, "uniqueViewers": 3280, "avgReadTimeSeconds": 142, "totalPublications": 15, "topPublications": [ { "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "views": 4200, "uniqueViewers": 1100 } ], "viewsByDay": [ { "date": "2026-02-01", "views": 420, "uniqueViewers": 110 }, { "date": "2026-02-02", "views": 380, "uniqueViewers": 95 } ] } } `

Publikationsanalysen

Ruft detaillierte Analysen für eine bestimmte Publikation ab, einschließlich seitenbasierter Heatmap-Daten, geografischer Verteilung und Geräte-Aufschlüsselung.

` GET /analytics/publications/:pubId `

Abfrageparameter

Parameter

Typ

Erforderlich

Beschreibung

start

string

Nein

Startdatum (ISO 8601)

end

string

Nein

Enddatum (ISO 8601)

Beispielanfrage

`bash curl "https://api.zenflip.io/v1/analytics/publications/a1b2c3d4-e5f6-7890-abcd-ef1234567890?start=2026-02-01T00:00:00Z&end=2026-02-20T23:59:59Z" \ -H "Authorization: Bearer YOUR_TOKEN" `

Beispielantwort

`json { "data": { "summary": { "totalViews": 4200, "uniqueViewers": 1100, "avgReadTimeSeconds": 165, "avgPagesViewed": 8.3, "bounceRate": 0.22 }, "pageHeatmap": [ { "pageNumber": 1, "views": 4200, "avgDurationSeconds": 8 }, { "pageNumber": 2, "views": 3900, "avgDurationSeconds": 12 }, { "pageNumber": 3, "views": 3100, "avgDurationSeconds": 15 }, { "pageNumber": 4, "views": 2800, "avgDurationSeconds": 20 } ], "geography": [ { "country": "US", "views": 2100, "percentage": 50.0 }, { "country": "GB", "views": 840, "percentage": 20.0 }, { "country": "DE", "views": 420, "percentage": 10.0 } ], "devices": [ { "deviceType": "desktop", "views": 2940, "percentage": 70.0 }, { "deviceType": "mobile", "views": 1050, "percentage": 25.0 }, { "deviceType": "tablet", "views": 210, "percentage": 5.0 } ], "browsers": [ { "browser": "Chrome", "views": 2520, "percentage": 60.0 }, { "browser": "Safari", "views": 1260, "percentage": 30.0 }, { "browser": "Firefox", "views": 420, "percentage": 10.0 } ], "viewsByDay": [ { "date": "2026-02-01", "views": 210, "uniqueViewers": 55 }, { "date": "2026-02-02", "views": 195, "uniqueViewers": 48 } ] } } `

Antwortfelder

Feld

Beschreibung

summary

Aggregierte Metriken für den Zeitraum

pageHeatmap

Aufrufe pro Seite und durchschnittliche Verweildauer

geography

Betrachterverteilung nach Land (ISO Alpha-2 Codes)

devices

Aufschlüsselung nach Gerätetyp (Desktop, Mobil, Tablet)

browsers

Aufschlüsselung nach Browsername

viewsByDay

Tägliche Zeitreihe von Aufrufen und eindeutigen Besuchern

Analysen als CSV exportieren

Exportiert Roh-Analysedaten als CSV-Datei zur Verwendung in Tabellenkalkulationen oder Business-Intelligence-Tools.

` GET /analytics/export `

Erforderlicher Plan: Creator oder höher.

Abfrageparameter

Parameter

Typ

Erforderlich

Beschreibung

pubId

string

Nein

Nach Publikations-ID filtern

start

string

Nein

Startdatum (ISO 8601)

end

string

Nein

Enddatum (ISO 8601)

Beispielanfrage

`bash curl "https://api.zenflip.io/v1/analytics/export?pubId=a1b2c3d4...&start=2026-01-01T00:00:00Z&end=2026-02-20T23:59:59Z" \ -H "Authorization: Bearer YOUR_TOKEN" `

Beispielantwort

`json { "data": "date,publication_id,event_type,page_number,viewer_id,device_type,country,city,duration\n2026-02-01,a1b2c3d4...,page_view,1,anon_xyz789,desktop,US,San Francisco,8\n2026-02-01,a1b2c3d4...,page_view,2,anon_xyz789,desktop,US,San Francisco,12\n" } `

Der CSV-String wird im data-Feld zurückgegeben. Parsen Sie ihn clientseitig oder speichern Sie ihn direkt in eine Datei.

Referenz der Ereignistypen

Ereignistyp

Beschreibung

session_start

Betrachter hat die Publikation geöffnet

page_view

Betrachter hat zu einer bestimmten Seite navigiert

session_end

Betrachter hat die Publikation geschlossen oder navigiert weg

download

Betrachter hat das PDF heruntergeladen (falls aktiviert)

share

Betrachter hat die Teilen-Funktion verwendet

Next →
Lead-Capture-API