Frequently Asked Questions

Here are some common questions developers have. If you don’t see the answer you are looking for, contact mobile-dev@kongregate.com. Please include as much detail as possible when sending questions (development environment, log, code snippets, etc).

Where can I find the latest Kongregate SDK?

A link to the latest Standard Kongregate SDK is linked at the top of the the Changelog. We sometimes maintain and Edge SDK with newer features. This version of the SDK is updated more rapidly and generally only given to games in active development. Ask your Kongregate producer if you think you need the Edge SDK.

What analytics fields and events are sent by the SDK?

The complete list of fields and events sent by the SDK are listed here. If an event you expect to appear does not, verify you are initializing the SDK with auto analytics enabled and are setting the Keen project ID and write keys as described here.

Where do I find the Apple ID for KONGREGATE_OPTION_APPLE_ID?

The Apple ID may be found in iTunes Connect under App Information.

Where do I find the Swrve and Adjust API keys and event tokens?

The Kongregate Producer for your game will provide these to you. Contact him/her if you don’t have it.

The Kongregate SDK fails to initialize on Android

Use monitor to view the logs and see if any of the following errors occur:

You need to add android-support-v4.jar to the libs you compile with. You may copy it from here <android-sdk-path>/extras/android/support/v4/android-support-v4.jar to your libs directlry. See here if you need more information: Android Support Library Setup

You need to include YourGameSharedSecretProvider. If you generated the JAR, be sure it’s included with your build. See instructions here: Shared Secret Provider

What provisioning profile (iOS) or certificate should I use to sign builds?

During active development you may use your own Ad-Hoc provisioning profile or private key for test builds. Prior to uploading builds to the Play Store or iTunes we will resign using Kongregate Certificates. Android builds should be delivered to the Kongregate producer as APKs and iOS builds as xarchives.

Unity / XCode build fails after integrating or upgrading the SDK?

Make sure your XCode project contains the KongregateSDK, KongregateUnityWrapperSDK, and various iOS Frameworks documented here: Unity iOS Setup. A common mistake is to forgot to add one of these when rebuilding an XCode project, resulting in linker errors when attempting to build. NOTE: recent versions of the Kongregate Unity plugin populates these frameworks as a post build step, so hopefully these error will become less common.

Another easy mistake to make is to update the C# files for the Unity wrapper but miss importing updated KongregateSDK or KongregateUnityWrapperSDK frameworks. Check the timestamps on the frameworks your using.

Unity / Android JNI errors after upating the SDK?

This may happen because you updated the C# file for the Kongregate Plugin, but failed to update the KongregateSDK.jar. Compare the timestamps and version numbers (from the logfile) to make sure they match.

My game crashes when opening the Kongregate Panel?

The most common reason we see a game crash upon loading the Kongregate Panel on iOS is due to memory constraints. In general, the Kongregate API is fairly lightweight. However, opening the Kongregate Panel entails creating and displaying a UIWebView which loads the Kongregate Web Application. If your game is already using up a lot of resources, this may push it over the edge. If you encounter this, our first recommendation is to free up some resources prior to opening the panel.

Anoter reason the panel may crash, particularly on Android, is do to some compatibility issue with WebKit and our Web Application. We occassionaly encounter these when new devices or OS updates are rolled out. We can usually find a work-a-round within our web page.

For any crash bug you suspect might be SDK related, please send along a log any other details to mobile-dev@kongregate.com.

How do I integrate the Google Play library project?

The Android SDK 1.1.1.5 and higher require your project include the Google Play Services API library project. See Google’s documentation for details on how to aquire and setup the library project as a dependency.

The basic steps are:

  1. Download Google Play Services SDK using the Android SDK Manager.

  2. Copy the Google Play Services library project, <android_sdk>/sdk/extras/google/google_play_services/libproject/google-play-services_lib to a location relative to your project. UNITY: place the new library project in the plugins directory (e.g. /Assets/Plugins/Android/google_play_services_lib)

  3. Update the Googe Play Services library project: android update lib-project --path /my/local/path/to/google-play-services_lib (not required for Unity projects).

  4. Add another refererence to your project .properties file: android.library.reference.1=/my/local/path/to/google-play-services_lib/ (not required for Unity projects).

  5. Create proguard exceptions if using Proguard (not supported by Unity project).

Alternatively, You may choose to import the library project into whatever IDE you use and add it as a dependency. You may also choose to use a 3rd party Google Play Services plugin.

Why do I see WARNING: THIS APP WAS NOT SIGNED BY KONGREGATE in the Kong Panel?

This warning message is shown for all Android buids that are not re-signed by Kongregate. You do not need to worry about this warning during active development. Once builds are re-signed to be submitted to the app store, this warning will go away. See Delivering Buids for more details.

How to migrate Adjust from SDK 1.1.5.x to 1.1.6.x.

For the few games migrating from the Edge version of Adjust in SDK 1.1.5.x to Standard 1.1.6.x, you will need to make a few changes.

  1. The Adjust meta-data tags (AdjustAppEnvironment, AdjustLogLevel, and AdjustEnvironment) should be removed from the AndroidManifest.xml. These values are now specified when initializing our SDK in the same way it was done for iOS. See Adjust Integration Docs for details. NOTE: the <receiver> entry in the AndroidManifest.xml should still contain the com.adjust.sdk.ReferrerReceiver forward.
  2. You must add event tokens for install and session events, in addition to sale. Again, see the Adjust Integration Doc for more details.
  3. Please verify the update against sandbox before submitting a release.

When I try to install my app I get an INSTALL_FAILED_DUPLICATE_PERMISSION error.

This error happens on Android 5.0 devices when you try to install an app that has not been re-signed by Kongregate and another Kongregate app exists on the device. The easiest solution is to uninstall other Kongregate games from the device while using it for development. An alternative solution is to temporarily remove the line defining the ReadSharedData2 permission from the manifest during development. Just be sure to re-add it for Release Candidate builds.

Does the Kongegate SDK still include Keen and Ad-X?

The SDK still includes Keen, but new games are not required to intergrate with it. Ad-X has been completely removed. The documentation for their setup has been moved to Legacy Support

The Kongregate SDK references unavailable libraries from the Facebook SDK

Prior to version 1.1.8.0 the SDK required the Facebook SDK v3.X to be used. Linker errors would occur when version 4.x was used by the game. The Kongregate SDK 1.1.8.0 and higher does not have a direct dependency on the FB SDK.

I see the following error in my iOS log: Assertion failure in -[KongKeyChainItemWrapper writeToKeychain]]

This error is normal for non-resigned builds. The Kongregate SDK needs to be signed by Kongregate to access the Key Chain used for Shared Sign On. This error is harmless while you are in active development. It only means shared sign on will not work. It should go away once your game is resigned.

How do I setup the Google v7 Appcompat Library project

Below are quick step-by-step instructions. Complete documentation for setting up and using v7 Appcompat library may be found here: Google v7 Appcompat Support Library

  1. Use the Android SDK Manager to download the Android Support Library
  2. copy the appcompat library project from the Android SDK to your project. UNITY: place the new library project in the plugins directory (e.g. /Assets/Plugins/Android/appcompat)
cp -R /path/to/android/sdk/extras/android/support/v7/appcompat /path/to/your/project/
  1. update the library project
android update lib-project --path /path/to/your/project/appcompat
  1. add a reference to the appcompat library project in your project.properties file. UNITY: this step is not needed for Unity. Unity automatically creates these references at build time.
android.library.reference.2=relative/path/to/appcompat

Upgrade Android SDK or Unity Plugin to version 1.1.8.4 from a previous version

  1. The Swrve SDK is no longer a simple JAR. Your project must use either the new Swrve Library Project or Android Archive. * Native Andriod: See the updated options for using the either the Swrve Library Project or Android Archive * Unity Plugin: The Swrve SDK is now imported with the Kongregate plugin as a seperate library project. You simply need to delete the old swrvegoogle.jar from the existing plugin libs directory: /Assets/Plugins/Android/Kongregate/libs/swrvegoogle.jar
  2. The AndroidManifest.xml entries for Swrve’s Google Cloud Messaging API have changed. Swrve documents the specific changes here. The Push Notifications documentation has also been updated to reflect these changes.
  3. The Swrve SDK uses features from Google Play Services v7. You will need to upgrade if you are currently using a lower version.

How to migrate from Keen to Swrve

The general process to migrate from Keen to Swrve:

  1. Release an update with both Keen and Swrve integrated
  2. Verify Swrve ingest is in working order
  3. Release an update with just Swrve integrated

Adding Swrve: To add Swrve support you simply need to initialize the SDK with the following options: KONGREGATE_OPTION_SWRVE_APP_ID and KONGREGATE_OPTION_SWRVE_API_KEY or for Unity KongregateAPI.Settings.SwrveAppID and KongregateAPI.Settings.SwrveApiKey. For development builds use the Sandbox ID and Key, and Production values RC builds.

At this point your game will fire the same events to both Swrve and Keen. Swrve has a handy QA Devices Tool you may use to verify events are indeed firing to Swrve.

Removing Keen: Once the release with Swrve integrated is live, Kongregate will verify the ingest pipeline from Swrve is in working order. At this point you may disable Keen by simply removing the two Keen options, KONGREGATE_KEEN_PROJECT_ID and KONGREGATE_KEEN_WRITE_KEY or for Unity KongregateAPI.Settings.KeenProjectId and KongregateAPI.Settings.KeenWriteKey. On Android in SDK 1.1.8.0 and higher you may remove the KeenClient-Android.jar as well. Older SDKs still need the Keen JAR even when it’s disabled.

“Unexpected CFBundleExecutable Key” error message uploading to iTunesConnect

This error appears when your game is built using XCode 7+ and includes a resource bundle that includes the CFBundleExecutable key in it’s PList file. Typically, this will be in some third party plugin or resource that needs to be updated. You may either update the plugin or user PListBuddy to remove the invalid entry.

For example, in Kongregate SDK 1.1.8.5 we accidentally forgot to remove this entry from the Swrve.bundle. You may either update to 1.1.8.6, or remove it with the following command:

/usr/libexec/PlistBuddy -c "Delete :CFBundleExecutable" Assets/Editor/Swrve.bundle/Info.plist

The error only appears when uploading to iTunesConnect. It does not appear at build time.

Unity Android Build Error: trouble writing output: Too many method references: 69021; max is 65536.

This error occurs in Unity Android builds when too many methods are included. This typically happens because all the classes included in the JARs and AARs under the /Assets/Plugins/Android directory will be included with the build, and they exceed the limit for a DEX file. The easiest way to fix this is to identify JAR/AARs you may not need and remove them.

Unity Android Build Error: No resource found that matches the given name…

An error like the following often means you may have stale resource files in an Android library project in your plug-in directory. A common situation where this will happen is when you re-import the Kongregate.unitypackage and it includes an updated version of Swrve.

Temp/StagingArea/android-libraries/SwrveLibProject/res/layout/cio__conversation_fragment.xml:2: error: Error: No resource found that matches the given name (at 'layout_width' with value '@dimen/cio__conversation_fragment_width').

To resolve this, you may need to delete the offending library project directory (e.g. /Assets/Plugins/Android/SwrveLibProject) and re-import Kongregate.unitypackage.

Adding Google Cloud Messaging and Ads modules to the Play Game Services Plugin for Unity

The Google Play Services Plugin for Unity includes a handy PlayServicesSupport class which may be leveraged to include additional modules. If you drop this class KongregateGPSDependencies.cs in the /Assets/Editor/ directory it should pull down the needed modules and their dependencies:

If you already include support-v4 or appcompat-v7 elsewhere in your plugin directory, you can delete them and let the PlayServicesSupport resolver handle keeping them up to date.

How to integrate the Kongregate SDK with the Unity IAP API

The Unity IAP API meets our requirement of not automatically removing purchases from the SKPaymentQueue on iOS. It also provides accessors to retrieve all the required receipt details. Therefore, it may be used to support IAPs in your game. A sample script that demonstrates how to use this API with our Analytics and Receipt Validation APIs may be found here: KongPurchasingDemo.cs. Adapt this script to use your own Receipt Validation server, if you have have one.

Swrve Push Notifications don’t work on Android

How do you add new Swrve events or user properties?

Nothing special needs to be done to add new events or user properties to Swrve. Swrve will start tracking them the first time a client sends them using either Analytics.AddEvent() or Analytics.GameUserUpdate(). Note the tools in the Swrve web app will not allow you to set filters or triggers on events and user properties until they’ve been created. That is, at least one client needs to fire the event/user property. Also be aware that there is a little delay before the event/user property will be available in the dashboard. Be patient if it doesn’t appear right away.

Attempting purchase IAP from Google Play Store results in error

If you see an error such as “This version of the application is not configured for billing through Google Play. Check the help center for more information” when you attempt a purchase, verify the APK you are testing meets the following criterea.

Android 6.0 prompts user for dangerous permissions at launch

By default if your app requires any dangerous permissions in it’s AndroidManifest.xml and it’s both running on Andriod 6.0 or higher device and your app’s targetSDKVersion is 23 or higher, Unity will prompt for these permissions one by one at start up. This may not be a great user experience. You have a few options to change this behavior.

  1. You may instruct Unity to not do this, by adding the following meta-tag to your AndroidManifest.xml under the <application> tag.

     <meta-data android:name="unityplayer.SkipPermissionsDialog" android:value="true" />
    

    However, your app will still need to request the permission before the dependent functionality may be used. If it’s a Unity plugin or library project that requires the permission, be sure it handles dynamically requesting the permission and falls back gracefully if the request is denied.

  2. You may target SDK level 22, though you will not be able to take advantage of newer API features.

     <uses-sdk android:targetSdkVersion="22"/>
    
  3. The Swrve and Kongregate SDKs (1.2.2.0 and below) include the dangerous WRITE_EXTERNAL_STORAGE permission, however it is not a hard requirements and may be removed from the AndroidManifest.xml file. This permission will be removed in future versions of the SDKs. In Unity you will need to remove these directly from the manifests /Assets/Plugins/Android/Kongregate/AndroidManifest.xml and /Assets/Plugins/Android/SwrveLibProject/AndroidManifest.xml. For standard gradle builds and perhaps other build pipelines you may add the following to your main AndroidManifest.xml to instruct the manifest merger to remove the node.

     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" tools:node="remove"/>
    
  4. In some cases the need for specific permissions have changed with the API level. For example WRITE_EXTERNAL_STORAGE is only needed to write to an applications external directory in API level 19 and below. It is still needed in 20 and above to write to the devices external storage. Depending on your applications needs, you may get away with only requiring a permission at certain API levels.

     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="19"/>
    
More Resources:

SWRVE manifest changes upgrading to Kongregate SDK 1.2.3.3 / SWRVE 4.5

A few minor changes are required to upgrad to Kongregate SDK 1.2.3.3 or higher from previous versions. These changes are required to accomodate the newer wrapped version of the SWRVE SDK (4.5)