{"__v":3,"_id":"570eae804a84800e0059a8ee","category":{"__v":3,"_id":"56af6d6ecc4cbd0d00ce2c88","pages":["56af6e8460a37a0d00ed87ac","56af71e58be2ea0d00b48887","56af73a08be2ea0d00b48890"],"project":"56abbf55f25f160d00e17f4e","version":"56abbf55f25f160d00e17f51","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-01T14:36:30.275Z","from_sync":false,"order":2,"slug":"concepts","title":"Kongregate APIs & Concepts"},"parentDoc":null,"project":"56abbf55f25f160d00e17f4e","user":"56abbec30b9e0b0d00616274","version":{"__v":12,"_id":"56abbf55f25f160d00e17f51","project":"56abbf55f25f160d00e17f4e","createdAt":"2016-01-29T19:36:53.665Z","releaseDate":"2016-01-29T19:36:53.665Z","categories":["56abbf56f25f160d00e17f52","56abca6bf9757e0d007c6650","56acddfa0ab3c00d00ce3332","56af65da9d32e30d0006d30f","56af66cab34d210d003d9ad0","56af6afcd21e9c0d00b628d1","56af6d6ecc4cbd0d00ce2c88","5705b12221cfed0e00e8c580","570a5676ade45d0e00c1ad33","570d7d25d1e4b82000d9e385","570eac3c3160d10e0041df0e","575709000fd6a3200010dded"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-13T20:39:28.024Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"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.\",\n  \"title\": \"Note\"\n}\n[/block]\n## Kongregate Analytics API\n\nKongregate'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. .\n\n### Overview\n\nThe Analytics API can be accessed via the `analytics` object on the Kongregate API.\n\n### Common Properties\n\nYou 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.\n\n**Example: Setting a common properties callback**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.analytics.setCommonPropsCallback(function():Object{\\n    return {\\n        random_number: Math.random(),\\n        array: [1,2,3],\\n        string: \\\"A string\\\"\\n    };\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.analytics.setCommonPropsCallback(function(){\\n    return {\\n        random_number: Math.random(),\\n        array: [1,2,3],\\n        string: \\\"A string\\\"\\n    };\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### Submitting Events\n\nThe `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.\n\n**Example: Submitting an event with properties**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.analytics.addEvent(\\\"my_event_name\\\", { \\n  prop_name: \\\"value\\\", \\n  another_prop: \\\"another value\\\"\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.analytics.addEvent(\\\"my_event_name\\\", { \\n  prop_name: \\\"value\\\", \\n  another_prop: \\\"another value\\\"\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### Tracking Purchases\n\nThe `startPurchase` and `finishPurchase` functions should be used in combination with the [virtual goods](doc:concepts-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.\n\n#### Starting a Purchase\n\nThe `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:\n\n**Example: Starting a purchase**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.analytics.startPurchase(\\\"item_identifier\\\", {\\n    type: \\\"my_type\\\",\\n    discount_percent: 0,\\n    context_of_offer: \\\"Storefront\\\"\\n});\\n\\nkongregate.mtx.purchaseItems(\\\"item_identifier\\\", function(result:Object):void {\\n  trace(\\\"Purchase box closed\\\");\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.analytics.startPurchase(\\\"item_identifier\\\", {\\n    type: \\\"my_type\\\",\\n    discount_percent: 0,\\n    context_of_offer: \\\"Storefront\\\"\\n});\\n\\nkongregate.mtx.purchaseItems(\\\"item_identifier\\\", function(result) {\\n  trace(\\\"Purchase box closed\\\");\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n#### Finishing a Purchase\n\nThe `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.\n\n**Example: Finishing a purchase**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"function onPurchaseResult(result:Object):void {\\n    var data:Object = {};\\n    if(result.success) {\\n        data = {\\n            type: \\\"my_type\\\",\\n            discount_percent: 0,\\n            context_of_offer: \\\"Storefront\\\",\\n            hard_currency_change: 50,\\n            soft_currency_change: 0,\\n            resources_change: null\\n        };\\n    }\\n\\n    var status:String = result.success ? \\\"SUCCESS\\\" : \\\"FAIL\\\";\\n    kongregate.analytics.finishPurchase(status, result.purchase_id, data);\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"function onPurchaseResult(result) {\\n    var data:Object = {};\\n    if(result.success) {\\n        data = {\\n            type: \\\"my_type\\\",\\n            discount_percent: 0,\\n            context_of_offer: \\\"Storefront\\\",\\n            hard_currency_change: 50,\\n            soft_currency_change: 0,\\n            resources_change: null\\n        };\\n    }\\n\\n    var status:String = result.success ? \\\"SUCCESS\\\" : \\\"FAIL\\\";\\n    kongregate.analytics.finishPurchase(status, result.purchase_id, data);\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"Track in-game events","slug":"api-analytics","type":"basic","title":"Analytics"}

Analytics

Track in-game events

[block:callout] { "type": "warning", "body": "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.", "title": "Note" } [/block] ## 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** [block:code] { "codes": [ { "code": "kongregate.analytics.setCommonPropsCallback(function():Object{\n return {\n random_number: Math.random(),\n array: [1,2,3],\n string: \"A string\"\n };\n});", "language": "javascript", "name": "ActionScript 3" }, { "code": "kongregate.analytics.setCommonPropsCallback(function(){\n return {\n random_number: Math.random(),\n array: [1,2,3],\n string: \"A string\"\n };\n});", "language": "javascript" } ] } [/block] ### 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** [block:code] { "codes": [ { "code": "kongregate.analytics.addEvent(\"my_event_name\", { \n prop_name: \"value\", \n another_prop: \"another value\"\n});", "language": "javascript", "name": "ActionScript 3" }, { "code": "kongregate.analytics.addEvent(\"my_event_name\", { \n prop_name: \"value\", \n another_prop: \"another value\"\n});", "language": "javascript" } ] } [/block] ### Tracking Purchases The `startPurchase` and `finishPurchase` functions should be used in combination with the [virtual goods](doc:concepts-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** [block:code] { "codes": [ { "code": "kongregate.analytics.startPurchase(\"item_identifier\", {\n type: \"my_type\",\n discount_percent: 0,\n context_of_offer: \"Storefront\"\n});\n\nkongregate.mtx.purchaseItems(\"item_identifier\", function(result:Object):void {\n trace(\"Purchase box closed\");\n});", "language": "javascript", "name": "ActionScript 3" }, { "code": "kongregate.analytics.startPurchase(\"item_identifier\", {\n type: \"my_type\",\n discount_percent: 0,\n context_of_offer: \"Storefront\"\n});\n\nkongregate.mtx.purchaseItems(\"item_identifier\", function(result) {\n trace(\"Purchase box closed\");\n});", "language": "javascript" } ] } [/block] #### 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** [block:code] { "codes": [ { "code": "function onPurchaseResult(result:Object):void {\n var data:Object = {};\n if(result.success) {\n data = {\n type: \"my_type\",\n discount_percent: 0,\n context_of_offer: \"Storefront\",\n hard_currency_change: 50,\n soft_currency_change: 0,\n resources_change: null\n };\n }\n\n var status:String = result.success ? \"SUCCESS\" : \"FAIL\";\n kongregate.analytics.finishPurchase(status, result.purchase_id, data);\n}", "language": "javascript", "name": "ActionScript 3" }, { "code": "function onPurchaseResult(result) {\n var data:Object = {};\n if(result.success) {\n data = {\n type: \"my_type\",\n discount_percent: 0,\n context_of_offer: \"Storefront\",\n hard_currency_change: 50,\n soft_currency_change: 0,\n resources_change: null\n };\n }\n\n var status:String = result.success ? \"SUCCESS\" : \"FAIL\";\n kongregate.analytics.finishPurchase(status, result.purchase_id, data);\n}", "language": "javascript" } ] } [/block]