{"_id":"570ec06f53bfcc0e0037f22c","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"},"__v":8,"parentDoc":null,"project":"56abbf55f25f160d00e17f4e","category":{"_id":"575709000fd6a3200010dded","project":"56abbf55f25f160d00e17f4e","__v":0,"version":"56abbf55f25f160d00e17f51","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-06-07T17:48:48.065Z","from_sync":false,"order":0,"slug":"test","title":"Platform Overview"},"user":"56abbec30b9e0b0d00616274","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-13T21:55:59.988Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"## Handling Guests in Kongregate Games\n\nSince guests are not allowed to access many different parts of the API, each developer must decide how they want to treat them. This document will go over how to detect when a user converts from a guest to a registered user in-page, which can happen without your game being reloaded. This documentation is meant to be supplimental to all other API documentation, and it assumes you have a general knowledge of how our API works, and are interested in improving the experience for guests who play your game.\n\nYou can determine if the user is a guest initially by calling the `isGuest` function on the Kongregate API services object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.services.isGuest();\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.services.isGuest();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Testing guest functionality\n\nIn order to test your game as a guest while it is still in the preview state, you must append a special `guest_access_key` parameter to your game URL. The link to your game which includes this key can be found on the same page as your API key as described in the [Server Side HTTP documentation](doc:server-side-http).\n\n## Guest to user conversion\n\nThere are two different methods possible for detecting when a user signs into their account while playing your game: listening for an event and manual polling.\n\n### User sign-in event\n\nWhen a user signs in using the welcome box or the link from chat, your application will receive an event (if you have registered for it) and you can process it however you like. Once the user is signed in, they will be able to save data, submit statistics, etc.\n\n**Integration**\n\nOnce the Kongregate client API has successfully loaded into your application, you may register an event listener to let you know when a player converts from a guest to a registered user, which can happen without the page being reloaded:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.services.addEventListener(\\\"login\\\", onKongregateInPageLogin);\\n\\nfunction onKongregateInPageLogin(event:Event):void {\\n  var user_id:Number = kongregate.services.getUserId();\\n  var username:String = kongregate.services.getUsername();\\n  var token:String = kongregate.services.getGameAuthToken();\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.services.addEventListener(\\\"login\\\", onKongregateInPageLogin);\\n\\nfunction onKongregateInPageLogin() {\\n  var user_id = kongregate.services.getUserId();\\n  var username = kongregate.services.getUsername();\\n  var token = kongregate.services.getGameAuthToken();\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n**AS2 integration**\n\nUnfortunately, no official API is currently available for hooking into this event with AS2, but the following code template (while a bit dirty) should suffice:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var services = _global.kongregate.services;\\nvar isGuest:Boolean = services.isGuest();\\n\\n// Register an event listener if the user is a guest, otherwise we can skip it\\nif( isGuest ){\\n  services.addMessageHandler({handleMessage:myMessageHandler});\\n}\\n\\n// This function handles internal Kongregate API messages, we use it to listen\\n// for the sign-in message so we can be notified when a user converts from a\\n// guest to a user. \\nfunction myMessageHandler(msg):Void{\\n    // Make sure to only handle the \\\"user.info\\\" message\\n  if(msg.getOpcode() == \\\"user.info\\\"){\\n    // If we started as a guest and aren't anymore, a sign-in occured\\n    if(isGuest && !services.isGuest()){\\n      // Don't process this message more than once\\n      isGuest = false;\\n\\n      // At this point services.getUsername() will contain the new username,\\n      // services.getUserId() will contain the player's Kongregate user_id,\\n      // and services.getGameAuthToken() will contain the new auth_token\\n    }\\n  }\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 2\"\n    }\n  ]\n}\n[/block]\n### Manual polling\n\nWhile slightly less efficient, this is can be the simplest method for catching the username/user_id change, as you can do it on your own terms, and handle the change when you are ready.\n\nYou can check manually for the username change by calling the `isGuest` function on the `kongregate.services` object, and detecting the change. If the user starts out as a guest, and they sign-in, the function will return `true`, and you can retrieve their `game_auth_token` and `user_id` using the `getGameAuthToken` and `getUserId` functions.\n\n## Showing the registration lightbox\n\nYou can use the Kongregate API to display a sign-in/register lightbox to the user. This functionality comes in handy for up-selling the user to create a Kongregate account, for example if they want to purchase an item.\n\nThis will show a registration overlay, exactly as if they had clicked the \"sign-in\" or \"register\" link in the chat UI:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"kongregate.services.showRegistrationBox();\",\n      \"language\": \"javascript\",\n      \"name\": \"ActionScript 3\"\n    },\n    {\n      \"code\": \"kongregate.services.showRegistrationBox();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf the user successfully signs in, or registers an account, you will receive the login event as described above which contains their new username and game_auth_token.\n\nWhen possible, especially on guest landing pages prior to loading a game, please use the Kongregate registration button provided below:\n\n![](https://cdn4.kongcdn.com/assets/files/0001/4446/kongregate-reg-btn-vertical.png) [Download](https://cdn2.kongcdn.com/assets/files/0001/4443/kongregate-reg-btn-vertical.png.zip)\n\n![](https://cdn3.kongcdn.com/assets/files/0001/4445/kongregate-reg-btn-horizontal.png) [Download](https://cdn2.kongcdn.com/assets/files/0001/4442/kongregate-reg-btn-horizontal.png.zip)","excerpt":"","slug":"concepts-handling-guests","type":"basic","title":"Handling Guests"}
## Handling Guests in Kongregate Games Since guests are not allowed to access many different parts of the API, each developer must decide how they want to treat them. This document will go over how to detect when a user converts from a guest to a registered user in-page, which can happen without your game being reloaded. This documentation is meant to be supplimental to all other API documentation, and it assumes you have a general knowledge of how our API works, and are interested in improving the experience for guests who play your game. You can determine if the user is a guest initially by calling the `isGuest` function on the Kongregate API services object: [block:code] { "codes": [ { "code": "kongregate.services.isGuest();", "language": "javascript", "name": "ActionScript 3" }, { "code": "kongregate.services.isGuest();", "language": "javascript" } ] } [/block] ## Testing guest functionality In order to test your game as a guest while it is still in the preview state, you must append a special `guest_access_key` parameter to your game URL. The link to your game which includes this key can be found on the same page as your API key as described in the [Server Side HTTP documentation](doc:server-side-http). ## Guest to user conversion There are two different methods possible for detecting when a user signs into their account while playing your game: listening for an event and manual polling. ### User sign-in event When a user signs in using the welcome box or the link from chat, your application will receive an event (if you have registered for it) and you can process it however you like. Once the user is signed in, they will be able to save data, submit statistics, etc. **Integration** Once the Kongregate client API has successfully loaded into your application, you may register an event listener to let you know when a player converts from a guest to a registered user, which can happen without the page being reloaded: [block:code] { "codes": [ { "code": "kongregate.services.addEventListener(\"login\", onKongregateInPageLogin);\n\nfunction onKongregateInPageLogin(event:Event):void {\n var user_id:Number = kongregate.services.getUserId();\n var username:String = kongregate.services.getUsername();\n var token:String = kongregate.services.getGameAuthToken();\n}", "language": "javascript", "name": "ActionScript 3" }, { "code": "kongregate.services.addEventListener(\"login\", onKongregateInPageLogin);\n\nfunction onKongregateInPageLogin() {\n var user_id = kongregate.services.getUserId();\n var username = kongregate.services.getUsername();\n var token = kongregate.services.getGameAuthToken();\n}", "language": "javascript" } ] } [/block] **AS2 integration** Unfortunately, no official API is currently available for hooking into this event with AS2, but the following code template (while a bit dirty) should suffice: [block:code] { "codes": [ { "code": "var services = _global.kongregate.services;\nvar isGuest:Boolean = services.isGuest();\n\n// Register an event listener if the user is a guest, otherwise we can skip it\nif( isGuest ){\n services.addMessageHandler({handleMessage:myMessageHandler});\n}\n\n// This function handles internal Kongregate API messages, we use it to listen\n// for the sign-in message so we can be notified when a user converts from a\n// guest to a user. \nfunction myMessageHandler(msg):Void{\n // Make sure to only handle the \"user.info\" message\n if(msg.getOpcode() == \"user.info\"){\n // If we started as a guest and aren't anymore, a sign-in occured\n if(isGuest && !services.isGuest()){\n // Don't process this message more than once\n isGuest = false;\n\n // At this point services.getUsername() will contain the new username,\n // services.getUserId() will contain the player's Kongregate user_id,\n // and services.getGameAuthToken() will contain the new auth_token\n }\n }\n}", "language": "javascript", "name": "ActionScript 2" } ] } [/block] ### Manual polling While slightly less efficient, this is can be the simplest method for catching the username/user_id change, as you can do it on your own terms, and handle the change when you are ready. You can check manually for the username change by calling the `isGuest` function on the `kongregate.services` object, and detecting the change. If the user starts out as a guest, and they sign-in, the function will return `true`, and you can retrieve their `game_auth_token` and `user_id` using the `getGameAuthToken` and `getUserId` functions. ## Showing the registration lightbox You can use the Kongregate API to display a sign-in/register lightbox to the user. This functionality comes in handy for up-selling the user to create a Kongregate account, for example if they want to purchase an item. This will show a registration overlay, exactly as if they had clicked the "sign-in" or "register" link in the chat UI: [block:code] { "codes": [ { "code": "kongregate.services.showRegistrationBox();", "language": "javascript", "name": "ActionScript 3" }, { "code": "kongregate.services.showRegistrationBox();", "language": "javascript" } ] } [/block] If the user successfully signs in, or registers an account, you will receive the login event as described above which contains their new username and game_auth_token. When possible, especially on guest landing pages prior to loading a game, please use the Kongregate registration button provided below: ![](https://cdn4.kongcdn.com/assets/files/0001/4446/kongregate-reg-btn-vertical.png) [Download](https://cdn2.kongcdn.com/assets/files/0001/4443/kongregate-reg-btn-vertical.png.zip) ![](https://cdn3.kongcdn.com/assets/files/0001/4445/kongregate-reg-btn-horizontal.png) [Download](https://cdn2.kongcdn.com/assets/files/0001/4442/kongregate-reg-btn-horizontal.png.zip)