Countly.setHttpPostForced(true); // default is false
+Countly.setHttpPostForced(true); // default is false
-Parameter Tampering Protection
+Parameter Tampering Protection
You can set optional salt to be used for calculating checksum of request data,
which will be sent with each request using &checksum field. You need to set
exactly the same salt on Countly server. If salt on Countly server is set, all
requests would be checked for validity of &checksum field before being processed.
-// sending data with salt
+// sending data with salt
Countly.enableParameterTamperingProtection("salt");
-Setting up custom events
+Setting up custom events
A custom event is any type of action that you can send to a Countly instance,
e.g purchase, settings changed, view enabled and so. This way it's possible to
@@ -82,7 +102,7 @@ Countly.enableParameterTamperingProtection("salt");
- Data passed should be in UTF-8
+ Data passed should be in UTF-8
All data passed to Countly server via SDK or API should be in UTF-8.
@@ -93,45 +113,45 @@ Countly.enableParameterTamperingProtection("salt");
what information each usage will provide us:
- - Usage 1: how many times purchase event occured.
- -
+
- Usage 1: how many times purchase event occured.
+ -
Usage 2: how many times purchase event occured + the total amount of those
purchases.
- -
+
-
Usage 3: how many times purchase event occured + which countries and application
versions those purchases were made from.
- -
+
-
Usage 4: how many times purchase event occured + the total amount both of
which are also available segmented into countries and application versions.
- -
+
-
Usage 5: how many times purchase event occured + the total amount both of
which are also available segmented into countries and application versions
+ the total duration of those events.
-1. Event key and count
-// example for sending basic custom event
+1. Event key and count
+// example for sending basic custom event
var events = {"key":"Basic Event","count":1};
Countly.recordEvent(events);
-2. Event key, count and sum
-// example for event with sum
+2. Event key, count and sum
+// example for event with sum
var events = {"key":"Event With Sum","count":1,"sum":"0.99"};
Countly.recordEvent(events);
-3. Event key and count with segmentation(s)
-// example for event with segment
+3. Event key and count with segmentation(s)
+// example for event with segment
var events = {"key":"Event With Segment","count":1};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
-4. Event key, count and sum with segmentation(s)
-// example for event with segment and sum
+4. Event key, count and sum with segmentation(s)
+// example for event with segment and sum
var events = {"key":"Event With Segment And Sum","count":1,"sum":"0.99"};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
-5. Event key, count, sum and duration with segmentation(s)
-var events = {
+5. Event key, count, sum and duration with segmentation(s)
+var events = {
"key": "Event With Sum And Segment duration",
"count": 1,
"Sum": "0.99",
@@ -147,25 +167,30 @@ Countly.recordEvent(events);
extend those examples and use country, app_version, game_level, time_of_day and
any other segmentation that will provide you valuable insights.
-Timed events
+Timed events
It's possible to create to create timed events by defining a start and stop moment.
-// Time Event
-Countly.startEvent("Timed Event");
setTimeout(function() {
+// Time Event
+Countly.startEvent("Timed Event");
+setTimeout(function() {
Countly.endEvent({ "key": "Timed Event");
-}, 1000);
+}, 1000);
+
// Time Event With Sum
Countly.startEvent("Timed Event With Sum");
-setTimeout(function() {
countly.endEvent({"key": "Timed Event With Sum", "sum": "0.99"});
}, 1000);
+setTimeout(function() {
+ countly.endEvent({"key": "Timed Event With Sum", "sum": "0.99"});
+}, 1000);
When ending a event you can also provide additional information. But in that
case you have to provide segmentation, count and sum. The default values for
those are "null", 1 and 0.
-
+
// Time Event with segment
-Countly.startEvent("Timed Event With Segment");
setTimeout(function() {
+Countly.startEvent("Timed Event With Segment");
+setTimeout(function() {
var events = {
"key": "Timed Event With Segment"
};
@@ -174,9 +199,11 @@ Countly.startEvent("Timed Event With Segment");
setTimeout(function() {
"Age": "28"
};
Countly.endEvent(events);
-}, 1000)
+}, 1000)
+
// Time Event with Segment, sum and count
-Countly.startEvent("Timed Event With Segment, Sum And Count");
setTimeout(function() {
+Countly.startEvent("Timed Event With Segment, Sum And Count");
+setTimeout(function() {
var events = {
"key": "timedEvent",
"count": 1,
@@ -186,74 +213,82 @@ Countly.startEvent("Timed Event With Segment, Sum And Count");
setTimeout(fun
"Country": "Turkey",
"Age": "28"
};
- Countly.endEvent(events);
}, 1000);
-Device ID
+ Countly.endEvent(events);
+}, 1000);
+Device ID
- When the SDK is initialized for the first time and no device ID is provided, a device ID will be generated by SDK.
+ When the SDK is initialized for the first time and no device ID is provided, a device ID will be generated by SDK.
- For iOS: the device ID generated by SDK is the Identifier For Vendor (IDFV)
For Android: the device ID generated by SDK is the OpenUDID or Google Advertising ID
+ For iOS: the device ID generated by SDK is the Identifier For Vendor (IDFV)
+ For Android: the device ID generated by SDK is the OpenUDID or Google Advertising ID
- You may provide your own custom device ID when initializing the SDK
+ You may provide your own custom device ID when initializing the SDK
-Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
-
- Changing the Device ID
+Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
+
+ Changing the Device ID
- You may configure/change the device ID anytime using:
+ You may configure/change the device ID anytime using:
+
-Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
+Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
- You may either allow the device to be counted as a new device or merge existing data on the server. If
- theonServer bool is set to true,
- the old device ID on the server will be replaced with the new one, and data associated with the old device ID will be merged automatically.
Otherwise, if onServer bool is set to false, the device will be counted as a new device on the server.
+ You may either allow the device to be counted as a new device or merge existing
+ data on the server. If theonServer bool is set to
+ true, the old device ID on the server will be replaced with the
+ new one, and data associated with the old device ID will be merged automatically.
+ Otherwise, if onServer bool is set to
+ false, the device will be counted as a new device on the server.
+
-Temporary Device ID
+Temporary Device ID
You may use a temporary device ID mode for keeping all requests on hold until
the real device ID is set later.
You can enable temporary device ID
- when initializing the SDK:
+ when initializing the SDK:
-Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
+Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
To enable a temporary device ID after init, you would call:
-Countly.changeDeviceId(Countly."TemporaryDeviceID", ON_SERVER);
+Countly.changeDeviceId(Countly."TemporaryDeviceID", ON_SERVER);
- Note: When passing TemporaryDeviceID for deviceID parameter,
- argument for onServerparameter does not matter.
+ Note: When passing TemporaryDeviceID for deviceID parameter,
+ argument for onServerparameter does not matter.
- As long as the device ID value is TemporaryDeviceID,
- the SDK will be in temporary device ID mode and all requests will be on hold,
- but they will be persistently stored.
+ As long as the device ID value is TemporaryDeviceID, the SDK will
+ be in temporary device ID mode and all requests will be on hold, but they will
+ be persistently stored.
When in temporary device ID mode, method calls for presenting feedback widgets
and updating remote config will be ignored.
- Later, when the real device ID is set using Countly.changeDeviceId(DEVICE_ID, ON_SERVER); method,
- all requests which have been kept on hold until that point will start with the
- real device ID
+ Later, when the real device ID is set using
+ Countly.changeDeviceId(DEVICE_ID, ON_SERVER); method, all requests
+ which have been kept on hold until that point will start with the real device
+ ID
-Retrieving the device id and its type
+Retrieving the device id and its type
You may wanty to see what device id Countly is assigning for the specific device
and what the source of that id is. For that you may use the following calls.
The id type is an enum with the possible values of: "DEVELOPER_SUPPLIED", "OPEN_UDID",
"ADVERTISING_ID".
-// get device id
+// get device id
Countly.getDeviceID(function(deviceId){
console.log(deviceId);
}, function(getDeviceIDError){
console.log(getDeviceIDError);
});
-User location
+User location
While integrating this SDK into your application, you might want to track your
user location. You could use this information to better know your apps user base
@@ -261,14 +296,14 @@ Countly.getDeviceID(function(deviceId){
are 4 fields that can be provided:
- - country code in the 2 letter iso standard
- - city name (has to be set together with country code)
- -
+
- country code in the 2 letter iso standard
+ - city name (has to be set together with country code)
+ -
Comma separate latitude and longitude values, for example "56.42345,123.45325"
- - ip address of your user
+ - ip address of your user
-// send user location
+// send user location
Countly.setLocation("28.006324", "-82.7166183");
When those values are set, they will be sent every time when initiating a session.
@@ -283,13 +318,13 @@ Countly.setLocation("28.006324", "-82.7166183");
It will erase cached location data from the device and the server.
-Remote Config
+Remote Config
Remote config allows you to modiffy how your app functions or looks by requesting
key-value pairs from your Countly server. The returned values can be modiffied
based on the user profile. For more details please see Remote Config documentation.
-Automatic Remote Config download
+Automatic Remote Config download
There are two ways of acquiring remote config data, by automatic download or
manual request. By default, automatic remote config is disabled and therefore
@@ -305,7 +340,8 @@ Countly.setLocation("28.006324", "-82.7166183");
Note: call setRemoteConfigAutomaticDownload method
before init
-// Call this method before init
Countly.setRemoteConfigAutomaticDownload(function(r){
+// Call this method before init
+Countly.setRemoteConfigAutomaticDownload(function(r){
alert(r)
}, function(r){
alert(r);
@@ -321,14 +357,14 @@ Countly.setLocation("28.006324", "-82.7166183");
instead). It is possible that a previously valid key returns no value after an
update.
-Manual Remote Config download
+Manual Remote Config download
There are three ways for manually requesting a Remote Config update:
- - Manually updating everything
- - Manually updating specific keys
- - Manually updating everything except specific keys
+ - Manually updating everything
+ - Manually updating specific keys
+ - Manually updating everything except specific keys
Each of these requests also has a callback. If that returns a non-null value,
@@ -341,7 +377,7 @@ Countly.setLocation("28.006324", "-82.7166183");
The advantage is that you can make the request whenever it is desirable for you.
It has a callback to let you know when it has finished.
-Countly.remoteConfigUpdate(function(r){
+Countly.remoteConfigUpdate(function(r){
alert(r)
}, function(r){
alert(r);
@@ -352,7 +388,7 @@ Countly.setLocation("28.006324", "-82.7166183");
updated. That list is an array with string values of those keys. It has a callback
to let you know when the request has finished.
-Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
+Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -362,7 +398,7 @@ Countly.setLocation("28.006324", "-82.7166183");
updateRemoteConfigExceptKeys. The key list is a array with string values of the
keys. It has a callback to let you know when the request has finished.
-Countly.updateRemoteConfigExceptKeys(["url"], function(r){
+Countly.updateRemoteConfigExceptKeys(["url"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -373,7 +409,7 @@ Countly.setLocation("28.006324", "-82.7166183");
will update all values. This means that it will also erase all keys not returned
by the server.
-Getting Remote Config values
+Getting Remote Config values
To request a stored value, call getRemoteConfigValueForKey with
the specified key. If it returns null then no value was found. The SDK has no
@@ -381,22 +417,22 @@ Countly.setLocation("28.006324", "-82.7166183");
needs to cast it to the appropriate type. The returned values can also be a JSONArray,
JSONObject or just a simple value like int.
-Countly.getRemoteConfigValueForKey("name", function(r){
+Countly.getRemoteConfigValueForKey("name", function(r){
alert(r)
}, function(r){
alert(r);
});
-Clearing stored Remote Config values
+Clearing stored Remote Config values
At some point you might want to erase all values downloaded from the server.
To achieve that you need to call one function, depicted below:
-Countly.remoteConfigClearValues(function(r){
+Countly.remoteConfigClearValues(function(r){
alert(r)
}, function(r){
alert(r);
});
-Setting up User Profiles
+Setting up User Profiles
Available with Enterprise Edition, User Profiles is a tool which helps you identify
users, their devices, event timeline and application crash information. User
@@ -415,7 +451,7 @@ Countly.setLocation("28.006324", "-82.7166183");
After you have provided user profile information, you must save it by calling
Countly.userData.save().
-/ example for setting user data
+/ example for setting user data
var options = {};
options.name = "Nicola Tesla";
options.username = "nicola";
@@ -428,55 +464,59 @@ options.gender = "Male";
options.byear = 1919;
Countly.setUserData(options);
The keys for predefined user data fields are as follows:
-
-
-
- Key
- Type
- Description
-
-
- name
- String
- User's full name
-
-
- username
- String
- User's nickname
-
-
- email
- String
- User's email address
-
-
- organization
- String
- User's organisation name
-
-
- phone
- String
- User's phone number
-
-
- picture
- String
- URL to avatar or profile picture of the user
-
-
- gender
- String
- User's gender as M for male and F for female
-
-
- byear
- String
- User's year of birth as integer
-
-
-
+
+
+
+
+ Key
+ Type
+ Description
+
+
+
+
+ name
+ String
+ User's full name
+
+
+ username
+ String
+ User's nickname
+
+
+ email
+ String
+ User's email address
+
+
+ organization
+ String
+ User's organisation name
+
+
+ phone
+ String
+ User's phone number
+
+
+ picture
+ String
+ URL to avatar or profile picture of the user
+
+
+ gender
+ String
+ User's gender as M for male and F for female
+
+
+ byear
+ String
+ User's year of birth as integer
+
+
+
+
Using "" for strings or a negative number for 'byear' will effectively delete
that property.
@@ -486,13 +526,13 @@ Countly.setUserData(options);
on your Countly backend. Note: keys with . or $ symbols will have those symbols
removed.
-Modifying custom data
+Modifying custom data
Additionally you can do different manipulations on your custom data values, like
increment current value on server or store a array of values under the same property.
Below is the list of available methods:
-// example for extra user features
+// example for extra user features
Countly.userData.setProperty("setProperty", "My Property");
Countly.userData.increment("increment");
@@ -501,11 +541,13 @@ Countly.userData.multiply("multiply", 20);
Countly.userData.saveMax("saveMax", 100);
Countly.userData.saveMin("saveMin", 50);
Countly.userData.setOnce("setOnce", 200);
-Countly.userData.pushUniqueValue("pushUniqueValue","morning");
Countly.userData.pushValue("pushValue", "morning");
Countly.userData.pullValue("pullValue", "morning");
+Countly.userData.pushUniqueValue("pushUniqueValue","morning");
+Countly.userData.pushValue("pushValue", "morning");
+Countly.userData.pullValue("pullValue", "morning");
In the end always call Countly.userData.save() to send them to the server.
-User Consent management
+User Consent management
To be compliant with GDPR, starting from 18.04, Countly provides ways to toggle
different Countly features on/off depending on the given consent.
@@ -515,7 +557,7 @@ Countly.userData.pushUniqueValue("pushUniqueValue","morning");
Countly.userDa
By default the requirement for consent is disabled. To enable it, you have to
call setRequiresConsent with true, before initializing Countly.
-Countly.setRequiresConsent(true);
+Countly.setRequiresConsent(true);
By default no consent is given. That means that if no consent is enabled, Countly
will not work and no network requests, related to features, will be sent. When
@@ -542,48 +584,48 @@ Countly.userData.pushUniqueValue("pushUniqueValue","morning");
Countly.userDa
The current features are:
- -
+
-
sessions - tracking when, how often and how long users use your app
- - events - allow sending custom events to server
- - views - allow tracking which views user visits
- - location - allow sending location information
- - crashes - allow tracking crashes, exceptions and errors
- -
+
- events - allow sending custom events to server
+ - views - allow tracking which views user visits
+ - location - allow sending location information
+ - 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
- - starRating - allow to send their rating and feedback
- - apm - allow application performance monitoring
+ - push - allow push notifications
+ - starRating - allow to send their rating and feedback
+ - apm - allow application performance monitoring
-Changing consent
+Changing consent
There are 3 ways of changing feature consent:
- -
+
-
giveConsent/removeConsent - gives or removes consent to a specific feature
-//giveConsent
+//giveConsent
Countly.giveConsent(["events", "views", "star-rating", "crashes"]);
// removeConsent
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);
- -
+
-
giveAllConsent/removeAllConsent - giveAll or removeAll consent to a specific
feature
-//giveAllConsent
+//giveAllConsent
Countly.giveAllConsent();
//removeAllConsent
Countly.removeAllConsent();
-Crash reporting
+Crash reporting
With this feature, Countly SDK will generate a crash report if your application
crashes due to an exception, and send it to Countly server for further inspection.
@@ -593,19 +635,22 @@ Countly.removeAllConsent();
unavailable server), then SDK stores the crash report locally in order to try
again later.
-
- Please add to your html file:
-
-
-// Using countly crash reports
+
+
+// Using countly crash reports
Countly.enableCrashReporting();
You can also send a custom crash log to Countly using code below.
-
+
// Send a custom crash log
Countly.addCrashLog("My crash log from JavaScript");
@@ -628,20 +673,20 @@ app.addCrashLog = function(){
},1000);
}
-View tracking
+View tracking
You can manually add your own views in your application, and each view will be
visible under Analytics > Views. Below you can see two examples of sending
a view using Countly.recordview function.
-// record a view on your application
+// record a view on your application
Countly.recordView("My Home Page");
Countly.recordView("Profile Page");
-Application Performance Monitoring
+Application Performance Monitoring
- Minimum Countly SDK Version
+ Minimum Countly SDK Version
This feature is only supported by the minimum SDK version 20.4.0.
@@ -656,22 +701,27 @@ Countly.recordView("Profile Page");
Here is how you can utilize Performance Monitoring feature in your apps:
First, you need to enable Performance Monitoring feature::
-Countly.enableApm(); // Enable APM features.
+Countly.enableApm(); // Enable APM features.
With this, Countly SDK will start measuring some performance traces automatically.
Those include app foreground time, app background time. Additionally, custom
traces and network traces can be manually recorded.
-Custom trace
+Custom trace
- You may also measure any operation you want and record it using custom traces. First, you need to start a trace by using the startTrace(traceKey) method:
+ You may also measure any operation you want and record it using custom traces. First, you need to start a trace by using the startTrace(traceKey) method:
-Countly.startTrace(traceKey);
+Countly.startTrace(traceKey);
Then you may end it using the
- endTrace(traceKey, customMetric)method, optionally passing any metrics as key-value pairs:
+ endTrace(traceKey, customMetric)method, optionally passing any metrics as key-value pairs:
-String traceKey = "Trace Key";
Map<String, int> customMetric = {
"ABC": 1233,
"C44C": 1337
};
Countly.endTrace(traceKey, customMetric);
+String traceKey = "Trace Key";
+Map<String, int> customMetric = {
+ "ABC": 1233,
+ "C44C": 1337
+};
+Countly.endTrace(traceKey, customMetric);
The duration of the custom trace will be automatically calculated on ending. Trace
names should be non-zero length valid strings. Trying to start a custom
@@ -679,17 +729,17 @@ Countly.recordView("Profile Page");
custom trace with already ended (or not yet started) name will have no effect.
- You may also cancel any custom trace you started, using cancelTrace(traceKey)method:
+ You may also cancel any custom trace you started, using cancelTrace(traceKey)method:
-Countly.cancelTrace(traceKey);
+Countly.cancelTrace(traceKey);
Additionally, if you need you may cancel all custom traces you started, using
- clearAllTraces()method:
+ clearAllTraces()method:
-Countly.clearAllTraces(traceKey);
-Network trace
+Countly.clearAllTraces(traceKey);
+Network trace
- You may record manual network traces using therecordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime) method.
+ You may record manual network traces using therecordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime) method.
A network trace is a collection of measured information about a network request.
@@ -708,8 +758,8 @@ Countly.recordView("Profile Page");
- endTime: UNIX time stamp in milliseconds for the ending time of
the request
-Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
-Getting user feedback
+Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
+Getting user feedback
There are two ways of getting feedback from your users: Star rating dialog, feedback
widget.
@@ -718,12 +768,12 @@ Countly.recordView("Profile Page");
Star rating dialog allows users to give feedback as a rating from 1 to 5. The
feedback widget allows to get the same 1 to 5 rating and also a text comment.
-Feedback widget
+Feedback widget
- Feedback widget shows a server configured widget to your user devices.
+ Feedback widget shows a server configured widget to your user devices.
- 
+ 
It's possible to configure any of the shown text fields and replace with a custom
@@ -744,13 +794,14 @@ Countly.recordView("Profile Page");
you first have to get the widget ID from your server:
- 
+ 
-
- Using that you can call the function to show the widget popup:
+
+ Using that you can call the function to show the widget popup:
-// Feedback Modal
countly.askForFeedback("5e425407975d006a22535fc", "close");
-Star rating dialog
+// Feedback Modal
+countly.askForFeedback("5e425407975d006a22535fc", "close");
+Star rating dialog
Star rating integration provides a dialog for getting user's feedback about the
application. It contains a title, simple message explaining what it is for, a
@@ -765,16 +816,17 @@ Countly.recordView("Profile Page");
Star-rating dialog's title, message and dismiss button text can be customized
- either through the init function or the SetStarRatingDialogTexts function.
+ either through the init function or the SetStarRatingDialogTexts function.
If you don't want to override one of those values, set it to "null".
-// Star Rating
countly.askForStarRating(Function(ratingResult){
console.log(ratingResult);
});
+// Star Rating
+countly.askForStarRating(Function(ratingResult){
+ console.log(ratingResult);
+});
-
-
-
+
-Push notifications
+Push notifications
Countly uses PhoneGap push notifications plugin.
Here is the link
@@ -783,73 +835,84 @@ Countly.recordView("Profile Page");
Here are the steps to make push notifications work:
- -
+
-
Go to https://firebase.google.com
- -
+
-
Register / Login to the Firebase console. You should be logged in to
https://console.firebase.google.com.
- - Create and select a project if you haven't done before.
- - Go to Settings > Project settings.
- - Create an app for Android and iOS.
- -
+
- Create and select a project if you haven't done before.
+ - Go to Settings > Project settings.
+ - Create an app for Android and iOS.
+ -
Download the
google-services.json for Android and
GoogleService-Info.plist for iOS.
- -
+
-
Place both files under your root project folder. i.e. above www folder.
- -
- Put these tags in config.xml file for Android and iOS:
+
-
+
Put these tags in config.xml file for Android and iOS:
- <platform name="android">
+ <platform name="android">
<resource-file src="google-services.json" target="app/google-services.json" />
</platform>
- <platform name="ios">
+ <platform name="ios">
<resource-file src="GoogleService-Info.plist" />
</platform>
- -
- Install the push notifications plugin.
-
cordova plugin add phonegap-plugin-push
+ -
+
Install the push notifications plugin.
+ cordova plugin add phonegap-plugin-push
- - Build your app, and test push notifications.
+ - Build your app, and test push notifications.
- Limitations of Cordova
+ Limitations of Cordova
Due to limitations of the way push is handled in a Cordova application, it's
not possible to report back actions done when a push notification is received.
-Push Method Implementation
+Push Method Implementation
- First, when setting up push for the Cordova SDK, you would first select the push token mode. This would allow you to choose either test or production modes, push
+ First, when setting up push for the Cordova SDK, you would first select the push
+ token mode. This would allow you to choose either test or production modes, push
token mode should be set before init.
-// Important call this method before init method
Countly.pushTokenType(Countly.messagingMode.DEVELOPMENT, "Channel Name", "Channel Description");
// Countly.messagingMode.DEVELOPMENT
// Countly.messagingMode.PRODUCTION
// Countly.messagingMode.ADHOC
+// Important call this method before init method
+Countly.pushTokenType(Countly.messagingMode.DEVELOPMENT, "Channel Name", "Channel Description");
+// Countly.messagingMode.DEVELOPMENT
+// Countly.messagingMode.PRODUCTION
+// Countly.messagingMode.ADHOC
- When you are finally ready to initialize Countly push, you would call Countly.askForNotificationPermission(), this function should be call after init.
+ When you are finally ready to initialize Countly push, you would call Countly.askForNotificationPermission(),
+ this function should be call after init.
-// Call this method any time.
Countly.askForNotificationPermission();
// This method will ask for permission,
// and send push token to countly server.
+// Call this method any time.
+Countly.askForNotificationPermission();
+// This method will ask for permission,
+// and send push token to countly server.
Cordova code to receive notification data. Call anywhere or event before init.
-Countly.registerForNotification(function(theNotification){
console.log(JSON.stringify(theNotification));
});
-Rich Push Notification
+Countly.registerForNotification(function(theNotification){
+console.log(JSON.stringify(theNotification));
+});
+Rich Push Notification
For Android, there is no special procedure required, you can install the community
plugin, and it should work.
@@ -858,14 +921,16 @@ Countly.recordView("Profile Page");
For iOS, you will need to follow these instruction:
https://resources.count.ly/docs/countly-sdk-for-ios-and-os-x#section-rich-push-notifications-ios10-only-
-Removing Plugin
-cordova plugin remove countly-sdk-js
cordova platform remove android
cordova platform remove ios
-Troubleshooting
+Removing Plugin
+cordova plugin remove countly-sdk-js
+cordova platform remove android
+cordova platform remove ios
+Troubleshooting
If you get the following error during implementation (for versions before v1.0
SDK):
-NSPersistentStoreCoordinator with a nil model
+NSPersistentStoreCoordinator with a nil model
In this case, go to
https://github.com/Countly/countly-sdk-cordova/tree/master/src/ios/sdk.
@@ -874,7 +939,7 @@ Countly.recordView("Profile Page");
- Warning about Java
+ Warning about Java
Note: As per the new release v1.0 you will need Java 1.8 to bundle the application.
@@ -885,7 +950,7 @@ Countly.recordView("Profile Page");
If you would like to set logging, use code snippet below in your code.
-// example for setLoggingEnabled
+// example for setLoggingEnabled
//Countly.setLoggingEnabled();
@@ -900,13 +965,13 @@ Countly.recordView("Profile Page");
The optional parameters are:
- - Country code: ISO Country code for the user's country
- - City: Name of the user's city
- -
+
- Country code: ISO Country code for the user's country
+ - City: Name of the user's city
+ -
Location: Comma separate latitude and longitude values, for example "56.42345,123.45325"
-
+
//setting optional parameters
Countly.setOptionalParametersForInitialization({
city: "Tampa",
diff --git a/legacy_docs/cordova/20.11.md b/legacy_docs/cordova/20.11.md
index f8cac047..bb8c1d59 100644
--- a/legacy_docs/cordova/20.11.md
+++ b/legacy_docs/cordova/20.11.md
@@ -21,15 +21,15 @@
Github repo.
It should show how most of the functionalities can be used.
-Adding the SDK to the project
+Adding the SDK to the project
The core of this SDK is developed around Cordova. We have a minimum version requirement
for it's core and android, ios modules that have to be satisfied:
- - cordova >= 9.0.0
- - cordova-android >= 8.0.0
- - cordova-ios >= 5.0.0
+ - cordova >= 9.0.0
+ - cordova-android >= 8.0.0
+ - cordova-ios >= 5.0.0
If you would integrate this SDK in any other project similar to cordova (like
@@ -37,9 +37,8 @@
platform requirements for those projects similar to these.
- Note : Development on PhoneGap stopped in
- 14 Aug 2020. To the best of our knowledge, this SDK should still
- be compatible with the final release.
+ Note : Development on PhoneGap stopped in 14 Aug 2020. To the
+ best of our knowledge, this SDK should still be compatible with the final release.
For more information about PhoneGap shut down,
@@ -57,88 +56,86 @@
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
# OR
cordova plugin add countly-sdk-js@20.11.0
-
If iOS/Android Platform are already added in your project, first remove them
-cordova platform remove android
+cordova platform remove android
cordova platform remove ios
Now add platform of your choice
-cordova platform add android
+cordova platform add android
cordova platform add ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-cordova build android
+cordova build android
ordova build ios
Now run the application directly for Android,
-cordova run android
+cordova run android
Or iOS:
-cordova run ios
+cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
- Ionic
+ Ionic
Add Countly SDK in your Ionic project using following commands:
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
ionic cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
# OR
ionic cordova plugin add countly-sdk-js@20.11.0
-
If iOS/Android Platform are already added in your project, first remove them
-ionic cordova platform remove android
+ionic cordova platform remove android
ionic cordova platform remove ios
Now add platform of your choice
-ionic cordova platform add android
+ionic cordova platform add android
ionic cordova platform add ios
Now prepare the platforms you have added
-ionic cordova prepare android
+ionic cordova prepare android
ionic cordova prepare ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-ionic cordova build android
+ionic cordova build android
ionic cordova build ios
Now run the application directly for Android,
-ionic cordova run android
+ionic cordova run android
Or iOS:
-ionic cordova run ios
+ionic cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
In your index.html, use the following lines:
-<script type="text/javascript" src="cordova.js"></script>
+<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript" src="Countly.js"></script>
-SDK Integration
-Minimal setup
+SDK Integration
+Minimal setup
Below you can find necessary code snippets to initialize the SDK for sending
data to Countly servers. Where possible, use your server URL instead of
try.count.ly in case you have your own server.
-// initialize
+// initialize
Countly.isInitialized().then((result) => {
if(result != "true") {
Countly.init("https://try.count.ly", "YOUR_API_KEY").then((result) => {
@@ -150,13 +147,12 @@ Countly.isInitialized().then((result) => {
},(err) => {
console.error(err);
});
-
For more information on how to acquire your application key (appKey) and server
URL, check
here.
-Enable logging
+Enable logging
If logging is enabled then our sdk will print out debug messages about it's internal
state and encountered problems.
@@ -164,9 +160,9 @@ Countly.isInitialized().then((result) => {
When advise doing this while implementing countly features in your application.
-// example for setLoggingEnabled
+// example for setLoggingEnabled
Countly.setLoggingEnabled();
-Device ID
+Device ID
When the SDK is initialized for the first time and no device ID is provided,
a device ID will be generated by SDK.
@@ -178,21 +174,21 @@ Countly.setLoggingEnabled();
You may provide your own custom device ID when initializing the SDK
-Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
-SDK data storage
+Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
+SDK data storage
For iOS: SDK data is stored in Application Support Directory in file named "Countly.dat"
For Android: SDK data is stored in SharedPreferences. A SharedPreferences object
points to a file containing key-value pairs and provides simple methods to read
and write them.
-Crash reporting
+Crash reporting
The Countly SDK has the ability to collect
crash reports,
which you may examine and resolve later on the server.
-Automatic crash handling
+Automatic crash handling
With this feature, the Countly SDK will generate a crash report if your application
crashes due to an exception and send it to the Countly server for further inspection.
@@ -206,16 +202,17 @@ Countly.setLoggingEnabled();
You will need to call the following method before calling init in
order to activate automatic crash reporting.
-
-
-
-
-// Using countly crash reports
+
+
+// Using countly crash reports
Countly.enableCrashReporting();
-Handled exceptions
+Handled exceptions
You might catch an exception or similar error during your app’s runtime.
@@ -226,7 +223,7 @@ Countly.enableCrashReporting();
You can also send a custom crash log to Countly using code below.
-// Send Exception to the server
+// Send Exception to the server
Countly.logException(["My Customized error message"], true, {"_facebook_version": "0.0.1"});
Countly.logException(stackFramesFromStackTraceJS, booleanNonFatal, segments);
@@ -242,7 +239,7 @@ Countly.logException(stackFramesFromStackTraceJS, booleanNonFatal, segments);
1. Manually report handled exception
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -256,11 +253,10 @@ Countly.logException("ERROR_STRING", true);
// With array of strings
Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], true);
-
2. Manually report handled exception with segmentation
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -274,11 +270,10 @@ Countly.logException("ERROR_STRING", true, {"\_facebook_version": "0.0.1"});
// With array of strings
Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], true, {"\_facebook_version": "0.0.1"});
-
3. Manually report fatal exception
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -292,11 +287,10 @@ Countly.logException("ERROR_STRING", false);
// With array of strings
Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], false);
-
4. Manually report fatal exception with segmentation
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -310,18 +304,17 @@ Countly.logException("ERROR_STRING", false, {"\_facebook_version": "0.0.1"});
// With array of strings
Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], false, {"\_facebook_version": "0.0.1"});
-
-Crash breadcrumbs
+Crash breadcrumbs
Throughout your app you can leave crash breadcrumbs which would describe previous
steps that were taken in your app before the crash. After a crash happens, they
will be sent together with the crash report.
Following the command adds crash breadcrumb:
-// Add crash breadcrumb
+// Add crash breadcrumb
Countly.addCrashLog("My crash log from JavaScript");
-Events
+Events
An Event is any type
of action that you can send to a Countly instance, e.g purchase, settings changed,
@@ -332,21 +325,21 @@ Countly.addCrashLog("My crash log from JavaScript");
Here are the detail about properties which we can use with event:
- -
+
-
key identifies the event
- -
+
-
count is the number of times this event occurred
- -
+
-
sum is an overall numerical data set tied to an event. For example,
total amount of in-app purchase event.
- -
+
-
duration is used to record and track the
duration of events.
- -
+
-
segmentation is a key-value pairs, we can use
segmentation to track additional information. The only valid
data types are: "String", "Integer", "Double" and "Boolean". All other types
@@ -355,35 +348,35 @@ Countly.addCrashLog("My crash log from JavaScript");
- Data passed should be in UTF-8
+ Data passed should be in UTF-8
All data passed to Countly server via SDK or API should be in UTF-8.
-Recording events
+Recording events
We will be recording a purchase event. Here is a quick summary
of what information each usage will provide us:
- -
+
-
Usage 1: how many times purchase event occurred.
- -
+
-
Usage 2: how many times purchase event occurred + the total
amount of those purchases.
- -
+
-
Usage 3: how many times purchase event occurred + which
countries and application versions those purchases were made from.
- -
+
-
Usage 4: how many times purchase event occurred + the total
amount both of which are also available segmented into countries and application
versions.
- -
+
-
Usage 5: how many times purchase event occurred + the total
amount both of which are also available segmented into countries and application
versions + the total duration of those events.
@@ -392,33 +385,33 @@ Countly.addCrashLog("My crash log from JavaScript");
1. Event key and count
-// example for sending basic event
+// example for sending basic event
var events = {"key":"Basic Event","count":1};
Countly.recordEvent(events);
2. Event key, count and sum
-// example for event with sum
+// example for event with sum
var events = {"key":"Event With Sum","count":1,"sum":"0.99"};
Countly.recordEvent(events);
3. Event key and count with segmentation(s)
-// example for event with segment
+// example for event with segment
var events = {"key":"Event With Segment","count":1};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
4. Event key, count and sum with segmentation(s)
-// example for event with segment and sum
+// example for event with segment and sum
var events = {"key":"Event With Segment And Sum","count":1,"sum":"0.99"};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
5. Event key, count, sum and duration with segmentation(s)
-var events = {
+var events = {
"key": "Event With Sum And Segment duration",
"count": 1,
"Sum": "0.99",
@@ -434,11 +427,11 @@ Countly.recordEvent(events);
those examples and use country, app_version, game_level, time_of_day and any
other segmentation that will provide you valuable insights.
-Timed events
+Timed events
It's possible to create timed events by defining a start and stop moment.
-// Time Event
+// Time Event
Countly.startEvent("Timed Event");
setTimeout(function() {
Countly.endEvent({ "key": "Timed Event");
@@ -449,13 +442,12 @@ Countly.startEvent("Timed Event With Sum");
setTimeout(function() {
countly.endEvent({"key": "Timed Event With Sum", "sum": "0.99"});
}, 1000);
-
When ending an event you can also provide additional information. But in that
case, you have to provide segmentation, count and sum. The default values for
those are "null", 1 and 0.
-
+
// Time Event with segment
Countly.startEvent("Timed Event With Segment");
setTimeout(function() {
@@ -483,29 +475,28 @@ events.segments = {
};
Countly.endEvent(events);
}, 1000);
-
-Sessions
-Automatic session tracking
+Sessions
+Automatic session tracking
To start recording an automatic session tracking you would call:
-Countly.start();
+Countly.start();
Countly.start(); will handle the start session,
update session and end session automatically.
This is how it works:
- -
+
-
Start/Begin session Request: It is sent on
Countly.start(); call and when the app comes
back to the foreground from the background, and it includes basic metrics.
- -
+
-
Update Session Request: It automatically sends a periodical
(60 sec by default) update session request while the app is in the foreground.
- -
+
-
End Session Request: It is sent at the end of a session
when the app goes to the background or terminates.
@@ -513,15 +504,15 @@ Countly.endEvent(events);
If you want to end automatic session tracking you would call:
-
Countly.stop();
-View tracking
+Countly.stop();
+View tracking
You may track custom views with the following code snippet:
-Countly.recordView("View Name")
+Countly.recordView("View Name")
While manually tracking views, you may add your custom segmentation to them like
this:
-var viewSegmentation = { "Country": "Germany", "Age": "28" };
+var viewSegmentation = { "Country": "Germany", "Age": "28" };
Countly.recordView("View Name", viewSegmentation);
To review the resulting data, open the dashboard and go to
@@ -532,7 +523,7 @@ Countly.recordView("View Name", viewSegmentation);
-Device ID management
+Device ID management
A device ID is a unique identifier for your users. You may specify the device
ID yourself or allow the SDK to generate it. When providing one yourself, keep
@@ -540,7 +531,7 @@ Countly.recordView("View Name", viewSegmentation);
an id could be the username, email or some other internal ID used by your other
systems.
-Device ID generation
+Device ID generation
When the SDK is initialized for the first time with no device ID, then SDK will
generate a device ID.
@@ -552,9 +543,9 @@ Countly.recordView("View Name", viewSegmentation);
For iOS: the device ID generated by SDK is the Identifier For Vendor (IDFV)
For Android: the device ID generated by SDK is the OpenUDID
-Changing the Device ID
+Changing the Device ID
You may configure/change the device ID anytime using:
-Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
+Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
You may either allow the device to be counted as a new device or merge existing
data on the server. If theonServer bool is set to
@@ -563,7 +554,7 @@ Countly.recordView("View Name", viewSegmentation);
Otherwise, if onServer bool is set to false, the device
will be counted as a new device on the server.
-Temporary Device ID
+Temporary Device ID
You may use a temporary device ID mode for keeping all requests on hold until
the real device ID is set later.
@@ -571,9 +562,9 @@ Countly.recordView("View Name", viewSegmentation);
You can enable temporary device ID when initializing the SDK:
-Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
+Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
To enable a temporary device ID after init, you would call:
-Countly.changeDeviceId("TemporaryDeviceID", ON_SERVER);
+Countly.changeDeviceId("TemporaryDeviceID", ON_SERVER);
Note: When passing TemporaryDeviceID for
deviceID parameter, argument for onServerparameter
@@ -594,75 +585,79 @@ Countly.recordView("View Name", viewSegmentation);
which have been kept on hold until that point will start with the real device
ID
-Retrieving current device ID
+Retrieving current device ID
You may want to see what device id Countly is assigning for the specific device.
For that you may use the following call:
-// get device id
+// get device id
Countly.getCurrentDeviceId(function(deviceId){
console.log(deviceId);
}, function(getDeviceIDError){
console.log(getDeviceIDError);
});
-Push notifications
-Integration
-Android setup
+Push notifications
+Integration
+Android setup
Here are the steps to make push notifications work on Android:
- -
+
-
For FCM credentials setup please follow the instruction from this URL
https://support.count.ly/hc/en-us/articles/360037754031-Android#getting-fcm-credentials.
- -
+
-
Make sure you have
google-services.json from
https://firebase.google.com/
- -
+
-
Make sure the app package name and the
google-services.json
package_name matches.
- -
+
-
Place this
google-services.json file under
your root project folder. i.e. above www folder.
- -
- Put these tags in config.xml file for Android:
+
-
+
Put these tags in config.xml file for Android:
- <platform name="android">
+ <platform name="android">
<resource-file src="google-services.json" target="app/google-services.json" />
</platform>
- -
- Put these tags in config.xml file if you are using cordova-android 9.x or
- greater:
+
-
+
+ Put these tags in config.xml file if you are using cordova-android 9.x
+ or greater:
+
- <preference name="GradlePluginGoogleServicesEnabled" value="true" />
+ <preference name="GradlePluginGoogleServicesEnabled" value="true" />
<preference name="GradlePluginGoogleServicesVersion" value="4.2.0" />
- -
- Install the google services plugin if you use cordova-android below version
- 9
-
cordova plugin add cordova-support-google-services --save
+ -
+
+ Install the google services plugin if you use cordova-android below version
+ 9
+
+ cordova plugin add cordova-support-google-services --save
- - Build your app, and test push notifications.
+ - Build your app, and test push notifications.
-iOS setup
+iOS setup
- By default push notification is enabled for iOS, to disable you need to add the COUNTLY_EXCLUDE_PUSHNOTIFICATIONS=1 flag to the Build Settings > Preprocessor Macros section in Xcode.
+ By default push notification is enabled for iOS, to disable you need to add the COUNTLY_EXCLUDE_PUSHNOTIFICATIONS=1 flag to the Build Settings > Preprocessor Macros section in Xcode.
- Minimum Countly SDK Version
+ Minimum Countly SDK Version
This COUNTLY_EXCLUDE_PUSHNOTIFICATIONS is only supported by the minimum SDK
@@ -673,25 +668,25 @@ Countly.getCurrentDeviceId(function(deviceId){
There are no additional steps required for iOS,everything is set up for you by
the Countly Cordova SDK.
-Enabling push
+Enabling push
First, when setting up push for the Cordova SDK, you would first select the push
token mode. This would allow you to choose either test or production modes, push
token mode should be set before init.
-// Set messaging mode for push notifications
+// Set messaging mode for push notifications
Countly.pushTokenType(Countly.messagingMode.DEVELOPMENT, "Channel Name", "Channel Description");
When you are finally ready to initialise Countly push, you would call this:
-// This method will ask for permission, enables push notification and send push token to countly server.
+// This method will ask for permission, enables push notification and send push token to countly server.
Countly.askForNotificationPermission();
-Handling push callbacks
+Handling push callbacks
To register a Push Notification callback after initializing the SDK, use the
method below.
-Countly.registerForNotification(function(theNotification){
+Countly.registerForNotification(function(theNotification){
console.log(JSON.stringify(theNotification));
});
@@ -699,12 +694,13 @@ Countly.askForNotificationPermission();
code in AppDelegate.m
Add header files
-#import "CountlyNative.h"
#import <UserNotifications/UserNotifications.h>
+#import "CountlyNative.h"
+#import <UserNotifications/UserNotifications.h>
Before @end add these methods
-// Required for the notification event. You must call the completion handler after handling the remote notification.
+// Required for the notification event. You must call the completion handler after handling the remote notification.
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
[CountlyNative onNotification: userInfo];
@@ -725,7 +721,7 @@ Countly.askForNotificationPermission();
[CountlyNative onNotification: notification.request.content.userInfo];
completionHandler(0);
}
-User location
+User location
While integrating this SDK into your application, you might want to track your
user location. You could use this information to better know your apps user base
@@ -733,14 +729,14 @@ completionHandler(0);
are 4 fields that can be provided:
- - country code in the 2 letter iso standard
- - city name (has to be set together with country code)
- -
+
- country code in the 2 letter iso standard
+ - city name (has to be set together with country code)
+ -
Comma separate latitude and longitude values, for example "56.42345,123.45325"
- - ip address of your user
+ - ip address of your user
-// send user location
+// send user location
Countly.setLocation("28.006324", "-82.7166183");
When those values are set, they will be sent every time when initiating a session.
@@ -755,13 +751,13 @@ Countly.setLocation("28.006324", "-82.7166183");
It will erase cached location data from the device and the server.
-Remote Config
+Remote Config
Remote config allows you to modiffy how your app functions or looks by requesting
key-value pairs from your Countly server. The returned values can be modiffied
based on the user profile. For more details please see Remote Config documentation.
-Automatic remote config
+Automatic remote config
There are two ways of acquiring remote config data, by automatic download or
manual request. By default, automatic remote config is disabled and therefore
@@ -777,7 +773,7 @@ Countly.setLocation("28.006324", "-82.7166183");
Note: call setRemoteConfigAutomaticDownload method
before init
-// Call this method before init
+// Call this method before init
Countly.setRemoteConfigAutomaticDownload(function(r){
alert(r)
}, function(r){
@@ -794,14 +790,14 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
instead). It is possible that a previously valid key returns no value after an
update.
-Manual remote config
+Manual remote config
There are three ways for manually requesting a Remote Config update:
- - Manually updating everything
- - Manually updating specific keys
- - Manually updating everything except specific keys
+ - Manually updating everything
+ - Manually updating specific keys
+ - Manually updating everything except specific keys
Each of these requests also has a callback. If that returns a non-null value,
@@ -814,7 +810,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
The advantage is that you can make the request whenever it is desirable for you.
It has a callback to let you know when it has finished.
-Countly.remoteConfigUpdate(function(r){
+Countly.remoteConfigUpdate(function(r){
alert(r)
}, function(r){
alert(r);
@@ -825,7 +821,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
updated. That list is an array with string values of those keys. It has a callback
to let you know when the request has finished.
-Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
+Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -835,7 +831,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
updateRemoteConfigExceptKeys. The key list is a array with string values of the
keys. It has a callback to let you know when the request has finished.
-Countly.updateRemoteConfigExceptKeys(["url"], function(r){
+Countly.updateRemoteConfigExceptKeys(["url"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -846,7 +842,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
will update all values. This means that it will also erase all keys not returned
by the server.
-Getting Remote Config values
+Getting Remote Config values
To request a stored value, call getRemoteConfigValueForKey with
the specified key. If it returns null then no value was found. The SDK has no
@@ -854,22 +850,22 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
needs to cast it to the appropriate type. The returned values can also be a JSONArray,
JSONObject or just a simple value like int.
-Countly.getRemoteConfigValueForKey("name", function(r){
+Countly.getRemoteConfigValueForKey("name", function(r){
alert(r)
}, function(r){
alert(r);
});
-Clearing stored values
+Clearing stored values
At some point you might want to erase all values downloaded from the server.
To achieve that you need to call one function, depicted below:
-Countly.remoteConfigClearValues(function(r){
+Countly.remoteConfigClearValues(function(r){
alert(r)
}, function(r){
alert(r);
});
-User feedback
+User feedback
There are two ways of getting feedback from your users: Star rating dialog, feedback
widget.
@@ -878,7 +874,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
Star rating dialog allows users to give feedback as a rating from 1 to 5. The
feedback widget allows to get the same 1 to 5 rating and also a text comment.
-Star rating dialog
+Star rating dialog
Star rating integration provides a dialog for getting user's feedback about the
application. It contains a title, simple message explaining what it is for, a
@@ -896,17 +892,17 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
either through the init function or the SetStarRatingDialogTexts
function. If you don't want to override one of those values, set it to "null".
-// Star Rating
+// Star Rating
countly.askForStarRating(Function(ratingResult){
console.log(ratingResult);
});
-Rating widget
+Rating widget
Feedback widget shows a server configured widget to your user devices.
-
+
It's possible to configure any of the shown text fields and replace with a custom
@@ -927,14 +923,14 @@ countly.askForStarRating(Function(ratingResult){
you first have to get the widget ID from your server:
-
+
Using that you can call the function to show the widget popup:
-// Feedback Modal
+// Feedback Modal
countly.askForFeedback("5e425407975d006a22535fc", "close");
-User Profiles
+User Profiles
Available with Enterprise Edition, User Profiles is a tool which helps you identify
users, their devices, event timeline and application crash information. User
@@ -953,7 +949,7 @@ countly.askForFeedback("5e425407975d006a22535fc", "close");
After you have provided user profile information, you must save it by calling
Countly.userData.save().
-/ example for setting user data
+/ example for setting user data
var options = {};
options.name = "Nicola Tesla";
options.username = "nicola";
@@ -966,55 +962,59 @@ options.gender = "Male";
options.byear = 1919;
Countly.setUserData(options);
The keys for predefined user data fields are as follows:
-
-
-
- Key
- Type
- Description
-
-
- name
- String
- User's full name
-
-
- username
- String
- User's nickname
-
-
- email
- String
- User's email address
-
-
- organization
- String
- User's organisation name
-
-
- phone
- String
- User's phone number
-
-
- picture
- String
- URL to avatar or profile picture of the user
-
-
- gender
- String
- User's gender as M for male and F for female
-
-
- byear
- String
- User's year of birth as integer
-
-
-
+
+
+
+
+ Key
+ Type
+ Description
+
+
+
+
+ name
+ String
+ User's full name
+
+
+ username
+ String
+ User's nickname
+
+
+ email
+ String
+ User's email address
+
+
+ organization
+ String
+ User's organisation name
+
+
+ phone
+ String
+ User's phone number
+
+
+ picture
+ String
+ URL to avatar or profile picture of the user
+
+
+ gender
+ String
+ User's gender as M for male and F for female
+
+
+ byear
+ String
+ User's year of birth as integer
+
+
+
+
Using "" for strings or a negative number for 'byear' will effectively delete
that property.
@@ -1024,13 +1024,13 @@ Countly.setUserData(options);
on your Countly backend. Note: keys with . or $ symbols will have those symbols
removed.
-Setting custom values
+Setting custom values
Additionally you can do different manipulations on your custom data values, like
increment current value on server or store a array of values under the same property.
Below is the list of available methods:
-// example for extra user features
+// example for extra user features
Countly.userData.setProperty("setProperty", "My Property");
Countly.userData.increment("increment");
@@ -1042,14 +1042,13 @@ Countly.userData.setOnce("setOnce", 200);
Countly.userData.pushUniqueValue("pushUniqueValue","morning");
Countly.userData.pushValue("pushValue", "morning");
Countly.userData.pullValue("pullValue", "morning");
-
In the end always call Countly.userData.save() to send them to the server.
-Application Performance Monitoring
+Application Performance Monitoring
- Minimum Countly SDK Version
+ Minimum Countly SDK Version
This feature is only supported by the minimum SDK version 20.4.0.
@@ -1064,20 +1063,20 @@ Countly.userData.pullValue("pullValue", "morning");
Here is how you can utilize Performance Monitoring feature in your apps:
First, you need to enable Performance Monitoring feature::
-Countly.enableApm();
+Countly.enableApm();
// Enable APM features.
With this, Countly SDK will start measuring some performance traces automatically.
Those include app foreground time, app background time. Additionally, custom
traces and network traces can be manually recorded.
-App Start Time
+App Start Time
For the app start time to be recorded, you need to call the
appLoadingFinished method. Make sure this method is called after
init.
-// Example of appLoadingFinished
+// Example of appLoadingFinished
Countly.init("https://try.count.ly", "YOUR_API_KEY").then((result) => {
Countly.appLoadingFinished();
},(err) => {
@@ -1092,19 +1091,19 @@ Countly.init("https://try.count.ly", "YOUR_API_KEY").then((result) => {
the app launch time can be recorded only once per app launch. So, the second
and following calls to this method will be ignored.
-Custom traces
+Custom traces
You may also measure any operation you want and record it using custom traces.
First, you need to start a trace by using the
startTrace(traceKey) method:
-Countly.startTrace(traceKey);
+Countly.startTrace(traceKey);
Then you may end it using the
endTrace(traceKey, customMetric)method, optionally
passing any metrics as key-value pairs:
-String traceKey = "Trace Key"
+String traceKey = "Trace Key"
;
Map<String, int> customMetric = {
"ABC": 1233,
@@ -1121,13 +1120,13 @@ Countly.endTrace(traceKey, customMetric);
You may also cancel any custom trace you started, using
cancelTrace(traceKey)method:
-Countly.cancelTrace(traceKey);
+Countly.cancelTrace(traceKey);
Additionally, if you need you may cancel all custom traces you started, using
clearAllTraces()method:
-Countly.clearAllTraces(traceKey);
-Network traces
+Countly.clearAllTraces(traceKey);
+Network traces
You may record manual network traces using theecordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime)
method.
@@ -1147,9 +1146,9 @@ Countly.endTrace(traceKey, customMetric);
time of the request - endTime: UNIX time stamp in milliseconds for
the ending time of the request
-Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
+Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
-User Consent
+User Consent
To be compliant with GDPR, starting from 18.04, Countly provides ways to toggle
different Countly features on/off depending on the given consent.
@@ -1159,7 +1158,7 @@ Countly.endTrace(traceKey, customMetric);
By default the requirement for consent is disabled. To enable it, you have to
call setRequiresConsent with true, before initializing Countly.
-Countly.setRequiresConsent(true);
+Countly.setRequiresConsent(true);
By default no consent is given. That means that if no consent is enabled, Countly
will not work and no network requests, related to features, will be sent. When
@@ -1186,78 +1185,75 @@ Countly.endTrace(traceKey, customMetric);
The current features are:
- -
+
-
sessions - tracking when, how often and how long users use your app
- - events - allow sending events to server
- - views - allow tracking which views user visits
- - location - allow sending location information
- - crashes - allow tracking crashes, exceptions and errors
- -
+
- events - allow sending events to server
+ - views - allow tracking which views user visits
+ - location - allow sending location information
+ - 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
- - starRating - allow to send their rating and feedback
- - apm - allow application performance monitoring
- -
+
- push - allow push notifications
+ - starRating - allow to send their rating and feedback
+ - apm - allow application performance monitoring
+ -
remote-config - allows downloading remote config values from your server
-Changing consent
+Changing consent
There are 3 ways of changing feature consent:
- -
+
-
giveConsentInit - To add consent for a single feature (string parameter)
or a subset of features (array of strings parameter). Use this method for
giving consent before initializing.
-//giveConsent
+//giveConsent
Countly.giveConsentInit(["events", "views", "star-rating", "crashes"]);
// removeConsent
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);
-
- -
+
-
giveConsent/removeConsent - gives or removes consent to a specific feature
-//giveConsent
+//giveConsent
Countly.giveConsent(["events", "views", "star-rating", "crashes"]);
// removeConsent
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);
-
- -
+
-
giveAllConsent/removeAllConsent - giveAll or removeAll consent to a specific
feature
-//giveAllConsent
+//giveAllConsent
Countly.giveAllConsent();
//removeAllConsent
Countly.removeAllConsent();
-
-Security and privacy
-Parameter Tampering Protection
+Security and privacy
+Parameter Tampering Protection
You can set optional salt to be used for calculating checksum of request data,
which will be sent with each request using &checksum field. You need to set
exactly the same salt on Countly server. If salt on Countly server is set, all
requests would be checked for validity of &checksum field before being processed.
-// sending data with salt
+// sending data with salt
Countly.enableParameterTamperingProtection("salt");
-Other features
-Forcing HTTP POST
+Other features
+Forcing HTTP POST
If the data sent to the server is short enough, the sdk will use HTTP GET requests.
In case you want an override so that HTTP POST is used in all cases, call the
@@ -1265,9 +1261,9 @@ Countly.enableParameterTamperingProtection("salt");
to later in the apps life cycle disable the override. This function has to be
called every time the app starts.
-Countly.setHttpPostForced(true); // default is false
+Countly.setHttpPostForced(true); // default is false
-Optional parameters during initialization
+Optional parameters during initialization
You can provide optional parameters that will be used during begin_session request.
They must be set right after the init function so that they are
@@ -1279,13 +1275,13 @@ Countly.enableParameterTamperingProtection("salt");
The optional parameters are:
- - Country code: ISO Country code for the user's country
- - City: Name of the user's city
- -
+
- Country code: ISO Country code for the user's country
+ - City: Name of the user's city
+ -
Location: Comma separate latitude and longitude values, for example "56.42345,123.45325"
-
+
//setting optional parameters
Countly.setOptionalParametersForInitialization({
city: "Tampa",
diff --git a/legacy_docs/cordova/21.11.md b/legacy_docs/cordova/21.11.md
index 8d29d6b5..492938ef 100644
--- a/legacy_docs/cordova/21.11.md
+++ b/legacy_docs/cordova/21.11.md
@@ -19,15 +19,15 @@
Github repo.
It should show how most of the functionalities can be used.
-Adding the SDK to the project
+Adding the SDK to the project
The core of this SDK is developed around Cordova. We have a minimum version requirement
for it's core and android, ios modules that have to be satisfied:
- - cordova >= 9.0.0
- - cordova-android >= 8.0.0
- - cordova-ios >= 5.0.0
+ - cordova >= 9.0.0
+ - cordova-android >= 8.0.0
+ - cordova-ios >= 5.0.0
If you would integrate this SDK in any other project similar to cordova (like
@@ -35,9 +35,8 @@
platform requirements for those projects similar to these.
- Note : Development on PhoneGap stopped in
- 14 Aug 2020. To the best of our knowledge, this SDK should still
- be compatible with the final release.
+ Note : Development on PhoneGap stopped in 14 Aug 2020. To the
+ best of our knowledge, this SDK should still be compatible with the final release.
For more information about PhoneGap shut down,
@@ -55,7 +54,7 @@
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
@@ -65,34 +64,34 @@ cordova plugin add countly-sdk-js@20.11.0
If iOS/Android Platform are already added in your project, first remove them
-cordova platform remove android
+cordova platform remove android
cordova platform remove ios
Now add platform of your choice
-cordova platform add android
+cordova platform add android
cordova platform add ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-cordova build android
+cordova build android
ordova build ios
Now run the application directly for Android,
-cordova run android
+cordova run android
Or iOS:
-cordova run ios
+cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
- Ionic
+ Ionic
Add Countly SDK in your Ionic project using following commands:
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
ionic cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
@@ -102,39 +101,39 @@ ionic cordova plugin add countly-sdk-js@20.11.0
If iOS/Android Platform are already added in your project, first remove them
-ionic cordova platform remove android
+ionic cordova platform remove android
ionic cordova platform remove ios
Now add platform of your choice
-ionic cordova platform add android
+ionic cordova platform add android
ionic cordova platform add ios
Now prepare the platforms you have added
-ionic cordova prepare android
+ionic cordova prepare android
ionic cordova prepare ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-ionic cordova build android
+ionic cordova build android
ionic cordova build ios
Now run the application directly for Android,
-ionic cordova run android
+ionic cordova run android
Or iOS:
-ionic cordova run ios
+ionic cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
In your index.html, use the following lines:
-<script type="text/javascript" src="cordova.js"></script>
+<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript" src="Countly.js"></script>
-SDK Integration
-Minimal setup
+SDK Integration
+Minimal setup
Below you can find necessary code snippets to initialize the SDK for sending
data to Countly servers. Where possible, use your server URL instead of
try.count.ly in case you have your own server.
-// initialize
+// initialize
Countly.isInitialized().then((result) => {
if(result != "true") {
Countly.init("https://try.count.ly", "YOUR_APP_KEY").then((result) => {
@@ -159,7 +158,7 @@ Countly.isInitialized().then((result) => {
here.
-Enable logging
+Enable logging
If logging is enabled then our sdk will print out debug messages about it's internal
state and encountered problems.
@@ -167,9 +166,9 @@ Countly.isInitialized().then((result) => {
When advise doing this while implementing countly features in your application.
-// example for setLoggingEnabled
+// example for setLoggingEnabled
Countly.setLoggingEnabled();
-Device ID
+Device ID
When the SDK is initialized for the first time and no device ID is provided,
a device ID will be generated by SDK.
@@ -181,21 +180,21 @@ Countly.setLoggingEnabled();
You may provide your own custom device ID when initializing the SDK
-Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
-SDK data storage
+Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
+SDK data storage
For iOS: SDK data is stored in Application Support Directory in file named "Countly.dat"
For Android: SDK data is stored in SharedPreferences. A SharedPreferences object
points to a file containing key-value pairs and provides simple methods to read
and write them.
-Crash reporting
+Crash reporting
The Countly SDK has the ability to collect
crash reports,
which you may examine and resolve later on the server.
-Automatic crash handling
+Automatic crash handling
With this feature, the Countly SDK will generate a crash report if your application
crashes due to an exception and send it to the Countly server for further inspection.
@@ -209,15 +208,17 @@ Countly.setLoggingEnabled();
You will need to call the following method before calling init in
order to activate automatic crash reporting.
-
-
-
-// Using countly crash reports
+
+
+// Using countly crash reports
Countly.enableCrashReporting();
-Handled exceptions
+Handled exceptions
You might catch an exception or similar error during your app’s runtime.
@@ -228,7 +229,7 @@ Countly.enableCrashReporting();
You can also send a custom crash log to Countly using code below.
-// Send Exception to the server
+// Send Exception to the server
Countly.logException(["My Customized error message"], true, {"_facebook_version": "0.0.1"});
Countly.logException(stackFramesFromStackTraceJS, booleanNonFatal, segments);
@@ -244,7 +245,7 @@ Countly.logException(stackFramesFromStackTraceJS, booleanNonFatal, segments);
1. Manually report handled exception
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -261,7 +262,7 @@ Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], true);
2. Manually report handled exception with segmentation
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -278,7 +279,7 @@ Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], true, {"\_facebook_vers
3. Manually report fatal exception
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -295,7 +296,7 @@ Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], false);
4. Manually report fatal exception with segmentation
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -309,17 +310,17 @@ Countly.logException("ERROR_STRING", false, {"\_facebook_version": "0.0.1"});
// With array of strings
Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], false, {"\_facebook_version": "0.0.1"});
-Crash breadcrumbs
+Crash breadcrumbs
Throughout your app you can leave crash breadcrumbs which would describe previous
steps that were taken in your app before the crash. After a crash happens, they
will be sent together with the crash report.
Following the command adds crash breadcrumb:
-// Add crash breadcrumb
+// Add crash breadcrumb
Countly.addCrashLog("My crash log from JavaScript");
-Events
+Events
An Event is any type
of action that you can send to a Countly instance, e.g purchase, settings changed,
@@ -330,21 +331,21 @@ Countly.addCrashLog("My crash log from JavaScript");
Here are the detail about properties which we can use with event:
- -
+
-
key identifies the event
- -
+
-
count is the number of times this event occurred
- -
+
-
sum is an overall numerical data set tied to an event. For example,
total amount of in-app purchase event.
- -
+
-
duration is used to record and track the
duration of events.
- -
+
-
segmentation is a key-value pairs, we can use
segmentation to track additional information. The only valid
data types are: "String", "Integer", "Double" and "Boolean". All other types
@@ -352,34 +353,36 @@ Countly.addCrashLog("My crash log from JavaScript");
- Data passed should be in UTF-8
+
+ Data passed should be in UTF-8
+
All data passed to Countly server via SDK or API should be in UTF-8.
-Recording events
+Recording events
We will be recording a purchase event. Here is a quick summary
of what information each usage will provide us:
- -
+
-
Usage 1: how many times purchase event occurred.
- -
+
-
Usage 2: how many times purchase event occurred + the total
amount of those purchases.
- -
+
-
Usage 3: how many times purchase event occurred + which
countries and application versions those purchases were made from.
- -
+
-
Usage 4: how many times purchase event occurred + the total
amount both of which are also available segmented into countries and application
versions.
- -
+
-
Usage 5: how many times purchase event occurred + the total
amount both of which are also available segmented into countries and application
versions + the total duration of those events.
@@ -388,33 +391,33 @@ Countly.addCrashLog("My crash log from JavaScript");
1. Event key and count
-// example for sending basic event
+// example for sending basic event
var events = {"key":"Basic Event","count":1};
Countly.recordEvent(events);
2. Event key, count and sum
-// example for event with sum
+// example for event with sum
var events = {"key":"Event With Sum","count":1,"sum":"0.99"};
Countly.recordEvent(events);
3. Event key and count with segmentation(s)
-// example for event with segment
+// example for event with segment
var events = {"key":"Event With Segment","count":1};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
4. Event key, count and sum with segmentation(s)
-// example for event with segment and sum
+// example for event with segment and sum
var events = {"key":"Event With Segment And Sum","count":1,"sum":"0.99"};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
5. Event key, count, sum and duration with segmentation(s)
-var events = {
+var events = {
"key": "Event With Sum And Segment duration",
"count": 1,
"Sum": "0.99",
@@ -430,11 +433,11 @@ Countly.recordEvent(events);
those examples and use country, app_version, game_level, time_of_day and any
other segmentation that will provide you valuable insights.
-Timed events
+Timed events
It's possible to create timed events by defining a start and stop moment.
-// Time Event
+// Time Event
Countly.startEvent("Timed Event");
setTimeout(function() {
Countly.endEvent({ "key": "Timed Event");
@@ -450,7 +453,7 @@ countly.endEvent({"key": "Timed Event With Sum", "sum": "0.99"});
case, you have to provide segmentation, count and sum. The default values for
those are "null", 1 and 0.
-
+
// Time Event with segment
Countly.startEvent("Timed Event With Segment");
setTimeout(function() {
@@ -478,28 +481,28 @@ events.segments = {
};
Countly.endEvent(events);
}, 1000);
-Sessions
-Automatic session tracking
+Sessions
+Automatic session tracking
To start recording an automatic session tracking you would call:
-Countly.start();
+Countly.start();
Countly.start(); will handle the start session,
update session and end session automatically.
This is how it works:
- -
+
-
Start/Begin session Request: It is sent on
Countly.start(); call and when the app comes
back to the foreground from the background, and it includes basic metrics.
- -
+
-
Update Session Request: It automatically sends a periodical
(60 sec by default) update session request while the app is in the foreground.
- -
+
-
End Session Request: It is sent at the end of a session
when the app goes to the background or terminates.
@@ -507,15 +510,15 @@ Countly.endEvent(events);
If you want to end automatic session tracking you would call:
-
Countly.stop();
-View tracking
+Countly.stop();
+View tracking
You may track custom views with the following code snippet:
-Countly.recordView("View Name")
+Countly.recordView("View Name")
While manually tracking views, you may add your custom segmentation to them like
this:
-var viewSegmentation = { "Country": "Germany", "Age": "28" };
+var viewSegmentation = { "Country": "Germany", "Age": "28" };
Countly.recordView("View Name", viewSegmentation);
To review the resulting data, open the dashboard and go to
@@ -524,9 +527,9 @@ Countly.recordView("View Name", viewSegmentation);
here.
- 
+ 
-Device ID management
+Device ID management
A device ID is a unique identifier for your users. You may specify the device
ID yourself or allow the SDK to generate it. When providing one yourself, keep
@@ -534,7 +537,7 @@ Countly.recordView("View Name", viewSegmentation);
an id could be the username, email or some other internal ID used by your other
systems.
-Device ID generation
+Device ID generation
When the SDK is initialized for the first time with no device ID, then SDK will
generate a device ID.
@@ -546,9 +549,9 @@ Countly.recordView("View Name", viewSegmentation);
For iOS: the device ID generated by SDK is the Identifier For Vendor (IDFV)
For Android: the device ID generated by SDK is the OpenUDID
-Changing the Device ID
+Changing the Device ID
You may configure/change the device ID anytime using:
-Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
+Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
You may either allow the device to be counted as a new device or merge existing
data on the server. If theonServer bool is set to
@@ -557,7 +560,7 @@ Countly.recordView("View Name", viewSegmentation);
Otherwise, if onServer bool is set to false, the device
will be counted as a new device on the server.
-Temporary Device ID
+Temporary Device ID
You may use a temporary device ID mode for keeping all requests on hold until
the real device ID is set later.
@@ -565,9 +568,9 @@ Countly.recordView("View Name", viewSegmentation);
You can enable temporary device ID when initializing the SDK:
-Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
+Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
To enable a temporary device ID after init, you would call:
-Countly.changeDeviceId("TemporaryDeviceID", ON_SERVER);
+Countly.changeDeviceId("TemporaryDeviceID", ON_SERVER);
Note: When passing TemporaryDeviceID for
deviceID parameter, argument for onServerparameter
@@ -588,77 +591,83 @@ Countly.recordView("View Name", viewSegmentation);
which have been kept on hold until that point will start with the real device
ID
-Retrieving current device ID
+Retrieving current device ID
You may want to see what device id Countly is assigning for the specific device.
For that you may use the following call:
-// get device id
+// get device id
Countly.getCurrentDeviceId(function(deviceId){
console.log(deviceId);
}, function(getDeviceIDError){
console.log(getDeviceIDError);
});
-Push notifications
-Integration
-Android setup
+Push notifications
+Integration
+Android setup
Here are the steps to make push notifications work on Android:
- -
+
-
For FCM credentials setup please follow the instruction from this URL
https://support.count.ly/hc/en-us/articles/360037754031-Android#getting-fcm-credentials.
- -
+
-
Make sure you have
google-services.json from
https://firebase.google.com/
- -
+
-
Make sure the app package name and the
google-services.json
package_name matches.
- -
+
-
Place this
google-services.json file under
your root project folder. i.e. above www folder.
- -
- Put these tags in config.xml file for Android:
+
-
+
Put these tags in config.xml file for Android:
- <platform name="android">
+ <platform name="android">
<resource-file src="google-services.json" target="app/google-services.json" />
</platform>
- -
- Put these tags in config.xml file if you are using cordova-android 9.x or
- greater:
+
-
+
+ Put these tags in config.xml file if you are using cordova-android 9.x
+ or greater:
+
- <preference name="GradlePluginGoogleServicesEnabled" value="true" />
+ <preference name="GradlePluginGoogleServicesEnabled" value="true" />
<preference name="GradlePluginGoogleServicesVersion" value="4.2.0" />
- -
- Install the google services plugin if you use cordova-android below version
- 9
-
cordova plugin add cordova-support-google-services --save
+ -
+
+ Install the google services plugin if you use cordova-android below version
+ 9
+
+ cordova plugin add cordova-support-google-services --save
- - Build your app, and test push notifications.
+ - Build your app, and test push notifications.
-iOS setup
+iOS setup
- By default push notification is enabled for iOS, to disable you need to add the COUNTLY_EXCLUDE_PUSHNOTIFICATIONS=1 flag to the Build Settings > Preprocessor Macros section in Xcode.
+ By default push notification is enabled for iOS, to disable you need to add the COUNTLY_EXCLUDE_PUSHNOTIFICATIONS=1 flag to the Build Settings > Preprocessor Macros section in Xcode.
- Minimum Countly SDK Version
+
+ Minimum Countly SDK Version
+
This COUNTLY_EXCLUDE_PUSHNOTIFICATIONS is only supported by the minimum SDK
version 20.11.3.
@@ -668,25 +677,25 @@ Countly.getCurrentDeviceId(function(deviceId){
There are no additional steps required for iOS,everything is set up for you by
the Countly Cordova SDK.
-Enabling push
+Enabling push
First, when setting up push for the Cordova SDK, you would first select the push
token mode. This would allow you to choose either test or production modes, push
token mode should be set before init.
-// Set messaging mode for push notifications
+// Set messaging mode for push notifications
Countly.pushTokenType(Countly.messagingMode.DEVELOPMENT, "Channel Name", "Channel Description");
When you are finally ready to initialise Countly push, you would call this:
-// This method will ask for permission, enables push notification and send push token to countly server.
+// This method will ask for permission, enables push notification and send push token to countly server.
Countly.askForNotificationPermission();
-Handling push callbacks
+Handling push callbacks
To register a Push Notification callback after initializing the SDK, use the
method below.
-Countly.registerForNotification(function(theNotification){
+Countly.registerForNotification(function(theNotification){
console.log(JSON.stringify(theNotification));
});
@@ -694,12 +703,13 @@ Countly.askForNotificationPermission();
code in AppDelegate.m
Add header files
-#import "CountlyNative.h"
#import <UserNotifications/UserNotifications.h>
+#import "CountlyNative.h"
+#import <UserNotifications/UserNotifications.h>
Before @end add these methods
-// Required for the notification event. You must call the completion handler after handling the remote notification.
+// Required for the notification event. You must call the completion handler after handling the remote notification.
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
[CountlyNative onNotification: userInfo];
@@ -720,16 +730,49 @@ Countly.askForNotificationPermission();
[CountlyNative onNotification: notification.request.content.userInfo];
completionHandler(0);
}
-Data Structure Received in Push Callbacks
+Data Structure Received in Push Callbacks
- Here is the example of how data will receive in push callbacks:
+ Here is the example of how data will receive in push callbacks:
Data Received for Android platform:
-{
"c.e.cc": "TR",
"c.e.dt": "mobile",
"Key": "value",
"c.i": "62b59b979f05a1f5e5592036",
"c.l": "https:\/\/www.google.com\/",
"c.m": "https:\/\/count.ly\/images\/logos\/countly-logo-mark.png?v2",
"c.li": "notify_icon",
"badge": "1",
"sound": "custom",
"title": "title",
"message": "Message"
}
+{
+"c.e.cc": "TR",
+"c.e.dt": "mobile",
+"Key": "value",
+"c.i": "62b59b979f05a1f5e5592036",
+"c.l": "https:\/\/www.google.com\/",
+"c.m": "https:\/\/count.ly\/images\/logos\/countly-logo-mark.png?v2",
+"c.li": "notify_icon",
+"badge": "1",
+"sound": "custom",
+"title": "title",
+"message": "Message"
+}
Data Received for iOS platform:
-{
Key = value;
aps = {
alert = {
body = Message;
subtitle = subtitle;
title = title;
};
badge = 1;
"mutable-content" = 1;
sound = custom;
};
c = {
a = "https://count.ly/images/logos/countly-logo-mark.png";
e = {
cc = TR;
dt = mobile;
};
i = 62b5b945cabedb0870e9f217;
l = "https://www.google.com/";
};
}
-User location
+{
+Key = value;
+ aps = {
+ alert = {
+ body = Message;
+ subtitle = subtitle;
+ title = title;
+ };
+ badge = 1;
+ "mutable-content" = 1;
+ sound = custom;
+ };
+ c = {
+ a = "https://count.ly/images/logos/countly-logo-mark.png";
+ e = {
+ cc = TR;
+ dt = mobile;
+ };
+ i = 62b5b945cabedb0870e9f217;
+ l = "https://www.google.com/";
+ };
+}
+User location
While integrating this SDK into your application, you might want to track your
user location. You could use this information to better know your apps user base
@@ -737,14 +780,14 @@ completionHandler(0);
are 4 fields that can be provided:
- - country code in the 2 letter iso standard
- - city name (has to be set together with country code)
- -
+
- country code in the 2 letter iso standard
+ - city name (has to be set together with country code)
+ -
Comma separate latitude and longitude values, for example "56.42345,123.45325"
- - ip address of your user
+ - ip address of your user
-// send user location
+// send user location
Countly.setLocation("28.006324", "-82.7166183");
When those values are set, they will be sent every time when initiating a session.
@@ -759,13 +802,13 @@ Countly.setLocation("28.006324", "-82.7166183");
It will erase cached location data from the device and the server.
-Remote Config
+Remote Config
Remote config allows you to modiffy how your app functions or looks by requesting
key-value pairs from your Countly server. The returned values can be modiffied
based on the user profile. For more details please see Remote Config documentation.
-Automatic remote config
+Automatic remote config
There are two ways of acquiring remote config data, by automatic download or
manual request. By default, automatic remote config is disabled and therefore
@@ -781,7 +824,7 @@ Countly.setLocation("28.006324", "-82.7166183");
Note: call setRemoteConfigAutomaticDownload method
before init
-// Call this method before init
+// Call this method before init
Countly.setRemoteConfigAutomaticDownload(function(r){
alert(r)
}, function(r){
@@ -798,14 +841,14 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
instead). It is possible that a previously valid key returns no value after an
update.
-Manual remote config
+Manual remote config
There are three ways for manually requesting a Remote Config update:
- - Manually updating everything
- - Manually updating specific keys
- - Manually updating everything except specific keys
+ - Manually updating everything
+ - Manually updating specific keys
+ - Manually updating everything except specific keys
Each of these requests also has a callback. If that returns a non-null value,
@@ -818,7 +861,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
The advantage is that you can make the request whenever it is desirable for you.
It has a callback to let you know when it has finished.
-Countly.remoteConfigUpdate(function(r){
+Countly.remoteConfigUpdate(function(r){
alert(r)
}, function(r){
alert(r);
@@ -829,7 +872,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
updated. That list is an array with string values of those keys. It has a callback
to let you know when the request has finished.
-Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
+Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -839,7 +882,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
updateRemoteConfigExceptKeys. The key list is a array with string values of the
keys. It has a callback to let you know when the request has finished.
-Countly.updateRemoteConfigExceptKeys(["url"], function(r){
+Countly.updateRemoteConfigExceptKeys(["url"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -850,7 +893,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
will update all values. This means that it will also erase all keys not returned
by the server.
-Getting Remote Config values
+Getting Remote Config values
To request a stored value, call getRemoteConfigValueForKey with
the specified key. If it returns null then no value was found. The SDK has no
@@ -858,22 +901,22 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
needs to cast it to the appropriate type. The returned values can also be a JSONArray,
JSONObject or just a simple value like int.
-Countly.getRemoteConfigValueForKey("name", function(r){
+Countly.getRemoteConfigValueForKey("name", function(r){
alert(r)
}, function(r){
alert(r);
});
-Clearing stored values
+Clearing stored values
At some point you might want to erase all values downloaded from the server.
To achieve that you need to call one function, depicted below:
-Countly.remoteConfigClearValues(function(r){
+Countly.remoteConfigClearValues(function(r){
alert(r)
}, function(r){
alert(r);
});
-User Feedback
+User Feedback
There are two ways of getting feedback from your users: Star rating dialog, feedback
widget.
@@ -882,8 +925,8 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
Star rating dialog allows users to give feedback as a rating from 1 to 5. The
feedback widget allows to get the same 1 to 5 rating and also a text comment.
-Ratings
-Star Rating Dialog
+Ratings
+Star Rating Dialog
Star rating integration provides a dialog for getting user's feedback about the
application. It contains a title, simple message explaining what it is for, a
@@ -901,17 +944,17 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
either through the init function or the SetStarRatingDialogTexts
function. If you don't want to override one of those values, set it to "null".
-// Star Rating
+// Star Rating
countly.askForStarRating(Function(ratingResult){
console.log(ratingResult);
});
-Rating Widget
+Rating Widget
Feedback widget shows a server configured widget to your user devices.
- 
+ 
It's possible to configure any of the shown text fields and replace with a custom
@@ -932,14 +975,14 @@ countly.askForStarRating(Function(ratingResult){
you first have to get the widget ID from your server:
- 
+ 
Using that you can call the function to show the widget popup:
-// Feedback Modal
+// Feedback Modal
countly.askForFeedback("5e425407975d006a22535fc", "close");
-User Profiles
+User Profiles
Available with Enterprise Edition, User Profiles is a tool which helps you identify
users, their devices, event timeline and application crash information. User
@@ -958,7 +1001,7 @@ countly.askForFeedback("5e425407975d006a22535fc", "close");
After you have provided user profile information, you must save it by calling
Countly.userData.save().
-/ example for setting user data
+/ example for setting user data
var options = {};
options.name = "Nicola Tesla";
options.username = "nicola";
@@ -971,55 +1014,59 @@ options.gender = "Male";
options.byear = 1919;
Countly.setUserData(options);
The keys for predefined user data fields are as follows:
-
-
-
- Key
- Type
- Description
-
-
- name
- String
- User's full name
-
-
- username
- String
- User's nickname
-
-
- email
- String
- User's email address
-
-
- organization
- String
- User's organisation name
-
-
- phone
- String
- User's phone number
-
-
- picture
- String
- URL to avatar or profile picture of the user
-
-
- gender
- String
- User's gender as M for male and F for female
-
-
- byear
- String
- User's year of birth as integer
-
-
-
+
+
+
+
+ Key
+ Type
+ Description
+
+
+
+
+ name
+ String
+ User's full name
+
+
+ username
+ String
+ User's nickname
+
+
+ email
+ String
+ User's email address
+
+
+ organization
+ String
+ User's organisation name
+
+
+ phone
+ String
+ User's phone number
+
+
+ picture
+ String
+ URL to avatar or profile picture of the user
+
+
+ gender
+ String
+ User's gender as M for male and F for female
+
+
+ byear
+ String
+ User's year of birth as integer
+
+
+
+
Using "" for strings or a negative number for 'byear' will effectively delete
that property.
@@ -1029,13 +1076,13 @@ Countly.setUserData(options);
on your Countly backend. Note: keys with . or $ symbols will have those symbols
removed.
-Setting custom values
+Setting custom values
Additionally you can do different manipulations on your custom data values, like
increment current value on server or store a array of values under the same property.
Below is the list of available methods:
-// example for extra user features
+// example for extra user features
Countly.userData.setProperty("setProperty", "My Property");
Countly.userData.increment("increment");
@@ -1050,9 +1097,11 @@ Countly.userData.pullValue("pullValue", "morning");
In the end always call Countly.userData.save() to send them to the server.
-Application Performance Monitoring
+Application Performance Monitoring
- Minimum Countly SDK Version
+
+ Minimum Countly SDK Version
+
This feature is only supported by the minimum SDK version 20.4.0.
@@ -1066,20 +1115,20 @@ Countly.userData.pullValue("pullValue", "morning");
Here is how you can utilize Performance Monitoring feature in your apps:
First, you need to enable Performance Monitoring feature::
-Countly.enableApm();
+Countly.enableApm();
// Enable APM features.
With this, Countly SDK will start measuring some performance traces automatically.
Those include app foreground time, app background time. Additionally, custom
traces and network traces can be manually recorded.
-App Start Time
+App Start Time
For the app start time to be recorded, you need to call the
appLoadingFinished method. Make sure this method is called after
init.
-// Example of appLoadingFinished
+// Example of appLoadingFinished
Countly.init("https://try.count.ly", "YOUR_APP_KEY").then((result) => {
Countly.appLoadingFinished();
},(err) => {
@@ -1094,19 +1143,19 @@ Countly.init("https://try.count.ly", "YOUR_APP_KEY").then((result) => {
the app launch time can be recorded only once per app launch. So, the second
and following calls to this method will be ignored.
-Custom traces
+Custom traces
You may also measure any operation you want and record it using custom traces.
First, you need to start a trace by using the
startTrace(traceKey) method:
-Countly.startTrace(traceKey);
+Countly.startTrace(traceKey);
Then you may end it using the
endTrace(traceKey, customMetric)method, optionally
passing any metrics as key-value pairs:
-String traceKey = "Trace Key"
+String traceKey = "Trace Key"
;
Map<String, int> customMetric = {
"ABC": 1233,
@@ -1123,13 +1172,13 @@ Countly.endTrace(traceKey, customMetric);
You may also cancel any custom trace you started, using
cancelTrace(traceKey)method:
-Countly.cancelTrace(traceKey);
+Countly.cancelTrace(traceKey);
Additionally, if you need you may cancel all custom traces you started, using
clearAllTraces()method:
-Countly.clearAllTraces(traceKey);
-Network traces
+Countly.clearAllTraces(traceKey);
+Network traces
You may record manual network traces using theecordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime)
method.
@@ -1149,9 +1198,9 @@ Countly.endTrace(traceKey, customMetric);
time of the request - endTime: UNIX time stamp in milliseconds for
the ending time of the request
-Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
+Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
-User Consent
+User Consent
To be compliant with GDPR, starting from 18.04, Countly provides ways to toggle
different Countly features on/off depending on the given consent.
@@ -1161,7 +1210,7 @@ Countly.endTrace(traceKey, customMetric);
By default the requirement for consent is disabled. To enable it, you have to
call setRequiresConsent with true, before initializing Countly.
-Countly.setRequiresConsent(true);
+Countly.setRequiresConsent(true);
By default no consent is given. That means that if no consent is enabled, Countly
will not work and no network requests, related to features, will be sent. When
@@ -1188,104 +1237,96 @@ Countly.endTrace(traceKey, customMetric);
The current features are:
- -
+
-
sessions - tracking when, how often and how long users use your app
- - events - allow sending events to server
- - views - allow tracking which views user visits
- - location - allow sending location information
- - crashes - allow tracking crashes, exceptions and errors
- -
+
- events - allow sending events to server
+ - views - allow tracking which views user visits
+ - location - allow sending location information
+ - 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
- - starRating - allow to send their rating and feedback
- - apm - allow application performance monitoring
- -
+
- push - allow push notifications
+ - starRating - allow to send their rating and feedback
+ - apm - allow application performance monitoring
+ -
remote-config - allows downloading remote config values from your server
-Changing consent
+Changing consent
There are 3 ways of changing feature consent:
- -
+
-
giveConsentInit - To add consent for a single feature (string parameter)
or a subset of features (array of strings parameter). Use this method for
giving consent before initializing.
-//giveConsent
+//giveConsent
Countly.giveConsentInit(["events", "views", "star-rating", "crashes"]);
// removeConsent
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);
- -
+
-
giveConsent/removeConsent - gives or removes consent to a specific feature
-//giveConsent
+//giveConsent
Countly.giveConsent(["events", "views", "star-rating", "crashes"]);
// removeConsent
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);
- -
+
-
giveAllConsent/removeAllConsent - giveAll or removeAll consent to a specific
feature
-//giveAllConsent
+//giveAllConsent
Countly.giveAllConsent();
//removeAllConsent
Countly.removeAllConsent();
-Security and privacy
-Parameter Tampering Protection
+Security and privacy
+Parameter Tampering Protection
You can set optional salt to be used for calculating checksum of request data,
which will be sent with each request using &checksum field. You need to set
exactly the same salt on Countly server. If salt on Countly server is set, all
requests would be checked for validity of &checksum field before being processed.
-// sending data with salt
+// sending data with salt
Countly.enableParameterTamperingProtection("salt");
-Using Proguard
+Using Proguard
If you are using Countly Messaging in your Android application, it is recommended
to obfuscate the Countly Messaging classes using Proguard. To do so, please follow
the instructions below:
- -
-
- Locate the app/proguard-rules.pro file within the /android/app/ folder.
-
-
- -
-
Add the following lines to the file:
+ -
+ Locate the app/proguard-rules.pro file within the /android/app/ folder.
+ - Add the following lines to the file:
--keep class ly.count.android.sdk.** { *; }
+-keep class ly.count.android.sdk.** { *; }
- -
-
- If Proguard is not yet configured, you must first enable shrinking and
- obfuscation in the build file. To do so, locate the build.gradle file
- within the /android/app/ folder.
-
-
- -
-
Add the following lines in bold to the build.gradle file:
+ -
+ If Proguard is not yet configured, you must first enable shrinking and obfuscation
+ in the build file. To do so, locate the build.gradle file within the /android/app/
+ folder.
+ - Add the following lines in bold to the build.gradle file:
-...
+...
buildTypes {
release { // Enables code shrinking, obfuscation, and optimization for only your project's release build type.
@@ -1300,8 +1341,8 @@ buildTypes {
By following these steps, the Countly Messaging classes will be obfuscated using
Proguard and your application will be better protected against reverse engineering.
-Other features
-Forcing HTTP POST
+Other features
+Forcing HTTP POST
If the data sent to the server is short enough, the sdk will use HTTP GET requests.
In case you want an override so that HTTP POST is used in all cases, call the
@@ -1309,9 +1350,9 @@ buildTypes {
to later in the apps life cycle disable the override. This function has to be
called every time the app starts.
-Countly.setHttpPostForced(true); // default is false
+Countly.setHttpPostForced(true); // default is false
-Optional parameters during initialization
+Optional parameters during initialization
You can provide optional parameters that will be used during begin_session request.
They must be set right after the init function so that they are
@@ -1323,13 +1364,13 @@ buildTypes {
The optional parameters are:
- - Country code: ISO Country code for the user's country
- - City: Name of the user's city
- -
+
- Country code: ISO Country code for the user's country
+ - City: Name of the user's city
+ -
Location: Comma separate latitude and longitude values, for example "56.42345,123.45325"
-
+
//setting optional parameters
Countly.setOptionalParametersForInitialization({
city: "Tampa",
@@ -1340,4 +1381,4 @@ Countly.setOptionalParametersForInitialization({
});
//and then call the below code
-Countly.init(this, "https://YOUR_SERVER", "YOUR_APP_KEY", "YOUR_DEVICE_ID")
+Countly.init(this, "https://YOUR_SERVER", "YOUR_APP_KEY", "YOUR_DEVICE_ID")
\ No newline at end of file
diff --git a/legacy_docs/cordova/current.md b/legacy_docs/cordova/current.md
index 352b81ae..c40d011a 100644
--- a/legacy_docs/cordova/current.md
+++ b/legacy_docs/cordova/current.md
@@ -19,15 +19,15 @@
Github repo.
It should show how most of the functionalities can be used.
-Adding the SDK to the project
+Adding the SDK to the project
The core of this SDK is developed around Cordova. We have a minimum version requirement
for it's core and android, ios modules that have to be satisfied:
- - cordova >= 9.0.0
- - cordova-android >= 8.0.0
- - cordova-ios >= 5.0.0
+ - cordova >= 9.0.0
+ - cordova-android >= 8.0.0
+ - cordova-ios >= 5.0.0
If you would integrate this SDK in any other project similar to cordova (like
@@ -35,9 +35,8 @@
platform requirements for those projects similar to these.
- Note : Development on PhoneGap stopped in
- 14 Aug 2020. To the best of our knowledge, this SDK should still
- be compatible with the final release.
+ Note : Development on PhoneGap stopped in 14 Aug 2020. To the
+ best of our knowledge, this SDK should still be compatible with the final release.
For more information about PhoneGap shut down,
@@ -55,7 +54,7 @@
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
@@ -65,34 +64,34 @@ cordova plugin add countly-sdk-js@20.11.0
If iOS/Android Platform are already added in your project, first remove them
-cordova platform remove android
+cordova platform remove android
cordova platform remove ios
Now add platform of your choice
-cordova platform add android
+cordova platform add android
cordova platform add ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-cordova build android
+cordova build android
ordova build ios
Now run the application directly for Android,
-cordova run android
+cordova run android
Or iOS:
-cordova run ios
+cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
- Ionic
+ Ionic
Add Countly SDK in your Ionic project using following commands:
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
ionic cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
@@ -102,39 +101,39 @@ ionic cordova plugin add countly-sdk-js@20.11.0
If iOS/Android Platform are already added in your project, first remove them
-ionic cordova platform remove android
+ionic cordova platform remove android
ionic cordova platform remove ios
Now add platform of your choice
-ionic cordova platform add android
+ionic cordova platform add android
ionic cordova platform add ios
Now prepare the platforms you have added
-ionic cordova prepare android
+ionic cordova prepare android
ionic cordova prepare ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-ionic cordova build android
+ionic cordova build android
ionic cordova build ios
Now run the application directly for Android,
-ionic cordova run android
+ionic cordova run android
Or iOS:
-ionic cordova run ios
+ionic cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
In your index.html, use the following lines:
-<script type="text/javascript" src="cordova.js"></script>
+<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript" src="Countly.js"></script>
-SDK Integration
-Minimal setup
+SDK Integration
+Minimal setup
Below you can find necessary code snippets to initialize the SDK for sending
data to Countly servers. Where possible, use your server URL instead of
try.count.ly in case you have your own server.
-// initialize
+// initialize
Countly.isInitialized().then((result) => {
if(result != "true") {
Countly.init("https://try.count.ly", "YOUR_APP_KEY").then((result) => {
@@ -159,7 +158,7 @@ Countly.isInitialized().then((result) => {
here.
-Enable logging
+Enable logging
If logging is enabled then our sdk will print out debug messages about it's internal
state and encountered problems.
@@ -167,9 +166,9 @@ Countly.isInitialized().then((result) => {
When advise doing this while implementing countly features in your application.
-// example for setLoggingEnabled
+// example for setLoggingEnabled
Countly.setLoggingEnabled();
-Device ID
+Device ID
When the SDK is initialized for the first time and no device ID is provided,
a device ID will be generated by SDK.
@@ -181,21 +180,21 @@ Countly.setLoggingEnabled();
You may provide your own custom device ID when initializing the SDK
-Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
-SDK data storage
+Countly.init(SERVER_URL, APP_KEY, DEVICE_ID)
+SDK data storage
For iOS: SDK data is stored in Application Support Directory in file named "Countly.dat"
For Android: SDK data is stored in SharedPreferences. A SharedPreferences object
points to a file containing key-value pairs and provides simple methods to read
and write them.
-Crash reporting
+Crash reporting
The Countly SDK has the ability to collect
crash reports,
which you may examine and resolve later on the server.
-Automatic crash handling
+Automatic crash handling
With this feature, the Countly SDK will generate a crash report if your application
crashes due to an exception and send it to the Countly server for further inspection.
@@ -209,15 +208,17 @@ Countly.setLoggingEnabled();
You will need to call the following method before calling init in
order to activate automatic crash reporting.
-
-
-
-// Using countly crash reports
+
+
+// Using countly crash reports
Countly.enableCrashReporting();
-Handled exceptions
+Handled exceptions
You might catch an exception or similar error during your app’s runtime.
@@ -228,7 +229,7 @@ Countly.enableCrashReporting();
You can also send a custom crash log to Countly using code below.
-// Send Exception to the server
+// Send Exception to the server
Countly.logException(["My Customized error message"], true, {"_facebook_version": "0.0.1"});
Countly.logException(stackFramesFromStackTraceJS, booleanNonFatal, segments);
@@ -244,7 +245,7 @@ Countly.logException(stackFramesFromStackTraceJS, booleanNonFatal, segments);
1. Manually report handled exception
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -261,7 +262,7 @@ Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], true);
2. Manually report handled exception with segmentation
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -278,7 +279,7 @@ Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], true, {"\_facebook_vers
3. Manually report fatal exception
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -295,7 +296,7 @@ Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], false);
4. Manually report fatal exception with segmentation
-// With stackframes
+// With stackframes
try {
// your code here...
} catch (err) {
@@ -309,17 +310,17 @@ Countly.logException("ERROR_STRING", false, {"\_facebook_version": "0.0.1"});
// With array of strings
Countly.logException(["ERROR_STRING", "ERROR_STRING_2"], false, {"\_facebook_version": "0.0.1"});
-Crash breadcrumbs
+Crash breadcrumbs
Throughout your app you can leave crash breadcrumbs which would describe previous
steps that were taken in your app before the crash. After a crash happens, they
will be sent together with the crash report.
Following the command adds crash breadcrumb:
-// Add crash breadcrumb
+// Add crash breadcrumb
Countly.addCrashLog("My crash log from JavaScript");
-Events
+Events
An Event is any type
of action that you can send to a Countly instance, e.g purchase, settings changed,
@@ -330,21 +331,21 @@ Countly.addCrashLog("My crash log from JavaScript");
Here are the detail about properties which we can use with event:
- -
+
-
key identifies the event
- -
+
-
count is the number of times this event occurred
- -
+
-
sum is an overall numerical data set tied to an event. For example,
total amount of in-app purchase event.
- -
+
-
duration is used to record and track the
duration of events.
- -
+
-
segmentation is a key-value pairs, we can use
segmentation to track additional information. The only valid
data types are: "String", "Integer", "Double" and "Boolean". All other types
@@ -352,34 +353,36 @@ Countly.addCrashLog("My crash log from JavaScript");
- Data passed should be in UTF-8
+
+ Data passed should be in UTF-8
+
All data passed to Countly server via SDK or API should be in UTF-8.
-Recording events
+Recording events
We will be recording a purchase event. Here is a quick summary
of what information each usage will provide us:
- -
+
-
Usage 1: how many times purchase event occurred.
- -
+
-
Usage 2: how many times purchase event occurred + the total
amount of those purchases.
- -
+
-
Usage 3: how many times purchase event occurred + which
countries and application versions those purchases were made from.
- -
+
-
Usage 4: how many times purchase event occurred + the total
amount both of which are also available segmented into countries and application
versions.
- -
+
-
Usage 5: how many times purchase event occurred + the total
amount both of which are also available segmented into countries and application
versions + the total duration of those events.
@@ -388,33 +391,33 @@ Countly.addCrashLog("My crash log from JavaScript");
1. Event key and count
-// example for sending basic event
+// example for sending basic event
var events = {"key":"Basic Event","count":1};
Countly.recordEvent(events);
2. Event key, count and sum
-// example for event with sum
+// example for event with sum
var events = {"key":"Event With Sum","count":1,"sum":"0.99"};
Countly.recordEvent(events);
3. Event key and count with segmentation(s)
-// example for event with segment
+// example for event with segment
var events = {"key":"Event With Segment","count":1};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
4. Event key, count and sum with segmentation(s)
-// example for event with segment and sum
+// example for event with segment and sum
var events = {"key":"Event With Segment And Sum","count":1,"sum":"0.99"};
events.segments = {"Country" : "Turkey", "Age" : "28"};
Countly.recordEvent(events);
5. Event key, count, sum and duration with segmentation(s)
-var events = {
+var events = {
"key": "Event With Sum And Segment duration",
"count": 1,
"Sum": "0.99",
@@ -430,11 +433,11 @@ Countly.recordEvent(events);
those examples and use country, app_version, game_level, time_of_day and any
other segmentation that will provide you valuable insights.
-Timed events
+Timed events
It's possible to create timed events by defining a start and stop moment.
-// Time Event
+// Time Event
Countly.startEvent("Timed Event");
setTimeout(function() {
Countly.endEvent({ "key": "Timed Event");
@@ -450,7 +453,7 @@ countly.endEvent({"key": "Timed Event With Sum", "sum": "0.99"});
case, you have to provide segmentation, count and sum. The default values for
those are "null", 1 and 0.
-
+
// Time Event with segment
Countly.startEvent("Timed Event With Segment");
setTimeout(function() {
@@ -478,28 +481,28 @@ events.segments = {
};
Countly.endEvent(events);
}, 1000);
-Sessions
-Automatic session tracking
+Sessions
+Automatic session tracking
To start recording an automatic session tracking you would call:
-Countly.start();
+Countly.start();
Countly.start(); will handle the start session,
update session and end session automatically.
This is how it works:
- -
+
-
Start/Begin session Request: It is sent on
Countly.start(); call and when the app comes
back to the foreground from the background, and it includes basic metrics.
- -
+
-
Update Session Request: It automatically sends a periodical
(60 sec by default) update session request while the app is in the foreground.
- -
+
-
End Session Request: It is sent at the end of a session
when the app goes to the background or terminates.
@@ -507,15 +510,15 @@ Countly.endEvent(events);
If you want to end automatic session tracking you would call:
-
Countly.stop();
-View tracking
+Countly.stop();
+View tracking
You may track custom views with the following code snippet:
-Countly.recordView("View Name")
+Countly.recordView("View Name")
While manually tracking views, you may add your custom segmentation to them like
this:
-var viewSegmentation = { "Country": "Germany", "Age": "28" };
+var viewSegmentation = { "Country": "Germany", "Age": "28" };
Countly.recordView("View Name", viewSegmentation);
To review the resulting data, open the dashboard and go to
@@ -524,9 +527,9 @@ Countly.recordView("View Name", viewSegmentation);
here.
-
+
-Device ID management
+Device ID management
A device ID is a unique identifier for your users. You may specify the device
ID yourself or allow the SDK to generate it. When providing one yourself, keep
@@ -534,7 +537,7 @@ Countly.recordView("View Name", viewSegmentation);
an id could be the username, email or some other internal ID used by your other
systems.
-Device ID generation
+Device ID generation
When the SDK is initialized for the first time with no device ID, then SDK will
generate a device ID.
@@ -546,9 +549,9 @@ Countly.recordView("View Name", viewSegmentation);
For iOS: the device ID generated by SDK is the Identifier For Vendor (IDFV)
For Android: the device ID generated by SDK is the OpenUDID
-Changing the Device ID
+Changing the Device ID
You may configure/change the device ID anytime using:
-Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
+Countly.changeDeviceId(DEVICE_ID, ON_SERVER);
You may either allow the device to be counted as a new device or merge existing
data on the server. If theonServer bool is set to
@@ -557,7 +560,7 @@ Countly.recordView("View Name", viewSegmentation);
Otherwise, if onServer bool is set to false, the device
will be counted as a new device on the server.
-Temporary Device ID
+Temporary Device ID
You may use a temporary device ID mode for keeping all requests on hold until
the real device ID is set later.
@@ -565,9 +568,9 @@ Countly.recordView("View Name", viewSegmentation);
You can enable temporary device ID when initializing the SDK:
-Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
+Countly.init(SERVER_URL, APP_KEY, "TemporaryDeviceID")
To enable a temporary device ID after init, you would call:
-Countly.changeDeviceId("TemporaryDeviceID", ON_SERVER);
+Countly.changeDeviceId("TemporaryDeviceID", ON_SERVER);
Note: When passing TemporaryDeviceID for
deviceID parameter, argument for onServerparameter
@@ -588,71 +591,75 @@ Countly.recordView("View Name", viewSegmentation);
which have been kept on hold until that point will start with the real device
ID
-Retrieving current device ID
+Retrieving current device ID
You may want to see what device id Countly is assigning for the specific device.
For that you may use the following call:
-// get device id
+// get device id
Countly.getCurrentDeviceId(function(deviceId){
console.log(deviceId);
}, function(getDeviceIDError){
console.log(getDeviceIDError);
});
-Push notifications
-Integration
-Android setup
+Push notifications
+Integration
+Android setup
Here are the steps to make push notifications work on Android:
- -
+
-
For FCM credentials setup please follow the instruction from this URL
https://support.count.ly/hc/en-us/articles/360037754031-Android#getting-fcm-credentials.
- -
+
-
Make sure you have
google-services.json from
https://firebase.google.com/
- -
+
-
Make sure the app package name and the
google-services.json
package_name matches.
- -
+
-
Place this
google-services.json file under
your root project folder. i.e. above www folder.
- -
- Put these tags in config.xml file for Android:
+
-
+
Put these tags in config.xml file for Android:
- <platform name="android">
+ <platform name="android">
<resource-file src="google-services.json" target="app/google-services.json" />
</platform>
- -
- Put these tags in config.xml file if you are using cordova-android 9.x or
- greater:
+
-
+
+ Put these tags in config.xml file if you are using cordova-android 9.x
+ or greater:
+
- <preference name="GradlePluginGoogleServicesEnabled" value="true" />
+ <preference name="GradlePluginGoogleServicesEnabled" value="true" />
<preference name="GradlePluginGoogleServicesVersion" value="4.2.0" />
- -
- Install the google services plugin if you use cordova-android below version
- 9
-
cordova plugin add cordova-support-google-services --save
+ -
+
+ Install the google services plugin if you use cordova-android below version
+ 9
+
+ cordova plugin add cordova-support-google-services --save
- - Build your app, and test push notifications.
+ - Build your app, and test push notifications.
-iOS setup
+iOS setup
- By default push notification is enabled for iOS, to disable you need to add the COUNTLY_EXCLUDE_PUSHNOTIFICATIONS=1 flag to the Build Settings > Preprocessor Macros section in Xcode.
+ By default push notification is enabled for iOS, to disable you need to add the COUNTLY_EXCLUDE_PUSHNOTIFICATIONS=1 flag to the Build Settings > Preprocessor Macros section in Xcode.
@@ -661,25 +668,25 @@ Countly.getCurrentDeviceId(function(deviceId){
There are no additional steps required for iOS,everything is set up for you by
the Countly Cordova SDK.
-Enabling push
+Enabling push
First, when setting up push for the Cordova SDK, you would first select the push
token mode. This would allow you to choose either test or production modes, push
token mode should be set before init.
-// Set messaging mode for push notifications
+// Set messaging mode for push notifications
Countly.pushTokenType(Countly.messagingMode.DEVELOPMENT, "Channel Name", "Channel Description");
When you are finally ready to initialise Countly push, you would call this:
-// This method will ask for permission, enables push notification and send push token to countly server.
+// This method will ask for permission, enables push notification and send push token to countly server.
Countly.askForNotificationPermission();
-Handling push callbacks
+Handling push callbacks
To register a Push Notification callback after initializing the SDK, use the
method below.
-Countly.registerForNotification(function(theNotification){
+Countly.registerForNotification(function(theNotification){
console.log(JSON.stringify(theNotification));
});
@@ -687,12 +694,13 @@ Countly.askForNotificationPermission();
code in AppDelegate.m
Add header files
-#import "CountlyNative.h"
#import <UserNotifications/UserNotifications.h>
+#import "CountlyNative.h"
+#import <UserNotifications/UserNotifications.h>
Before @end add these methods
-// Required for the notification event. You must call the completion handler after handling the remote notification.
+// Required for the notification event. You must call the completion handler after handling the remote notification.
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
[CountlyNative onNotification: userInfo];
@@ -713,16 +721,49 @@ Countly.askForNotificationPermission();
[CountlyNative onNotification: notification.request.content.userInfo];
completionHandler(0);
}
-Data Structure Received in Push Callbacks
+Data Structure Received in Push Callbacks
- Here is the example of how data will receive in push callbacks:
+ Here is the example of how data will receive in push callbacks:
Data Received for Android platform:
-{
"c.e.cc": "TR",
"c.e.dt": "mobile",
"Key": "value",
"c.i": "62b59b979f05a1f5e5592036",
"c.l": "https:\/\/www.google.com\/",
"c.m": "https:\/\/count.ly\/images\/logos\/countly-logo-mark.png?v2",
"c.li": "notify_icon",
"badge": "1",
"sound": "custom",
"title": "title",
"message": "Message"
}
+{
+"c.e.cc": "TR",
+"c.e.dt": "mobile",
+"Key": "value",
+"c.i": "62b59b979f05a1f5e5592036",
+"c.l": "https:\/\/www.google.com\/",
+"c.m": "https:\/\/count.ly\/images\/logos\/countly-logo-mark.png?v2",
+"c.li": "notify_icon",
+"badge": "1",
+"sound": "custom",
+"title": "title",
+"message": "Message"
+}
Data Received for iOS platform:
-{
Key = value;
aps = {
alert = {
body = Message;
subtitle = subtitle;
title = title;
};
badge = 1;
"mutable-content" = 1;
sound = custom;
};
c = {
a = "https://count.ly/images/logos/countly-logo-mark.png";
e = {
cc = TR;
dt = mobile;
};
i = 62b5b945cabedb0870e9f217;
l = "https://www.google.com/";
};
}
-User location
+{
+Key = value;
+ aps = {
+ alert = {
+ body = Message;
+ subtitle = subtitle;
+ title = title;
+ };
+ badge = 1;
+ "mutable-content" = 1;
+ sound = custom;
+ };
+ c = {
+ a = "https://count.ly/images/logos/countly-logo-mark.png";
+ e = {
+ cc = TR;
+ dt = mobile;
+ };
+ i = 62b5b945cabedb0870e9f217;
+ l = "https://www.google.com/";
+ };
+}
+User location
While integrating this SDK into your application, you might want to track your
user location. You could use this information to better know your apps user base
@@ -730,14 +771,14 @@ completionHandler(0);
are 4 fields that can be provided:
- - country code in the 2 letter iso standard
- - city name (has to be set together with country code)
- -
+
- country code in the 2 letter iso standard
+ - city name (has to be set together with country code)
+ -
Comma separate latitude and longitude values, for example "56.42345,123.45325"
- - ip address of your user
+ - ip address of your user
-// send user location
+// send user location
Countly.setLocation("28.006324", "-82.7166183");
When those values are set, they will be sent every time when initiating a session.
@@ -752,13 +793,13 @@ Countly.setLocation("28.006324", "-82.7166183");
It will erase cached location data from the device and the server.
-Remote Config
+Remote Config
Remote config allows you to modiffy how your app functions or looks by requesting
key-value pairs from your Countly server. The returned values can be modiffied
based on the user profile. For more details please see Remote Config documentation.
-Automatic remote config
+Automatic remote config
There are two ways of acquiring remote config data, by automatic download or
manual request. By default, automatic remote config is disabled and therefore
@@ -774,7 +815,7 @@ Countly.setLocation("28.006324", "-82.7166183");
Note: call setRemoteConfigAutomaticDownload method
before init
-// Call this method before init
+// Call this method before init
Countly.setRemoteConfigAutomaticDownload(function(r){
alert(r)
}, function(r){
@@ -791,14 +832,14 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
instead). It is possible that a previously valid key returns no value after an
update.
-Manual remote config
+Manual remote config
There are three ways for manually requesting a Remote Config update:
- - Manually updating everything
- - Manually updating specific keys
- - Manually updating everything except specific keys
+ - Manually updating everything
+ - Manually updating specific keys
+ - Manually updating everything except specific keys
Each of these requests also has a callback. If that returns a non-null value,
@@ -811,7 +852,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
The advantage is that you can make the request whenever it is desirable for you.
It has a callback to let you know when it has finished.
-Countly.remoteConfigUpdate(function(r){
+Countly.remoteConfigUpdate(function(r){
alert(r)
}, function(r){
alert(r);
@@ -822,7 +863,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
updated. That list is an array with string values of those keys. It has a callback
to let you know when the request has finished.
-Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
+Countly.updateRemoteConfigForKeysOnly(["name"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -832,7 +873,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
updateRemoteConfigExceptKeys. The key list is a array with string values of the
keys. It has a callback to let you know when the request has finished.
-Countly.updateRemoteConfigExceptKeys(["url"], function(r){
+Countly.updateRemoteConfigExceptKeys(["url"], function(r){
alert(r)
}, function(r){
alert(r);
@@ -843,7 +884,7 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
will update all values. This means that it will also erase all keys not returned
by the server.
-Getting Remote Config values
+Getting Remote Config values
To request a stored value, call getRemoteConfigValueForKey with
the specified key. If it returns null then no value was found. The SDK has no
@@ -851,22 +892,22 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
needs to cast it to the appropriate type. The returned values can also be a JSONArray,
JSONObject or just a simple value like int.
-Countly.getRemoteConfigValueForKey("name", function(r){
+Countly.getRemoteConfigValueForKey("name", function(r){
alert(r)
}, function(r){
alert(r);
});
-Clearing stored values
+Clearing stored values
At some point you might want to erase all values downloaded from the server.
To achieve that you need to call one function, depicted below:
-Countly.remoteConfigClearValues(function(r){
+Countly.remoteConfigClearValues(function(r){
alert(r)
}, function(r){
alert(r);
});
-User Feedback
+User Feedback
There are two ways of getting feedback from your users: Star rating dialog, feedback
widget.
@@ -875,8 +916,8 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
Star rating dialog allows users to give feedback as a rating from 1 to 5. The
feedback widget allows to get the same 1 to 5 rating and also a text comment.
-Ratings
-Star Rating Dialog
+Ratings
+Star Rating Dialog
Star rating integration provides a dialog for getting user's feedback about the
application. It contains a title, simple message explaining what it is for, a
@@ -894,17 +935,17 @@ Countly.setRemoteConfigAutomaticDownload(function(r){
either through the init function or the SetStarRatingDialogTexts
function. If you don't want to override one of those values, set it to "null".
-// Star Rating
+// Star Rating
countly.askForStarRating(Function(ratingResult){
console.log(ratingResult);
});
-Rating Widget
+Rating Widget
Feedback widget shows a server configured widget to your user devices.
-
+
It's possible to configure any of the shown text fields and replace with a custom
@@ -925,14 +966,14 @@ countly.askForStarRating(Function(ratingResult){
you first have to get the widget ID from your server:
-
+
Using that you can call the function to show the widget popup:
-// Feedback Modal
+// Feedback Modal
countly.askForFeedback("5e425407975d006a22535fc", "close");
-User Profiles
+User Profiles
Available with Enterprise Edition, User Profiles is a tool which helps you identify
users, their devices, event timeline and application crash information. User
@@ -951,7 +992,7 @@ countly.askForFeedback("5e425407975d006a22535fc", "close");
After you have provided user profile information, you must save it by calling
Countly.userData.save().
-/ example for setting user data
+/ example for setting user data
var options = {};
options.name = "Nicola Tesla";
options.username = "nicola";
@@ -964,55 +1005,59 @@ options.gender = "Male";
options.byear = 1919;
Countly.setUserData(options);
The keys for predefined user data fields are as follows:
-
-
-
- Key
- Type
- Description
-
-
- name
- String
- User's full name
-
-
- username
- String
- User's nickname
-
-
- email
- String
- User's email address
-
-
- organization
- String
- User's organisation name
-
-
- phone
- String
- User's phone number
-
-
- picture
- String
- URL to avatar or profile picture of the user
-
-
- gender
- String
- User's gender as M for male and F for female
-
-
- byear
- String
- User's year of birth as integer
-
-
-
+
+
+
+
+ Key
+ Type
+ Description
+
+
+
+
+ name
+ String
+ User's full name
+
+
+ username
+ String
+ User's nickname
+
+
+ email
+ String
+ User's email address
+
+
+ organization
+ String
+ User's organisation name
+
+
+ phone
+ String
+ User's phone number
+
+
+ picture
+ String
+ URL to avatar or profile picture of the user
+
+
+ gender
+ String
+ User's gender as M for male and F for female
+
+
+ byear
+ String
+ User's year of birth as integer
+
+
+
+
Using "" for strings or a negative number for 'byear' will effectively delete
that property.
@@ -1022,13 +1067,13 @@ Countly.setUserData(options);
on your Countly backend. Note: keys with . or $ symbols will have those symbols
removed.
-Setting custom values
+Setting custom values
Additionally you can do different manipulations on your custom data values, like
increment current value on server or store a array of values under the same property.
Below is the list of available methods:
-// example for extra user features
+// example for extra user features
Countly.userData.setProperty("setProperty", "My Property");
Countly.userData.increment("increment");
@@ -1043,7 +1088,7 @@ Countly.userData.pullValue("pullValue", "morning");
In the end always call Countly.userData.save() to send them to the server.
-Application Performance Monitoring
+Application Performance Monitoring
Performance Monitoring feature allows you to analyze your application's performance
on various aspects. For more details please see
@@ -1053,20 +1098,20 @@ Countly.userData.pullValue("pullValue", "morning");
Here is how you can utilize Performance Monitoring feature in your apps:
First, you need to enable Performance Monitoring feature::
-Countly.enableApm();
+Countly.enableApm();
// Enable APM features.
With this, Countly SDK will start measuring some performance traces automatically.
Those include app foreground time, app background time. Additionally, custom
traces and network traces can be manually recorded.
-App Start Time
+App Start Time
For the app start time to be recorded, you need to call the
appLoadingFinished method. Make sure this method is called after
init.
-// Example of appLoadingFinished
+// Example of appLoadingFinished
Countly.init("https://try.count.ly", "YOUR_APP_KEY").then((result) => {
Countly.appLoadingFinished();
},(err) => {
@@ -1081,19 +1126,19 @@ Countly.init("https://try.count.ly", "YOUR_APP_KEY").then((result) => {
the app launch time can be recorded only once per app launch. So, the second
and following calls to this method will be ignored.
-Custom traces
+Custom traces
You may also measure any operation you want and record it using custom traces.
First, you need to start a trace by using the
startTrace(traceKey) method:
-Countly.startTrace(traceKey);
+Countly.startTrace(traceKey);
Then you may end it using the
endTrace(traceKey, customMetric)method, optionally
passing any metrics as key-value pairs:
-String traceKey = "Trace Key"
+String traceKey = "Trace Key"
;
Map<String, int> customMetric = {
"ABC": 1233,
@@ -1110,13 +1155,13 @@ Countly.endTrace(traceKey, customMetric);
You may also cancel any custom trace you started, using
cancelTrace(traceKey)method:
-Countly.cancelTrace(traceKey);
+Countly.cancelTrace(traceKey);
Additionally, if you need you may cancel all custom traces you started, using
clearAllTraces()method:
-Countly.clearAllTraces(traceKey);
-Network traces
+Countly.clearAllTraces(traceKey);
+Network traces
You may record manual network traces using theecordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime)
method.
@@ -1136,9 +1181,9 @@ Countly.endTrace(traceKey, customMetric);
time of the request - endTime: UNIX time stamp in milliseconds for
the ending time of the request
-Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
+Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);
-User Consent
+User Consent
To be compliant with GDPR, starting from 18.04, Countly provides ways to toggle
different Countly features on/off depending on the given consent.
@@ -1148,7 +1193,7 @@ Countly.endTrace(traceKey, customMetric);
By default the requirement for consent is disabled. To enable it, you have to
call setRequiresConsent with true, before initializing Countly.
-Countly.setRequiresConsent(true);
+Countly.setRequiresConsent(true);
By default no consent is given. That means that if no consent is enabled, Countly
will not work and no network requests, related to features, will be sent. When
@@ -1175,104 +1220,96 @@ Countly.endTrace(traceKey, customMetric);
The current features are:
- -
+
-
sessions - tracking when, how often and how long users use your app
- - events - allow sending events to server
- - views - allow tracking which views user visits
- - location - allow sending location information
- - crashes - allow tracking crashes, exceptions and errors
- -
+
- events - allow sending events to server
+ - views - allow tracking which views user visits
+ - location - allow sending location information
+ - 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
- - starRating - allow to send their rating and feedback
- - apm - allow application performance monitoring
- -
+
- push - allow push notifications
+ - starRating - allow to send their rating and feedback
+ - apm - allow application performance monitoring
+ -
remote-config - allows downloading remote config values from your server
-Changing consent
+Changing consent
There are 3 ways of changing feature consent:
- -
+
-
giveConsentInit - To add consent for a single feature (string parameter)
or a subset of features (array of strings parameter). Use this method for
giving consent before initializing.
-//giveConsent
+//giveConsent
Countly.giveConsentInit(["events", "views", "star-rating", "crashes"]);
// removeConsent
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);
- -
+
-
giveConsent/removeConsent - gives or removes consent to a specific feature
-//giveConsent
+//giveConsent
Countly.giveConsent(["events", "views", "star-rating", "crashes"]);
// removeConsent
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);
- -
+
-
giveAllConsent/removeAllConsent - giveAll or removeAll consent to a specific
feature
-//giveAllConsent
+//giveAllConsent
Countly.giveAllConsent();
//removeAllConsent
Countly.removeAllConsent();
-Security and privacy
-Parameter Tampering Protection
+Security and privacy
+Parameter Tampering Protection
You can set optional salt to be used for calculating checksum of request data,
which will be sent with each request using &checksum field. You need to set
exactly the same salt on Countly server. If salt on Countly server is set, all
requests would be checked for validity of &checksum field before being processed.
-// sending data with salt
+// sending data with salt
Countly.enableParameterTamperingProtection("salt");
-Using Proguard
+Using Proguard
If you are using Countly Messaging in your Android application, it is recommended
to obfuscate the Countly Messaging classes using Proguard. To do so, please follow
the instructions below:
- -
-
- Locate the app/proguard-rules.pro file within the /android/app/ folder.
-
-
- -
-
Add the following lines to the file:
+ -
+ Locate the app/proguard-rules.pro file within the /android/app/ folder.
+ - Add the following lines to the file:
--keep class ly.count.android.sdk.** { *; }
+-keep class ly.count.android.sdk.** { *; }
- -
-
- If Proguard is not yet configured, you must first enable shrinking and
- obfuscation in the build file. To do so, locate the build.gradle file
- within the /android/app/ folder.
-
-
- -
-
Add the following lines in bold to the build.gradle file:
+ -
+ If Proguard is not yet configured, you must first enable shrinking and obfuscation
+ in the build file. To do so, locate the build.gradle file within the /android/app/
+ folder.
+ - Add the following lines in bold to the build.gradle file:
-...
+...
buildTypes {
release { // Enables code shrinking, obfuscation, and optimization for only your project's release build type.
@@ -1287,8 +1324,8 @@ buildTypes {
By following these steps, the Countly Messaging classes will be obfuscated using
Proguard and your application will be better protected against reverse engineering.
-Other features
-Forcing HTTP POST
+Other features
+Forcing HTTP POST
If the data sent to the server is short enough, the sdk will use HTTP GET requests.
In case you want an override so that HTTP POST is used in all cases, call the
@@ -1296,9 +1333,9 @@ buildTypes {
to later in the apps life cycle disable the override. This function has to be
called every time the app starts.
-Countly.setHttpPostForced(true); // default is false
+Countly.setHttpPostForced(true); // default is false
-Optional parameters during initialization
+Optional parameters during initialization
You can provide optional parameters that will be used during begin_session request.
They must be set right after the init function so that they are
@@ -1310,13 +1347,13 @@ buildTypes {
The optional parameters are:
- - Country code: ISO Country code for the user's country
- - City: Name of the user's city
- -
+
- Country code: ISO Country code for the user's country
+ - City: Name of the user's city
+ -
Location: Comma separate latitude and longitude values, for example "56.42345,123.45325"
-
+
//setting optional parameters
Countly.setOptionalParametersForInitialization({
city: "Tampa",
diff --git a/legacy_docs/cordova/next.md b/legacy_docs/cordova/next.md
index 1cf92837..c40d011a 100644
--- a/legacy_docs/cordova/next.md
+++ b/legacy_docs/cordova/next.md
@@ -1,4 +1,4 @@
-
+
This document will guide you through the process of Countly SDK installation
and it applies to version 22.09.0
Countly is an open source SDK, you can take a look at our SDK code in the
@@ -19,15 +19,15 @@
Github repo.
It should show how most of the functionalities can be used.
-Adding the SDK to the project
+Adding the SDK to the project
The core of this SDK is developed around Cordova. We have a minimum version requirement
for it's core and android, ios modules that have to be satisfied:
- - cordova >= 9.0.0
- - cordova-android >= 8.0.0
- - cordova-ios >= 5.0.0
+ - cordova >= 9.0.0
+ - cordova-android >= 8.0.0
+ - cordova-ios >= 5.0.0
If you would integrate this SDK in any other project similar to cordova (like
@@ -35,9 +35,8 @@
platform requirements for those projects similar to these.
- Note : Development on PhoneGap stopped in
- 14 Aug 2020. To the best of our knowledge, this SDK should still
- be compatible with the final release.
+ Note : Development on PhoneGap stopped in 14 Aug 2020. To the
+ best of our knowledge, this SDK should still be compatible with the final release.
For more information about PhoneGap shut down,
@@ -55,7 +54,7 @@
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
@@ -65,34 +64,34 @@ cordova plugin add countly-sdk-js@20.11.0
If iOS/Android Platform are already added in your project, first remove them
-cordova platform remove android
+cordova platform remove android
cordova platform remove ios
Now add platform of your choice
-cordova platform add android
+cordova platform add android
cordova platform add ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-cordova build android
+cordova build android
ordova build ios
Now run the application directly for Android,
-cordova run android
+cordova run android
Or iOS:
-cordova run ios
+cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
- Ionic
+ Ionic
Add Countly SDK in your Ionic project using following commands:
Note: use the latest SDK version currently available, not specifically
the one shown in the sample below.
-cd PATH_TO_YOUR_PROJECT
+cd PATH_TO_YOUR_PROJECT
ionic cordova plugin add https://github.com/Countly/countly-sdk-cordova.git
@@ -102,39 +101,39 @@ ionic cordova plugin add countly-sdk-js@20.11.0
If iOS/Android Platform are already added in your project, first remove them
-ionic cordova platform remove android
+ionic cordova platform remove android
ionic cordova platform remove ios
Now add platform of your choice
-ionic cordova platform add android
+ionic cordova platform add android
ionic cordova platform add ios
Now prepare the platforms you have added
-ionic cordova prepare android
+ionic cordova prepare android
ionic cordova prepare ios
It's important that you make sure you build it with Cordova, as Cordova links
folders very well.
-ionic cordova build android
+ionic cordova build android
ionic cordova build ios
Now run the application directly for Android,
-ionic cordova run android
+ionic cordova run android
Or iOS:
-ionic cordova run ios
+ionic cordova run ios
Alternatively, you can open the source in Xcode, or Android Studio and move on
with further development.
In your index.html, use the following lines:
-<script type="text/javascript" src="cordova.js"></script>
+