{"_id":"57c99d19b562960e0086c6e8","__v":0,"category":{"_id":"56af6d6ecc4cbd0d00ce2c88","pages":["56af6e8460a37a0d00ed87ac","56af71e58be2ea0d00b48887","56af73a08be2ea0d00b48890"],"version":"56abbf55f25f160d00e17f51","__v":3,"project":"56abbf55f25f160d00e17f4e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-01T14:36:30.275Z","from_sync":false,"order":2,"slug":"concepts","title":"Kongregate APIs & Concepts"},"project":"56abbf55f25f160d00e17f4e","user":"56abbec30b9e0b0d00616274","parentDoc":null,"version":{"_id":"56abbf55f25f160d00e17f51","project":"56abbf55f25f160d00e17f4e","__v":12,"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-09-02T15:39:05.682Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":true,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":18,"body":"# Kongregate AS3 API for Externally Hosted Games\n\nThe Kongregate AS3 API now supports a basic subset of analytics functionality when used in games hosted on sites other than Kongregate. When loaded outside of Kongregate the user will be treated as a guest, and most functions will be [stubbed out](https://en.wikipedia.org/wiki/Method_stub). Generally, you will only need this functionality if you are instructed to use it by someone at Kongregate.\n\n## Determining which API to load\n\nIn order to make your game utilize the API when hosted either on or off Kongregate, you must write some logic to determine whether to load the standard or external Kongregate API. This must be done in a game-specific fashion. For example, you may want to use the External API in all cases where the game is not either running locally or running on Kongregate (which can generally be determined by looking at the parameters passed into the SWF), like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var hostedUrl:String = LoaderInfo(root.loaderInfo).url;\\nvar paramObj:Object = LoaderInfo(root.loaderInfo).parameters;\\nvar external:Boolean = hostedUrl.indexOf(\\\"file://\\\") != 0 && !paramObj.kongregate;\",\n      \"language\": \"haxe\",\n      \"name\": \"ActionScript 3\"\n    }\n  ]\n}\n[/block]\nThe logic you use to enable the External API may need to be more complex depending on your situation. You may need to look at the domain hosting the SWF to conditionally enable it, for example.\n\n## Conditionally loading the External API\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"If you are using the Kongregate AIR SDK for a web build of your mobile game you can skip this section and see the notes specifically about AIR below.\"\n}\n[/block]\nOnce you have determined whether or not to utilize the External API, you need to slightly modify the code used to load the AS3 API SWF. The External API SWF should be loaded from `https://api.kongregate.com/api/API_AS3.swf` as opposed to using the usual Flash variables (since they will not be passed in when hosted on a site other than Kongregate), below is a basic example of how this can be accomplished:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var apiPath:String;\\nif(external) {\\n  // Load the external API\\n  apiPath = \\\"https://api.kongregate.com/api/API_AS3.swf\\\";\\n} else {\\n  // Load either the normal Kongregate API, or the Local \\\"stub\\\" version\\n  apiPath = paramObj.kongregate_api_path || \\n     \\t\\t\\t\\t\\\"https://assets.kongregate.com/flash/API_AS3_Local.swf\\\";\\n}\\n  \\nSecurity.allowDomain(apiPath);\\nSecurity.allowDomain(apiPath.replace(\\\"api\\\", \\\"assets\\\"));\\n\\nvar request:URLRequest = new URLRequest(apiPath);\\nvar loader:Loader = new Loader();\\nloader.contentLoaderInfo.addEventListener(Event.COMPLETE, \\n                                          onKongregateAPILoaded);\\nloader.load(request);\\nthis.addChild(loader);\",\n      \"language\": \"haxe\",\n      \"name\": \"ActionScript 3\"\n    }\n  ]\n}\n[/block]\n## Initializing the External API\n\nOnce the External API is loaded there is a special `connectExternal` function that needs to be called in place of the normal `connect` method. It accepts a single argument, which is an object containing various configuration properties. The list of properties accepted is as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`game_id`\",\n    \"0-1\": \"`Number`\",\n    \"0-2\": \"The Kongregate game ID for your game\",\n    \"1-0\": \"`client_version`\",\n    \"1-1\": \"`String`\",\n    \"1-2\": \"The current version of your game client\",\n    \"2-0\": \"`analytics_mode`\",\n    \"2-1\": \"`String`\",\n    \"2-2\": \"The analytics mode to use (`auto`, `cloud`, or `none`), use `auto` if unsure\",\n    \"3-0\": \"`swrve_app_id`\",\n    \"3-1\": \"`String`\",\n    \"3-2\": \"Your Swrve application ID\",\n    \"4-0\": \"`swrve_api_key`\",\n    \"4-1\": \"`String`\",\n    \"4-2\": \"Your swrve API key\",\n    \"5-0\": \"`platform`\",\n    \"5-2\": \"Name of the platform the game is hosted on, for example `r2games` or `armorgames`\",\n    \"5-1\": \"`String`\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\nThe `connectExternal` method should be called as soon as the API has finished loading. Below is an example call:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"if(external) {\\n  kongregate.services.connectExternal({\\n    game_id: gameId,\\n    analytics_mode: \\\"auto\\\",\\n    swrve_app_id: \\\"mySwrveAppId\\\",\\n    swrve_api_key: \\\"mySwrveApiKey\\\",\\n    client_version: \\\"1.0.3\\\",\\n    platform: \\\"armorgames\\\"\\n  });\\n} else {\\n  kongregate.services.connect();\\n}\",\n      \"language\": \"haxe\",\n      \"name\": \"ActionScript 3\"\n    }\n  ]\n}\n[/block]\nOnce the `connectExternal` method has been called, you can proceed to utilize the [Analytics API](doc:api-analytics) as you would when hosted on Kongregate. \n\n## Initializing the External API (Kongregate AIR SDK)\n\nThe Kongregate Mobile SDK for AIR supports external hosting for web games. The `externalApi` property of the `Settings` object can be set to an object to let the SDK know that the game is being hosted externally, and the SDK wrapper will take care of loading the proper API SWF for you. If the `externalApi` property is set, and the game is not hosted on Kongregate (determined by looking at the Flash Variables), then the external API will be loaded and initialized.\n\nThe `externalApi` setting can have the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`client_version`\",\n    \"0-1\": \"`String`\",\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"The current version of your game client\",\n    \"1-0\": \"`platform`\",\n    \"1-1\": \"`String`\",\n    \"1-2\": \"Name of the platform the game is hosted on, for example `r2games` or `armorgames`\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\nBelow is an example of setting the `externalApi` object on the `Settings` class for locations that do not begin with `file://`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"if (LoaderInfo(root.loaderInfo).url.indexOf(\\\"file://\\\") != 0) {\\n  KongregateAPI.settings.externalApi = {\\n    platform: 'dreamhost',\\n    clientVersion: '1.0.0'\\n  };\\n}\",\n      \"language\": \"haxe\",\n      \"name\": \"ActionScript 3\"\n    }\n  ]\n}\n[/block]\n## Purchase Tracking\n\nPurchase tracking on external sites is done very similarly to when a game is hosted on Kongregate. However, since the Kreds lightbox is not available and purchasing may occur in a popup window or new tab instead, determining when a purchase has completed can be a bit problematic. \n\nIf your SWF has JavaScript access, we recommend you set up an `ExternalInterface` callback, and then notify your SWF using `window.opener` or a similar mechanism when a purchase has completed. Make sure to pass along a success flag and any transaction ID, where possible.\n\nIt is also recommended to use `window.onbeforeunload` to notify of an unsuccessful purchase if the user decides to close the purchase UI before completion.","excerpt":"","slug":"concepts-external-hosting","type":"basic","title":"Externally Hosted Games"}

Externally Hosted Games


# Kongregate AS3 API for Externally Hosted Games The Kongregate AS3 API now supports a basic subset of analytics functionality when used in games hosted on sites other than Kongregate. When loaded outside of Kongregate the user will be treated as a guest, and most functions will be [stubbed out](https://en.wikipedia.org/wiki/Method_stub). Generally, you will only need this functionality if you are instructed to use it by someone at Kongregate. ## Determining which API to load In order to make your game utilize the API when hosted either on or off Kongregate, you must write some logic to determine whether to load the standard or external Kongregate API. This must be done in a game-specific fashion. For example, you may want to use the External API in all cases where the game is not either running locally or running on Kongregate (which can generally be determined by looking at the parameters passed into the SWF), like so: [block:code] { "codes": [ { "code": "var hostedUrl:String = LoaderInfo(root.loaderInfo).url;\nvar paramObj:Object = LoaderInfo(root.loaderInfo).parameters;\nvar external:Boolean = hostedUrl.indexOf(\"file://\") != 0 && !paramObj.kongregate;", "language": "haxe", "name": "ActionScript 3" } ] } [/block] The logic you use to enable the External API may need to be more complex depending on your situation. You may need to look at the domain hosting the SWF to conditionally enable it, for example. ## Conditionally loading the External API [block:callout] { "type": "info", "title": "Note", "body": "If you are using the Kongregate AIR SDK for a web build of your mobile game you can skip this section and see the notes specifically about AIR below." } [/block] Once you have determined whether or not to utilize the External API, you need to slightly modify the code used to load the AS3 API SWF. The External API SWF should be loaded from `https://api.kongregate.com/api/API_AS3.swf` as opposed to using the usual Flash variables (since they will not be passed in when hosted on a site other than Kongregate), below is a basic example of how this can be accomplished: [block:code] { "codes": [ { "code": "var apiPath:String;\nif(external) {\n // Load the external API\n apiPath = \"https://api.kongregate.com/api/API_AS3.swf\";\n} else {\n // Load either the normal Kongregate API, or the Local \"stub\" version\n apiPath = paramObj.kongregate_api_path || \n \t\t\t\t\"https://assets.kongregate.com/flash/API_AS3_Local.swf\";\n}\n \nSecurity.allowDomain(apiPath);\nSecurity.allowDomain(apiPath.replace(\"api\", \"assets\"));\n\nvar request:URLRequest = new URLRequest(apiPath);\nvar loader:Loader = new Loader();\nloader.contentLoaderInfo.addEventListener(Event.COMPLETE, \n onKongregateAPILoaded);\nloader.load(request);\nthis.addChild(loader);", "language": "haxe", "name": "ActionScript 3" } ] } [/block] ## Initializing the External API Once the External API is loaded there is a special `connectExternal` function that needs to be called in place of the normal `connect` method. It accepts a single argument, which is an object containing various configuration properties. The list of properties accepted is as follows: [block:parameters] { "data": { "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-0": "`game_id`", "0-1": "`Number`", "0-2": "The Kongregate game ID for your game", "1-0": "`client_version`", "1-1": "`String`", "1-2": "The current version of your game client", "2-0": "`analytics_mode`", "2-1": "`String`", "2-2": "The analytics mode to use (`auto`, `cloud`, or `none`), use `auto` if unsure", "3-0": "`swrve_app_id`", "3-1": "`String`", "3-2": "Your Swrve application ID", "4-0": "`swrve_api_key`", "4-1": "`String`", "4-2": "Your swrve API key", "5-0": "`platform`", "5-2": "Name of the platform the game is hosted on, for example `r2games` or `armorgames`", "5-1": "`String`" }, "cols": 3, "rows": 6 } [/block] The `connectExternal` method should be called as soon as the API has finished loading. Below is an example call: [block:code] { "codes": [ { "code": "if(external) {\n kongregate.services.connectExternal({\n game_id: gameId,\n analytics_mode: \"auto\",\n swrve_app_id: \"mySwrveAppId\",\n swrve_api_key: \"mySwrveApiKey\",\n client_version: \"1.0.3\",\n platform: \"armorgames\"\n });\n} else {\n kongregate.services.connect();\n}", "language": "haxe", "name": "ActionScript 3" } ] } [/block] Once the `connectExternal` method has been called, you can proceed to utilize the [Analytics API](doc:api-analytics) as you would when hosted on Kongregate. ## Initializing the External API (Kongregate AIR SDK) The Kongregate Mobile SDK for AIR supports external hosting for web games. The `externalApi` property of the `Settings` object can be set to an object to let the SDK know that the game is being hosted externally, and the SDK wrapper will take care of loading the proper API SWF for you. If the `externalApi` property is set, and the game is not hosted on Kongregate (determined by looking at the Flash Variables), then the external API will be loaded and initialized. The `externalApi` setting can have the following properties: [block:parameters] { "data": { "0-0": "`client_version`", "0-1": "`String`", "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-2": "The current version of your game client", "1-0": "`platform`", "1-1": "`String`", "1-2": "Name of the platform the game is hosted on, for example `r2games` or `armorgames`" }, "cols": 3, "rows": 2 } [/block] Below is an example of setting the `externalApi` object on the `Settings` class for locations that do not begin with `file://`: [block:code] { "codes": [ { "code": "if (LoaderInfo(root.loaderInfo).url.indexOf(\"file://\") != 0) {\n KongregateAPI.settings.externalApi = {\n platform: 'dreamhost',\n clientVersion: '1.0.0'\n };\n}", "language": "haxe", "name": "ActionScript 3" } ] } [/block] ## Purchase Tracking Purchase tracking on external sites is done very similarly to when a game is hosted on Kongregate. However, since the Kreds lightbox is not available and purchasing may occur in a popup window or new tab instead, determining when a purchase has completed can be a bit problematic. If your SWF has JavaScript access, we recommend you set up an `ExternalInterface` callback, and then notify your SWF using `window.opener` or a similar mechanism when a purchase has completed. Make sure to pass along a success flag and any transaction ID, where possible. It is also recommended to use `window.onbeforeunload` to notify of an unsuccessful purchase if the user decides to close the purchase UI before completion.