Developer Zone

Custom Event Tracking

Custom Event Tracking works in a similar way to Exception Tracking. In both cases, data can either be previewed by retrieving the latest data in JSON format or else, zipped CSV files can be downloaded for offline processing.

Latest Data Preview

This request returns the last few custom events that have been collected including the product and system metadata of the client on which each event was collected in JSON format.

Request/response parameters summary

POST /customEventTracking/getLastLines

The request and reponse are both JSON objects. The following is a summary of the properties inside the request and response objects.

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account. Required only for non-cookie authentication.
  • sessionId (string) – The sessionId obtained via POST /auth/login. Required only for non-cookie authentication.
  • productId (integer) – The product ID on which this request is being done.
  • lineCount (string) – The number of lines/events to retrieve.
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR
  • reason (string) – Present only if status is not OK. Contains error message (reason)
  • fieldNames (object) – Maps the key names in the result object with a user friendly name
  • results (array) – Contains the results as requested represented as a JSON array. The result format is described below.

Results format

The results element is an array containing the actual results. Each event is presented as a JSON object inside the results array. This is the same data contained in the downloadable zipped CSV files.

In the following example, the last 2 lines in the CSV are being requested (the lineCount property is set to 2)

Example request:

POST /customEventTracking/getLastLines  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 2376158762,
    "lineCount": 2
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status":"OK",
   "fieldNames":{
      "timestamp":"Timestamp",
      "clientId":"Client ID",
      "prodEdition":"Edition",
      "prodVersion":"Version",
      "prodBuild":"Build",
      "prodLanguage":"Language",
      "licenseType":"License Type",
      "licenseStatus.whitelisted":"Key Whitelisted",
      "licenseStatus.blacklisted":"Key Blacklisted",
      "licenseStatus.activated":"Key Activated",
      "licenseStatus.expired":"Key Expired",
      "os.version":"OS Type",
      "osWordLength":"OS Architecture",
      "osLanguage":"OS Language",
      "cpuType":"CPU Type",
      "cpuCores":"CPU Cores",
      "ram":"RAM",
      "displayCount":"Number of Monitors",
      "resolution":"Screen Resolution",
      "dotNetVersion": ".NET Versions",
      "gpu.model": "GPU",
      "formFactor":"Computer Type",
      "geography.country":"Country",
      "geography.usState":"US State",
      "event.category":"Event Category",
      "event.name":"Event Type",
      "event.data":"Event Data"
   },
   "results":[
      {
         "timestamp":"2017-11-22T12:41:19",
         "clientId":"AE99797E4B480921",
         "prodEdition":"Standard",
         "prodVersion":"3.1",
         "prodBuild":"951",
         "prodLanguage":"German",
         "licenseType":"purchased",
         "licenseStatus.whitelisted":"N",
         "licenseStatus.blacklisted":"N",
         "licenseStatus.activated":"N",
         "licenseStatus.expired":"N",
         "os.version":"MS Win XP",
         "osWordLength":"64-bit",
         "osLanguage":"German",
         "cpuType":"Intel Core i7",
         "cpuCores":"4",
         "ram":"8192",
         "displayCount":"1",
         "resolution":"1920x1080",
         "dotNetVersion": "2.0;3.5 SP1;3.0 SP2",
         "gpu.model": "Intel HD Graphics 620",
         "formFactor":"Desktop",
         "geography.country":"DE",
         "geography.usState":"",
         "event.category":"File Operations",
         "event.name":"Save",
         "event.data":"final21.doc"
      },
      {
         "timestamp":"2017-11-22T14:51:54",
         "clientId":"2958A7C5911ABF77",
         "prodEdition":"Premium",
         "prodVersion":"2",
         "prodBuild":"719",
         "prodLanguage":"English",
         "licenseType":"purchased",
         "licenseStatus.whitelisted":"N",
         "licenseStatus.blacklisted":"N",
         "licenseStatus.activated":"N",
         "licenseStatus.expired":"N",
         "os.version":"MS Win Vista",
         "osWordLength":"64-bit",
         "osLanguage":"English",
         "cpuType":"Intel Pentium",
         "cpuCores":"2",
         "ram":"1024",
         "displayCount":"1",
         "resolution":"1920x1080",
         "dotNetVersion": "2.0;3.5 SP1;3.0 SP2",
         "gpu.model": "Intel HD Graphics 620",
         "formFactor":"Desktop",
         "geography.country":"US",
         "geography.usState":"IL",
         "event.category":"File Operations",
         "event.name":"Open",
         "event.data":"testfl.doc"
      }
   ]
}

Downloadable File Listing

This request returns the list of zipped CSV files that are on the server. This list is to be used to see what files are available for download and then be able to request files for downloading.

Request/response parameters summary

POST /customEventTracking/listFiles

The request and reponse are both JSON objects. The following is a summary of the properties inside the request and response objects.

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account
  • sessionId (string) – The sessionId obtained via POST /auth/login
  • productId (integer) – The product ID on which this request is being done
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR
  • reason (string) – Present only if status is not OK. Contains error message (reason)
  • openDailyFiles (array) – Array of JSON objects containing information about daily files that are not finalized yet. This normally contains only 1 element which refers to today’s file. This file is still being used to collect data, and therefore, if it is downloaded now, the contents would be different than if it is downloaded later, even though the file name is the same. The objects in this array do not contain a compressedSizeKB element since this is constantly changing. Also, the objects contain a boolean property named isAvailable. If this file is currently being processed by the system, it may be unavailable for download, and therefore this value would be false.
  • dailyFiles (array) – Array of JSON objects containing information about daily files that are finalized. These files can be requested for download.
  • monthlyFiles (array) – Array of JSON objects containing information about monthly files. These files can be requested for download.

Example request/response

Example request:

POST /customEventTracking/listFiles  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 2376158762
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status":"OK",
   "openDailyFiles":[
      {
         "fileName":"2376158762_cust_2017-11-24.zip",
         "uncompressedSizeKB":1.317,
         "fileDate":"2017-11-24",
         "isAvailable":true
      }
   ],
   "dailyFiles":[
      {
         "fileName":"2376158762_cust_2017-11-22.zip",
         "uncompressedSizeKB":3.055,
         "compressedSizeKB":1.018,
         "fileDate":"2017-11-22"
      },
      {
         "fileName":"2376158762_cust_2017-11-23.zip",
         "uncompressedSizeKB":2.129,
         "compressedSizeKB":0.881,
         "fileDate":"2017-11-23"
      }
   ],
   "monthlyFiles":[
      {
         "fileName":"2376158762_cust_2017-11-01_to_2017-11-23.zip",
         "uncompressedSizeKB":4.897,
         "compressedSizeKB":1.273,
         "fileStartDate":"2017-11-01",
         "fileStopDate":"2017-11-23"
      }
   ]
}

Download Zipped CSV File

In order to download the data files, the file needs to be requested to the API which returns a secure URL from which the file can be downloaded.

POST /customEventTracking/getDownloadUrl

The request and reponse are both JSON objects. The following is a summary of the properties inside the request and response objects.

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account
  • sessionId (string) – The sessionId obtained via POST /auth/login
  • productId (integer) – The product ID on which this request is being done
  • fileName (string) – The filename of the file being requested to download
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR
  • reason (string) – Present only if status is not OK. Contains error message (reason)
  • downloadUrl (string) – The one-time URL used to download the zip file

Example request/response

Example request:

POST /customEventTracking/getDownloadUrl  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 2376158762,
    "fileName": "2376158762_cust_2017-11-23.zip"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status":"OK",
   "downloadUrl":"https://sh1.revulytics.com/downloadExc/1ij4buyJtsTrx"
}