Analytics Only Unity Quick Start

This Guide details how to integrate Kongregate and Adjust Analytics into your Unity Game.

Download the Kongregate SDK

A Unity Plugin is included with the Kongregate SDK available at the top of the Changlog. Note: You will need to request permission to download our SDK from the Google Drive, if you don’t already have access

Request kong-config.json from Kongregate

Before you begin you will need a kong-config.json file from Kongregate. This file contains the various keys and IDs required to initialize the Kongregate SDK.

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.

Note: some of the demo scripts depends on the Unity Purchasing plugin. You must enable UnityPurchasing before importing the scripts. If you plan to use another In App Purchasing library the demo scripts should still provide a useful reference.

Kongregate Plugin Demo Scripts

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.)

The scene contains a KongregateAPI Game Object with KongregateInit.cs and KongAnalyticsOnlyDemo.cs scripts 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.

In the Unity Inspector drag your kong-config.json file into the Config JSON property associated with the KongregateInit demo script.

Since the Kongregate and Adjust SDKs are native plugins for iOS and Android, they will only work when run on actual devices or simulators and not within the Editor.

Enable Kongregate and Adjust in Your Game!

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

  1. Create an empty Game Object and attach the KongregateInit.cs script to host the Kongregate API. You may use KongAnalyticsOnlyDemo.cs as a starting point.
  2. Drag kong-config.json into your Asset Tree and set as the Config JSON property of your Kongregate API game object.
  3. In the Game Objects Start() method set the common properties callback (KongregateInit.SetCommonPropsCallback()). Implement the callback 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.

     KongregateInit.SetCommonPropsCallback(CommonPropsCallback);
    
  4. 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. The SDK relies on certain API methods to be invoked to fire the iap_transactions events. Other events are sent using the IAnalytics.AddEvent method.

Within your game schema, where the SDK Input is auto, the event and fields are either automatically fired by our SDK or fired in response to an API call such as IAnalytics.AddGoogleIapTransactin(). If the SDK Input is listed as Game Schema the event and fields should be fired using IAnalytics.AddEvent().

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 supports 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. This ensures it’s ready when the session_starts and 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.

Deferred Analytics

To enable deferred analytics change DeferAnalytics property to true in kong-config.json. When set to true, you must manually start the Analytics subsytem by invoking KongregateAPI.GetAPI().Analytics.Start() when you are ready to start firing events.

Release Candidates

By default all analytics are sent to sandbox locations. There are two options to eanble release candidate builds which will send analytics data to production databases.

  1. Change the ReleaseCandidate property in kong-config.json to true.
  2. Set a RELEASE_CANDIDATE Scripting Defind Symbol in your Player Settings. This will take precedent over any value set in kong-config.json