Introduction
This document (please see navigation on the left hand side) lists all API methods, and details the authentication mechanism. Countly API uses HTTP and a RESTful endpoint structure. Request and response payloads are formatted as JSON.
/i
Writing sessions, metrics and events
This is main path where to submit session data, metrics and events.
If you want to develop SDK for Countly, you would need to implement calls that you need in your SDK to Countly REST API from this page.
Each session should start with begin_session=1, then it should be extended with session_duration=seconds, to indicate the duration of the session. Session duration should not exceed time period specified in /api/config.js as session_duration_limit which by default is 120 seconds.
So you need to update session at least once in this period, to collect correct session duration information. The recommended period is every 60 seconds.
When user exists app or ends session, you can provided end_session=1 to indicate that this session ended for user.
Parameters listed below are mandatory for every write API request.
app_key
Application key for the current application. Can be obtained from your dashboard after creating your application.
device_id
Unique id for the user device. You can retrieve device specific ID or generate any unique ID you can using libraries like Open UDID
Session
begin_session
Indicates the start of the user session. begin_session should be used with the API call you make at the beginning of user's session. begin_session should be given the value 1.
end_session
Indicates the end of the user session. end_session should be used with the API call you make at the end of user's session. end_session should be given the value 1.
session_duration
Heartbeat like parameter for extending session duration of the user for session_duration seconds.
Metrics
JSON object containing key, value pairs. metrics can only be sent together with begin_session.
Currently below predefined metrics are valid;
metrics={
"_os": "Android",
"_os_version": "4.1",
"_device": "Samsung Galaxy",
"_resolution": "1200x800",
"_carrier": "Vodafone",
"_app_version": "1.2",
"_density": "MDPI",
"_store": "com.android.vending",
"_browser": "Chrome",
"_browser_version": "40.0.0"
}Events
JSON array containing event objects. Each event object can have below properties;
- key (Mandatory, String)
- count (Mandatory, Integer)
- sum (Optional, Double)
- dur (Optional, Double)
- segmentation (Optional, Dictionary Object)
- timestamp (Optional)
- hour (Optional)
- dow (Optional)
A sample event array will look like this;
[
{
"key": "level_success",
"count": 4
},
{
"key": "level_fail",
"count": 2
},
{
"key": "in_app_purchase",
"count": 3,
"sum": 2.97,
"dur": 1000,
"segmentation": {
"app_version": "1.0",
"country": "Germany"
}
}
]Ater this request we will be able to;
See how many times user completed a level successfully or failed.
See how many times in app purchase occurred and the total amount of these IAPs.
Segment IAP data into two levels, one is app_version and the other is country. So we will be able to identify which application version performed best in terms of IAP and which countries tend to do IAP more.
User details
JSON object containing key, value pairs.
All values are optional and currently you can pass this information about user:
user_details={
"name": "Arturs Sosins",
"username": "ar2rsawseen",
"email": "[email protected]",
"organization": "Countly",
"phone": "+37112345678",
//Web URL to picture
"picture": "https://pbs.twimg.com/profile_images/1442562237/012_n_400x400.jpg",
"gender": "M",
"byear": 1987, //birth year
"custom":{
"key1":"value1",
"key2":"value2",
...
}
}If you set value as null, you will delete the property.
Additionally you can upload picture of the user to the server by sending POST request to the same URL you would provide user information to.
If you don't have any user information to provide, you can simply upload profile picture to
"/i?app_key=APP_KEY&device_id=DEVICE_ID&user_details"
Accepted picture formats are .png, .gif and .jpeg and picture will be resized to maximal 150x150 dimensions.
Modifying custom user data
You can provide custom properties for user using custom key and providing JSON object with key and values to store for this user.
Note: dots (.) and dollar signs ($) in key names will be stripped out.
Also you can modify custom properties, like increment value stored on server by 1, or store array of values (including unique only values) under same key.
Here are example of possible modifications:
user_details={
"custom":{
//simply set key value
"key":"value",
//increment value on server by 2
"key2":{"$inc":2},
//multiply value on server by 2
"key3":{"$mul":2},
//store maximal value between provided and server value
"key4":{"$max":10},
//store minimal value between provided and server value
"key5":{"$min":10},
//store value if it does not exist on server yet
"key6":{"$setOnce":"initial value"},
//add one value to array
"key7":{"$push":"value"},
//add multiple values to array
"key8":{"$push":["value1","value2"]},
//add value to array, if it is already in array, it won't add it
"key9":{"$addToSet":"value"},
//add values to array, if values is already in array, it won't add them
"key10":{"$addToSet":["value1","value2"]},
//remove one value from array
"key11":{"$pull":"value"},
//remove multiple values from array
"key12":{"$pull":["value1","value2"]},
...
}
}List of possible commands:
- $inc - to increment value on server by provided value (if no value on server, assumes it is 0)
- $mul - to multiply value on server by provided value (if no value on server, assumes it is 0)
- $max - to store maximal value from the one on server and provided value (if no value on server, uses provided value)
- $min - to store minimal value from the one on server and provided value (if no value on server, uses provided value)
- $setOnce - set's value to key, only if property was not defined before for this user
- $push - add one or many values to array property (can have multiple same values, if property is not array, converts it to array)
- $addToSet - add one or many values to array property (will only store unique values in array, if property is not array, converts it to array)
- $pull - remove one or many values from array property (only removes value from array properties)
Consents
SDK can provide or revoke consent for specific features in consent object using feature name as key and value:
- true - to provide consent
- false - to revoke.
Currently available features are:
- sessions - tracking when, how often and how long users use your app/website
- events - allow sending custom events to server
- location - allow sending location information, if consent not given, SDK should force send empty location, to prevent server from determining location by IP address
- views - allow tracking which views/pages user visits
- scrolls - allow tracking user scrolls for scroll heatmap
- clicks - allow tracking user clicks for heatmap as well as link clicks
- forms - allow tracking user's form submissions
- crashes - allow tracking crashes, exceptions and errors
- attribution - allow tracking from which campaign did user come
- users - allow collecting/providing user information, including custom properties
- push - allow push notifications
- star-rating - allow to send their rating and feedback
- accessory-devices - allow to detect accessory or wearable devices like Apple Watch etc.
Note that available features may change depending on platform. And SDK can implement and manage it own set of features. The API is only for notifying server to store consent status for legal reasons.
A sample providing consent for crashes and revoking consent from sessions would look like this:
consent={
"crashes":true,
"sessions": false
}Change ID and merge data
old_device_id
If for some reason you want to change device_id that was provided to Countly for specific user, you can use new device id as device_ID parameter and specify old device ID as old_device_id parameter. That way Countly will switch the device ID used for this user from old one to new one transferring all data to it. If user with new device ID already existing, then their data will be merged together into single user.
device_id=myNewId&old_device_id=myOldIdAdditional parameters
timestamp
10 digit UTC timestamp for recording past data.
hour
Current user local hour (0 - 23)
dow
Currenr user day of the week (0-sunday, 1 - monday, ... 6 - saturday)
ip_address
IP address of the user. By default IP address of the user is detected from the connection but you can send it manually using this parameter. ip_address parameter can only be used with the begin_session request.
country_code and city
Additionally to passing the IP address from which location can be determined, it is also possible to directly provide user's country and city. For country you only need to provide ISO standard two letter country code. For city you may provide city name as string value
location
If you can provide user's location coordinates, you can do that though this parameter, passing value as location=lat,lng
For example, location=56.42345,123.45325
Push notifications
To specify that device is capable of receiving push notifications, you need to provide a token to Countly server by adding these parameters to your request:
token_session=1 saying that you will provide token in this request
test_mode=0 for production token, 1 for development build token, 2 for test / iOS Ad Hoc / TestFlight token
ios_token = {your token here} - push notification token for iOS
android_token = {your token here} - push notification token for Android
token_session=1&test_mode=0&android_token=12345678To notify Countly that user performed action on a push notification send [CLY]_push_action with "i" segment as message ID. If user opened a default URL, add "b" segment with "0" in it. In case user opened one of action buttons, put index of that button in "b" segment (starting from "1"). In the example below server will record a click on first button of message 123456789012345678901234.
events=[
{
"key": "[CLY]_push_action",
"count": 1,
"segmentation": {
"b": "1",
"i": "123456789012345678901234"
}
}
]Crash Analytics
crash - JSON object containing key, value pairs.
All values except _os, _app_version and _error are optional, but more information you provide, more information you will have when resolving crashes
Currently supported fields are:
crash={
//device metrics
"_os":"Android",
"_os_version":"4.1",
"_manufacture":"Samsung", //may not be provided for ios or be constant, like Apple
"_device": "Galaxy S4", //model for Android, iPhone1,1 etc for iOS
"_resolution": "1900x1080",
"_app_version":"2.1",
"_cpu": "armv7", //type of cpu used on device (for ios will be based on device)
"_opengl":"2.1", //version of open gl supported
//state of device
"_ram_current":1024, //in megabytes
"_ram_total":4096,
"_disk_current":3000, //in megabytes
"_disk_total":10240,
"_bat":99, //battery level from 0 to 100
//or provide "_bat_current" and "_bat_total" if other scale
"_orientation":"portrait", //in which device was held, landscape, portrait, etc
//bools
"_root":false, //true if device is rooted/jailbroken, false or not provided if not
"_online":true, //true if device is connected to the internet (WiFi or 3G), false or not provided if not connected
"_muted":false, //true if volume is off, device is in muted state
"_background":false, //true if app was in background when it crashed
//error info
"_name":"Null Pointer exception", //optional if provided by OS/Platform, else will use first line of stack
"_error":"Some error stack here", //error stack, can provide multiple separated by blank new line
"_nonfatal":false, //true if handled exception, false or not provided if unhandled crash
"_logs":"logs provided here",//some additional logs provided, if any
"_run":180, //running time since app start in seconds
//custom key/values provided by developers
"_custom":{
"facebook_sdk": "3.5",
"admob": "6.5"
}
}You can provide custom properties for crash using custom key and providing JSON object with key and values to store for this crash report and server will segment values for you for the same crash.
Views
You can report what views did user view and for how long. This is done by adding event with key [CLY]_view and event dur property for duration, and providing additional values as event segments, as:
- name - name of the view
- visit - 1 or true to count a visit to this view
- segment - single segment option (platform for mobile apps, domain for websites)
- start - 1 or true if user started session with this view
The usual flow is to create event when user visits view, and report duration when user exits it.
Here is the example for scenario, where user starts app with view1, views it for 60 seconds and moves to view2, views it for 30 seconds and exists app.
events=[
{
"key": "[CLY]_view",
"count": 1,
"segmentation": {
"name": "view1",
"segment": "Android",
"visit": 1,
"start": 1
}
}
]events=[
//firstly report previous view duration
{
"key": "[CLY]_view",
"count": 1,
"dur": 60,
"segmentation": {
"name": "view1",
"segment": "Android"
}
},
//then report new view
{
"key": "[CLY]_view",
"count": 1,
"segmentation": {
"name": "view2",
"segment": "Android",
"visit": 1
}
}
]events=[
//report last view duration on exit
{
"key": "[CLY]_view",
"count": 1,
"dur": 30,
"segmentation": {
"name": "view2",
"segment": "Android"
}
}
]View actions
Additionally it is possible to report actions taken on views to display on heat maps. For that you need to create [CLY]_action event with segment properties as:
- type - action type, as click, touch, longpress,etc
- x - x coordinate of action
- y - y coordinate of action
- width - width of the screen
- height - height of the screen
As example:
events=[
{
"key": "[CLY]_action",
"count": 1,
"segmentation": {
"type": "click",
"x": 120,
"y": 200,
"width": 1920,
"height": 1200
}
}
]Star Rating
SDK can provide a dialog for user to rate the app. To store this rating on server you need to submit custom event with key "[CLY]_star_rating" with these segments:
- platform - platform on which application runs
- app_version - application's version number
- rating - user's 1-to-5 rating
Star rating plugin should be enabled on server for this data to be properly recorded
Attribution
There is a way you can attribute a click from campaign to an install through API. Usually it is used to import attribution from third party sites as a postback to Count.ly server. You at least need to provide campaign ID (the last part of your campaign url).
If possible, provide also Countly generated user ID (which is usually passed to campaigns url too),mostly for the situations where you can pass data to app install like Google Play INSTALL_REFERRER.
You can provide any number of other conversion segments and their values, they all need to be prefixed by campaign_
To sum it up:
campaign_id
ID of the campaign you created in Countly
campaign_user
Countly generated user ID based on digital fingerprint of the user, that you can pass with the link to install if platform supports it
campaign_{param}
Any other parameters/segments that you want to pa with this conversion
/api-key
Retrieve user's API_KEY
This API call is meant to retrieve user's API_KEY based on user's login credentials (username and password).
Most common use case is when integrating Countly with your own system, to retrieve user's API KEY so API requests can be made on user's behalf (usually server to server requests)
This API endpoint uses Basic Authentication, so HTTP request should be (constructed respectively)[https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme]
The easiest way is to construct authentication URL and retrieve API key in body of response:
/o/users/all
Retrieve information about all users
Retrieve information about all users.
This request require API_KEY of a user who is global administrator
/o/users/me
Retrieve information about user
Retrieve information about user, who is the owner of the API_KEY
/o/apps/all
Retrieve information about all apps
Retrieve information about all users. This request require API_KEY of a user who is global administrator
/o/apps/mine
Retrieve information about user's apps
Retrieve information about apps which were created by the user, who is the owner of the API_KEY
/o/apps/details
Retrieve detailed information about app users (available from v16.12)
Retrieve information about apps which were created by the user, who is the owner of the API_KEY
/o?method=locations
Retrieve locations of the app
Retrieves the raw location data of the app, the object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
e - events or requests sent to server
n - new sessions
t - total sessions
u - unique locations
d - total session duration
ds - durations (counts)
f - frequency
l - loyalty
/o?method=sessions
Retrieve session information of the app
Retrieves the raw session data of the app, the object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
e - events or requests sent to server
n - new sessions
t - total sessions
u - unique locations
d - total session duration
ds - durations (counts)
f - frequency
l - loyalty
/o?method=users
Retrieve users of the app
Retrieves the raw users data of the app, the object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
e - events or requests sent to server
n - new sessions
t - total sessions
u - unique locations
d - total session duration
ds - durations (counts)
f - frequency
l - loyalty
/o?method=devices
Retrieve devices information of the app
Retrieves the raw devices data of the app, the object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
n - new devices
t - total devices
u - unique devices
/o?method=device_details
Retrieve device details data of the app
Retrieves the raw device details data of the app segmented by display resolutions, display densities, os, os versions and app versions. The object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
n - new instances
t - total instances
u - unique instances
Due to MongoDB inability to use key names that contain dots, all dots are replace by colons ":". So 1.2 becomes 1:2.
To differentiate platform versions, each platform version is formed by using first letter of platform name and version, so Windows 8.1 becomes w8:1
/o?method=carriers
Retrieve carriers of the app
Retrieves the raw carriers data of the app, the object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
n - new carries
t - total carries
u - unique carriers
/o?method=app_versions
Retrieve app versions data of the app
Retrieves the raw device details data of the app (including app version), the object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
n - new app version instances
t - total app version instances
u - unique app version instances
Note that app version names are modified per MongoDB inability to use dots in key names, so all dots in app version are replaces by colon ":"
/o?method=cities
Retrieve city locations of the app
Retrieves the raw city location data of the app, the object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
Note: that you must enable collecting city data, by setting city_data to true in /api/config.js
n - new cities
t - total cities
u - unique cities
/o?method=events
Retrieve events of the app
Retrieves the raw event data of the app segmented by provided event segmentation. The object is divided by time metrics, like year, month, date and can be processed by Countly JavaScript libraries
c - total count
s - total sum
/o?method=get_events
Retrieve list of events of the app
Retrieves the list of events and segments of the app
/o?method=get_period_obj
Get information about period object selected in dashboard
Retrieve data about periods
/o?method=top_events
Retrieve current user breakdown by metric
TopEvents endpoint is updated every 24 hours using jobs. You can see the data for 30 days and only daily. The limit parameter is an option. In the above example, the value of the limit parameter is defined as 2.
/o?method=total_users
Retrieve current user breakdown by metric
The data retrieved is current segmentation of users by provided metric. Mostly used to correct estimation, this api can also be used simply to get breakdown of current users by provided segment
/o/analytics/dashboard
Retrieve analytics data for dashboard
Retrieves the pre processed data to display at countly dashboard.
It displays data in 3 ranges:
recent 30 days
recent 7 days
and today
Each time period provides dashboard data, some top metrics and period name
Dashboard data can contain total sessions, total users, new users, total time, average time and average request.
Each data contains:
total amount or sum of instances for this period,
change in percentage or NA if not available
trend, which can be u for up and d for down
Top contains some top metrics as platforms, resolutions, carriers and users with percentage amount
/o/analytics/countries
Retrieve analytics data about countries
Retrieves the pre processed data about countries.
And similar to dashboard data, country data is divided in same time periods: 30 days, 7 days and today
It provides country name and code and:
t - total amount of sessions
u - unique amount of sessions
n - new amount of sessions
/o/analytics/sessions
Retrieve session data for specified period
Returns session related data as an array.
Each array item has following properties;
_id: Date in one of the following formats YYYY-M, YYYY-M-D, YYYY-M-D H:00
u: Total (unique) users
t: Total sessions
n: New users
d: Total session duration (in seconds)
e: Total write API requests received
/o/analytics/metric
Retrieve metric data for specified period
Returns metric related data as an array. Each array item has following properties:
_id: Group/segment. For example if you are fetching data for devices this will be the device name.
u: Total (unique) users
t: Total sessions
n: New users
Available metrics to query:
- app_versions
- carriers
- countries
- density
- devices
- langs
- os
- os_versions
- resolutions
/o/analytics/events
Retrieve event data for specified period
Returns breakdown data of event:
If you provide only event key is provided then
- _id: date/time bucket
- c: Total count
- s: Total sum
- dur: Total duration
But if you provide event key and segmentation then:
- _id: value for segment
- c: Total count
- s: Total sum
- dur: Total duration
You can provide:
- event=YourEventKey
- events=["Key1","Key2"]
- event=YourEventKey&segmentation=YourSegment
- events=["Key1","Key2"]&segmentation=YourSegment
/o/analytics/tops
Retrieve up to top 3 values for specified period
Retrieves up to 3 top values with percentages for platforms, resolutions, carries and countries
/o/analytics/loyalty
Retrieves loyalty data for specified period
Retrieves loyalty data, where
- l - loyalty bucket id
- t - amount of users in bucket for that period
- percent - percentage of users in bucket for that period
Loyalty buckets are:
- "1"
- "2"
- "3-5"
- "6-9"
- "10-19"
- "20-49"
- "50-99"
- "100-499"
- "> 500"
/o/analytics/frequency
Retrieves frequency data for specified period
Retrieves frequency data, where
- f - frequency bucket id
- t - amount of users in bucket for that period
- percent - percentage of users in bucket for that period
Frequency buckets are:
- "1-24 hours"
- "1 day"
- "2 days"
- "3 days"
- "4 days"
- "5 days"
- "6 days"
- "7 days"
- "8-14 days"
- "15-30 days"
- "30+ days"
/o/analytics/durations
Retrieves durations data for specified period
Retrieves durations data, where
- ds - durations bucket id
- t - amount of users in bucket for that period
- percent - percentage of users in bucket for that period
Durations buckets are:
- "0-10 seconds"
- "11-30 seconds"
- "31-60 seconds"
- "1-3 minutes"
- "3-10 minutes"
- "10-30 minutes"
- "30-60 minutes"
- "> 1 hours"
/o/ping
Server health check
This api allows to check if Countly server is running and has connection to the database
/i/users/create
Create new user
Creates new users from values provided in args parameter as stringified JSON
The value that can be included in args are:
'full_name': { 'required': true, 'type': 'String' },// name of the user
'username': { 'required': true, 'type': 'String' },// username of the user
'password': { 'required': true, 'type': 'String' }, //user's password
'email': { 'required': true, 'type': 'String' },// user's email
'admin_of': { 'required': false, 'type': 'Array' },// list of apps which user will be admin of
'user_of': { 'required': false, 'type': 'Array' }, //list of apps which user will be user of
'global_admin': { 'required': false, 'type': 'Boolean' }// is user a global admin
/i/users/update
Update user
Update user's information from values provided in args parameter as stringified JSON
The value that can be included in args are:
'user_id': { 'required': true, 'type': 'String' }, //ID of user to update
'full_name': { 'required': false, 'type': 'String' }, //new full name
'username': { 'required': false, 'type': 'String' }, //new username
'password': { 'required': false, 'type': 'String' }, //new password
'email': { 'required': false, 'type': 'String' }, //new email
'admin_of': { 'required': false, 'type': 'Array' }, //list of apps to make admin of
'user_of': { 'required': false, 'type': 'Array' }, //list of apps is user of
'global_admin': { 'required': false, 'type': 'Boolean' }, //should be global admin
'send_notification': { 'required': false, 'type': 'Boolean' } //send email notification about changes
/i/users/delete
Delete users
Delete users with provided user ids from args parameter's user_ids list property. args parameter should be passed as stringified JSON
Example args content:
{user_ids:["542bd25ab3bced1a67000005", "542bd25ab3bced1a67000006", "542bd25ab3bced1a67000007"]}
/i/users/deleteOwnAccount
Used to delete own user account
Used to delete own account. Account is any deleted if password is right for the one found based on API key. Last global admin can't be deleted.
/i/apps/create
Create new app
Creates new app from values provided in args parameter as stringified JSON
args can contain this properties:
'name': { 'required': true, 'type': 'String' }, //name of the app
'country': { 'required': false, 'type': 'String' }, //your country
'type': { 'required': false, 'type': 'String' }, // type of the app, mobile, web, et
'category': { 'required': false, 'type': 'String' },// ID of app category
'timezone': { 'required': false, 'type': 'String' }// timezone in which to display statistics
Example request could look like
/i/apps/create?api_key=your-api-key&args={"name":"Test App","type":"mobile"}
/i/apps/update
Update app information
Update app information from values provided in args parameter as stringified JSON
args can contain this properties:
'app_id': { 'required': true, 'type': 'String'}, //ID of the app to change information
'name': { 'required': false, 'type': 'String' },// new app name
'category': { 'required': false, 'type': 'String' },// new app category ID
'timezone': { 'required': false, 'type': 'String' },//new timezone
'country': { 'required': false, 'type': 'String' } //new app country
/i/apps/reset
Reset all app data and events
Reset all app data (sessions, events, metrics, etc) with provided app id from args parameter's app_id property. Parameter period controls which data will be deleter.
args parameter should be passed as stringified JSON
Example args content: {"app_id":"542bad58b3bced1a67000003", "period":"all"}
If period parameter is all, then data for all periods will be deleted.
If period parameter is reset, then not only all data will be deleted, but also all app configuration will be reset. Like deletes all created campaigns, bookmarked drill queries, etc.
Other period parameter values indicate the period for which app data should be preserved and older data deleted:
- 1month - delete data older than 1 month
- 3month - delete data older than 3 month
- 6month - delete data older thanb6 month
- 1year - delete data older than 1 year
- 2year -delete data older than 2 years
/i/apps/delete
Delete app
Delete app with provided app id from args parameter's app_id property. args parameter should be passed as stringified JSON
Example args content: {app_id:"542bad58b3bced1a67000003"}
/i/bulk
Bulk session, metric, event data writing
Bulk method limitations
Countly v16.02 had issues with parallelization. Basically there is no guarantee that bulk requests will be executed in the order you provided them, they also can be executed simultaneously.
If order of execution does not matter (as events, crashes, user info), you can use bulk API. But if order of execution matters, like in sessions, then results may be inconsistent with what you would receive if you execute all requests separately.
This has been since fixed in Countly v16.06
Basically instead of sending separate requests to /i with session data, metrics and events, you can combine them in one single HTTP request (for example when sending older data with timestamp, while user did not have Internet connection)
For that you would need to convert normal /i request parameters into JSON object, so for example, sending bulk data which combine 4 normal requests:
1) to start session with metrics
2) to update session duration
3) to send an event
4) to end session
[
{
"device_id":"1234567890",
"app_key":"9a4d196c01d3ca82876c0398ab774e5e",
"begin_session":1,
"metrics":
{
"_os": "IOS",
"_os_version": "7.1",
"_resolution": "2048x1536",
"_density": "200dpi",
"_device": "iPod",
"_carrier": "Telecom",
"_app_version": "1.2"
}
},
{
"device_id":"1234567890",
"app_key":"9a4d196c01d3ca82876c0398ab774e5e",
"session_duration":30
},
{
"device_id":"1234567890",
"app_key":"9a4d196c01d3ca82876c0398ab774e5e",
"events":
[
{
"key": "test2",
"count": 2,
"sum":1.50,
"segmentation":
{
"country": "Latvia",
"market": "googleplay"
}
}
]
},
{
"device_id":"1234567890",
"app_key":"9a4d196c01d3ca82876c0398ab774e5e",
"end_session":1
}
];Also, it's possible to combine the 'start_session', 'metrics', 'session_duration', 'events' and 'end_session' together into one JSON block, with the appropriate device_id and api_key. You only need to make sure that the order is correct.
Here's an example:
var params = [
{"device_id":DEVICE_ID, "app_key":APP_KEY, "begin_session":1, "metrics":{"os": "Android"}},
{"device_id":DEVICE_ID, "app_key":APP_KEY, "session_duration":30},
{"device_id":DEVICEID+"A", "app_key":APP_KEY, "end_session":1}
];/i/app_users/create
Create new app user
Creates new user with provided properties.
The only mandatory property is did which is device_id
/i/app_users/update
Update existing app user
Updates existing app users based on provided query parameter to select which users to update and using update object to modify document
/i/app_users/delete
Delete existing app user
Delete existing app user and everything Countly knows about this user
/i/app_users/export
Export information about app user
Starts the export process, which generate export file on server, that can be downloaded later
/i/app_users/deleteExport/:filename
Delete previously exported file
Deletes export file by provided name, that was previously generated
/o/app_users/download/:filename
Download previously exported file
Downloads exported file by provided name, that was previously generated
/o?method=segmentation
Breakdown of data for specific event by provided bucket
This api allows to query events that were recorded in drill. Event can be any custom event sent to Countly server, as well as internal events like:
- [CLY]_session for sessions
- [CLY]_crash for crahses
- [CLY]_view for views
- [CLY]_action for actions
- [CLY]_push_action for actions performed on push notifications
- [CLY]_push_open for opened push notifications
- [CLY]_push_sent for sent push notifications
It provides following properties for each bucket:
- u - unique users
- t - total times/count
- s - sum property if provided for event
- dur - duration property if provided for event
meta property lists breakdown by segments for queries with projection key
/o?method=segmentation_users
Get list of user uid properties for provided segmentation query
This api allows to query user lists for segmented events that were recorded in drill. Event can be any custom event sent to Countly server, as well as internal events like:
- [CLY]_session for sessions
- [CLY]_crash for crahses
- [CLY]_view for views
- [CLY]_action for actions
- [CLY]_push_action for actions performed on push notifications
- [CLY]_push_open for opened push notifications
- [CLY]_push_sent for sent push notifications
It provides JSON array with uid properties, which are Countly internal user ids.
/o?method=segmentation_meta
Fetches all segment data for provided event
This api returns all segment values for all properties in drill for provided event, except from big list properties, which have too many values and are stored separately.
/o?method=segmentation_big_meta
Fetches segments for big list properties (available since 16.12)
Due to UI limitations by default this api outputs maximum of 200 items (configurable). But it is possible to pre filter with a regex through search parameter to return only set of values for which user is searching
/o?method=drill_bookmarks
Get bookmarked filter query from drill (available in drill plugin)
Retrieve bookmarked Countly Drill data query
/i/drill/add_bookmark
Add drill query to bookmarks (available in drill plugin)
Add new drill bookmark
/i/drill/delete_bookmark
Remove drill bookmark (available in drill plugin)
Delete drill bookmark
/i/pushes/create
In most cases, process of sending a message involves 2 steps:
- Preparation, that is calculation of audience and extracting their language preferences.
- Creation. That is taking a prepared message and creating schedule job .
When using API rather than Countly Dashboard, (1) and (2) can be done in background, so only request (2) is required. But in any case, (1) and (2) will be performed.
This request performs step (2). It creates message and sets it's status to "Created". It also creates a schedule a job for this message which is run right away for non-timezoned messages. If message is about to be sent in users' timezones, it's scheduled 24 hours prior to sending date to ensure users won't move between timezones.
Note that while most of arguments are cross-platform, there are still some differences between iOS & Android platforms which need to be addressed.
Returned JSON contains full message object. Note that Countly supports sending messages to multiple apps at once and even to multiple platforms at once.
Message status
Countly message status (result.status key) is a bitmap of following statuses:
0 (0)
NotCreated
1 (1 << 0)
Created - have been created, but haven't been scheduled yet
2 (1 << 1)
Scheduled - put into sending queue, will be sent on scheduled date
4 (1 << 2)
Sending - being sent right now
8 (1 << 3)
Done - done with any processing
16 (1 << 4)
Error - some error happened during sending
32 (1 << 5)
Success - sending is completed with some success
1024 (1 << 10)
Aborted - processing was aborted and won't be repeated due to non-recoverable error (usually credentials error)
2048 (1 << 11)
Deleted - message was deleted
Note that statuses above are often combined. For example standard message waiting to be sent within an hour will have status 3 (1 << 0 | 1 << 1). Message which was aborted, but had some successful sends will have status 1081.
Usual way of status transitions is following:
NotCreated => Created => Created | Scheduled => Created | Scheduled | Sending => Created | Done | Success => Created | Done | Success | Deleted
Message result
Result is a JSON object containing results of message sending process:
{
"status": 7,
"total": 23812,
"processed": 123,
"sent": 120,
"error": "Some error string if any",
"resourceErrors": [{"date": 123912313123, "error": "error string"}],
"aborts": [{"date": 123912313123, "error": "error string"}],
}- total number represents total number of recipients found for this message;
- processed number shows number of notifications sent to APN or GCM service;
- sent number represents number of notifications accepted by APN or GCM (tokens are valid);
- error appears only when all retries spent or unrecoverable error happened;
- resourseErrors appear as message is being sent, mostly connectivity issues are listed here;
- aborts contains unrecoverable errors.
Message localisation
To localise your messages, you need to supply correct messagePerLocale property:
{
"default": "Default message",
"default|p": {
"0": {
"f": "our wonderful user",
"c": true,
"k": "name"
}
},
"default|t": "Default message title",
"default|0|t": "Default button 0 title",
"default|0|l": "http://default.button0.link.com",
"default|1|t": "Default button 1 title",
"default|1|l": "http://default.button1.link.com",
"en": "Message in English",
"en|p": {
"0": {
"f": "our wonderful English-speaking user",
"c": true,
"k": "name"
}
},
"de": "... in Deutsch",
"ru": "... на Русском",
"ru|t": "Заголовок сообщения на Русском",
"en|1|t": "Button 1 title in English"}
}Correct messagePerLocale object must have "default" message and a message per each locale you want your message to be localized in.
Note complex keys in messagePerLocale:
- LOCALE|p stands for message personalisation object.
- LOCALE|t stands for message title.
- LOCALE|tp stands for message title personalisation object.
- LOCALE|0|t stands for button 0 title.
- LOCALE|0|l stands for button 0 link.
- LOCALE|1|t stands for button 1 title.
- LOCALE|1|l stands for button 1 link.
Button attribute consists of locale name followed by separator (vertical line |, not L letter), then button index (0 or 1), separator again, then either t for title or l (this time lower L) for link.
No need to specify all properties for all locales. Just set default locale and override values for locale you have localisation for. For example set all button titles and links in default locale and only override button titles in languages you support.
Locales are 2-character codes from ISO 639-1 taken from corresponding iOS & Android APIs with exception of all Chinese-language locales (China, Taiwan, etc.) which have only two codes: "zh_hans" for Simplified Chinese and "zh_hant" for Traditional Chinese.
Note that locale parameter is just a helper for Countly Dashboard which contains percentages (from 0.0 to 1.0) for all message texts specified in messagePerLocale for this message (when the message was created). Example message above has locale property saying that 90% of message recipients have English language on their devices, while other 10% of users have other locales and Countly will send default message to them. This distribution is acquired from /i/pushes/prepare method.
Message personalisation
You can make messages dynamic by inserting personalised content into your messages. For example, user's first name or company name. Any property from a user profile can be used for message personalisation. Personalisation object is a key-value pair where key ("0" in example above) is a place in a corresponding string (index) of where to insert user profile property value, and value is an object with 3 mandatory keys: "k" is property key in user profile, "c" is a boolean defining whether to capitalise first letter of the property value, "f" is a fallback value to use when no such property exists in a user profile.
Message sounds
Behaviour of sound property is not cross-platform unless you pay attention to your app implementation:
- On iOS, sound is what it should be - just a sound property in message JSON, see Apple documentation: Preparing Custom Alert Sounds.
- On Android, sound must be a
Uripointing at corresponding sound file with an exception of"default"value which falls back to default sound of notification -Notification.DEFAULT_SOUND.
Message segmentation
userConditions & drillConditions limit audience of a particular message to users with some user properties or behaviour. For example, to send a message to a set of device ids, you can use:
{... "userConditions": {"did": {"$in": ["did1", "did2", ...]}} ...}
To send to users with some custom property set from SDKs:
{... "userConditions": {"custom.propName": {"$in": ["v1", "v2", ...]}} ...}
userConditions is a standard MongoDB query, while drillConditions is a specialised drill query. Easiest way to determine a query for a particular use case would be using Chrome Developer Tools to record a request made from Countly dashboard to Countly server.
Transactional messages
Introduced in 18.08 transactional messages allow reusing the same message again and again by just adding users to it with a separate API call. This message must be first created by running this API call (/create) with tx property set to true. See corresponding API method description for details.
/i/pushes/prepare
In most cases, process of sending a message involves 2 steps:
- Preparation, that is extracting push tokens from database and saving them in separate collection. This step also allows calculation of audience and gathering distinct user locales used in this message.
- Actual sending. That is taking prepared collection of tokens and sending push notifications to APN or GCM.
When using API rather than Countly Dashboard, (1) can be done in background, so only request (2) is required. But in any case, (1) will be performed.
This request performs step (1). It builds audience collection(s) and returns number of users found in the database along with number of users for each locale (tab 2 of example response).
Note that sometimes, when calculation process takes too much time, request will return temporary result (tab 1 of example response) with only one total key in build property of returned JSON. Temporary total number represents total number of push-enabled users for all app-platform combinations supplied in request, meaning it's not final and it shouldn't be used for any important decisions. In this case the request can be submitted again, with same parameters and with _id returned in first response, to check if process of message preparing is finished. When done, response build key will have count subobject with locale information and optionally tzs key containing all timezones of audience built.
/i/pushes/message
This method just retrieves message object from database along with short analytics overview. It's useful when you want to check status of message which was recently sent or how much messages is being sent for automated messages case.
Top result property of message is just an aggregation of all its partial messages from pushly property. sent & actions sub properties represent bar chart on message view screen displaying number of messages sent & actioned respectfully.
/i/pushes/delete
This method marks the message as deleted (note "result.status" in JSON). Also aborts any future batches of notifications for this message.
/i/pushes/active
This endpoint activates deactivated automated and transactional messages or vice versa.
/i/pushes/push
This endpoint allows adding a set of users defined by args.userConditions and args.drillConditions to existing transactional message of _id specified in args._id.
Note that existing notification must be active (or Scheduled in dashboard, result.status & 2 > 0) and transactional (tx === true).
Users are added to the queue right away, meaning scheduling part is done during request processing, not in a detached job way as in /create request.
Returned object shows how much push notifications has been added to the sending queue (total) as well as closest date on which they'll start being sent (next).
/o/campaign
Retrieve data of all campaigns
This API allows to query information about campaigns. You can also get data for specific campaign by optionally providing camp_id.
The property data contains standard Countly data by period encoding format
/o/campaign?data
Retrieve click, install and other data about provided campaigns
The property data contains standard Countly data by period encoding format. Providing data in buckets, year, month, day, hour.
It can have properties as:
- clk - unique clicks
- aclk - total clicks
- ins - installs
- ses - sessions
- rev - revenue reports
So for example data:
"data": {
"2016": {
"3": {
"19": {
"14": {
"aclk": 1,
"clk": 1
},
}
}
}Would mean there was 1 click / 1 unique click on 19th of March, 2016 between 14:00 and 14:59
/o/campaign?camp_id
Retrieve data of specific campaign