Developer Zone

Basic Event Tracking Reports

Basic event tracking reports are presented in either a data table format which is meant to show a list of all known events within a date range and how they occurred, and also in a timeline format which is meant to show the daily usage of a smaller subset. Normally, the timeline chart is used to drill-down on a selection of events that can be seen on the data table.

Data Table Report

This report returns data that is to be represented in tabular format. It contains data about each tracked event, how many times it occurred, how many times each user performed each event on average, etc.

Request/response parameters summary

POST /reporting/eventTracking/basic/dataTable

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
  • startDate (string) – The first date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
  • stopDate (string) – The last date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
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)
  • results (object) – Contains the results as requested represented as a JSON object. The result format is described below.

Results format

The results are formatted as an array which contains a JSON object for each category. Each of these objects has a property named “category” which refers to the category names of the events. If there are events that were not assigned a category, they can be found under a category named null. Each of these objects contains 3 other keys - categoryUsageSummary, categoryCustomValuesSummary, and categoryEventsData. The first two contain objects that contain values regarding the totals for each category. In the below example, the events in the File Operations category occurred for a total of 554 times. This is displayed in the cumulativeUsageCount property inside categoryUsageSummary.

The categoryEventsData object, contains data about each individual event type in that particular category. This object contains a number of sub-objects, each referring to a particular event name. The keys refer to the event names. Each of these sub-objects contain 2 keys - eventUsage and eventCustomValues. These contain the data values for individual events. For example, the event Menu Launched inside the Print Operations category occurred only 1 time, and the total numeric custom value collected by this event was 1.29.

Example request:

POST reporting/eventTracking/basic/dataTable  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "startDate": "2014-08-01",
    "stopDate": "2014-08-03"
}

Example response:

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

{
    "status": "OK",
    "results": [
        {
            "category": "File Operations",
            "categoryUsageSummary": {
                "cumulativeUsageCount": 554,
                "averageCountPerUser": 1.01,
                "averageCountPerSession": 0.21,
                "averageCountPerRuntimeHour": 0.01
            },
            "categoryCustomValuesSummary": {
                "cumulativeCustomValueCount": 2495.03,
                "averageCustomValuePerEvent": 4.66,
                "averageCustomValuePerUser": 4.71,
                "averageCustomValuePerSession": 0.99,
                "averageCustomValuePerRuntimeHour": 0.03
            },
            "categoryEventsData": {
                "Open": {
                    "eventUsage": {
                        "cumulativeUsageCount": 455,
                        "averageCountPerUser": 0.71,
                        "averageCountPerSession": 0.15,
                        "averageCountPerRuntimeHour": 0.24
                    },
                    "eventCustomValues": {
                        "cumulativeCustomValueCount": 2118.31,
                        "averageCustomValuePerEvent": 4.66,
                        "averageCustomValuePerUser": 3.3,
                        "averageCustomValuePerSession": 0.69,
                        "averageCustomValuePerRuntimeHour": 1.11
                    }
                },
                "Save": {
                    "eventUsage": {
                        "cumulativeUsageCount": 99,
                        "averageCountPerUser": 0.15,
                        "averageCountPerSession": 0.03,
                        "averageCountPerRuntimeHour": 0.05
                    },
                    "eventCustomValues": {
                        "cumulativeCustomValueCount": 376.72,
                        "averageCustomValuePerEvent": 3.81,
                        "averageCustomValuePerUser": 0.59,
                        "averageCustomValuePerSession": 0.12,
                        "averageCustomValuePerRuntimeHour": 0.2
                    }
                }
            }
        },
        {
            "category": "Print Operations",
            "categoryUsageSummary": {
                "cumulativeUsageCount": 418,
                "averageCountPerUser": 0.65,
                "averageCountPerSession": 0.14,
                "averageCountPerRuntimeHour": 0
            },
            "categoryCustomValuesSummary": {
                "cumulativeCustomValueCount": 563.37,
                "averageCustomValuePerEvent": 1.35,
                "averageCustomValuePerUser": 0.88,
                "averageCustomValuePerSession": 0.18,
                "averageCustomValuePerRuntimeHour": 0
            },
            "categoryEventsData": {
                "Edit Mode": {
                    "eventUsage": {
                        "cumulativeUsageCount": 224,
                        "averageCountPerUser": 0.35,
                        "averageCountPerSession": 0.07,
                        "averageCountPerRuntimeHour": 0.12
                    },
                    "eventCustomValues": {
                        "cumulativeCustomValueCount": 149,
                        "averageCustomValuePerEvent": 0.67,
                        "averageCustomValuePerUser": 0.23,
                        "averageCustomValuePerSession": 0.05,
                        "averageCustomValuePerRuntimeHour": 0.08
                    }
                },
                "Preview Mode": {
                    "eventUsage": {
                        "cumulativeUsageCount": 141,
                        "averageCountPerUser": 0.22,
                        "averageCountPerSession": 0.05,
                        "averageCountPerRuntimeHour": 0.07
                    },
                    "eventCustomValues": {
                        "cumulativeCustomValueCount": 274,
                        "averageCustomValuePerEvent": 1.94,
                        "averageCustomValuePerUser": 0.43,
                        "averageCustomValuePerSession": 0.09,
                        "averageCustomValuePerRuntimeHour": 0.14
                    }
                },
                "Button Clicked": {
                     "eventUsage": {
                        "cumulativeUsageCount": 52,
                        "averageCountPerUser": 0.08,
                        "averageCountPerSession": 0.02,
                        "averageCountPerRuntimeHour": 0.03
                    },
                    "eventCustomValues": {
                        "cumulativeCustomValueCount": 139.08,
                        "averageCustomValuePerEvent": 2.67,
                        "averageCustomValuePerUser": 0.22,
                        "averageCustomValuePerSession": 0.05,
                        "averageCustomValuePerRuntimeHour": 0.07
                    }
                },
                "Menu Launched": {
                    "eventUsage": {
                        "cumulativeUsageCount": 1,
                        "averageCountPerUser": 0,
                        "averageCountPerSession": 0,
                        "averageCountPerRuntimeHour": 0
                    },
                    "eventCustomValues": {
                        "cumulativeCustomValueCount": 1.29,
                        "averageCustomValuePerEvent": 1.29,
                        "averageCustomValuePerUser": 0,
                        "averageCustomValuePerSession": 0,
                        "averageCustomValuePerRuntimeHour": 0
                    }
                 }
            }
        }
    ]
}

Timeline Report

This report returns a daily/weekly/monthly timeline of how many times each of the requested events occurred. The event occurrence counts can optionally be divided by the number of users on each day/week/month, the number of user sessions, runtime hours, etc.

Request/response parameters summary

POST /reporting/eventTracking/basic/timeline

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
  • startDate (string) – The first date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
  • stopDate (string) – The last date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
  • dateSplit (string) – Whether to present results by day, week, or month.
  • dataView (string) – Whether to show the counts of the number of times each event occurred (usageCount) or the total of the numeric custom values passed with each event (customValues).
  • divisor (string) – Optional parameter to divide the data by a related value. The possible values are users, sessions”, *runtime, usageCounts. Note that usageCounts cannot be selected if dataView is set to usageCount. To get the raw values with no divisors, you may leave the divisor property out or set its value to null.
  • events (array) – An array contining JSON objects, each containing a 2 string values - category and name.
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)
  • results (object) – Contains the results as requested represented as a JSON object. The result format is described below.

Results format

The results object contains a number of members having a date as the key and an object as the value. The date is formatted as YYYY-MM-DD regardless of whether the report is being split by day, week, or month. If the report is being split by week or by month, the first date of the week or month is used.

Each sub-object contains a sub-object for each event. These contain the event category and name, and the number of times it occurred, or the custom numeric value that was sent with it, deending on whether the dataView value is set as usageCount or customValues.

Example request:

POST reporting/eventTracking/basic/timeline  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "startDate": "2014-08-01",
    "stopDate": "2014-08-03",
    "dateSplit": "day",
    "dataView": "usageCounts",
    "divisor": null,
    "events": [
                  {
                      "category": "File Operations",
                      "name": "Open"
                  },
                  {
                      "category": "File Operations",
                      "name": "Save"
                  }

              ]
}

Example response:

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

{
    "status": "OK",
    "results": {
        "2014-08-01": [
            {
                "category": "File Operations",
                "name": "Open",
                "value": 295
            },
            {
                "category": "File Operations",
                "name": "Save",
                "value": 59
            }
        ],
        "2014-08-02": [
            {
                "category": "File Operations",
                "name": "Open",
                "value": 132
            },
            {
                "category": "File Operations",
                "name": "Save",
                "value": 24
            }
        ],
        "2014-08-03": [
            {
                "category": "File Operations",
                "name": "Open",
                "value": 14
            },
            {
                "category": "File Operations",
                "name": "Save",
                "value": 2
            }
        ]
    }
}