Share:
ClickHelp Documentation

Reporting

In addition to the visual reports available in Report Center, ClickHelp also allows you to retrieve data measured by your portal via the REST API. Reporting functions allow you to retrieve information on what Power Readers are doing when working with the portal. This information can be used by various third-party systems to get insight on your end users behavior.

Reporting Functions List

Get Topic Views

Returns information on topics viewed by the given Power Reader user during the given period, ordered by dates (latest go first). The userName parameter refers to the login name of the Power Reader user. The startDate and endDate parameters are date and time string values in the ISO 8601 format (a date can be in any time zone). For example, such strings can be generated by the JavaScript toISOString method.

GET /api/v1/reports/user-events/{userName}/articles?startDate={startDate}&endDate={endDate} HTTP/1.1 

Response Fields

Field Type Description
href String

The URL which can be used to retrieve detailed information on the topic viewed by the user.

dateTime String

Event timestamp string in the ISO 8601 format, in the GMT timezone.

referrerUrl String The URL of the referrer page from which the user navigated to the topic.
actionType String

The type of the topic view action. Can be one of the following:

  • DirectNavigation - navigation via link clicks.
  • FromToc - the topic was opened as a result of a TOC node click.
  • FromIndex - the topic was opened by index keyword click.
  • FromSearch - the topic was opened from full-text search results.
  • FromContextHelp - the topic was loaded as a Context Help snippet.

Request Example

Below, is an example of a CURL command line you can use in a batch file to get topic views of the "reader" user from December 1 (in GMT) till specific time on December 31 of 2017 (in GMT).

curl -X GET ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --cacert comodo.ca-bundle ^
  https://doc.clickhelp.co/api/v1/reports/user-events/reader/articles?startDate=2017-12-01&endDate=2017-12-31T17:55:13%2B03:00

Response Example

{[  
  {  
    "href":"/api/v1/projects/my-manual-publication/articles/introduction",
    "dateTime":"2017-12-23T13:23:45",
    "referrerUrl":null,
    "actionType":"FromToc"
  },
  {  
    "href":"/api/v1/projects/my-manual-publication/articles/my-topic",
    "dateTime":"2017-12-07T12:11:47",
    "referrerUrl":"http://test.com/best-help-topics-ever/",
    "actionType":"DirectNavigation"
  }
]}

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    The request has succeeded, the response body contains the requested information.
  • 403
    The user does not have the permission to view Power Reader profiles.

Get Full-Text Search Queries

Returns information on full-text search queries performed by the given Power Reader user during the given period, ordered by dates (latest go first). The userName parameter refers to the login name of the Power Reader user. The startDate and endDate parameters are date and time string values in the ISO 8601 format (a date can be in any time zone). For example, such strings can be generated by the JavaScript toISOString method.

GET /api/v1/reports/user-events/{userName}/search-queries?startDate={startDate}&endDate={endDate} HTTP/1.1 

Response Fields

Field Type Description
queryText String

The full-text search query.

dateTime String

Event timestamp string in the ISO 8601 format, in the GMT timezone.

resultsTotal Integer The total number of search results returned.

Request Example

Below, is an example of a CURL command line you can use in a batch file to get full-text search queries of the "reader" user from December 1 (in GMT) till specific time on December 31 of 2017 (in GMT+3).

curl -X GET ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --cacert comodo.ca-bundle ^
  https://doc.clickhelp.co/api/v1/reports/user-events/reader/search-queries?startDate=2017-12-01&endDate=2017-12-31T17:55:13%2B03:00

Response Example

{[  
  {  
    "queryText":"getting data",
    "dateTime":"2017-12-23T13:23:45",
    "resultsTotal":456,
  },
  {  
    "queryText":"how to write to files",
    "dateTime":"2017-12-07T12:11:47",
    "resultsTotal":0
  }
]}

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    The request has succeeded, the response body contains the requested information.
  • 403
    The user does not have the permission to view Power Reader profiles.