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 Analytics.AddEvent (Unity/Android/iOS) 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().
The iap_transactions event is fired when you invoke one of the following methods:
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.
Unity Android:
// 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);
Native Android:
// Object with access to original JSON receipt and signature
Purchase purchase = ...
// other params from you schema to include with the event
Map<String,Object> eventFields = new HashMap<String, Object>();
eventFields.put("hard_currency_change", 5);
// Fire the Kongregate Analytics `iap_transactions` and Adjust `sale` events
mAPI.analytics().addIapTransaction(0.99, purchase.getOriginalJson(), purchase.getSignature(), 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.
Unity iOS:
// parse transaction ID from the unfinished transaction
string transactionId = args.purchasedProduct.transactionID;
// Fire the Kongregate Analytics `iap_transactions` and Adjust `sale` events
KongregateAPI.GetAPI().Analytics.AddIOSIapTransaction(revenueUSD, transactionId, eventFields);
Native iOS:
// the unfinished transaction
SKPaymentTransaction* transaction = ...
// other params from you schema to include with the event
NSDictionary* eventFields = @{ @"hard_currency_change": @5 };
// Fire the Kongregate Analytics `iap_transactions` and Adjust `sale` events
[KongregateAPI.instance.analytics addIapTransaction:1.99
withTransactionId:transaction.transactionIdentifier
withGameFields:eventFields];
// It is now safe to remove the transaction from the payment queue
[[SKPaymentQueue defaultQueue] finishTransaction:transaction];
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 Unity/iOS/Android 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.
To send events through Kongregate Analytics, simply invoke IAnalytics.AddEvent (Unity/iOS/Android) passing the event name and Dictionary of fields to include. Remember, all fields included with the Common Properties Callback will also be included.
Unity:
KongregateAPI.GetAPI().Analytics.AddEvent("game_play", new Dictionary<string, object>() {
{ "round", mRound }
});
iOS:
[[[KongregateAPI instance] analytics] addEvent:@{@"round": @1 } toCollection:@"game_play"];
Android:
Map<String,Object> event = new HashMap<String, Object>();
event.put("round", 1);
mKongAPI.analytics().addEvent("game_play", event);
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.
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.
Unity:
KongregateAPI.GetAPI.Analytics.AddEvent("adjust.nnclzg", (string) null);
iOS:
[[[KongregateAPI instance] analytics] addEvent:nil toCollection:@"adjust.nnclzg"];
Android:
mKongAPI.analytics().addEvent("adjust.nnclzg", 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.
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.
To enable deferred analytics for Unity change DeferAnalytics property to true in kong-config.json. For iOS and Android you may enable deferred analytics by setting the KONGREGATE_OPTION_DEFER_ANALYTICS option to true in your API settings may when you initialize the SDK.
When set to true, you must manually start the Analytics subsytem by invoking KongregateAPI.GetAPI().Analytics.Start() (Unity/iOSAndroid)when you are ready to start firing events.