アナリティクスAPI

アナリティクスAPI

アナリティクスAPIを使用すると、パブリケーションに対する閲覧者のインタラクションを追跡し、エンゲージメント指標を取得できます。アナリティクスデータには、ページビュー、ユニーク閲覧者数、閲覧時間、ページレベルのヒートマップ、地域分布、デバイス別内訳が含まれます。

ベースURL: https://api.zenflip.io/v1/analytics

イベントの追跡

閲覧者のインタラクションイベントを記録します。これは埋め込みフリップブックビューアーが使用するパブリックエンドポイントであり、認証は不要です。

` POST /analytics/track `

レート制限：IPアドレスあたり毎秒30イベント（素早いページめくりに対応するため）。

リクエストボディ

リクエスト例

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

レスポンス例

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

組織全体の概要

組織内のすべてのパブリケーションにわたるアナリティクスの概要サマリーを取得します。

` GET /analytics/overview `

クエリパラメータ

リクエスト例

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

レスポンス例

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

パブリケーションアナリティクス

特定のパブリケーションの詳細なアナリティクスを取得します。ページレベルのヒートマップデータ、地域分布、デバイス別内訳が含まれます。

` GET /analytics/publications/:pubId `

クエリパラメータ

リクエスト例

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

レスポンス例

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

レスポンスフィールド

アナリティクスのCSVエクスポート

スプレッドシートやビジネスインテリジェンスツールで使用するために、生のアナリティクスデータをCSVファイルとしてエクスポートします。

` GET /analytics/export `

必要なプラン: Creator以上。

クエリパラメータ

リクエスト例

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

レスポンス例

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

CSV文字列はdataフィールドに返されます。クライアント側でパースするか、ファイルに直接保存してください。

イベントタイプリファレンス