This document will guide you through the process of Countly SDK installation and it applies to version 24.1.X

This document includes the necessary information for integrating Countly Flutter SDK in your application. Flutter SDK requires Android and iOS SDKs, hence all the features and limitations regarding those platforms also apply to Countly Flutter SDK.

Countly is an open source SDK, you can take a look at our SDK code in the Github repo

Supported Platforms: Countly SDK supports iOS and Android.

Below you can see steps to download the Countly Flutter example application. It assumes Flutter is installed in your system:

# clone the Countly SDK repository
git clone https://github.com/Countly/countly-sdk-flutter-bridge.git

# dive into the cloned repo
cd countly-sdk-flutter-bridge/example

# install packages and run
flutter pub get
flutter run

This example application has most of the methods mentioned in this documentation, and it is an excellent way to understand how different methods work, like events, custom user profiles, and views.

Adding the SDK to the project

Add this to your project's pubspec.yaml file:

dependencies:
  countly_flutter: ^24.1.0

After you can install packages from the command line with Flutter:

flutter pub get

SDK Integration

Minimal setup

The shortest way to initialize the SDK, if you want Countly SDK to take care of device ID seamlessly, is to use the code below.

Countly.isInitialized().then((bool isInitialized){
  if(!isInitialized) {
    // Create the configuration with your app key and server URL
    CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);

    // Initialize with that configuration
    Countly.initWithConfig(config).then((value){
      Countly.start(); // Enables automatic view tracking
    });
  } else {
    print("Countly: Already initialized.");
  }
});

Please check here for more information on how to acquire your application key (APP_KEY) and server URL.

A "CountlyConfig" object is used to configure the SDK during initialization. As shown above, you would create a "CountlyConfig" object and then call its provided methods to enable the functionalities you need before initializing the SDK.

Click here for more information about the "CountlyConfig" object functionalities.

Enable logging

If logging is enabled, then our SDK will print out debug messages about its internal state and encountered problems.

We advise doing this while implementing Countly features in your application.

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setLoggingEnabled(true);

For more information on where to find the SDK logs you can check the documentation here.

SDK data storage

SDK data storage locations are platform-specific:

• For iOS, the SDK data is stored in the Application Support Directory in a file named "Countly.dat"
• For Android, the SDK data is stored in SharedPreferences. A SharedPreferences object points to a file containing key-value pairs and provides simple reading and writing methods.

Crash reporting

This feature allows the Countly SDK to record crash reports of either encountered issues or exceptions which cause your application to crash. Those reports will be sent to your Countly server for further inspection.

If a crash report can not be delivered to the server (e.g. no internet connection, unavailable server), then SDK stores the crash report locally in order to try again later.

Automatic crash handling

If you want to enable automatic unhandled crash reporting, you need to call this before init:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.enableCrashReporting()

By doing that it will automatically catch all errors that are thrown from within the Flutter framework.

If you want to catch Dart errors, run your app inside a Zone and supply Countly.recordDartError to the onError parameter:

void main() {
  runZonedGuarded<Future<void>>(() async {
    runApp(MyApp());
  }, Countly.recordDartError);
}

Automatic crash report segmentation

You may add a key/value segment to crash reports. For example, you could set which specific library or framework version you used in your app. You may then figure out if there is any correlation between the specific library or another segment and the crash reports.

The following call will add the provided segmentation to all recorded crashes. Use the following function for this purpose:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setCustomCrashSegment(Map<String, Object> segments);

Handled exceptions

There are multiple ways you could report a handled exception/error to Countly.

This call does not add a stacktrace automatically. If it is required, it should be provided to the function. A potential use case would be to exception.toString()

Countly.logException(String exception, bool nonfatal, [Map<String, Object> segmentation])

The issue is recorded with a provided Exception object. If no stacktrace is set,StackTrace.current will be used.

Countly.logExceptionEx(Exception exception, bool nonfatal, {StackTrace stacktrace, Map<String, Object> segmentation})

The exception/error is recorded through a string message. If no stack trace is provided, StackTrace.current will be used.

Countly.logExceptionManual(String message, bool nonfatal, {StackTrace stacktrace, Map<String, Object> segmentation})

Below are some examples that how to log handled/nonfatal and unhandled/fatal exceptions manually.

1. Manually report exception

bool nonfatal = true; // Set it false in case of fatal exception
// With Exception object
Countly.logExceptionEx(EXCEPTION_OBJECT, nonfatal);

// With String message
Countly.logExceptionManual("MESSAGE_STRING", nonfatal);

2. Manually report exception with stack trace

bool nonfatal = true; // Set it false in case of fatal exception
// With Exception object
Countly.logExceptionEx(EXCEPTION_OBJECT, nonfatal, stacktrace: STACK_TRACE_OBJECT);

// With String message
Countly.logExceptionManual("MESSAGE_STRING", nonfatal, stacktrace: STACK_TRACE_OBJECT);

3. Manually report exception with segmentation

bool nonfatal = true; // Set it false in case of fatal exception
// With Exception object
Countly.logExceptionEx(EXCEPTION_OBJECT, nonfatal, segmentation: {"_facebook_version": "0.0.1"});

// With String message
Countly.logExceptionManual("MESSAGE_STRING", nonfatal, segmentation: {"_facebook_version": "0.0.1"});

4. Manually report exception with stack trace and segmentation

bool nonfatal = true; // Set it false in case of fatal exception
// With Exception object
Countly.logExceptionEx(EXCEPTION_OBJECT, nonfatal, STACK_TRACE_OBJECT, {"_facebook_version": "0.0.1"});

// With String message
Countly.logExceptionManual("MESSAGE_STRING", nonfatal, STACK_TRACE_OBJECT, {"_facebook_version": "0.0.1"});

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.

The following function call adds a crash breadcrumb:

Countly.addCrashLog(String logs)

Events

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 get much more information from your application compared to what is sent from Flutter SDK to Countly instance by default.

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 will be ignored.

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 a purchase event occurred.
• Usage 2: how many times a purchase event occurred + the total amount of those purchases.
• Usage 3: how many times a purchase event occurred + which countries and application versions those purchases were made from.
• Usage 4: how many times a 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 (under Timed Events topic below).

1. Event key and count

// example for sending basic event
var event = {
  "key": "Basic Event",
  "count": 1
};

Countly.recordEvent(event);

2. Event key, count and sum

// example for event with sum
var event = {
  "key": "Event With Sum",
  "count": 1,
  "sum": "0.99",
};

Countly.recordEvent(event);

3. Event key and count with segmentation(s)

// example for event with segment
var event = {
  "key": "Event With Segment",
  "count": 1
};

event["segmentation"] = {
  "Country": "Germany",
  "Age": "28"
};

Countly.recordEvent(event);

4. Event key, count and sum with segmentation(s)

// example for event with segment and sum
var event = {
  "key": "Event With Sum And Segment",
  "count": 1,
  "sum": "0.99"
};

event["segmentation"] = {
  "Country": "Germany",
  "Age": "28"
};

Countly.recordEvent(event);

5. Event key, count, sum and duration with segmentation(s)

// example for event with segment and sum
var event = {
  "key": "Event With Sum And Segment",
  "count": 1,
  "sum": "0.99",
  "duration": "0"
};

event["segmentation"] = {
  "Country": "Germany",
  "Age": "28"
};

Countly.recordEvent(event);

Timed events

It's possible to create timed events by defining a start and a stop moment.

1.Timed event with key

// Basic event
Countly.startEvent("Timed Event");

Timer timer = Timer(new Duration(seconds: 5), () {
  Countly.endEvent({ "key": "Timed Event" });
});

2.Timed event with key and sum

// Event with sum
Countly.startEvent("Timed Event With Sum");

Timer timer = Timer(new Duration(seconds: 5), () {
  Countly.endEvent({ "key": "Timed Event With Sum", "sum": "0.99" });
});

3.Timed event with key, count and segmentation

// Event with segment
Countly.startEvent("Timed Event With Segment");

Timer timer = Timer(new Duration(seconds: 5), () {
  var event = {
    "key": "Timed Event With Segment",
    "count": 1,
  };
  event["segmentation"] = {
    "Country": "Germany",
    "Age": "28"
  };
  Countly.endEvent(event);
});

4.Timed event with key, count, sum and segmentation

// Event with Segment, sum and count
Countly.startEvent("Timed Event With Segment, Sum and Count");

Timer timer = Timer(new Duration(seconds: 5), () {
  var event = {
    "key": "Timed Event With Segment, Sum and Count",
    "count": 1,
    "sum": "0.99"
  };
  event["segmentation"] = {
    "Country": "Germany",
    "Age": "28"
  };
  Countly.endEvent(event);
});

Sessions

Automatic session tracking

Automatic sessions tracks user activity with respect to the app visibility. Basically it handles making certain requests to the server to inform it about the user session. Automatic sessions are enabled by default and SDK handles the necessary calls (by sending start session, update session and end session requests) to track a session automatically. This is how it works:

• Start/Begin session Request: It is sent to the server 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.

Manual sessions

Sometimes, it might be preferable to control the session manually instead of relying on the SDK.

It can be enabled during init with:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.enableManualSessionHandling();

Afterwards it is up to the implementer to make calls to:

• Begin session (Starts a session)
• Update session duration (By default, you would call this every 60 seconds after beginning a session so that it is not closed server side. If you would want to increase that duration, you would have to increase the "Maximal Session Duration" in your server API configuration)
• End session (Ends and updates duration)

You can use the 'sessions interface' to make these calls:

Countly.instance.sessions.beginSession();
Countly.instance.sessions.updateSession();
Countly.instance.sessions.endSession();

View tracking

Manual view recording

You can manually track views in your application.

When starting a view it would return an ID. This ID can be used to further interract with the view to pause, resume and stop it. You can start multiple views with the same name. The ID is used to uniquely identify the view.

Views will be automatically paused when going to the background, and resumed when coming back.

Auto Stopped Views

If you want to start a view that will be automatically stopped when starting another view, use the following method:

// record a view on your application
final String? viewID = await Countly.instance.views.startAutoStoppedView("Dashboard");

You can also specify the custom segmentation key-value pairs while starting views:

Map<String, Object> segmentation = {
  "Cats": 123,
  "Moons": 9.98,
  "Moose": "Deer"
};

final String? anotherViewID = Countly.instance.views.startAutoStoppedView("HomePage", segmentation);

Regular Views

Opposed to "auto stopped views", with regular views you can have multiple of them started at the same time, and then you can control them independently. You can manually start a view using the startViewmethod with a view name. This will start tracking a view and return a unique identifier, and the view will remain active until explicitly stopped using stopViewWithName or stopViewWithID

// record a view on your application
Countly.instance.views.startView("HomePage");
final String? viewID = await Countly.instance.views.startView("Dashboard");

You can also specify the custom segmentation key-value pairs while starting views:

Map<String, Object> segmentation = {
  "Cats": 123,
  "Moons": 9.98,
  "Moose": "Deer"
};

final String? anotherViewID = Countly.instance.views.startView("HomePage", segmentation);

Stopping Views

Stopping a view can either be done using the view id or the name. If there are multiple views with the same name (they would have different identifiers) and you try to stop one with that name, the SDK would close one of those randomly.

Below you can see example ways of stopping views.

Countly.instance.views.stopViewWithName("HomePage");

This function allows you to manually stop the tracking of a view identified by its name. You can also specify the custom segmentation key-value pairs while stopping views:

Countly.instance.views.stopViewWithName("HomePage", segmentation);

You can also stop view tracking by its unique idetifier using stopViewWithID

Countly.instance.views.stopViewWithID(viewID);

You can also specify the custom segmentation key-value pairs while stopping views:

Countly.instance.views.stopViewWithID(anotherViewID, segmentation);

You can stop all views tracking using stopAllViews

Countly.instance.views.stopAllViews();

You can also specify the custom segmentation key-value pairs while stopping all views:

Countly.instance.views.stopAllViews(segmentation);

Pausing and Resuming Views

This SDK allows you to start multiple views at the same time. If you are starting multiple views at the same time it might be necessary for you to pause some views while others are still continuing. This can be achieved by using the unique identifier you get while starting a view.

You can pause view tracking by its unique identifier using pauseViewWithID

Countly.instance.views.pauseViewWithID(viewID);

This function temporarily pauses the tracking of a view identified by its unique identifier.

You can resume view tracking by its unique identifier using resumeViewWithID:

Countly.instance.views.resumeViewWithID(viewID);

This function resumes the tracking of a view identified by its unique identifier.

Adding Segmentation to Started Views

Once a view has been started (but before it has been ended), you can add segmentation to a view either with its name or its ID.

Here is an example on how to achieve that using the view name:

Map<String, Object> segmentation = {
  "Cats": 123,
  "Moons": 9.98,
  "Moose": "Deer"
};
Countly.instance.views.addSegmentationToViewWithName(viewName, segmentation);

Here is an example for how to add segmentation to a view using its ID:

Map<String, Object> segmentation = {
  "Cats": 123,
  "Moons": 9.98,
  "Moose": "Deer"
};
Countly.instance.views.addSegmentationToViewWithID(viewID, segmentation);

Global View Segmentation

It is possible to set global segmentation for all recorded views. This can be done either during initialization or subsequently. Segmentation provided with the start or stop calls will take precedence, and neither of them can override segmentation keys used by the SDK internally for views.

For setting global segmentation values during SDK initialization, use the following method:

// set global segmentation at initialization
final CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setGlobalViewSegmentation(segmentation);

If you want to change the segmentation after initialization, you can use one of the following methods.

ThesetGlobalViewSegmentation method will replace the previously set values..

Countly.instance.views.setGlobalViewSegmentation(segmentation);

The updateGlobalViewSegmentation method will modify the previously set values and overwrite any previously set keys.

Countly.instance.views.updateGlobalViewSegmentation(segmentation);

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 in mind that it has to be unique for all users. Some potential sources for such an id could be the username, email or some other internal ID used by your other systems.

You may provide your own custom device ID when initializing the SDK

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setDeviceId(DEVICE_ID);

Changing the Device ID

You may configure/change the device ID anytime using:

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.

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:

Countly.init(SERVER_URL, APP_KEY, Countly.deviceIDType["TemporaryDeviceID"])

To enable a temporary device ID after init, you would call:

Countly.changeDeviceId(Countly.deviceIDType["TemporaryDeviceID"], ON_SERVER);

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.

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

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:

String currentDeviceId = Countly.getCurrentDeviceId();

You can use getDeviceIDType method which returns a DeviceIDType to get the current device ID type. The id type is an enum with the possible values of:

• "DEVELOPER_SUPPLIED" - device ID was supplied by the host app.
• "SDK_GENERATED" - device ID was generated by the SDK.
• "TEMPORARY_ID" - the SDK is in temporary device ID mode.

DeviceIdType? deviceIdType = await Countly.getDeviceIDType();

Device ID generation

When the SDK is initialized for the first time with no device ID, then SDK will generate a device ID.

Here are the underlying mechanisms used to generate that value for some platforms:

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.

Push notifications

Countly gives you the ability to send Push Notifications to your users using your app with the Flutter SDK integration. For more information on how to best use this feature you can check this article.

To make this feature work you will need to make some configurations both in your app and at your Countly server. Both platforms (Android and iOS) would need different steps to integrate Push Notification feature into your application, as explained below.

Integration

Android setup

Step 1: For FCM credentials setup please follow the instruction from here.

Step 2: Make sure you have google-services.json from https://firebase.google.com/

Step 3: Make sure the app package name and the google-services.json package_name matches.

Step 4: Place the google-services.json file inside android/app

Step 5: Add the following line in file android/app/src/main/AndroidManifest.xml inside application tag.

<application ...>
...
  <service android:name="ly.count.dart.countly_flutter.CountlyMessagingService">
    <intent-filter>
      <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
  </service>
</application>

Step 6: Add the following line in file android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
    }
}

You can get the latest version from here and here.

Step 7: Add the following line in file android/app/build.gradle

dependencies {
  implementation 'ly.count.android:sdk:22.02.1'
  implementation 'com.google.firebase:firebase-messaging:20.0.0'
}
// Add this at the bottom of the file
apply plugin: 'com.google.gms.google-services'

iOS setup

First, you will need to acquire Push Notification credentials from Apple. (If you don't have them you can check this article to learn how you can do it.)

Then you would need to upload these credentials to your Countly server. You can refer to this article for learning how you can do that.

Finally, under the Capabilities section of Xcode, enable Push Notifications and the Remote notifications Background Mode for your target.

For Swift projects you might need to make sure Bridging Header File is configured properly for each target as explained here. For this purpose you can find CountlyNotificationService.h/m file under:

Pods/Development Pods/Countly/{PROJECT_NAME}/ios/.symlinks/plugins/countly_flutter/ios/Classes/CountlyiOS/CountlyNotificationService.h/m

Some tips to find the files from deep hierarchy:

• You can filter the files in the navigator using a shortcut ⌥⌘J (Option-Command-J), in the filter box type "CountlyNotificationService" and it will show the related files only.
• You can find the file using the shortcut ⇧⌘O (Shift-Command-O) and then navigate to that file using the shortcut ⇧⌘J (Shift-Command-J)

You can drag and drop the file from Pod to Compile Sources.

Enabling push

First, when setting up push for the Flutter 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
Countly.pushTokenType(Countly.messagingMode["TEST"]);

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.
Countly.askForNotificationPermission();

Also it is important to note that push notification is enabled for iOS by default, so to disable you need to call disablePushNotifications method:

// Disable push notifications feature for iOS, by default it is enabled.
Countly.disablePushNotifications();

Removing Push and Its Dependencies

Countly Flutter SDK comes with push notification capabilities embedded. For the flavor without the push notifications features (like Firebase libraries) please check here.

Handling push callbacks

To register a Push Notification callback after initializing the SDK, use the method below.

Countly.onNotification((String notification) {
  print(notification);
});

In order to listen to notification receive and click events, Place below code in AppDelegate.swift

Add header files

import countly_flutter

Add these methods:

// Required for the notification event. You must call the completion handler after handling the remote notification.
func application(application: UIApplication,  didReceiveRemoteNotification userInfo: [NSObject : AnyObject],  fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {
  CountlyFlutterPlugin.onNotification(userInfo);
  completionHandler(.newData);
}

@available(iOS 10.0, \*)
override func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (_ options: UNNotificationPresentationOptions) -> Void) {

  //Called when a notification is delivered to a foreground app.

  let userInfo: NSDictionary = notification.request.content.userInfo as NSDictionary
  CountlyFlutterPlugin.onNotification(userInfo as? [AnyHashable : Any])
}

@available(iOS 10.0, \*)
override func userNotificationCenter(\_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {

  // Called to let your app know which action was selected by the user for a given notification.
  let userInfo: NSDictionary = response.notification.request.content.userInfo as NSDictionary
  // print("\(userInfo)")
  CountlyFlutterPlugin.onNotification(userInfo as? [AnyHashable : Any])
}

Data Structure Received 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"
}

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

Countly allows you to send geolocation-based push notifications to your users. By default, the Countly Server uses the GeoIP database to deduce a user's location.

Set User Location

If your app has a different way of detecting location, you may send this information to the Countly Server by using the setLocation of  CountlyConfig during init orsetUserLocation method after init.

When setting user location information, you would be setting these values:

• countryCode a string in ISO 3166-1 alpha-2 format country code
• city a string specifying city name
• location a string comma-separated latitude and longitude
• IP a string specifying an IP address in IPv4 or IPv6 formats

All values are optional, but at least one should be set.

// Example for setLocation
CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setLocation(country_code: 'TR', city: 'Istanbul', gpsCoordinates: '41.0082,28.9784', ipAddress: '10.2.33.12')

Geolocation recording methods may also be called at any time after the Countly SDK has started. To do so, use the setUserLocation method as shown below.

// Example for setUserLocation
Countly.setUserLocation(countryCode: 'TR', city: 'Istanbul', gpsCoordinates: '41.0082,28.9784', ipAddress: '10.2.33.12');

Disable Location

To erase any cached location data from the device and stop further location tracking, use the following method. Note that if after disabling location, the setUserLocation is called with any non-null value, tracking will resume.

//disable location tracking
Countly.disableLocation();

Remote Config

Remote config allows you to modify how your app functions or looks by requesting key-value pairs from your Countly server. The returned values may be modified based on the user properties. For more details, please see the Remote Config documentation.

Once downloaded, Remote config values will be saved persistently and available on your device between app restarts unless they are erased.

The two ways of acquiring remote config data are enabling automatic download triggers or manual requests.

If a full download of remote config values is performed, the previous list of values is replaced with the new one. If a partial download is performed, only the retrieved keys are updated, and values that are not part of that download stay as they were. A previously valid key may return no value after a full download.

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY)
  ..enableRemoteConfigAutomaticTriggers(); // necessary to enable the feature

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY) 
  ..enableRemoteConfigValueCaching(); 

Manually Calls

There are three ways to trigger remote config value download manually:

• Manually downloading all keys
• Manually downloading specific keys
• Manually downloading, omitting (everything except) keys.

Each of these calls also has an optional parameter that you can provide a RCDownloadCallback to, which would be triggered when the download attempt has finished.

dowloadAllKeys is the same as the automatically triggered update - it replaces all stored values with the ones from the server (all locally stored values are deleted and replaced with new ones).

Or you might only want to update specific key values. To do so, you will need to call downloadSpecificKeys to downloads new values for the wanted keys. Those are provided with a String array.

Or you might want to update all the values except a few defined keys. To do so,  call downloadOmittingKeys would update all values except the provided keys. The keys are provided with a String array.

Countly.instance.remoteConfig.downloadAllKeys((rResult, error, fullValueUpdate, downloadedValues) {
  if (rResult == RequestResult.Success) {
    // do sth
  } else {
    // do sth
  }
});

Countly.instance.remoteConfig.downloadSpecificKeys(List<String> keysToInclude, (rResult, error, fullValueUpdate, downloadedValues) {
  if (rResult == RequestResult.Success) {
    // do sth
  } else {
    // do sth
  }
});

Countly.instance.remoteConfig.downloadOmittingKeys(List<String> keysToExclude, (rResult, error, fullValueUpdate, downloadedValues) {
  if (rResult == RequestResult.Success) {
    // do sth
  } else {
    // do sth
  }
});

When making requests with an "inclusion" or "exclusion" array, if those arrays are empty or null, they will function the same as a dowloadAllKeys request and will update all the values. This means it will also erase all keys not returned by the server.

Accessing Values

To get a stored value, call getValue with the specified key. This returns an Future<RCData> object that contains the value of the key and the metadata about that value's owner. If value in RCData was null then no value was found or the value was null.  

Object? value_1 = await Countly.instance.remoteConfig.getValue("key_1").value;
Object? value_2 = await Countly.instance.remoteConfig.getValue("key_2").value;
Object? value_3 = await Countly.instance.remoteConfig.getValue("key_3").value;
Object? value_4 = await Countly.instance.remoteConfig.getValue("key_4").value;

int intValue = value1 as int;
double doubleValue = value2 as double;
JSONArray jArray = value3 as JSONArray;
JSONObject jObj = value4 as JSONObject;

If you want to get all values together you can use getAllValues which returns a Future<Map<String, RCData>>. The SDK does not know the returned value type, so, it will return the Object. The developer then needs to cast it to the appropriate type. The returned values may also be JSONArray, JSONObject, or just a simple value, such as int.

Map<String, RCData> allValues = await Countly.instance.remoteConfig.getAllValues();

int intValue = allValues["key_1"] as int;
double doubleValue = allValues["key_2"] as double;
JSONArray jArray = allValues["key_3"] as JSONArray;
JSONObject jObj = allValues["key_4"] as JSONObject;

RCData object has two keys: value (Object) and isCurrentUsersData (Boolean). Value holds the data sent from the server for the key that the RCData object belongs to. The isCurrentUsersData is only false when there was a device ID change, but somehow (or intentionally) a remote config value was not updated.

Class RCData {
  Object value;
  Boolean isCurrentUsersData;
}

Clearing Stored Values

At some point, you might like to erase all the values downloaded from the server. You will need to call one function to do so.

Countly.instance.remoteConfig.clearAll();

Global Download Callbacks

Also, you may provide a global callback function to be informed when the remote config download request is finished with remoteConfigRegisterGlobalCallback during the SDK initialization:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY) 
  ..remoteConfigRegisterGlobalCallback((rResult, error, fullValueUpdate, downloadedValues) {
    if (error != null) {
      // do sth
    }
  })

RCDownloadCallback is called when the remote config download request is finished, and it would have the following parameters:

• rResult: RequestResult Enum (either Error, Success or NetworkIssue)
• error: String (error message. "null" if there is no error)
• fullValueUpdate: boolean ("true" - all values updated, "false" - a subset of values updated)
• downloadedValues: Map<String, RCData> (the whole downloaded remote config values)

RCDownloadCallback {
  void callback(RequestResult rResult, String error, boolean fullValueUpdate, Map<String, RCData> downloadedValues)
}

downloadedValues would be the downloaded remote config data where the keys are remote config keys, and their value is stored in RCData class with metadata showing to which user data belongs. The data owner will always be the current user.

You can also register (or remove) callbacks to do different things after the SDK initialization. You can register these callbacks multiple times:

// register a callback
Countly.instance.remoteConfig.registerDownloadCallback((rResult, error, fullValueUpdate, downloadedValues) {
  // do sth
});

// remove a callback
Countly.instance.remoteConfig.removeDownloadCallback((rResult, error, fullValueUpdate, downloadedValues) {
  // do sth
});

A/B Testing

You can enroll your users into into A/B tests for certain keys or remove them from some or all existing A/B tests available.

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY)
..enrollABOnRCDownload();

Countly.instance.remoteConfig.enrollIntoABTestsForKeys(List<String> keys);

If you want to remove users from A/B tests of certain keys you can use the following function:

Countly.instance.remoteConfig.exitABTestsForKeys(List<String> keys);

Here if no keys are provided it would remove the user from all A/B tests instead.

User feedback

There are a couple ways of receiving feedback from your users: star-rating dialog, the rating widget and the feedback widgets (survey, nps).

Star-rating dialog allows users to give feedback as a rating from 1 to 5. The rating widget allows users to rate using the same 1 to 5 rating system as well as leave a text comment. Feedback widgets (survey, nps) allow for even more textual feedback from users.

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 1-to-5 star meter for getting users rating and a dismiss button in case the user does not want to give a rating.

This star-rating has nothing to do with Google Play Store ratings and reviews. It is just for getting brief feedback from users, to be displayed on the Countly dashboard. If the user dismisses star rating dialog without giving a rating, the event will not be recorded.

Countly.askForStarRating();

The star-rating dialog's title, message, and dismiss button text may be customized either through the following functions:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setStarRatingTextTitle("Custom title"); // Only available for Android
config.setStarRatingTextMessage("Custom message");
config.setStarRatingTextDismiss("Custom message"); // Only available for Android

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 them with a custom string of your choice.

In addition to a 1 to 5 rating, it is possible for users to leave a text comment and also leave an email in case the user would want some contact from the app developer.

Trying to show the rating widget is a single call, but underneath is a two-step process. Before it is shown, the SDK tries to contact the server to get more information about the dialog. Therefore a network connection to it is needed.

You can try to show the widget after you have initialized the SDK. To do that, you first have to get the widget ID from your server:

Using that you can call the function to show the widget popup:

Countly.presentRatingWidgetWithID(RATING_WIDGET_ID, closeButtonText: "close", ratingWidgetCallback: (error) {
  if(error != null) {
    print(error);
  }
});

closeButtonText and ratingWidgetCallback are optional.

Feedback Widget

It is possible to display 2 kinds of Surveys widgets: NPS and Surveys. Both widgets are shown as webviews and they both use the same code methods.

Before any Surveys widget can be shown, you need to create them in your Countly Dashboard.

When the widgets are created, you need to use 2 calls in your SDK: one to get all available widgets for a user and another to display a chosen widget.

To get your available widget list, use the call below.

FeedbackWidgetsResponse feedbackWidgetsResponse = await Countly.getAvailableFeedbackWidgets() ;

From the callback you would get FeedbackWidgetsResponse object which contains the list of all available widgets that apply to the current device id.

The objects in the returned list look like this:

class CountlyPresentableFeedback {
  public String widgetId;
  public String type;
  public String name;
}

To determine what kind of widget that is, check the "type" value. The potential values are "survey" and "nps".

Then use the widget type and description (which is the same as provided in the Dashboard) to decide which widget to show.

After you have decided which widget you want to display, call the function below.

You would then use the widget type and description (which is the same as provided in the dashboard) to decide which widget to show.

After you have decided which widget you want to display, you would provide that object to the following function:

await Countly.presentFeedbackWidget(widgets.first, 'Close', widgetShown: () {
  print('Widget Appeared');
}, widgetClosed: () {
  print('Widget Dismissed');
});

widgetShown and widgetClosed are optional callbacks, you can pass these callbacks if you want to perform some actions when widget appear or dismiss.

Manual Reporting

There might be some use-cases where you might to use the native UI or a custom UI you have created instead of our webview solution. In those cases you would have to request all the widget related information and then report the result manually.

For a sample integration, have a look at our sample app in the repo.

First you would need to retrieve the available widget list with the previously mentioned getAvailableFeedbackWidgets call. After that you would have a list of possible CountlyPresentableFeedback objects. You would pick the one widget you would want to display.

Having the CountlyPresentableFeedback object of the widget you would want to display, you could use the 'getFeedbackWidgetData'  method to retrieve the widget information with an optional 'onFinished' callback. In case you want to use with callback then you can call 'getFeedbackWidgetData' in this way:

Countly.getFeedbackWidgetData(chosenWidget, onFinished: (retrievedWidgetData, error) {
  if (error == null) {
  }
});

If you want to use it without a callback then you can call 'getFeedbackWidgetData' in this way:

List result = await Countly.getFeedbackWidgetData(chosenWidget);
String? error = result[1];
if (error == null) {
  Map<String, dynamic> retrievedWidgetData = result[0];
}

retrievedWidgetData would contain a Map with all of the required information to present the widget yourself.

After you have collected the required information from your users, you would package the responses into a Map<String, Object> and then use it, the widgetInformation and the widgetData to report the feedback result with the following call:

//this contains the reported results
Map<String, Object> reportedResult = {};

//
// You would fill out the results here. That step is not displayed in this sample
//

//report the results to the SDK
Countly.reportFeedbackWidgetManually(chosenWidget, retrievedWidgetData , reportedResult);

If the user would have closed the widget, you would report that by passing a "null" reportedResult.

For more information regarding how to structure the reported result, you would look here.

User Profiles

Using the following calls, you can set key/value to the visitors user profile. After you send user data, it can be viewed under the User Profiles menu.

Note that this feature is available only for Enterprise Edition.

You would call Countly.instance.userProfile.to see the available functionality for modifying user properties.

Setting User profile values during init

If possible set user properties during initialization. This way they would be reflected when the session is started shortly.

Using the following call, you can set both the predefined and the custom user properties during initialization:

var userProperties = {
  "customProperty": "custom Value",
  "username": "USER_NAME",
  "email": "USER_EMAIL"
};
CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setUserProperties(userProperties); 

Setting User profile values

Ther following calls can be used after init.

If you want to set a single property, you can call Countly.userProfile.setUserProperty(key, value)

Countly.instance.userProfile.setProperty("specialProperty", "value");
Countly.instance.userProfile.save();

If you want to set multiple properties at the same time, you can use: Countly.userProfile.setUserProperties(userProperties)

// example for setting user data
Map<String, Object> userProperties= {
  "name": "Nicola Tesla",
  "username": "nicola",
  "email": "info@nicola.tesla",
  "organization": "Trust Electric Ltd",
  "phone": "+90 822 140 2546",
  "picture": "http://images2.fanpop.com/images/photos/3300000/Nikola-Tesla-nikola-tesla-3365940-600-738.jpg",
  "picturePath": "",
  "gender": "M", // "F"
  "byear": "1919",
  "special_value": "something special"
};
Countly.instance.setUserProperties(userProperties);
Countly.instance.userProfile.save();

After you have provided the user profile information, you must save it by calling Countly.userProfile.save(). This would then create a request and send it to the server.

If you changed your mind and want to clear the currently prepared values, call Countly.userProfile.clear()before calling "save".

Modifying custom data

Additionally, you can do different manipulations on your custom data values, like increment current value on the server or store an array of values under the same property.

Below is the list of available methods:

//increment used value by 1
Countly.instance.increment("increment");
//increment used value by provided value
Countly.instance.incrementBy("incrementBy", 10);
//multiply value by provided value
Countly.instance.multiply("multiply", 20);
//save maximal value
Countly.instance.saveMax("saveMax", 100);
//save minimal value
Countly.instance.saveMin("saveMin", 50);
//set value if it does not exist
Countly.instance.setOnce("setOnce", 200);

//insert value to array of unique values
Countly.instance.pushUnique("type", "morning");;
//insert value to array which can have duplocates
Countly.instance.push("type", "morning");
//remove value from array
Countly.instance.pull("type", "morning");

Application Performance Monitoring

The SDK provides manual and automatic mechanisms for Application Performance Monitoring (APM). All of the automatic mechanisms are disabled by default and to start using them you would first need to enable them and give the required consent if it was required:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);

// this interface exposes the available APM features and their modifications.
config.apm. 

While using APM calls, you have the ability to provide trace keys by which you can track those parameters in your dashboard.

Custom Traces

Currently, you can use custom traces to record the duration of application processes. At the end of them, you can also provide any additionally gathered data.

The trace key uniquely identifies the thing you are tracking and the same name will be shown in the dashboard. The SDK does not support tracking multiple events with the same key.

To start a custom trace, use:

Countly.startTrace(traceKey);

To end a custom trace, use:

String traceKey = "Trace Key";
Map<String, int> customMetric = {
  "ABC": 1233,
  "C44C": 1337
};
Countly.endTrace(traceKey, customMetric);

In this sample, a Map of integer values is provided when ending a trace. Those will be added to that trace in the dashboard.

Network Traces

You can use the APM to track your requests. You would record the required info for your selected approach of making network requests and then call this after your network request is done:

Countly.recordNetworkTrace(networkTraceKey, responseCode, requestPayloadSize, responsePayloadSize, startTime, endTime);

networkTraceKey is a unique identifier of the API endpoint you are targeting or just the url you are targeting, all params should be stripped. You would also provide the received response code, sent payload size in bytes, received payload size in bytes, request start time timestamp in milliseconds, and request end finish timestamp in milliseconds.

Automatic Device Traces

There are a couple of performance metrics the SDK can gather for you automatically. These are:

• App Start Time
• App Background and Foreground time

Tracking of these metrics are disabled by default and must be explicitly enabled by the developer during init.

For tracking app start time automatically you will need to enable it in SDK init config:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);

// enable it here separately with 'apm' interface.
config.apm.enableAppStartTimeTracking();

This calculates and records the app launch time for performance monitoring.

If you want to determine when the end time for this calculation should be you, will have to enable the usage of manual triggers together with enableAppStartTimeTracking during init:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);

// enable it here separately with 'apm' interface.
config.apm.enableAppStartTimeTracking().enableManualAppLoadedTrigger();

Now you can call Countly.appLoadingFinished() any time after SDK initialization to record that moment as the end of app launch time. The starting time of the app load will be automatically calculated and recorded. Note that the app launch time can be recorded only once per app launch. So, the second and following calls to this method will be ignored.

If you also want to manipulate the app launch starting time instead of using the SDK calculated value then you will need to call a third method on the config object with the timestamp (in milliseconds) of that time you want:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);

// generate the timestamp you want (or you can directly pass a ts)
int ts = DateTime.now().millisecondsSinceEpoch - 500; // 500 ms ago as an example

// this would also work with manual trigger
config.apm.enableAppStartTimeTracking().setAppStartTimestampOverride(ts);

Lastly if you want to enable the SDK to record the time an app is in foreground or background automatically you would need to enable this option during init:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);

// enable it here separately with 'apm' interface.
config.apm.enableForegroundBackgroundTracking();

User consent

For compatibility with data protection regulations, such as GDPR, the Countly Flutter SDK allows developers to enable/disable any feature at any time depending on user consent. More information about GDPR can be found here.

Currently, available features with consent control are as follows:

• sessions - tracking when, how often and how long users use your app.
• events - allow sending events to the 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
• star-rating - allow sending their rating and feedback
• apm - allow application performance monitoring
• remote-config - allows downloading remote config values from your server

Setup During Init

By default the requirement for consent is disabled. To enable it, you have to call setRequiresConsent with true, before initializing Countly.

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.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 the consent status of a feature is changed, that change will be sent to the Countly server.

To give consent during initialization, you have to call setConsentEnabledon the config object with an array of consent values.

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setConsentEnabled(["location", "sessions", "attribution", "push", "events", "views", "crashes", "users", "push", "star-rating", "apm", "feedback", "remote-config"])

The Countly SDK does not persistently store the status of given consents except push notifications. You are expected to handle receiving consent from end-users using proper UIs depending on your app's context. You are also expected to store them either locally or remotely. Following this step, you will need to call the giveConsent method on each app launch depending on the permissions you managed to get from the end-users.

Ideally you would give consent during initialization.

Changing Consent

The end-user can change their mind about consents at a later time.

To reflect these changes in the Countly SDK, you can use the removeConsent or giveConsent methods.

//give consent values after init
Countly.giveConsent(["events", "views", "star-rating", "crashes"]);

//remove consent values after init
Countly.removeConsent(["events", "views", "star-rating", "crashes"]);

You can also either give or remove consent to all possible SDK features:

//give consent to all features
Countly.giveAllConsent();

//remove consent from all features
Countly.removeAllConsent();

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 the Countly server. If salt on Countly server is set, all requests would be checked for the validity of &checksum field before being processed.

// sending data with salt
CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setParameterTamperingProtectionSalt("salt");

Make sure not to use salt on the Countly server and not on the SDK side, otherwise, Countly won't accept any incoming requests.

Using Proguard

Proguard obfuscates the Countly Messaging classes. If you use Countly Messaging in your application, find app/proguard-rules.pro file which sits inside /android/app/ folder and adds the following lines:

-keep class ly.count.android.sdk.** { *; }

If Proguard is not already configured then first, enable shrinking and obfuscation in the build file. Find build.gradle file which sits inside /android/app/ folder and adds lines in bold.

android {
  buildTypes {
    release {
      // Enables code shrinking, obfuscation, and optimization for only
      // your project's release build type.
      minifyEnabled true

      // Enables resource shrinking, which is performed by the
      // Android Gradle plugin.
      shrinkResources true

      // Includes the default ProGuard rules files that are packaged with
      // the Android Gradle plugin. To learn more, go to the section about
      // R8 configuration files.
      proguardFiles getDefaultProguardFile(
        'proguard-android-optimize.txt'),
        'proguard-rules.pro'
      }
  }
...
}

Next create a configuration that will preserve the entire Flutter wrapper code. Create /android/app/proguard-rules.pro file and insert inside:

#Flutter Wrapper
-keep class io.flutter.app.** { *; }
-keep class io.flutter.plugin.**  { *; }
-keep class io.flutter.util.**  { *; }
-keep class io.flutter.view.**  { *; }
-keep class io.flutter.**  { *; }
-keep class io.flutter.plugins.**  { *; }

More info related to code shrinking can be found here for flutter and android.

Other Features and Notes

SDK Config Parameters Explained

Here is the list of functionalities "CountlyConfig" provides:

• Device Id - A device ID is a unique identifier for your users. You may specify the device ID yourself or allow the SDK to generate it.
• Enable Logging - To enable countly internal debugging logs.
• Enable Crash Reporting - To enable uncaught crash reporting.
• Salt - Set the optional salt to be used for calculating the checksum of requested data which will be sent with each request.
• Event queue threshold - Set the threshold for event grouping. Event count that is bellow the threshold will be sent on update ticks.
• Update Session Timer - Sets the interval for the automatic session update calls.
• Custom Crash Segment -Set custom crash segmentation which will be added to all recorded crashes.
• User consent - Set if consent should be required and give consents.
• Forcing HTTP POST - When set to true, all requests made to the Countly server will be done using HTTP POST. Otherwise, the SDK sends all requests using the HTTP GET method. In some cases, if the data to be sent exceeds the 1800-character limit, the SDK uses the POST method. The default value is false.
• Star Rating Text - Set shown title, message and dismiss buttim text for the star rating dialogs.
• Application Performance Monitoring - Enable APM features, which includes the recording of app start time.
• Set User Location - Set user location manually instead of using Countly server to use GeoIP database to deduce a user's location.
• Max Queue Size Limit - Set maximum size for the request queue.
• Manual Sessions - To enable manual session handling
• Automatic Remote Config - If enabled, will automatically download newest remote config values.
• Direct Attribution - Report direct user attribution
• Indirect Attribution - Report indirect user attribution

Setting Maximum Request Queue Size

When you initialize Countly, you can specify a value for the setMaxRequestQueueSize flag. This flag limits the number of requests that can be stored in the request queue when the Countly server is unavailable or experiencing connection problems.

If the server is down, requests sent to it will be queued on the device. If the number of queued requests becomes excessive, it can cause problems with delivering the requests to the server, and can also take up valuable storage space on the device. To prevent this from happening, the setMaxRequestQueueSize flag limits the number of requests that can be stored in the queue.

If the number of requests in the queue reaches the setMaxRequestQueueSize limit, the oldest requests in the queue will be dropped, and the newest requests will take their place. This ensures that the queue doesn't become too large, and that the most recent requests are prioritized for delivery.

If you do not specify a value for the setMaxRequestQueueSize flag, the default setting of 1,000 will be used.

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setMaxRequestQueueSize(5000);

Attribution

Countly Attribution Analytics allows you to measure your marketing campaign performance by attributing installs from specific campaigns. This feature is available for the Enterprise Edition.

There are 2 forms of attribution: direct Attribution and indirect Attribution.

Direct Attribution

You can pass "Campaign type" and "Campaign data". The "type" determines for what purpose the attribution data is provided. Depending on the type, the expected data will differ, but usually that will be a string representation of a JSON object.

You can use recordDirectAttribution to set attribution values during initialization.

String campaignData = 'JSON_STRING';
CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.recordDirectAttribution('CAMPAIN_TYPE', campaignData);

You can also use recordDirectAttribution function to manually report attribution later:

String campaignData = 'JSON_STRING';
Countly.recordDirectAttribution('CAMPAIN_TYPE', campaignData);

Currently this feature is limited and accepts data only in a specific format and for a single type. That type is "countly". It will be used to record install attribution. The data also needs to be formatted in a specific way. Either with the campaign id or with the campaign id and campaign user id.

String campaignData = '{cid:"[PROVIDED_CAMPAIGN_ID]", cuid:"[PROVIDED_CAMPAIGN_USER_ID]"}';
Countly.recordDirectAttribution('countly', campaignData);

Indirect Attribution

This feature would be used to report things like advertising ID's. For each platform those would be different values. For the most popular keys we have a class with predefined values to use, it is called "AttributionKey".

You can use recordDirectAttribution to set attribution values during initialization.

Map<String, String> attributionValues = {};
if(Platform.isIOS){
  attributionValues[AttributionKey.IDFA] = 'IDFA';
}
else {
  attributionValues[AttributionKey.AdvertisingID] = 'AdvertisingID';
}

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.recordIndirectAttribution(attributionValues);

You can also use recordIndirectAttribution function to manually report attribution later

Map<String, String> attributionValues = {};
if(Platform.isIOS){
  attributionValues[AttributionKey.IDFA] = 'IDFA';
}
else {
  attributionValues[AttributionKey.AdvertisingID] = 'AdvertisingID';
}

Countly.recordIndirectAttribution(attributionValues);

In case you would be accessing IDFA for ios, for iOS 14+ due to the changes made by Apple, regarding Application Tracking, you need to ask the user for permission to track the Application.

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 setHttpPostForced function after you called init. You can use the same function later in the app's life cycle to disable the override. This function has to be called every time the app starts.

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setHttpPostForced(true); // default is false

Interacting with the internal request queue

When recording events or activities, the requests don't always get sent immediately. Events get grouped together. All the requests contain the same app key which is provided in the init function.

There are two ways to interact with the app key in the request queue at the moment.

1. You can replace all requests with a different app key with the current app key:

//Replaces all requests with a different app key with the current app key.
Countly.replaceAllAppKeysInQueueWithCurrentAppKey();

In the request queue, if there are any requests whose app key is different than the current app key, these requests app key will be replaced with the current app key. 2. You can remove all requests with a different app key in the request queue:

//Removes all requests with a different app key in request queue.
Countly.removeDifferentAppKeysFromQueue();

In the request queue, if there are any requests whose app key is different than the current app key, these requests will be removed from the request queue.

Drop Old Requests

If you are concerned about your app being used sparsely over a long time frame, old requests inside the request queue might not be important. If, for any reason, you don't want to get data older than a certain timeframe, you can configure the SDK to drop old requests:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setRequestDropAgeHours(10); // a positive integer indicating hours

By using the setRequestDropAgeHours method while configuring the SDK initialization options, you can set a timeframe (in hours) after which the requests would be removed from the request queue. For example, by setting this option to 10, the SDK would ensure that no request older than 10 hours would be sent to the server.

Setting an event queue threshold

Events get grouped together and are sent either every minute or after the unsent event count reaches a threshold. By default it is 10. If you would like to change this, call:

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);
config.setEventQueueSizeToSend(6);

Checking if the SDK has been initialized

In case you would like to check if init has been called, you may use the following function:

Countly.isInitialized();

A/B Experiment Testing

Variant Level Control

Downloading

You can fetch a map of all A/B testing parameters (keys) and variants associated with it:

Countly.instance.remoteConfig.testingDownloadVariantInformation((rResult, error){
  // do sth
})

You can provide a callback (which is optional) to be called when the fetching process ends. Depending on the situation, this would return a RequestResponse Enum (Success, NetworkIssue, or Error) as the first parameter and a String error as the second parameter if there was an error ("null" otherwise).

Accessing

When test variants are fetched, they are saved to the memory. If the memory is erased, you must fetch the variants again. So a common flow is to use the fetched values right after fetching them. To access all fetched values, you can use:

Countly.sharedInstance().remoteConfig().testingGetAllVariants()

This would return a Future<Map<String, List<String>>> where a test's parameter is associated with all variants under that parameter. The parameter would be the key, and its value would be a String List of variants. For example:

{
  "key_1" : ["variant_1", "variant_2"],
  "key_2" : ["variant_3"]
}

Or instead you can get the variants of a specific key:

Countly.sharedInstance().remoteConfig().testingGetVariantsForKey(String valueKey)

This would only return a Future<List<String>> of variants for that specific key. If no variants were present for a key, it would return an empty list. A typical result would look like this:

["variant_1", "variant_2"]

Enrolling / Exiting

After fetching A/B testing parameters and variants from your server, you next would like to enroll the user to a specific variant. To do this, you can use the following method:

Countly.instance.remoteConfig.testingEnrollIntoVariant(String keyName, String variantName, void Function(RequestResult, String?)? callback)

Here the 'valueKey' would be the parameter of your A/B test, and 'variantName' is the variant you have fetched and selected to enroll for. The callback function is optional and works the same way as explained above in the Fetching Test Variants section.

Experiment Level Control

Downloading

You can fetch information about the A/B tests in your server including test name, description and the current variant:

Countly.instance.remoteConfig.testingDownloadExperimentInformation((rResult, error){
  // do sth
})

You can provide a callback (which is optional) to be called when the fetching process ends. Depending on the situation, this would return a RequestResponse Enum (Success, NetworkIssue, or Error) as the first parameter and a String error as the second parameter if there was an error ("null" otherwise).

Accessing

After fetching the experiment information the SDK saves it in the RAM, so if the memory is erased, you must fetch the information again. You can access this information through this call:

Countly.sharedInstance().remoteConfig().testingGetAllExperimentInfo()

This would return a Future<Map<String, ExperimentInformation>> where the keys are experiment IDs as String and the values are the ExperimentInformation Class which contains information about the experiment with that ID. This Class' structure is like this:

class ExperimentInformation {
  // same ID as used in the map
  String experimentID;
  // the name of the experiment
  String experimentName;
  // the description of the experiment
  String experimentDescription;
  // the name of the currently assigned variant for this user (e.g., 'Control Group', 'Variant A')
  String currentVariant;
  // variant information for this experiment
  Map<String, Map<String, Object?>> variants;
}

So an example data structure you might get at the end would look something similar to this:

{
  some_exp_ID: {
    experimentID: some_ID,
    experimentName: some_name,
    experimentDescription: some description,
    currentVariant: variant_name,
    variants: {
      Control Group: {
        key_1: val,
        key_2: val,
      },
      Variant A: {
        key_1: val,
        key_2: val,
      }
    }
  }
}

Enrolling / Exiting

To enroll a user into the A/B experiment using experiment ID, you use the following method:

Countly.instance.remoteConfig.testingEnrollIntoABExperiment(String expID);

If you want to remove users from A/B experiment using experiment ID, you can use the following function:

Countly.instance.remoteConfig.testingExitABExperiment(String expID);

FAQ

What Information is Collected by the SDK?

The data that SDKs gather to carry out their tasks and implement the necessary functionalities is mentioned in here