Share:
ClickHelp Documentation

API: Reporting and Analytics

 

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. For example, reporting functions allow you to retrieve information on what Power Readers are doing when working with the portal. Various third-party systems can use this information to get insight into your end users' behavior.

Reporting functions list:


Get Topic Views

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

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.

Authorization

This request is using basic authentication.

Request parameters

Path parameters

userName

required

string The login of the user whose topic views will be retrieved. 

Query string parameters

Field Type Description
startDate DateTime Report start date timestamp string in the ISO 8601 format, in the GMT timezone.
endDate DateTime Report end date timestamp string in the ISO 8601 format, in the GMT timezone.

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 a specific time on December 31 of 2017 (in GMT).

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

Response example

Copy Code
JSON
{[  
  {  
    "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 fields

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. It 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.

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: Forbidden

The user does not have the permission to view Power Reader profiles.

Get Full-Text Search Queries

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

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.

Authorization

This request is using basic authentication.




  Request parameters



Path parameters
userName
REQUIRED
stringThe login of the user whose search queries will be retrieved. 
Query string parameters

  
    
FieldTypeDescription

  
  
startDatedatetimeReport start date timestamp string in the ISO 8601 format, in the GMT timezone.

    
endDatedatetimeReport end date timestamp string in the ISO 8601 format, in the GMT timezone.

    
  




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).
Copy Code
Code
curl -X GET ^
  --basic ^
  --user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
  --cacert comodo.ca-bundle ^
  https://mycompany.clickhelp.co/api/v1/reports/user-events/reader/search-queries?startDate=2017-12-01&endDate=2017-12-31T17:55:13%2B03:00


  
  
  
Response example
Copy Code
JSON
{[  
  {  
    "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 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.
      

    
  





  
  
  


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: Forbidden




  The user does not have permission to view Power Reader profiles.

    


    
ClickHelp - Online Documentation and Help Authoring Tool

    
    
©
        ClickHelp Team. All rights reserved.