Insights API
The Kaon Insights Portal (contact your Kaon PM for access) provides an easy-to-use interface to access information about how your applications on the Kaon SaaS Platform are being used. In addition to this web interface, there is API access to analytics data. This document details that REST API.
To use analytics, you will need an API key. This API key should be kept secret, since anyone holding the key can see all the analytics data for your application. Contact support@kaon.com if you need a key generated for you.
Overview
The general form of the API is a URL like this:
https://insights.v-central.com/api/{api name}?apikey={your api key}&client={ID for your app}&{other parameters}All API calls should use the HTTP GET verb. Kaon will supply you with the api key and client ID for your application.
All successful API calls return a JSON object with a 200 result code. Passing invalid data will result in a 403 (unauthorized) or 404 (not found) error.
Many API calls use "week" numbers. Every week is assigned a number, counting from 1/1/2012 (the date the first app went live on the Kaon SaaS platform). Full insights data is only available starting the week of 12/29/2019 which is week 417. Hit count data is available back to whenever the application first went live.
/api/weeks
Returns the weeks for which full data is available for this application.
Parameters:
Returns:
/api/engagement
Returns engagement information for one week.
Parameters:
Returns:
Engagement data is a histogram of durations. Idle time is not included, and if the user accesses the application multiple times with less than a 30 minute gap, those are considered a single engagement.
Bucket values:
/api/uid
Returns unique device information for one week. Every device is assigned a completely random identifier (uid) on its first run, which allows analysis of frequency of use by that device. Note that browsers tend to discard this information, so only non-web device uids are reliable over the long term.
Parameters:
Returns:
The uids string is a concatenation of uid values in the format: 0x[16 hex digits]0x[16 hex digits]...
The number of devices is therefore the length of the uids string divided by 18.
To determine the number of unique devices across time spans longer than a week, the caller will need to split the IDs and manage their own sets.
/api/countries
Returns a count of the number of unique engagements in each country.
Parameters:
Returns:
/api/lang
Returns a count of the number of unique engagements in each language.
Parameters:
Returns:
Note that language strings in Kaon apps are not precisely the same as the ISO standards. These are the current set of languages:
en Englishgb English (UK)ar عربى (Arabic)cs Česky (Czech)da Dansk (Danish)de Deutsch (German)el Ελληνικά (Greek)es Español (Spanish)fi Suomi (Finnish)fr Français (French)ca Français (Canadian French)it Italiano (Italian)ja 日本語 (Japanese)ko 한국어 (Korean)nl Nederlands (Dutch)no Norsk (Norweigan)pl Polski (Polish)pt Português (Portuguese)bz Português (Brasilian Portuguese)ru Русский (Russian)sv Svenska (Swedish)th ไทย (Thai)tr Türkçe (Turkish)vi Tiếng Việt (Vietnamese)zh 中文 (Chinese)zt 繁體中文 (Traditional Chinese)/api/hits
Returns hit count information for a particular item in the app.
Parameters:
If a path is provided, and no week is provided, all hits for that path in all time will be returned (this may go back several years)
If no path is provided, all hits for that week (defaulting to the current week if no week is present) will be returned
The detail parameter is supported only if a path is provided, and requests more detail about the hits. The only supported value is "country"
Returns:
Paths can be analyzed to understand what kind of a hit they represent. paths are URL-encoded (so, for example, spaces appear as %20). After decoding the following conventions are used:
If the optional parameter detail=country is included in the request, each hit will include an object mapping two-letter country codes to the number of hits attributable to that country. Note that the total country-based hits will not necessarily match the count value exactly, as the per-country data is only an approximation.
/api/external
Returns hit information associated with an external ID.
Parameters:
The optional parameter start is the timestamp below which data is not requested. The first call should omit this, then subsequent calls should pass the timestamp of the last record returned.
If specified, the limit will control how many records are returned. Setting this to too-high a value could result in database timeouts, so it's recommended to just use the default. However, during testing, you may want to set it to a low number (like 10) in order to test that you are paging through data correctly.
Returns:
In some cases, a Kaon app will be provided with an external ID to use for individual behavior tracking. (Kaon does not know who these IDs correspond to, and it is the responsibility of the company providing these IDs to get proper consent from the users. See our app privacy policy.) In these cases a click-stream of activity from that user is recorded, and can be accessed using this API.
Since there could be a lot of data, the caller should expect to make multiple requests. The first request should omit the "start" attribute. Subsequent calls should pass the timestamp of the last returned record. The caller can then append all the returned records together for analysis.
The timestamp is a standard unix timestamp (integer seconds).