API de Analiticas
Rastrea la interaccion de los lectores y obtiene datos analiticos que incluyen vistas de pagina, lectores unicos, tiempo de lectura, distribucion geografica y estadisticas de dispositivos.
- Registrar un Evento
- Cuerpo de la Solicitud
- Ejemplo de Solicitud
- Ejemplo de Respuesta
- Resumen de la Organizacion
- Parametros de Consulta
- Ejemplo de Solicitud
- Ejemplo de Respuesta
- Analiticas de Publicacion
- Parametros de Consulta
- Ejemplo de Solicitud
- Ejemplo de Respuesta
- Campos de Respuesta
- Exportar Analiticas como CSV
- Parametros de Consulta
- Ejemplo de Solicitud
- Ejemplo de Respuesta
- Referencia de Tipos de Evento
API de Analiticas
La API de Analiticas te permite rastrear las interacciones de los lectores con tus publicaciones y obtener metricas de interaccion. Los datos analiticos incluyen vistas de pagina, lectores unicos, tiempo de lectura, mapas de calor a nivel de pagina, distribucion geografica y desgloses por dispositivo.
URL base: https://api.zenflip.io/v1/analytics
Registrar un Evento
Registra un evento de interaccion del lector. Este es un endpoint publico utilizado por el visor de flipbook integrado --- no se requiere autenticacion.
` POST /analytics/track `
Limite de tasa: 30 eventos por segundo por direccion IP (para acomodar cambios de pagina rapidos).
Cuerpo de la Solicitud
Campo | Tipo | Requerido | Descripcion |
|---|---|---|---|
| string | Si | UUID de la publicacion visualizada |
| string | Si | Tipo de evento (max 30 caracteres): |
| string | No | Identificador de sesion del lector (max 100 caracteres) |
| string | No | Identificador anonimo del lector (max 100 caracteres) |
| integer | No | Numero de pagina visualizada |
| integer | No | Tiempo en la pagina en segundos |
| string | No | Categoria de dispositivo: |
| string | No | Nombre del navegador (ej., |
| string | No | Sistema operativo (ej., |
| string | No | Codigo de pais ISO 3166-1 alpha-2 (ej., |
| string | No | Nombre de la ciudad (max 100 caracteres) |
| string | No | URL de referencia (max 500 caracteres) |
| object | No | Metadatos arbitrarios de clave-valor |
Ejemplo de Solicitud
`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" }' `
Ejemplo de Respuesta
`json { "message": "Event tracked" } `
Resumen de la Organizacion
Obtiene un resumen analitico de alto nivel de todas las publicaciones de tu organizacion.
` GET /analytics/overview `
Parametros de Consulta
Parametro | Tipo | Requerido | Descripcion |
|---|---|---|---|
| string | No | Fecha de inicio en formato ISO 8601 (ej., |
| string | No | Fecha de fin en formato ISO 8601 |
| string | No | Rango abreviado: |
Ejemplo de Solicitud
`bash curl "https://api.zenflip.io/v1/analytics/overview?range=30d" \ -H "Authorization: Bearer YOUR_TOKEN" `
Ejemplo de Respuesta
`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 } ] } } `
Analiticas de Publicacion
Obtiene analiticas detalladas para una publicacion especifica, incluyendo datos de mapa de calor a nivel de pagina, distribucion geografica y desglose por dispositivo.
` GET /analytics/publications/:pubId `
Parametros de Consulta
Parametro | Tipo | Requerido | Descripcion |
|---|---|---|---|
| string | No | Fecha de inicio (ISO 8601) |
| string | No | Fecha de fin (ISO 8601) |
Ejemplo de Solicitud
`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" `
Ejemplo de Respuesta
`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 } ] } } `
Campos de Respuesta
Campo | Descripcion |
|---|---|
| Metricas agregadas para el rango de fechas |
| Conteos de vistas por pagina y tiempo promedio de permanencia |
| Distribucion de lectores por pais (codigos ISO alpha-2) |
| Desglose por tipo de dispositivo (desktop, mobile, tablet) |
| Desglose por nombre de navegador |
| Serie temporal diaria de vistas y lectores unicos |
Exportar Analiticas como CSV
Exporta datos analiticos sin procesar como un archivo CSV para usar en hojas de calculo o herramientas de inteligencia empresarial.
` GET /analytics/export `
Plan requerido: Creator o superior.
Parametros de Consulta
Parametro | Tipo | Requerido | Descripcion |
|---|---|---|---|
| string | No | Filtrar por ID de publicacion |
| string | No | Fecha de inicio (ISO 8601) |
| string | No | Fecha de fin (ISO 8601) |
Ejemplo de Solicitud
`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" `
Ejemplo de Respuesta
`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 cadena CSV se devuelve en el campo data. Analízala en el lado del cliente o guardala directamente en un archivo.
Referencia de Tipos de Evento
Tipo de Evento | Descripcion |
|---|---|
| El lector abrio la publicacion |
| El lector navego a una pagina especifica |
| El lector cerro la publicacion o navego fuera |
| El lector descargo el PDF (si esta habilitado) |
| El lector uso la funcionalidad de compartir |