Overview

The following steps outline how to integrate the Kongregate SDK and Adjust into your game. Note many games only need to integrate the Analytics portions of the SDK. That is, they do not use Kongregate for authentication or the Kongregate Panel to integrate with features from kongregate.com (i.e. forums, badges, etc). Steps labeled FULL INTEGRATION ONLY may be skipped if you are only integrating with Kongregate and Adjust Analytics.

Gradle Project Setup

Add the Kongregate and Adjust SDK dependencies to your gradle file.

1. Add a reference to the flatDir repository where the Kongregate SDK and supporting JARs may be found

    repositories {
        flatDir { dirs '/my/local/path/to/kongregate-sdk-X.X.X/Android/flatRepo'}
        ...
    }
   

2. Add dependencies for Kongregate SDK and Adjust SDKs, as well as Google’s install referrer and analytics SDKs.

    dependencies {
        implementation 'com.kongregate:KongregateSDK:+@aar'
        implementation ':adjust'
        implementation 'com.android.installreferrer:installreferrer:1.0'
        implementation 'com.google.android.gms:play-services-analytics:16+'
    }
   

Shared Secret Provider

FULL INTEGRATION_ONLY

Kongregate Shared Sign-On means when you log into one Kongregate Game you automatically log into other Kongregate Games without needing to re-enter a username and password. To support this on Android your game must:

1. Be signed using Kongregate’s certificate (see Mobile Build System)
2. Define a Shared Secret Provider and the custom ReadSharedData2 permission as described below.

Place the following in your AndroidManifest.xml at the <manifest> tag level.

<permission android:name="com.kongregate.permission.ReadSharedData2" android:protectionLevel="signature"/>
<uses-permission android:name="com.kongregate.permission.ReadSharedData2"/>

Create a [YourGame]SharedSecretProvider class. Simply extend com.kongregate.android.api.providers.KongregateSharedSecretProvider. This class body should be empty. Of course replace [YourGame] with the name of your game. The purpose of this class is simply to provide a unique name to prevent conflicts with other Kongregate games that may be installed on the device.

package com.kongregate.android.api.providers;
import com.kongregate.android.api.providers.KongregateSharedSecretProvider;
public class [YourGame]ActivitySharedSecretProvider extends KongregateSharedSecretProvider { }

Add the newly created provider to the manifest under the <application> tag. The name and authorities attributes must match the classname of the provider from the previous step.

<provider android:name="com.kongregate.android.api.providers.[YourGame]SharedSecretProvider"
    android:authorities="com.kongregate.android.api.providers.[YourGame]SharedSecretProvider"
    android:multiprocess="true"
    android:readPermission="com.kongregate.permission.ReadSharedData2"
    android:exported="true">
</provider>

Initialization

Ideally the Kongregate SDK should be initialized in each Activity’s onCreate() method. Subsequent invocations simply return a reference the to the API singleton so it’s OK to invoke multiple times. If you are using a game engine that does not give you direct access to the Activity.onCreate() method, then invoke initializeNativeAPI() as soon as possible after your games is launched.

NOTE: it’s important not to initialize our SDK in Application.onCreate() since this may be invoked to handle background tasks such as handling remote or local notifications. We only want the Kongregate SDK initialized when the user actually launches the game.

Replace the option values below with values included with your welcome email. NOTE: KONGREGATE_OPTION_KONG_ANALYTICS_KEY and KONGREGATE_OPTION_ADJUST_ENVIRONMENT have different values for test/dev and live/rc builds.

// configure API options
Map<String,Object> options = new HashMap<>();
options.put(KongregateAPI.KONGREGATE_OPTION_KONG_ANALYTICS_KEY, "you-kong-analytics-key");
options.put(KongregateAPI.KONGREGATE_OPTION_KONG_ANALYTICS_ID, "/studio/game-name/dev");
options.put(KongregateAPI.KONGREGATE_OPTION_ADJUST_APP_TOKEN, "abcdef123456");
options.put(KongregateAPI.KONGREGATE_OPTION_ADJUST_ENVIRONMENT, "sandbox");
options.put(KongregateAPI.KONGREGATE_ADJUST_SALE_EVENT_TOKEN, "abcdef");
options.put(KongregateAPI.KONGREGATE_ADJUST_INSTALL_EVENT_TOKEN, "ghijkl");
options.put(KongregateAPI.KONGREGATE_ADJUST_SESSION_EVENT_TOKEN, "mnopqr");

Analytics only integrations should initialize the API with the Activity and API Options Map only.

// initialize the API for Analytics only integrations
APIBootstrap.initializeNativeAPI(activity, apiOptions);

Full integrations will also pass a game ID and Mobile API key to the initialization method.

// initialize the API for full Kongregate and Analytics integrations
APIBootstrap.initializeNativeAPI(activity, gameCode, "mobile-api-key", apiOptions);

Set the CommonPropertiesEvaluator to retrieve properties from your game to included with all events. The fields to include are detailed in the schema provided in the integration welcome email. Entries with Table Name COMMON FIELDS and SDK Input as Callback should be returned by your callback.

This is required for all integrations.

api.analytics().setCommonPropertiesEvaluator(new CommonPropertiesEvaluator() {
  @Override
  public Map<String, Object> getCommonProperties() {
    // build and return analytics data
    HashMap<String,Object> props = new HashMap<String, Object>();
    props.put("tutorial_completed", isTutorialComplete);
    props.put("soft_currency_balance", softCurrencyBalance);
    props.put("hard_currency_balance", hardCurrencyBalance);
    // ...
    return props;
  }
});

FULL INTEGRATIONS should also register a listener for Kongregate Events

// register to listen for Kongregate events.
KongregateAPI api = APIBootstrap.getInstance();
api.addEventBundleListener(new KongregateEventBundleListener() {
  @Override
  public void onKongregateEventBundle(String event, String eventPayload) {
    if (KongregateEvent.USER_CHANGED.equals(event)) {
      String user = APIBootstrap.getInstance().services().getUsername();
    }
    // See Events docs for complete set of events.
  }
});

See Events for more details handling Kongregate API events.

Sending Events

Analytics only integrations may find details on sending events on the Analytics Only Events Page.

FULL INTEGRATIONS may find details on the analytics system in the Main Analytics Page.

Mobile Control & Button

FULL INTEGRATION_ONLY

The Kongregate button is a button that will exist somewhere in your UI to open up the Kongregate UI, used to login navigate high scores, etc. The easiest way to add the button, is to place the following tag somewhere in the layout XML resource that defines your UI.

<com.kongregate.android.api.KongregateButton
  android:id="@+id/kong_api_button"
  android:layout_width="72dp"
  android:layout_height="72dp"
  android:src="@drawable/kongregate_button"
  android:visibility="invisible"
  />

Alternatively, you may programmatically open the Kongregate UI.

api.mobile().openKongregateWindow(context);

Event Callbacks

FULL INTEGRATION_ONLY

You should set a callback listener for processing Kongregate events.

// register to listen for Kongregate events.
KongregateAPI api = APIBootstrap.getInstance();
api.addEventBundleListener(new KongregateEventBundleListener() {
  @Override
  public void onKongregateEventBundle(String event, String eventPayload)  {
    if (KongregateEvent.USER_CHANGED.equals(event)) {
      String user = APIBootstrap.getInstance().services().getUsername();
    }
    // See Events docs for complete set of events.
  }
});

User info & Services

FULL INTEGRATION_ONLY

Use the services API to access user and auth tokens from our SDK.

KongregateAPI api = APIBootstrap.getInstance();
boolean isGuest = api.services().isGuest();
String username = api.services().getUsername();
String authToken = api.services().getGameAuthToken();

Statistics, Scores & Achievements

FULL INTEGRATION_ONLY

Use the statistics API if your game will support Kongregate High Scores and Achievements.

APIBootstrap.getInstance().stats().submit("HighScore", 1);

ProGuard:

If you are obfuscating your project with ProGuard, you will need to take care to skip some of the SDK classes. See the required additions in kongregate-sdk-x.x.x/Android/proguard.txt.

Troubleshooting

Launch the App and look for KONGREGATE CONFIGURATION WARNING or ERROR in logcat. Severe warnings will post toast messages or may even crash the app at launch to protect against releasing a misconfigured game.

For specific troubleshooting issues, see the Troubleshooting FAQ

API Docs & Usage

View API Documentation