Analytics
Analytics data can be accessed via our public API.
Accessing the API¶
All analytics endpoints can be found at https://analytics.app.delivery/api/v1
Generating an access token¶
To access the API data you must generate an access token, from within the Analytics service in the Agency Console under the Explore section there is an API tab.
From this section you can manage existing tokens, revoke their access, and create new ones.
Click the add button to create your first access token.
Authentication¶
Any access to the following api endpoints requires authentication via the authorization header, using a valid access token as a bearer.
Authorization: Bearer [access token]
The Accept header should also be set for application/json
.
Required querystring parameters¶
All sample requests in the following examples are assumed to have these parameters included.
From / To
- ISO8601 formatted date filter, for new installs and all installs this relates to the dates they were created between. For active installs the install must have been used at least once to be counted for any given day.
simulatorFilter
- Filter installs running on a simulator can be one of:
1
Return all installs2
Return only installs running on a simulator3
Return only instals running on a real device
targetTypeFilter
- Filter out installs using release and / or debug builds
1
Return all installs2
Return only installs running a debug build3
Return only installs running a release build
Resource Types¶
References to the {resourceType}
within the path refers to the type of installs to be counted, can be one of:
new-installs
Installs created within the periodactive-installs
Installs that have interacted with Kumulos within the periodall-installs
Total installs at the end of the period
Available APIs¶
Install counts by series¶
/api/v1/{resourceType}/{series}
This API returns the count of the type of install grouped by the specified series, ordered by the install count descending.
Series can be one of:
countries
cities
os-versions
app-versions
devices
For example /api/v1/active-installs/os-versions
will return
[
{"name":"iOS","version":"11.3.1","installCount":1771},
{"name":"Android","version":"Android 6.0","installCount":1417},
{"name":"Android","version":"ANDROID 5.1","installCount":447},
{"name":"Android","version":"Android 4.4.2","installCount":311},
{"name":"iOS","version":"10.2.1","installCount":232},
{"name":"iOS","version":"9.3.5","installCount":72}
]
Install counts by series over time¶
/api/v1/{resourceType}/{grouping}/{series}
This API returns the count of the type of install grouped by the grouping type, then the specified series.
Series can be one of:
countries
os-type
Grouping can be one of:
daily
monthly
For example api/v1/active-installs/daily/countries
will return
[
{"date":"2018-06-28T00:00:00+00:00","installCount":22,"name":"Canada"},
{"date":"2018-06-28T00:00:00+00:00","installCount":22,"name":"Germany"},
{"date":"2018-06-28T00:00:00+00:00","installCount":6,"name":"France"},
{"date":"2018-06-28T00:00:00+00:00","installCount":42,"name":"United Kingdom"},
{"date":"2018-06-28T00:00:00+00:00","installCount":109,"name":"United States"},
{"date":"2018-06-29T00:00:00+00:00","installCount":39,"name":"Canada"},
{"date":"2018-06-29T00:00:00+00:00","installCount":23,"name":"Germany"},
{"date":"2018-06-29T00:00:00+00:00","installCount":11,"name":"France"},
{"date":"2018-06-29T00:00:00+00:00","installCount":51,"name":"United Kingdom"},
{"date":"2018-06-29T00:00:00+00:00","installCount":149,"name":"United States"},
{"date":"2018-06-30T00:00:00+00:00","installCount":18,"name":"Canada"},
{"date":"2018-06-30T00:00:00+00:00","installCount":18,"name":"Germany"},
{"date":"2018-06-30T00:00:00+00:00","installCount":4,"name":"France"},
{"date":"2018-06-30T00:00:00+00:00","installCount":57,"name":"United Kingdom"},
{"date":"2018-06-30T00:00:00+00:00","installCount":129,"name":"United States"}
]
Event counts¶
/api/v1/events
This API returns the number of occurrences of analytics events received from devices, with extra querystring parameters you can select what type of counting, grouping of counts, and filter out kumulos generated system events. All the count types return counts per the operating system that triggered the event, in addition to the total.
countBy
can be one of:
events
installs
users
Events will count the number of times the event has occurred, installs will count the number of unique devices which have raised the event and users will count the distinct users who have raised the event within the period.
hideSystemEvents
can be one of:
true
false
groupBy
is an optional parameter, and if supplied allows grouping on a user attribute or event data property:
user.*
would group by a user attribute, for exampleuser.isCustomer
data.*
would group by a event data property, for exampledata.screenName
Groupings can be multi-dimensional and combine with a comma separated list of fields, for example: groupBy=user.isCustomer,data.screenName
.
The example query /api/v1/events?countBy=events&hideSystemEvents=false
will return
{
[
{"name":"App backgrounded (system event)","type":"k.bg","counts":{"Total":50939,"iOS":24825,"Android":26114}},
{"name":"App foregrounded (system event)","type":"k.fg","counts":{"Total":50939,"iOS":24825,"Android":26114}},
{"name":"Push notification opened (system event)","type":"k.push.opened","counts":{"Total":1603,"iOS":773,"Android":830}},
{"name":"Viewed special offers","type":"offers.opened","counts":{"Total":1498,"iOS":721,"Android":777}},
{"name":"Viewed a product","type":"product.viewed","counts":{"Total":1236,"iOS":586,"Android":650}},
{"name":"Added a product to cart","type":"added.to.cart","counts":{"Total":858,"iOS":402,"Android":456}},
{"name":"Entered or selected delivery details","type":"delivery.completed","counts":{"Total":675,"iOS":314,"Android":361}},
{"name":"Entered or selected payment details","type":"payment.completed","counts":{"Total":460,"iOS":206,"Android":254}},
{"name":"Completed order","type":"order.completed","counts":{"Total":267,"iOS":125,"Android":142}}
]
}
Session data¶
/api/v1/sessions/{resourceName}
These resources describe aspects of the active users sessions, for example their distribution over localized time of day or their duration.
Resource Name can be one of:
time-of-day
- For each day of the week show how many sessions for localized hour of daydistribution
- For equally weighted buckets show how users are grouped in terms of number of sessions.daily
- Count of sessions per daysummary
- Average session duration and average sessions per dayduration
- Mean session length grouped by dayduration-filtered
- Mean session length grouped by day, filterable on user attributes
For example /api/v1/sessions/distribution
will return
[
{"from":1,"to":11,"count":2097},
{"from":12,"to":22,"count":1498},
{"from":23,"to":33,"count":472},
{"from":34,"to":44,"count":62},
{"from":45,"to":55,"count":5}
]
When using the filtered resources the following parameters can be provided.
filters
Provided as an array of key value pairs where the key is the attribute and the value is the filter, for example:
filters[user.lifetimeValue]=105&filters[user.isCustomer]=true
Any responses will match the unfiltered resource.
Retention¶
/api/v1/{resourceType}/retention
This resource describes how users are making use of the app over a period of days, showing how often and when users are likely to re-engage, this is available for new-installs
and active-installs
only.
Extra querystring parameters are required for each request.
cohort
can be one of:
time
countries
os-types
periods
describes the day increments between results for example
1,2,3,4,5,6,7
would give a complete 7 day window.
For example new-installs/retention?cohort=time&periods=1,2,3,4,5,6,7
will return
[
{"cohort":"2018-08-20T00:00:00+00:00","count":75,"r1":12,"r2":11,"r3":9,"r4":5,"r5":10,"r6":4,"r7":8},
{"cohort":"2018-08-21T00:00:00+00:00","count":76,"r1":15,"r2":2,"r3":9,"r4":6,"r5":8,"r6":7,"r7":0},
{"cohort":"2018-08-22T00:00:00+00:00","count":78,"r1":2,"r2":10,"r3":7,"r4":6,"r5":8,"r6":0,"r7":0},
{"cohort":"2018-08-23T00:00:00+00:00","count":78,"r1":7,"r2":7,"r3":11,"r4":12,"r5":0,"r6":0,"r7":0},
{"cohort":"2018-08-24T00:00:00+00:00","count":81,"r1":6,"r2":10,"r3":9,"r4":0,"r5":0,"r6":0,"r7":0},
{"cohort":"2018-08-25T00:00:00+00:00","count":82,"r1":7,"r2":7,"r3":0,"r4":0,"r5":0,"r6":0,"r7":0},
{"cohort":"2018-08-26T00:00:00+00:00","count":83,"r1":11,"r2":0,"r3":0,"r4":0,"r5":0,"r6":0,"r7":0},
{"cohort":"2018-08-27T00:00:00+00:00","count":86,"r1":0,"r2":0,"r3":0,"r4":0,"r5":0,"r6":0,"r7":0}
]