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 installs
• 2 Return only installs running on a simulator
• 3 Return only instals running on a real device

targetTypeFilter - Filter out installs using release and / or debug builds

• 1 Return all installs
• 2 Return only installs running a debug build
• 3 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 period
• active-installs Installs that have interacted with Kumulos within the period
• all-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 example user.isCustomer
• data.* would group by a event data property, for example data.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 day
• distribution - For equally weighted buckets show how users are grouped in terms of number of sessions.
• daily - Count of sessions per day
• summary - Average session duration and average sessions per day
• duration - Mean session length grouped by day
• duration-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}
]