Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Docs analytics and reader feedback

See which pages readers open, what they search for and fail to find, and which pages they find unhelpful, without recording who they are.

What is recorded

Page views
The topic id, the reader's release line and where it was read: site (the docs site), embed (the help panel in a host app) or api (the JSON help API). Pages a reader cannot see are not counted.
Searches
Searches from the docs site's search page (site), the help panel (embed) and the JSON help API (api): the query, in lower case with spaces tidied, and how many results it found. Email addresses and runs of seven or more digits are replaced with [email] and [number] before anything is stored. Empty searches are not counted.
Feedback
Whether a page was helpful, and an optional comment of up to 1000 characters.

Every row also carries the reader's organization slug and the time. No row holds a reader's email, name or id, or an IP address, so the numbers cannot be traced back to a person.

Readers who opt out

When the browser sends DNT: 1 (Do Not Track) or Sec-GPC: 1 (Global Privacy Control), that reader's page views and searches are not recorded. Feedback is still accepted, because the reader sends it on purpose.

To turn everything off, set OPEND_ANALYTICS=0. Nothing is recorded and the feedback form disappears. See Environment variable reference.

The feedback form

Every topic page on the site, and every topic in the help panel, ends with Was this page helpful? Yes / No. No? Tell us what was missing opens a comment box. The form is plain HTML and works without JavaScript; the reader returns to the same page with a thank-you message.

Only signed-in readers see the form. Answers are accepted only from the form on the reader's own page, and only for topics that reader can see; anything else gets the same Page not found answer, so the form cannot be used to find out which hidden topics exist.

Reading the numbers

Use the admin API (see Admin API reference):

  • GET /admin/api/analytics/summary?days=30: top pages, top searches, searches with no results, and the share of helpful answers per page. Searches with no results show what readers expect to find and cannot; the least helpful pages come first.
  • GET /admin/api/analytics/feedback?topic=topics/install&days=90: the answers and comments for one page, newest first. Add comments=1 for comments only.
  • GET /admin/api/analytics/feedback.csv: the same as a spreadsheet.
curl -H "Authorization: Bearer $OPEND_ADMIN_TOKEN" \
  "$PUBLIC_URL/admin/api/analytics/summary?days=30&org=acme"

How long it is kept

Rows older than OPEND_ANALYTICS_RETENTION_DAYS (default 180) are deleted by the worker when it starts and every six hours after. To purge now, or with a shorter period:

opend-server purge-analytics            # uses OPEND_ANALYTICS_RETENTION_DAYS
opend-server purge-analytics --days 30

Analytics rows live in Postgres with everything else, so database backups include them; see Back up and restore.