Analytics

🚧

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. This API is available via the AS3 and Javascript interfaces. .

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"
    };
});

kongregate.analytics.setCommonPropsCallback(function(){
    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"
});

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(result:Object):void {
  trace("Purchase box closed");
});

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

kongregate.mtx.purchaseItems("item_identifier", function(result) {
  trace("Purchase box closed");
});

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.

Example: Finishing a purchase

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);
}

function onPurchaseResult(result) {
    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);
}