Kumulos provides an SDK in the form of a Unity package for use with iOS & Android applications created with Unity.

Integrate SDK components and dependencies

The Kumulos SDK is an open source project hosted on Github. You can find a link to the project in your agency console and here: It is distributed as a Unity package for importing into your projects.

To get started, download the Unity package from GitHub and import it into your project.

Import the package to your project

Once imported, simply attach the KumulosInit script to your main scene's camera object by dragging it from the Assets browser to the Main camera.

Attach the initializer to the main camera


To configure the SDK for use you need to initialize it with your app's API credentials. This should be done early in your application startup so that you can start calling API methods and using features.

In the KumulosInit behavior, edit the config object to set up your credentials:

var config = (new Config.Builder ("YOUR_API_KEY", "YOUR_SECRET_KEY"))
    .Build ();

Kumulos.Initialize (config);

Your API Key and Secret Key can be obtained from the App Dashboard in your agency console.

Checking installs of your App

When you run your app on a simulator or install your app on a device, you can check that the SDK has been initialized correctly by selecting the app and clicking the Installs tab to see the ten most recent installs of your app. Click on any install to see more information.

Recent installs

If you experience any difficulties integrating an SDK or initializing the Kumulos client, please don't hesitate to contact support who are standing by to help!

That's it, you're now good to go! Continue reading to learn more about analytics, configuring push notifications and calling Build API methods in your app.


So long as you have completed the above initialization steps, Kumulos will automatically record analytics data such as the device model, operating system version and more, available in Analytics & Reporting for your app.

Installation ID

When initialized for the first time, the Kumulos SDK will create a unique identifier for the current installation. This identifier can be used to target push notifications to a specific device through KScript or the Push Notifications API.

In order to retrieve this identifier, simply access the class variable:

string id = Kumulos.Shared.InstallId;

Once you have the installation ID, you can send it to your app's backend to be used later for push targeting. For more information about push targeting, please see the KScript Documentation or push notification documentation as appropriate.

Location Tracking

You can send Kumulos location updates and use this to trigger events such as push notifications when an install enters a GeoFence.

How you configure the Core Location services for iOS depends on the specific use case of your app. You should consider both accuracy and battery life when making this decision. See the Unity API for further information.

You can use the helper method in the Kumulos SDK to send location updates to Kumulos:

Kumulos.Shared.SendLocationUpdate(new LocationUpdate(-54.618946, -65.234551));


The Kumulos SDK provides push notifications via APNS and GCM. To integrate Kumulos Push into your app you have to complete the following steps.

Configuring APNS

Configuring APNS for iOS with Kumulos

Configuring GCM

Configuring GCM for Android with Kumulos

Next you need to enable and configure the Kumulos push service with the certificates you have created.

Registering for and Handling Push Notifications

The KumulosSDK provides a helper method to configure notification permissions for alert, badge and sound permissions then trigger a user prompt with one line of code.


On iOS, this method will prompt the user about sending remote notifications, so you should consider applying a permission priming UX pattern to prepare the user for this step.

After registering for notifications, you should set up a handler to make use of received notifications:

Kumulos.Shared.OnPushReceived += (PushMessage message) => {
    Debug.Log("Push message received");

This handler will be called when a push is received when the app is in the foreground, or when the app has been opened from the tray notification.

Tracking open rates and conversions (opening the app from a push), and URL pushes are handled automatically by the SDK.

iOS Config

In Unity's generated Xcode project, you should ensure that:

  • Your bundle ID matches your push certificates (adjust in Unity: Edit > Project Settings > Player)
  • Your team is correctly selected in the Xcode project's "General" settings

If you are having trouble, please also ensure that:

  • The Xcode project's "Push Notifications" capability is enabled
  • The Xcode project's "remote-notifications" background mode capability is enabled
  • The "UserNotifications.framework" is linked to your build target

Android Config

When you have configured GCM, you need to set up the sender ID in the Kumulos initialization step, like so:

var config = (new Config.Builder ("YOUR_API_KEY", "YOUR_SECRET_KEY"))
    .Build ();

Checking Push Registrations

When you run your app on a simulator or install your app on a device, you can check that the install has successfully registered for push notifications by selecting the app and clicking the Installs tab to see the ten most recent installs of your app. Click on any install and then click on Push tab.

Install push details


You can create and manage subscriptions to push notification Channels via the SDK. Channels allow your users to define preferences for the type of content they would like to receive via notifications.

You can manage all channel interactions via the KumulosSDK.PushSubscriptionManager class in the SDK. Helper methods are available for creating, listing and managing subscriptions to channels. To create a subscription manager, simply construct one as follows:

var pushManager = new PushSubscriptionManager (Kumulos.Shared);

Listing Channels

To list available & subscribes channels, you can call ListChannels:

pushManager.ListChannels ((List<PushChannel> channels) => {

Channel visibility and meta data can be controlled when they are created.

Managing Subscriptions

Channel subscriptions can be managed with the Subscribe, Unsubscribe, SetSubscriptions, and ClearSubscriptions method. For example:

pushManager.SetSubscriptions (new string[]{ "stone-crows" });

Creating a Channel

pushManager.CreateChannel (new CreatePushChannelRequest ("brazen-beasts", true), (PushChannel obj) => {
    Debug.Log("Created channel");

Background Data

Background data pushes on Unity will wake up the native application layer, but not the handler attached to your scene.


You can call API methods defined in the Kumulos Build service using the Kumulos.Call method.

Parameters are optionally provided as a dictionary. Assume in this example you expect a list of characters:

class House
    public string name;
    public int influence;

class Character

    public string name;
    public int age;
    public House house;

Kumulos.Shared.Call<List<Character>>("myApiMethod", (Kumulos.KumulosCallResult<List<Character>> result) =>
    if (!result.IsSuccessful) {

    var character = result.payload[0];
    Debug.Log("I am " + " of " +;

Note that the model classes must have the [System.Serializable] attribute in order to be deserialized correctly.

Kumulos stores data fields as base64 encoded data, so if you receive data from Kumulos, you will have to base64 decode it to access the original data. Similarly, when you send data to Kumulos, you should base64 encode it before transport.



  • Add location update helper


  • Initial release with Analytics, Push, and Build support for iOS & Android