Integration

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: https://github.com/Kumulos/KumulosSdkUnity. 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

Initialization

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.

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.

Analytics

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));

Push

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.

Kumulos.Shared.PushRegister();

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"))
    .SetGcmSenderId("YOUR_SENDER_ID")
    .Build ();

Channels

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) => {
    Debug.Log(channels[0].IsSubscribed);
});

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.

Build

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:


[Serializable]
class House
{
    public string name;
    public int influence;
}

[Serializable]
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) {
        Debug.Log("Error");
        return;
    }

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

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.

Changelog

1.1.0

  • Add location update helper

1.0.0

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