Integrate an SDK

To track your web pages (SPA, MPA or mobile applications that consist of HTML5 views) and browser extensions, you can use Countly Web SDK. Countly can run with all browsers that supports ECMAScript 5.

Use one of these methods to add it to your project:

https://yourcountlydomain/sdk/web/countly.min.js

npm install countly-sdk-web

yarn add countly-sdk-web

# latest non minified
cdn.jsdelivr.net/npm/countly-sdk-web@latest/lib/countly.js

# latest minified
cdn.jsdelivr.net/npm/countly-sdk-web@latest/lib/countly.min.js
      
# 25.4.1 non minified
cdn.jsdelivr.net/npm/countly-sdk-web@25.4.1/lib/countly.js

# 25.4.1 minified (JSDelivr or Cloudflare)
cdn.jsdelivr.net/npm/countly-sdk-web@25.4.1/lib/countly.min.js 
# or
cdnjs.cloudflare.com/ajax/libs/countly-sdk-web/25.4.1/countly.min.js

countly.min.js

To track your mobile Android applications you can use Countly Android SDK. Countly Android SDK requires a minimum Android version of 5.0 (API Level 21).

Make sure MavenCentral repository is included in your project and add Countly SDK dependency build.gradle like:

buildscript {
  repositories {
      mavenCentral()
  }
}

dependencies {
  implementation 'ly.count.android:sdk:26.1.3'
}

Additionally, ensure INTERNET and ACCESS_NETWORK_STATE permissions are set in your manifest file:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Countly iOS SDK supports minimum Deployment Target iOS 10.0 (watchOS 4.0, tvOS 10.0, macOS 10.14), and it requires Xcode 13.0+.

Use one of these methods to add it to your project, you can use master branch to get latest updates easily or you can lock version to latest 26.1.1:

# XCode > File > Add Packages and target the master branch or exact version
https://github.com/Countly/countly-sdk-ios.git 

# in Podfile, target master branch or exact version
# to target master branch remove :tag paramater
countly = { :git = 'https://github.com/Countly/countly-sdk-ios.git' :tag = '26.1.1' }

target 'MyApp' do
  pod 'Countly', countly
end
# pod install

# in Cartfile, target master branch or exact version
# to target master branch remove "==" and version
github "Countly/countly-sdk-ios" == 26.1.1

git submodule add https://github.com/Countly/countly-sdk-ios
# and to target exact version do steps below
cd countly-sdk-ios
git checkout 26.1.1

For server-side tracking you can use Countly NodeJS. It runs with the following node versions and up:

Use one of these methods to add it to your project:

npm install countly-sdk-nodejs

yarn add countly-sdk-nodejs

For your Flutter applications running on Android, iOS and web you can use Countly Flutter SDK. It uses Web, Android and iOS Countly SDKs underneath so same minimum platform limitations apply.

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

dependencies:
  countly_flutter: ^26.1.0

Next to download the SDK:

flutter pub get

For pure Dart applications (CLI, server-side and other non-Flutter runtimes), use Countly Dart Core SDK.

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

dependencies:
  countly_sdk_dart_core: ^26.1.0

Next to download the SDK:

dart pub get

For your React Native applications running on Android and iOS you can use Countly React Native SDK. It uses Android and iOS Countly SDKs underneath so same minimum platform limitations apply. While it can possibly work with older versions, the currently supported react-native versions are 0.60.0

Add it to your project with npm:

npm install --save countly-sdk-react-native-bridge@latest

For your .NET applications you can use Countly Windows SDK. For included and compatible target framework list you can check here.

To install the package, you can use either the NuGet Package Manager or the Package Manager Console. When you install a package, NuGet records the dependency, either in your project file or a packages.config file (depending on the project format).

1. In Solution Explorer, right-click References and choose Manage NuGet Packages.
2. Choose "nuget.org" as the Package source, select the Browse tab, search for Countly, select that package in the list, and select Install:
3. Accept any license prompts.

For your Unity projects you can use Countly Unity SDK. SDK requires the .NET profile to be at least ".NET 4.x" (".NET Framework " or ".NET Standard 2.1" are acceptable targets.)

It is validated against the following platforms: Android, iOS, Windows, UWP, Linux, and Mac OSX. The SDK is also validated against the following LTS versions: 2020.X, 2021.X, 2022.X, and 2023.X.

Download the unitypackage from GitHub and import it into your project.

To import the package (right click on Assets => Import Package => Custom Package => Path_To_Package) and leave all the files checked because we need to import all the files in the package.

This SDK uses the Newtonsoft Json package internally and it is required for the SDK to work.

Since Unity version 2020 this package is added to your project automatically by Unity. For versions before that, (2018 and 2019) you have to install this package in the project manually.

One way to do Install the Newtonsoft Json package would be to use the built-in package manager. You would go to Windows => Package Manager. In there you would see something like this:

If the Newtonsoft Json package doesn't appear in the Package Manager, you can add it manually. To achieve this, you would need to add:

"com.unity.nuget.newtonsoft-json": "3.0.2"

This line, in the "manifest.json" file. After adding the line and saving it, the package would be added automatically. It should also appear in the Package Manager afterward.

For server-side tracking and for your Java projects you can use Countly Java SDK. Minimum supported target version is Java 8.

Make sure MavenCentral repository is included in your project and add the dependency build.gradle like:

buildscript {
  repositories {
    mavenCentral()
  }
}
  
dependencies {
  implementation "ly.count.sdk:java:24.1.5"
}

Or as:

<dependency>
  <groupId>ly.count.sdk</groupId>
  <artifactId>java</artifactId>
  <version>24.1.5</version>
  <type>pom</type>
</dependency>

Countly C++ SDK has been designed to work with very few dependencies in order to run on most platforms. To build this SDK, you need:

• C++ compiler with C++14 support
• libcurl (with openssl) and its headers if you are on *nix
• cmake >= 3.13

First, clone the repository with its submodules:

git clone --recursive https://github.com/Countly/countly-sdk-cpp
# if needed:
# git submodule update --init --recursive

If you want to use SQLite to store session data persistently, build sqlite:

# assuming we are on project root
cd vendor/sqlite
cmake -D BUILD_SHARED_LIBS=ON -B build . # out of source build, we don't like clutter :)
# we define `BUILD_SHARED_LIBS` because sqlite's cmake file compiles statically by default for some reason
cd build
make # you might want to add something like -j8 to parallelize the build process

The cmake build flow is pretty straightforward:

# assuming we are on project root again
ccmake -B build . # this will launch a TUI, configure the build as you see fit
cd build
make

cmake -DCOUNTLY_BUILD_SAMPLE=ON -DCOUNTLY_BUILD_TESTS=ON -DCOUNTLY_USE_SQLITE=ON -B build . # or do it interactively with cmake
cd build
make ./countly-tests   # run unit test
make ./countly-sample  # run sample app

For your Google Tag Manager projects you can use Countly GTM SDK.

You can reach the Countly SDK template in your Google Tag Manager container through:

Workspace > Tags > New > Tag Configuration > Community Template Gallery > Countly Analytics

Another method to get the SDK template is to add it manually after downloading it from the Git repo here. You can either download it as a zip file and extract its content:

Code > Download ZIP 

or you can clone the repo and reach files directly:

git clone https://github.com/Countly/countly-sdk-gtm.git

After you should import the template.tpl file you have downloaded to your container through:

Workspace > Templates > New > Import

Now it should be available at:

Workspace > Tags > New > Tag Configuration > Countly Analytics

If none of our SDK offerings is suitible for your projects you can still feed data to your server with custom API calls. In this method you will not need any installation. You can directly read other Quick Access documents to see how to send data.

When embedding directly into your website you can use Countly Web SDK synchronously or asynchronously. Asynchronous usage would work without blocking content loading. This would also allow you to use Countly while the Countly script has not yet been loaded. This can be done by pushing function calls into the Countly.q queue, which SDK will execute after it is initialized. If you are using a framework then sync method is preferred.

<script type='text/javascript'>
  (function(l,t){function y(c){return function(){p.push([c].concat(Array.prototype.slice.call(arguments,0)));return d}}function u(c,a,e){e=y(e||a);e.__isCountlyStub=!0;c[a]=e}function z(c){if(!v&&!m){m=!0;var a=t.createElement("script");a.type="text/javascript";a.async=!0;a.src=c;a.crossOrigin="anonymous";a.onload=function(){v=!0;m=!1;var h=l.Countly;h&&"function"===typeof h.init&&h.init(w||{});h=l.Countly;var x=p.slice();p=[];for(var q=0;q<x.length;q++){var b=x[q],f=h,A=b.slice(1);b=b[0].split(".");
  for(var r=0;r<b.length-1;r++)f=f&&f[b[r]];b=b[b.length-1];b=f&&f[b];"function"!==typeof b||b.__isCountlyStub||b.apply(f,A||[])}};a.onerror=function(){m=!1;console.error("Countly loader failed to load SDK from:",c)};var e=t.getElementsByTagName("script")[0];e.parentNode.insertBefore(a,e)}}var d=l.Countly||(l.Countly={}),p=[],m=!1,v=!1,w=null;d.__clyBootstrap={version:"1.0.0",name:"countly-unified-loader"};for(var n="track_sessions track_pageview track_performance add_event user_details track_errors track_forms track_clicks track_scrolls track_links recordError change_id set_id uploadUserProfilePicture content.enterContentZone content.refreshContentZone content.exitContentZone feedback.showNPS feedback.showSurvey feedback.showRating userData.set userData.set_once userData.increment userData.increment_by userData.multiply userData.max userData.min userData.push userData.push_unique userData.pull userData.unset userData.save".split(" "),
  k=0;k<n.length;k++){var g=n[k].split(".");2===g.length?(d[g[0]]=d[g[0]]||{},u(d[g[0]],g[1],n[k])):u(d,g[0],n[k])}d.init=function(c,a){"object"===typeof c&&(a=c||{},c=a.app_key);a=a||{};c&&(a.app_key=c);for(var e in a)Object.prototype.hasOwnProperty.call(a,e)&&(d[e]=a[e]);"YOUR_APP_KEY"!==d.app_key&&"https://your.server.ly"!==d.url||console.warn("Please do not use default set of app key and server url");w=a;z(d.sdk_url||"https://cdn.jsdelivr.net/npm/countly-sdk-web@latest/lib/countly.min.js");return d}})(window,
  document);

  Countly.init("YOUR_APP_KEY", {
    url: "https://YOUR_SERVER_URL",
  });
</script>      

import Countly from "countly-sdk-web";

window.Countly = Countly;
Countly.init({
  app_key: "APP_KEY",
  url: "SERVER_URL"
});

<!--inside <head></head>-->
<script type='text/javascript'>
var Countly = Countly || {};
Countly.q = Countly.q || [];

Countly.app_key = "APP_KEY"; 
Countly.url = "SERVER_URL";

// Load Countly script asynchronously
(function() {
  var cly = document.createElement('script'); cly.type = 'text/javascript';
  cly.async = true;
  cly.src = 'https://cdn.jsdelivr.net/npm/countly-sdk-web@latest/lib/countly.min.js';
  cly.onload = function(){Countly.init()};
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(cly, s);
})();
</script>

<!--inside <head></head>-->
<script type='text/javascript' src='https://cdn.jsdelivr.net/npm/countly-sdk-web@latest/lib/countly.min.js'></script>
<script type='text/javascript'>

Countly.init({
  app_key: "APP_KEY",
  url: "SERVER_URL"
});
</script>

Before you can use any functionality, you have to initialize the SDK. That can be done either in your Application subclass (strongly recommended), or from your main activity onCreate method.

The shortest way to init the SDK is with this call:

Countly.sharedInstance().init(new CountlyConfig(this, APP_KEY, SERVER_URL));

In your application delegate, import Countly.h, and add the following lines at the beginning inside application:didFinishLaunchingWithOptions:

#import "Countly.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  CountlyConfig* config = CountlyConfig.new;
  config.appKey = @"APP_KEY";
  config.host = @"SERVER_URL";
  [Countly.sharedInstance startWithConfig:config];

  // your code

  return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
{
  let config: CountlyConfig = CountlyConfig()
  config.appKey = "APP_KEY"
  config.host = "SERVER_URL"
  Countly.sharedInstance().start(with: config)
  
  // your code

  return true
}

Note: Make sure you start Countly iOS SDK on the main thread.

Import and initialize the SDK:

var Countly = require('countly-sdk-nodejs');

Countly.init({
  app_key: "APP_KEY",
  url: "SERVER_URL"
});

CountlyConfig config = CountlyConfig(SERVER_URL, APP_KEY);

Countly.initWithConfig(config).then((value){
  // handle extra SDK logic if needed
});

import 'package:countly_sdk_dart_core/countly_sdk_dart_core.dart';

final config = CountlyConfig(
    appKey: 'APP_KEY',
    serverUrl: 'SERVER_URL',
);

final sdk = await Countly.init(config);
await sdk.consents.giveConsent();

Your main app component's componentDidMountmethod may be a good place for initialization:

import Countly from 'countly-sdk-react-native-bridge';
import CountlyConfig from 'countly-sdk-react-native-bridge/CountlyConfig';

const countlyConfig = new CountlyConfig("SERVER_URL", "APP_KEY");
await Countly.initWithConfig(countlyConfig);

The shortest way to initialize the SDK is with this call:

CountlyConfig cc = new CountlyConfig();
cc.serverUrl = "SERVER_URL";
cc.appKey = "APP_KEY";

Countly.Instance.Init(cc);

The shortest way to initialize the SDK is with this code snippet:

string appKey = "APP_KEY";
string serverUrl = "SERVER_URL";

CountlyConfiguration config = new CountlyConfiguration(appKey, serverUrl);
Countly.Instance.Init(config);

The shortest way to initialize the SDK is with this code snippet:

File targetFolder = new File("d:\\__COUNTLY\\java\\");

Config config = new Config("SERVER_URL", "APP_KEY", targetFolder);
Countly.instance().init(config);

The shortest way to initialize the SDK is with this code snippet:

cly::Countly& countly = cly::Countly::getInstance();
countly.start("APP_KEY", "SERVER_URL", 443, true);

The first thing you should be doing with the SDK template is to initialize the SDK as soon as possible on your web page by selecting a proper trigger. Initialization trigger is a good candidate for this. For SDK initialization the template offers the action Initialize the SDK in the drop down menu:

In this method you will not need to initialize an SDK. You can directly read other Quick Access documents to see how to send data.