ALERT: As of 3.0, Swrve is no longer included in the Kongregate SDK. This page is for legacy purposes only.

Swrve Overview

The Kongregate SDK wraps the Swrve SDK. In addition to analytics, Swrve includes features for managing push notifications, in-app messaging and running A/B tests. Details of these features may be found on Swrves Documentation Site. This page shows how to setup some of these features through the Kong SDK.

Enabling Swrve

To enalbe Swrve you simply need to include Kongregate API settings for KONGREGATE_OPTION_SWRVE_APP_ID and KONGREGATE_OPTION_SWRVE_APP_KEY as specified in the initialization sections for each platform.

Swrve Events

All automatic events will be fired to Swrve. Events may also be added to Swrve using the Analytics.AddEvent(event_name, fields) method. By default events added in this will include all automatic and common callback fields. They will also be renamed Kongregate.Raw.<event_name> when viewed in the Swrve dashboard. This is the method you will use for most events you plan to perform detailed analysis on.

Swrve Only Events

There may be cases where you only want to use events as triggers for various Swrve features, such as In-App Messaging or the Push Notification Permission. For these case, you want to fire Swrve only events, that will not include the added overhead of collecting automatic and common fields. To do this, prefix the event name you pass to AddEvent with swrve.<event_name>. IMPORTANT NOTE: these events are renamed Kongregate.<event_name> when they are sent to swrve. This is the format you will use when scheduling them as triggers.

Of course, you may also use the defauls Kongregate.Raw.<event_name> or any of the built-in swrve.<event_name> events as triggers as well.

Swrve Virtual Economy Events

If you wish to pass virtual economy events to Swrve, you may use the following special event names. These will essentially pass through directly to the SWRVE API calls descriped here: Swrve Virtual Economy Events.

Dictionary<string,object> purchasePayload = new Dictionary<string,object>()
{
  { Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_PARAM_ITEM, "an_item" },
  { Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_PARAM_CURRENCY, "hard_currency_change" },
  { Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_PARAM_COST, 100 },
  { Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_PARAM_QUANTITY, 5 }
};
KongregateAPI.GetAPI().Analytics.AddEvent(Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_EVENT_PURCHASE, purchasePayload);

Dictionary<string,object> giftPayload = new Dictionary<string,object>()
{
  { Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_PARAM_CURRENCY, "soft_currency_change" },
  { Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_PARAM_AMOUNT, 4.99 }
};
KongregateAPI.GetAPI().Analytics.AddEvent(Kongregate.Analytics.SWRVE_VIRTUAL_ECONOMY_EVENT_GIFT, giftPayload);

Swrve User Attributes

User attributes may be used to create segments when targeting some Swrve features, such as in-app messages. Our SDK automatically populates the following user attributes.

You may add you own custom user attributes with the following Analytics.gameUserUpdate() method. Note, Swrve expects all values to be Strings.

Unity
Dictionary<string,object> gameUserProps = new Dictionary<string, object>()
{
  { "level", "1" },
};
KongregateAPI.GetAPI().Analytics.GameUserUpdate(gameUserProps);
Objective-C
[KongregateAPI.instance.analytics gameUserUpdate:@{ @"level" : @"1"}];
Java
Map<String,String> gameUserData = new HashMap<String, String>();
gameUserData.put("level", "1");
APIBootstrap.getInstance().analytics().gameUserUpdate(gameUserData);

Push Notification

Swrve may be used to manage Push Notifications. See the Push Notification Documentation for integration details.

Push Notification Permission

By default Swrve will request the Push Notification permission when the app comes to the foreground. You may change this behavior to have the dialog be displayed in response to a specific event. Note, this is an iOS only feature.

To set this up you must do 2 things. First, initialize the SDK with the events that should trigger the permission dialog, replacing the default behavior. Second, you must fire an event that triggers the notification at the approptiate time.

Unity

// initialize Swrve with the set of events that will initiate the permission request.
KongregateAPI.Settings.SwrveConfig = new Dictionary<string, object>() {
	{ KongregateAPI.KONGREGATE_SWRVE_PUSH_NOTIFICATION_EVENTS,
		new String[] { "Kongregate.pushNotificationPermission" }
	}
};

// this event will trigger the permission dialog. Note, the prefix differs (see below)
KongregateAPI.GetAPI().Analytics.AddEvent("swrve.pushNotificationPermission", new Dictionary<string,object>(0));

Objective-C

// initialize Swrve with the set of events that will initiate the permission request.
NSDictionary* apiSettings = @{
  KONGREGATE_SWRVE_PUSH_NOTIFICATION_EVENTS: [NSSet setWithArray:@[@"Kongregate.pushNotificationPermission"]],
  // other settings
};
[KongregateAPI initialize:gameId apiKey:apiKey withSettings:apiSettings];

// this event triggers the permission dialog. Note, the prefix differs (see below)
[KongregateAPI.instance.analytics addEvent:@{} toCollection:@"swrve.pushNotificationPermission"];

IMPORTANT NOTE: when an event is added to Kongregate with the swrve. prefix, the prefix will change to Kongregate. when it’s sent to Swrve. This is the setup and add event steps above have different prefixes. This is done because the Kongregate AddEvent call may send the event through various wrapped SDK (e.g. Keen, Swrve), the swrve. prefix tells the Kong SDK to only route it to Swrve.

Testing

Testing the push notification permission dialog can be tricky. iOS will only ask once at most once a day. To test the timings of the dialog, you can work around this by changing the date to more than 1 day in advance, restart the device, and relaunch your app.

In-App Messaging

Swrve may be used to send in-app messages. See Swrve In-App Messaging documentation for details. No special client side setup is needed for either iOS or Android to enable in-app messaging. However, you may choose to trigger in-app messages in response to Swrve events, rather than displaying them as soon as possible. These are the two options when configuring in-app messages in the Swrve dashboard. Similar to the push notification permission event above, you way want to use Swrve only events for this purpose. These events will be more streamlined and willnot include properties from automatic and game callbacks.

Unity
KongregateAPI.GetAPI().Analytics.AddEvent("swrve.inAppMessage", new Dictionary<string,object>(0));
Objective-C
[KongregateAPI.instance.analytics addEvent:@{} toCollection:@"swrve.inAppMessage"];
Java
APIBootstrap.getInstance().analytics().addEvent("swrve.inAppMessage",event);

SWRVE Action Button Callback / Deep Links

In the Swrve dashboard you may specify an action or deep link to be fired when a user presses a button to dismiss the In-App Message dialog. To use this feature you must specify a method to handle these actions. This is done as follows.

Unity
// here KongGameObject is a game object with the method HandleSwrveAction, which will be invoked
// when the Swrve action is fired.
KongregateAPI.GetAPI().Analytics.SetSwrveButtonListener("KongGameObject", "HandleSwrveAction");

// You can see the method receives a single string parameter, which will be whatever you set as the
// Action in the Swrve dashboard
void HandleSwrveAction(String action) {
    Debug.Log("swrve action: " + action);
}

See KongregateGameObject-Example.cs for another Unity code sample.

Objective-C
// Set a block to receive the Action
[[[KongregateAPI instance] analytics] setSwrveButtonCallback:^(NSString * action) {
    NSLog(@"swrve button callback: %@", action);
}];
Java
// set an `ISwrveCustomButtonListener` implementation to handle the action.
mAPI.analytics().setSwrveCustomButtonListener(new ISwrveCustomButtonListener() {
    @Override
    public void onAction(String action) {
        android.util.Log.d("your_app", "Swrve Action: " + action);
    }
});

The Kongregate SDK will automatically handle deep links with the format kong_panel [TARGET], where [TARGET] is one of the valid panel targets. For example, kong_panel registration opens the Kongregate registration. Deep links that do not follow this format are passed on to your custom action button callback, if set, or fallback to the default behavoir of opening a URI.

A/B Testing

Your game may leverage Swrve to run A/B tests. The Swrve docs site includes a detailed reference on how to setup and run an A/B Test (see Integating Resource A/B Testing). This document outlines how to access the Swrve resources through the Kongregate Client SDK.

Accessing Swrve Resources

KongregateAPI kongApi = APIBootstrap.getInstance();
kongApi.analytics().getResourceAsString("a_resource", "a_string_attr", "n/a"));
kongApi.analytics().getResourceAsInt("a_resource", "an_int_attr", 0));
kongApi.analytics().getResourceAsFloat("a_resource", "a_float_attr", 0));
kongApi.analytics().getResourceAsBool("a_resource", "a_bool_attr", false));

These methods are available in Unity/C#, Android/Java, and iOS/Objective-C. See the respective API documentation for details. They all take a resource, attribute, and default_value parameter and return a value of the specified type. Be sure the Kongregate SDK is initialized before using these methods. If the SDK is not yet initalized, they will simply return the default value. You may also see the KongregateGameObject-Exampe.cs file for a Unity implementation.

Resource Updated Event

When a Swrve resource changes, your Kongregate Event Handler will receive the SWRVE_RESOURCES_UPDATES event.

mAPI.addEventListener(new KongregateEventListener() {
    @Override
    public void onEvent(String event) {
        if (KongregateEvent.SWRVE_RESOURCES_UPDATES.equals(event)) {
            // get resource values for the active player
          String monsterName = mAPI.analytics().getResourceAsString("monster_config", "name", "jake");
        }
    }

Similar events are fired for Objective-c (KONGREGATE_EVENT_SWRVE_RESOURCES_UPDATED) and C# (KongregateAPI.KONGREGATE_EVENT_SWRVE_RESOURCES_UPDATES) clients.

SWRVE Configuation

The default SWRVE configuration may be overridden by passing any of the following API options with the apiSettings when you initialize the Kongregate SDK. Most games do not need to override any of the default Swrve settings.