SDK v2.1.2 contains important changes to support GDPR compliance.
Kongregate SDK 2.1.1 Fixes a crash that occurs when a user opens the Kongregate Panel on Android 8.0 device. NOTE: This will only occur if you use the PANEL_ORIENTATION_OVERRIDE option and build targetting API level 27. The cause of this crash is an Android 8.0 bug which is fixed in Android 8.1.
Kongregate SDK 2.0.6 and up includes a new version of the Adjust SDK, which supports the the Google Referrer API. Follow the steps below to enusure your game takes full advantage of this API:

Add the Kongregate SDK

You have 2 options for adding the Kongregate SDK to your project. You may use the Android Archive file (AAR) or a Library project. The AAR approach is more convenient for Gradle and Android Studio projects, while importing our Libary project is better for Ant based builds and tools that don’t support AARs.

Option 1: Use the Kongregate SDK in Gradle Builds

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

     repositories {
         jcenter { url '' }
         flatDir { dirs '/my/local/path/to/kongregate-sdk-X.X.X/Android/flatRepo'}
  2. Add dependencies for Kongregate, Swrve and Adjust SDKs (be sure to speficy the exact Swrve version 4.5.0) :

     dependencies {
         compile 'com.kongregate:KongregateSDK:+@aar'
         compile ''
         compile ''
         compile ':adjust'

Option 2: Import the Kongregate and Swrve SDKs as Library Projects for Ant Builds

It’s highly recommended you use Gradle for native Android builds. Google no longer directly maintains library projects. To use more recent Google support libaries you need to convert the AARs to library projects, which will make your project difficult to maintain.

  1. Android requires the library to be built with your project. To do so, it will need to be updated with the location of the android SDK in your local environment. This is done by:

    android update lib-project --path /my/local/path/to/kongregate-sdk-X.X.X/Android/KongregateSDKLib/ android update lib-project --path /my/local/path/to/kongregate-sdk-X.X.X/Android/SwrveLibProject/

  2. Next, the Kongregate library will need to be added to your project. This is done in your project’s file or similar. Add the following line:

    android.library.reference.1=my/relative/path/to/kongregate-sdk-X.X.X/Android/KongregateSDKLib/ android.library.reference.2=my/relative/path/to/kongregate-sdk-X.X.X/Android/SwrveLibProject

  3. The SDK requires the Google Play Services API library project v7 or higher. You may see the faq for step-by-step instructions, if your app does not already use the API.

  4. The Swrve SDK requires the Google v7 Appcompat Library project. You may see the faq for step-by-step instructions.

  5. The Adjust SDK requires the Google RerferrerAPI. You must download the AAR from Google’s maven repository and convert it into a Library project.

Shared Secret Provider

Most Kongregate games support Shared Sign-On meaning 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 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.

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="[YourGame]SharedSecretProvider"


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

NOTE: it’s important not to initialize our SDK when the Application is created, since the Application may be created 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 provided by your Kongregate producer.

// Set api options.
// Most apps will enable Keen and AdX
Map<String,Object> apiOptions = new HashMap<String,Object>();

// Swrve keys and IDs
apiOptions.put(KongregateAPI.KONGREGATE_OPTION_SWRVE_APP_ID, 1234);
apiOptions.put(KongregateAPI.KONGREGATE_OPTION_SWRVE_API_KEY, "MySwrveApiKey");

// Adjust keys and tokens
apiOptions.put(KongregateAPI.KONGREGATE_OPTION_ADJUST_APP_TOKEN, "MyAdjustAppToken");
apiOptions.put(KongregateAPI.KONGREGATE_OPTION_ADJUST_ENVIRONMENT, "sandbox"); // change to "production" for RC builds
apiOptions.put(KongregateAPI.KONGREGATE_ADJUST_SALE_EVENT_TOKEN, "MySaleEventToken");
apiOptions.put(KongregateAPI.KONGREGATE_ADJUST_INSTALL_EVENT_TOKEN, "MyInstallEventToken");
apiOptions.put(KongregateAPI.KONGREGATE_ADJUST_SESSION_EVENT_TOKEN, "MySessionEventToken");

// initialize the API
APIBootstrap.initializeNativeAPI(activity, 1234, "MyKongApiKey", apiOptions);

// register to listen for Kongregate events.
KongregateAPI api = APIBootstrap.getInstance();
api.addEventBundleListener(new KongregateEventBundleListener() {
  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.

// Setup analytics event callback. This is how you pass common fields along with Keen/Swrve events CommonPropertiesEvaluator() {
  public Map<String, Object> getCommonProperties() {
    // build and return analytics data
    HashMap<String,Object> props = new HashMap<String, Object>();
    props.put("tuturial_completed", isTutorialComplete);
    props.put("soft_currency_balance", softCurrencyBalance);
    props.put("hard_currency_balance", hardCurrencyBalance);
    // ...
    return props;

See Events and Analytcs for more details handling Kongregate API events and using the Analytics API.

Mobile Control & Button

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.


Alternatively, you may programmatically open the Kongregate UI.;

Event Callbacks

You should set a callback listener for processing Kongregate events.

// register to listen for Kongregate events.
KongregateAPI api = APIBootstrap.getInstance();
api.addEventBundleListener(new KongregateEventBundleListener() {
  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.

Lifecycle Hooks

Notify the Kongregate SDK when various lifecyle events occur. This is only required if your game is going to support API levels below 14. For 14 and up, the Kongregate SDK will register for Application.ActivityLifecyleCallbacks.

// where mAPI is a reference to Kongregate API
protected void onCreate(Bundle savedInstanceState) {

    // Initialize the Kongregate SDK
    mAPI = APIBootstrap.initializeNativeAPI(activity, 1234, "MyKongApiKey", apiOptions);

protected void onPause() {
    if(mAPI != null) {

protected void onResume() {
    if(mAPI != null) {

protected void onDestroy() {
    if (mAPI != null) {

public void onLowMemory() {
    if (mAPI != null) {

User info & Services

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

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

Statistics, Scores & Achievements

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

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


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.


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