/i

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.

Mandatory Parameters

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

Optional Parameters

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=myOldId

Additional 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=12345678

To 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