Kongregate Developers

Note: This feature is only enabled for games published by Kongregate. Your Kongregate producer will contact you when it is time to enable and implement analytics for your game.

Kongregate Analytics API

Kongregate's Analytics API allows you to track in-game events and monetization in your game.

The Analytics API is available via the AS3 and Javascript interfaces. The examples here are in AS3, but can be ported to Javascript by removing the type information.

Overview

The Analytics API can be accessed via the analytics object on the Kongregate API.

Common Properties

You can use the setCommonPropsCallback function to set a callback to be evaluated before event submission. These properties will automatically be evaluated and attached to all events.

Example: Setting a common properties callback
kongregate.analytics.setCommonPropsCallback(function():Object{
    return {
        random_number: Math.random(),
        array: [1,2,3],
        string: "A string"
    };
});

Submitting Events

The addEvent function can be used to submit an analytics event to the server. The first argument is the name of the event, and the second is an object containing the properties, which will be merged with both the common properties and Kongregate automatic properties.

Example: Submitting an event with properties
kongregate.analytics.addEvent("my_event_name", { 
  prop_name: "value", 
  another_prop: "another value"
});

Tracking Purchases

The startPurchase and finishPurchase functions should be used in combination with the virtual goods function calls in order to track purchasing and revenue information. The functions will automatically handle adding the product_id, iap_id, currency, and cost information to the submitted event payload, so you don't need to add those to the parameters. Currently, the Dynamic Purchase API is not supported for analytics.

Starting a Purchase

The startPurchase function accepts a item identifier string, and a parameters object. It generates the iap_attempts analytics event. You should call this function immediately before showing the purchase dialog. The item identifier should be the same one you pass to purchaseItems, as that will allow pricing information to be retrieved. Below is an example of how to track the start of a purchase:

Example: Starting a purchase
kongregate.analytics.startPurchase("item_identifier", {
    type: "my_type",
    discount_percent: 0,
    context_of_offer: "Storefront"
});

kongregate.mtx.purchaseItems("item_identifier", function(){/*...*/});

Finishing a Purchase

The finishPurchase method accepts a status string, a transaction id, and a parameters object. It generates either a iap_transactions or iap_fails event. This function should be called from the callback you passed into purchaseItems, as it uses some fields from the result object. Below is an example of how to use this method:
function onPurchaseResult(result:Object):void {
    var data:Object = {};
    if(result.success) {
        data = {
            type: "my_type",
            discount_percent: 0,
            context_of_offer: "Storefront",
            hard_currency_change: 50,
            soft_currency_change: 0,
            resources_change: null
        };
    }
	
    var status:String = result.success ? "SUCCESS" : "FAIL";
    kongregate.analytics.finishPurchase(status, result.purchase_id, data);
}

Comments