API Analytics

Suivez l'engagement des lecteurs et récupérez les données analytiques incluant les pages vues, les visiteurs uniques, le temps de lecture, la répartition géographique et les statistiques par appareil.

On this page

API Analytics

L'API Analytics vous permet de suivre les interactions des lecteurs avec vos publications et de récupérer des métriques d'engagement. Les données analytiques incluent les pages vues, les visiteurs uniques, le temps de lecture, les cartes thermiques page par page, la distribution géographique et la répartition par appareil.

URL de base : https://api.zenflip.io/v1/analytics

Suivre un événement

Enregistrez un événement d'interaction d'un lecteur. Il s'agit d'un endpoint public utilisé par le lecteur flipbook intégré --- aucune authentification n'est requise.

` POST /analytics/track `

Limite de débit : 30 événements par seconde par adresse IP (pour gérer les changements de page rapides).

Corps de la requête

Champ

Type

Requis

Description

publicationId

string

Oui

UUID de la publication consultée

eventType

string

Oui

Type d'événement (max 30 car.) : page_view, session_start, session_end, download, share

sessionId

string

Non

Identifiant de session du lecteur (max 100 car.)

viewerId

string

Non

Identifiant anonyme du lecteur (max 100 car.)

pageNumber

integer

Non

Numéro de la page consultée

duration

integer

Non

Temps passé sur la page en secondes

deviceType

string

Non

Catégorie d'appareil : desktop, tablet, mobile

browser

string

Non

Nom du navigateur (ex. : Chrome, Safari)

os

string

Non

Système d'exploitation (ex. : macOS, Windows, iOS)

country

string

Non

Code pays ISO 3166-1 alpha-2 (ex. : US, GB)

city

string

Non

Nom de la ville (max 100 car.)

referrer

string

Non

URL de provenance (max 500 car.)

metadata

object

Non

Métadonnées arbitraires clé-valeur

Exemple de requête

`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" }' `

Exemple de réponse

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

Vue d'ensemble de l'organisation

Récupérez un résumé analytique de haut niveau pour l'ensemble des publications de votre organisation.

` GET /analytics/overview `

Paramètres de requête

Paramètre

Type

Requis

Description

start

string

Non

Date de début au format ISO 8601 (ex. : 2026-01-01T00:00:00Z)

end

string

Non

Date de fin au format ISO 8601

range

string

Non

Plage raccourcie : 7d, 30d, 90d (remplacée par start/end)

Exemple de requête

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

Exemple de réponse

`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 } ] } } `

Analytics par publication

Récupérez des analyses détaillées pour une publication spécifique, y compris les données de carte thermique page par page, la distribution géographique et la répartition par appareil.

` GET /analytics/publications/:pubId `

Paramètres de requête

Paramètre

Type

Requis

Description

start

string

Non

Date de début (ISO 8601)

end

string

Non

Date de fin (ISO 8601)

Exemple de requête

`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" `

Exemple de réponse

`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 } ] } } `

Champs de réponse

Champ

Description

summary

Métriques agrégées pour la période

pageHeatmap

Nombre de vues par page et temps moyen passé

geography

Distribution des lecteurs par pays (codes ISO alpha-2)

devices

Répartition par type d'appareil (desktop, mobile, tablette)

browsers

Répartition par nom de navigateur

viewsByDay

Série temporelle journalière des vues et visiteurs uniques

Exporter les analytics en CSV

Exportez les données analytiques brutes sous forme de fichier CSV pour utilisation dans des tableurs ou des outils de business intelligence.

` GET /analytics/export `

Forfait requis : Creator ou supérieur.

Paramètres de requête

Paramètre

Type

Requis

Description

pubId

string

Non

Filtrer par identifiant de publication

start

string

Non

Date de début (ISO 8601)

end

string

Non

Date de fin (ISO 8601)

Exemple de requête

`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" `

Exemple de réponse

`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" } `

La chaîne CSV est renvoyée dans le champ data. Analysez-la côté client ou enregistrez-la directement dans un fichier.

Référence des types d'événements

Type d'événement

Description

session_start

Le lecteur a ouvert la publication

page_view

Le lecteur a navigué vers une page spécifique

session_end

Le lecteur a fermé la publication ou quitté la page

download

Le lecteur a téléchargé le PDF (si activé)

share

Le lecteur a utilisé la fonctionnalité de partage

Next →
API de capture de prospects