Analytics

Overview

The analytics endpoint tracks page views and engagement time for shared folios. It is designed as a lightweight beacon — no authentication is required, and the endpoint is resilient to empty or malformed bodies.

Analytics data includes:

• Views — total unique page loads
• Total time — cumulative seconds viewers have spent on the folio
• Average time — average seconds per view
• Device breakdown — mobile vs desktop view counts

Track Analytics

POST /api/files/{id}/analytics
Content-Type: application/json

Sends an analytics beacon for a folio view. The client should call this endpoint:

1. On initial page load — with isInitial: true to increment the view counter
2. Periodically during the session — to accumulate session time (e.g., every 30 seconds)

Request Body:

Field	Type	Required	Description
sessionSeconds	number	No	Seconds to add to total time (default: 0)
isInitial	boolean	No	Whether this is the first beacon for this view (increments view count)
device	string	No	"mobile" or other (defaults to desktop)

Example — Initial page load beacon:

curl -X POST https://livefolio.cloud/api/files/a1b2c3d/analytics \
  -H "Content-Type: application/json" \
  -d '{
    "sessionSeconds": 0,
    "isInitial": true,
    "device": "desktop"
  }'

Example — Periodic time tracking beacon:

curl -X POST https://livefolio.cloud/api/files/a1b2c3d/analytics \
  -H "Content-Type: application/json" \
  -d '{
    "sessionSeconds": 30
  }'

Response:

{
  "success": true
}

Note: An empty body is handled gracefully and returns success without error.

Analytics Data Model

Analytics are stored per folio as:

{
  "views": 245,
  "totalTimeSeconds": 18450,
  "avgTimeSeconds": 75,
  "mobileViews": 89,
  "desktopViews": 156
}

Field	Description
views	Total unique page loads
totalTimeSeconds	Cumulative seconds across all sessions
avgTimeSeconds	Average seconds per view (recalculated on each beacon)
mobileViews	Views from mobile devices
desktopViews	Views from desktop devices

Client-Side Implementation

Here is a minimal JavaScript snippet for embedding analytics in a shared folio:

<script>
(function() {
  var folioId = 'a1b2c3d';
  var baseUrl = 'https://livefolio.cloud';
  var isMobile = /Mobi|Android/i.test(navigator.userAgent);

  // Initial beacon
  fetch(baseUrl + '/api/files/' + folioId + '/analytics', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      sessionSeconds: 0,
      isInitial: true,
      device: isMobile ? 'mobile' : 'desktop'
    })
  });

  // Periodic time tracking (every 30 seconds)
  setInterval(function() {
    fetch(baseUrl + '/api/files/' + folioId + '/analytics', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sessionSeconds: 30 })
    });
  }, 30000);
})();
</script>

Retrieving Analytics

Analytics data is included in the full folio object returned by GET /api/files/{id} (requires authentication). There is no dedicated analytics retrieval endpoint. The data is in the analytics field of the folio object.