Analytics Only Quick Start

This Guide details how to integrate Kongregate and Adjust Analytics into your Unity Game. Our Unity Plugin is included with the Kongregate SDK available at the top of the Changlog page. This is a simplified integration that does not include a full integration with the Kongregate Platform (e.g. authentication, badges, …). If you require those features, start here

You will need to request permission to download our SDK from the Google Drive, if you don’t already have access

Import Kongregate SDK Plugin

In Unity, select Assets -> Import Package -> Custom Package... and import Unity/Kongregate.unitypackage within the Kongregate SDK zip. Import all files. This plugin includes both the Kongregate and Adjust SDKs along with a handful of demo scripts.

Configure the Kongregate Analytics Only Demo

Assets/Plugins/Kongregate/demo/KongregateAnalyticsOnlyScene.unity is a great first stop to familiarize yourself with how to integrate Adjust and Kongregate Analytics. (KongregateDemoScene.unity is a demo for a complete integration with the Kongregate Platform. It is not needed for this guide.)

KongregateAnalyticsOnlyScene depends on the Unity Purchasing plugin. You must enable UnityPurchasing before importing this script. If you plan to use another In App Purchasing library this script should still provide a useful reference, but you won’t be able to run it out of the box.

The scene contains a KongregateAPI Game Object with the KongAnalyticsOnlyDemo.cs script attached. This is a barebones implementation of the Kongregate and Adjust SDK. You may use this for reference or a starting point for your own Kongregate API Game Object.

Be sure to update the values of the public variables to those provided in your Kongregate Integration Email.

Enable Kongregate and Adjust Analytics in Your Game!

Below are detailed steps for integrating the Kongregate SDK into your game. See KongAnalyticsOnlyDemo.cs for a sample implementation.

  1. Create an empty Game Object and attach a script to host the Kongregate API. You may use KongAnalyticsOnlyDemo.cs as a starting point. Be sure to mark the object DontDestroyOnLoad(gameObject) to prevent the SDKs from being unloaded.
  2. In Start() initialize the KongregateAPI.Settings objects with the required IDs and Keys.

     #if RELEASE_CANDIDATE
     	KongregateAPI.Settings.KongAnalyticsId = PRODUCTION_KONG_ID;
     	KongregateAPI.Settings.AdjustEnvironment = "production";
     #else
     	KongregateAPI.Settings.KongAnalyticsId = DEVELOPMENT_KONG_ID;
     	KongregateAPI.Settings.AdjustEnvironment = "sandbox";
     #endif
     	KongregateAPI.Settings.KongAnalyticsKey = KONG_ANALYTICS_KEY;
     	KongregateAPI.Settings.AdjustAppToken = ADJUST_APP_TOKEN;
     	KongregateAPI.Settings.AdjustEventTokenMap = new Dictionary<string,object>() {
     		{ KongregateAPI.ADJUST_INSTALL, INSTALL_EVENT_TOKEN },
     		{ KongregateAPI.ADJUST_SESSION, SESSION_EVENT_TOKEN },
     		{ KongregateAPI.ADJUST_SALE, SALE_EVENT_TOKEN }};
    

    Note we use different values for Release Candidate builds and Development or QA builds. This helps keep analytics from dev/QA environments from appearing in production analysis.

  3. Initialize the SDKs using KongregateAPI.Initialize. Assuming all the above keys/IDs are set, this will initialize both the Adjust and Kongregate SDKs.

     KongregateAPI.Initialize (gameObject);
    
  4. Set the Common Properties Callback using IAnalytics.SetCommonPropsCallback. The callback you set will be invoked to retrieve properties from your game to include with all events. The fields to include are detailed in the schema provided in the integration welcome email. Entries with Callback listed in the SDK Input column should be returned by your callback.

     KongregateAPI.GetAPI().Analytics.SetCommonPropsCallback(CommonPropsCallback);
    
  5. Invoke IAnalytics.UpdateCommonProps() whenever you’re application is paused or resumed. This helps ensure our SDK has up-to-date common properties when the game goes to or returns from the background.

     void OnApplicationPause(bool pausing) {
       KongregateAPI.GetAPI().Analytics.UpdateCommonProps();
     }
    
  6. Android Only: Kongregate and Adjust SDKs require the installreferrer, play-services-ads-identifier, and support-v4 libraries. If your game uses Google Play Game Services Unity Plugin then you should be all set. Our plugin includes /Assets/Kongregate/Editor/Dependencies.xml which is read and resolved by the PlayServicesResolver included with the Google Play Services Plugin. If you disabled auto-resolve, you may need to run Assets->Play Services Resolver->Android Resolver->Resolver. If you are not using the Google Play Services Plugin and need to pull over these archives, you can find Adjust Instruction’s Here.

Sending Events

The Kongregate and Adjust SDK automatically fire a handful of events, including session_starts and installs. However, our SDK relies on certain API methods to be invoked to fire the iap_transactions events. Other events are sent using the IAnalytics.AddEvent method.

Adding iap_transactions events

The iap_transactions event is fired when you invoke one of the following methods: IAnalytics.AddGoogleIapTransaction() or IAnalytics.AddIOSIapTransaction(). These methods should be invoked after a the receipt has been verified on your server or some third party R/V service. Note PlayFab support receipt validation with their free tier.

These will populate the iap_transactions event with the fields labeled auto in the SDK Input column of your schema. The fields labeled param should be included with the Dictionary parameter passed to this method. This is the eventFields variable in the example below). As usual all common fields will also be included via the common properties callback.

For Android you pass in the revenue in USD along with the Original Receipt JSON and signature returned from Google Play. The example below shows how to pull this information when using UnityPurchasing.

// the USD cost to the product purchased
double revenueUSD = 0.99

// other params from you schema to include with the event
Dictionary<string,object> eventFields = new Dictionary<string,object>() {
  { 'hard_currency_change', 123 }
}

// parse the receipt json and data signature
Dictionary<string,object> receipt = Json.Deserialize(args.purchasedProduct.receipt) as Dictionary<string,object>;
Dictionary<string,object> payload = Json.Deserialize(receipt["Payload"] as string) as Dictionary<string,object>;
string googleReceiptJSON = payload["json"] as string;
string googleSignature = payload["signature"] as string;

// Fire the Kongregate Analytics `iap_transactions` and Adjust `sale` events
KongregateAPI.GetAPI().Analytics.AddGoogleIapTransaction(revenueUSD, googleReceiptJSON, googleSignature, eventFields);

For iOS you must include the unfinished transaction ID along with the revenueUSD and eventFields. For iOS it’s important that the transaction has not been finished/consumed when you invoke this method. Once a method is finished it is removed from the iOS transaction queue and we are unable to extract various details about the transaction. Many IAP plugins automatically consume/finish transactions by default, but most (including UnityPurchasing and Prime31) provide a way to change this behavior.

// parse transaction ID
string transactionId = args.purchasedProduct.transactionID;

// Fire the Kongregate Analytics `iap_transactions` and Adjust `sale` events
KongregateAPI.GetAPI().Analytics.AddIOSIapTransaction(revenueUSD, transactionId, eventFields);

For simplicity KongAnalyticsOnlyDemo.cs does not include receipt validation.

Other Scenarios: If for some reason you are unable to retrieve the Google Play Receipt or obtain the transaction ID prior to the transaction being consumed, we offer a handful of other methods to enable tracking revenue. See KongAnalyticsOnlyDemo.cs and API docs for more details. It is best to use the variants with the receipt/transaction ID so we can extract extra additional information from the purchase to include with the event. Finally, we also offer variants that don’t require revenue in USD. Always specifying cost in USD is preferred because though Adjust will convert revenue into USD, Kongregate Analytics will not. Including costs in USD allows us to normalize revenue in USD everywhere.

The StartPurchase() and FinishPurchase() methods are for games that follow the strict txx_item SKU naming convention of Product IDs. If your game follows this convention you should use the Tracking Purchases Flow, the advantage of which is you do not need to specify USD cost or currency in the API call.

Adding Kongregate Analytics Events

To send events through Kongregate Analytics, simply invoke IAnalytics.AddEvent passing the event name and Dictionary of fields to include. Remember, all fields included with the Common Properties Callback will also be included.

KongregateAPI.GetAPI().Analytics.AddEvent("game_play", new Dictionary<string, object>() {
  { "round", mRound }
});

This event will be sent through Kongregate’s data pipe. However, the event will not be sent to Adjust. In the schema provided with your integration welcome email, events not listed as auto in the Imp Status column should be fired this way.

Adding Additional Adjust Events

To send events to Adjust, you use the same AddEvent() method with an event name using the following format adjust.<token> and an empty event payload.

KongregateAPI.GetAPI.Analytics.AddEvent("adjust.nnclzg", (string) null);

This sends the event with Adjust token nnclzg to the Adjust SDK. You will use this method when sending events other than the sale (or IAP Event), session, or installs events to Adjust. sale, session, and install are automatically fired by our SDK to adjust. The other Adjust Events listed in your integration welcome email should be fired this way.

Initializing Common Props

As stated earlier, the Common Properties Callback should be set immediately after the Initialize() method is invoked. This ensures it’s ready when the first session_starts and/or installs events are fired. A common issue is for a game to need to wait for a response from a server before common properties are available. There are a few ways to handle this.