For the complete documentation index, see llms.txt. This page is also available as Markdown.

collection.getReaderStats

Returns statistics for one reader of a specified flipbook.

Note:

  • Requests must be made to https://api.flipsnack.com/v1.

  • Only GET requests are accepted.

Use this method to retrieve statistics for one reader of a flipbook.

Request parameters

Name
Type
Description

apiKey (required)

string

The API key provided for your user. A missing key returns code 30. An invalid key returns code 41.

signature (required)

string

The request signature. See How to sign a request. A missing signature returns code 30. An invalid signature returns code 44.

action (required)

string

The API method. Set this to collection.getReaderStats.

collectionHash (required)

string

The hash of the flipbook.

readerEmail

string

Email address of a tracked reader.

otpEmail

string

Email address of a reader authenticated through one-time password access.

ssoViewerId

string

Viewer ID for a reader authenticated through SSO.

trackableLinkHash

string

Hash of the trackable link used by the reader.

linkId

string

ID of the trackable link used by the reader.

startDate

string

First date in the reporting interval, formatted as YYYY-MM-DD.

endDate

string

Last date in the reporting interval, formatted as YYYY-MM-DD.

includePageBreakdown

boolean

When true, includes activity for each page. Default: false.

includeLinkClicks

boolean

When true, includes link-click activity. Default: false.

includeSessionDetails

boolean

When true, includes session details. Default: false.

Provide exactly one reader identifier: readerEmail, otpEmail, ssoViewerId, trackableLinkHash, or linkId.

When both dates are omitted, the report covers 30 days inclusive: today in UTC and the preceding 29 days. When one date is omitted, the API sets the other date 29 days away. For spans longer than 1,825 days, the API keeps endDate and moves startDate forward. The response contains the effective date range.

Response parameters

Name
Type
Description

collectionHash

string

Hash of the requested flipbook.

reader.identifierType

string

Identifier type: reader, otp, sso, or link.

reader.identifierValue

string

Value of the reader identifier.

summary.impressions

number

Times the reader loaded the flipbook player.

summary.views

number

Times the reader interacted with the player.

summary.time_spent

number

Total viewing time in seconds.

summary.pages_read

number

Number of pages read by the reader.

summary.downloads

number

Times the reader downloaded the flipbook content.

summary.clicks

number

Number of clicks made by the reader.

startDate

string

Effective start date, formatted as YYYY-MM-DD.

endDate

string

Effective end date, formatted as YYYY-MM-DD.

pageBreakdown

array

Returned when includePageBreakdown is true. Includes every flipbook page, including pages with zero activity. Each item includes page, average time_spent in seconds per view, clicks, and views.

linkClicks

array

Returned when includeLinkClicks is true. Each item includes page, targetUrl, and clicks.

sessionDetails

array

Returned when includeSessionDetails is true. Each item includes firstViewedAt, lastActiveAt, and devices.

Error codes

For complete list of error codes and messages go to API status codes section.

Example

Request

Response

Last updated