{"_id":"57c3a192bd48430e00df26e0","category":{"_id":"55dc751b00a8811900c230e3","pages":["55dc75b27fa0290d00559123","55dc75c055be9f21004ee24e","55dc75ef00a8811900c230e7","55dc76036f16451700843e0c","55dc760e00a8811900c230e9","55dc767d55be9f21004ee251","55df5db386ae7f0d00db4ccd","55df64cfaf76b70d0060a60e","55df7263c59b180d005fa70e","55e0b72fa44fae0d002148c5","55e0c42b5087cb1900986c0f","55e36b1bac4eef230079a735","55f363ea2d3bae21009c47aa","55f36bcc5f8674370067b73c","55f36c23ec46040d0030326a","5605d2eda4574a0d00811346","560ac5fef6994b0d0023bca6","561be02937781d0d007942b0","56782f0048c8d00d0094b7fc"],"project":"55db8f8f1a91690d007ad975","version":"55db8f901a91690d007ad978","__v":19,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-25T14:00:59.500Z","from_sync":false,"order":1,"slug":"how-to-get-started","title":"Agent Installation"},"parentDoc":null,"user":"55dde261746ace2b00dd6f73","__v":1,"githubsync":"","project":"55db8f8f1a91690d007ad975","version":{"_id":"55db8f901a91690d007ad978","project":"55db8f8f1a91690d007ad975","__v":17,"createdAt":"2015-08-24T21:41:36.034Z","releaseDate":"2015-08-24T21:41:36.034Z","categories":["55db8f901a91690d007ad979","55db9856b3d6540d00886426","55dc751b00a8811900c230e3","55dc766255be9f21004ee250","55dc769200a8811900c230ed","55e4c701177b6e0d003330fa","55f4915caf0bc71900a53130","55f491b2be9c2b2100f0635d","560b22739c7be70d00100bd8","57488c53e8c6a420000b729c","574cefd95953e20e00f40f9f","5798edfd7700d30e00ad250c","579ac88234b5fd0e00b9e140","57c81c6d690c200e0047b72e","57d9b8fbda17c30e003897f1","57d9b90e608ea00e00f358d8","57d9b91cda17c30e003897f4"],"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-08-29T02:44:34.040Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"# immunio.js\n\n`immunio.js` provides browser-side support for the IMMUNIO agent.  It enables browser side web applications to handle presentation of Captchas when mitigating account take over attacks. `immunio.js` supports 2 methods for serving Captchas:\n  - On page load/reload\n  - On ajax response (for Single Page Application)\n\n## On Page Load/Reload\nThis method can be used when the browser side application loads or reloads the page and the immunio.js script. \n \n### Usage\n\nInclude this script on pages where you want to use the additional features:\n\n```html\n<script src=\"https://cdn.immun.io/v0.3.0/immunio.js\" async defer></script>\n```\n\n*Optional*: \nOnce the script is loaded and ready, it can call an optional callback function, where you can set up any event listeners:\n\n```html\n<script src=\"https://cdn.immun.io/v0.3.0/immunio.js?onload=myCallbackFunction\" async defer></script>\n```\n\n\n### API\n\n`immunio.js` exposes an event emitter style interface:\n\n```js\nimmunio.on(event, callback, [context]) // fire callback on event\nimmunio.once(event, callback, [context]) // fire callback on event once\nimmunio.removeListener(event, callback, [context]) // remove callback from event\n```\n\n#### Supported events:\n  - `captcha-required`: The user must solve a captcha\n  - `captcha-solved`: The user has successfuly solved a captcha\n  - `captcha-expired`: The user's solved captcha has expired.\n    They must re-solve it.\n\n\n### CAPTCHA\n\nThe IMMUNIO agent may require a user to solve a CAPTCHA in response to certain events. Instead of presenting it as a full page CAPTCHA, an element id can be defined in the script tag `data-div` attribute that matches an element in the html:\n\n```html\n<script src=\"https://cdn.immun.io/v0.3.0/immunio.js\" data-div=\"immunio-captcha\" async defer> \n</script>\n\n<div id=\"immunio-captcha\"></div>\n```\n\nIf a CAPTCHA is required, it will be injected into the target element.\n\nThe class of the element will change if a CAPTCHA is required or not:\n  - `immunio-captcha-hidden`\n  - `immunio-captcha-visible`\n\n*Optional*:\n The div supports the following optional data attributes:\n  - `data-submit-element-id`: If provided, the element with this id will be\n    enabled/disabled based on the solved state of the CAPTCHA.\n  - `data-theme`: Either `light` or `dark`. Defaults to `light`.\n\n#### Testing CAPTCHA\n\nTo test display of the CAPTCHA, set `immunio.testCaptcha` in localStorage:\n\n```js\nlocalStorage['immunio.testCaptcha'] = true;\n```\n\nWhen the page is loaded, it will display a CAPTCHA either full page or in a target element if specified.\n\n\n## On Ajax Response\nThis method can be used when the application is for example a Single Page Application, for example built with JavaScript frameworks such as AngularJS.\n\n\n### Usage\nInclude this script on pages where you want to use the additional features:\n\n```html\n<script src=\"https://cdn.immun.io/v0.3.0/immunio.js\" async defer></script>\n```\n\nThe communications between the immunio.js and Immunio agents is done using internal cookies. In order to facilitate the communication, especially with cross domains, all requests must be made with credentials set to true. \n\nIn AngularJS 1.x this can be achieved for example with the following code inserted in a config block of the application:\n\n```js\n$httpProvider.defaults.withCredentials = true;\n```\n\nThe application's JavaScript must then invoke immunio.js' API when a response to an Ajax request to the server returns a 403, as described in the next section\n\n### API\nWhen a request is required to be mitigated with a captcha, the Immunio agents respond to the request with a 403 HTTP response code and include metadata enabling immunio.js to handle the captcha. \n\n`immunio.js` includes a method , triggerCaptcha, that is invoked by the application for immunio.js to handle the captcha. The method returns a boolean indicating whether it handled the captcha or not:\n  - `if true`: `immunio.js` detected the request required to be mitigated with a captcha and handled the captcha presentation.\n  - `if false`: `immunio.js` couldn't handle the captcha presentation. This would be returned for example in the case where the application's server can return 403 for other internal reasons. In that case the application needs to handle the response to the 403.\n\nThe `triggerCaptcha` method can be invoked with or without an arguments, depending on the preferred captcha presentation:\n\n#### Captcha as a Popup/Lightbox\nThis presentation option is the default behaviour, i.e. when `triggerCaptcha` is invoked without arguments. In that case the captcha is presented in a popup. Once resolved, the popup is closed and the user can continue. Example of Javascript for this option:\n\n```js\n$http.post(url + '/login', userObj)\n    .then(function (response) {\n       // success method\n    })\n    .catch(function (err) {\n      if (err.status === 403) {\n         var isCaptcha = immunio.triggerCaptcha();\n\n         // if the 403 was returned by your server rather\n         // than Immunio, isCaptcha is false, in that case\n         // your application can handle the 403.\n         if(!isCaptcha) {\n             //handle application's generated 403 here\n         }\n      }\n    });\n```\n\n#### Captcha in a specified div container\nSupplying the id of a div to the `triggerCaptcha` method will use that div as the captcha container. No popup will occur, the captcha will simply be injected into the desired target div. If a `data-submit-element-id` attribute is found on the captcha container set to the id of another element, the element with the id provided will be disabled. On captcha resolve, the element will be re-enabled and the user can attempt the login again. Example of Javascript for this option:\n\n```js\n$http.post(url + '/login', userObj)\n      .then(function(response){\n        //success method\n      })\n      .catch(function(err){\n        if(err.status === 403){\n          var isCaptcha= immunio.triggerCaptcha(\"captcha-container\");\n\n         // if the 403 was returned by your server rather\n         // than Immunio, isCaptcha is false, in that case\n         // your application can handle the 403.\n          if(!isCaptcha) {\n             //handle application's generated 403 here\n          }\n        }\n      });\n```\n\n```html\n<button id=“login\">Login</button>\n<div id=\"captcha-container\" data-submit-element-id=\"login\"></div>\n```","excerpt":"Integrating IMMUNIO with client-side javacript","slug":"browser-integration","type":"basic","title":"Browser Integration"}

Browser Integration

Integrating IMMUNIO with client-side javacript

# immunio.js `immunio.js` provides browser-side support for the IMMUNIO agent. It enables browser side web applications to handle presentation of Captchas when mitigating account take over attacks. `immunio.js` supports 2 methods for serving Captchas: - On page load/reload - On ajax response (for Single Page Application) ## On Page Load/Reload This method can be used when the browser side application loads or reloads the page and the immunio.js script. ### Usage Include this script on pages where you want to use the additional features: ```html <script src="https://cdn.immun.io/v0.3.0/immunio.js" async defer></script> ``` *Optional*: Once the script is loaded and ready, it can call an optional callback function, where you can set up any event listeners: ```html <script src="https://cdn.immun.io/v0.3.0/immunio.js?onload=myCallbackFunction" async defer></script> ``` ### API `immunio.js` exposes an event emitter style interface: ```js immunio.on(event, callback, [context]) // fire callback on event immunio.once(event, callback, [context]) // fire callback on event once immunio.removeListener(event, callback, [context]) // remove callback from event ``` #### Supported events: - `captcha-required`: The user must solve a captcha - `captcha-solved`: The user has successfuly solved a captcha - `captcha-expired`: The user's solved captcha has expired. They must re-solve it. ### CAPTCHA The IMMUNIO agent may require a user to solve a CAPTCHA in response to certain events. Instead of presenting it as a full page CAPTCHA, an element id can be defined in the script tag `data-div` attribute that matches an element in the html: ```html <script src="https://cdn.immun.io/v0.3.0/immunio.js" data-div="immunio-captcha" async defer> </script> <div id="immunio-captcha"></div> ``` If a CAPTCHA is required, it will be injected into the target element. The class of the element will change if a CAPTCHA is required or not: - `immunio-captcha-hidden` - `immunio-captcha-visible` *Optional*: The div supports the following optional data attributes: - `data-submit-element-id`: If provided, the element with this id will be enabled/disabled based on the solved state of the CAPTCHA. - `data-theme`: Either `light` or `dark`. Defaults to `light`. #### Testing CAPTCHA To test display of the CAPTCHA, set `immunio.testCaptcha` in localStorage: ```js localStorage['immunio.testCaptcha'] = true; ``` When the page is loaded, it will display a CAPTCHA either full page or in a target element if specified. ## On Ajax Response This method can be used when the application is for example a Single Page Application, for example built with JavaScript frameworks such as AngularJS. ### Usage Include this script on pages where you want to use the additional features: ```html <script src="https://cdn.immun.io/v0.3.0/immunio.js" async defer></script> ``` The communications between the immunio.js and Immunio agents is done using internal cookies. In order to facilitate the communication, especially with cross domains, all requests must be made with credentials set to true. In AngularJS 1.x this can be achieved for example with the following code inserted in a config block of the application: ```js $httpProvider.defaults.withCredentials = true; ``` The application's JavaScript must then invoke immunio.js' API when a response to an Ajax request to the server returns a 403, as described in the next section ### API When a request is required to be mitigated with a captcha, the Immunio agents respond to the request with a 403 HTTP response code and include metadata enabling immunio.js to handle the captcha. `immunio.js` includes a method , triggerCaptcha, that is invoked by the application for immunio.js to handle the captcha. The method returns a boolean indicating whether it handled the captcha or not: - `if true`: `immunio.js` detected the request required to be mitigated with a captcha and handled the captcha presentation. - `if false`: `immunio.js` couldn't handle the captcha presentation. This would be returned for example in the case where the application's server can return 403 for other internal reasons. In that case the application needs to handle the response to the 403. The `triggerCaptcha` method can be invoked with or without an arguments, depending on the preferred captcha presentation: #### Captcha as a Popup/Lightbox This presentation option is the default behaviour, i.e. when `triggerCaptcha` is invoked without arguments. In that case the captcha is presented in a popup. Once resolved, the popup is closed and the user can continue. Example of Javascript for this option: ```js $http.post(url + '/login', userObj) .then(function (response) { // success method }) .catch(function (err) { if (err.status === 403) { var isCaptcha = immunio.triggerCaptcha(); // if the 403 was returned by your server rather // than Immunio, isCaptcha is false, in that case // your application can handle the 403. if(!isCaptcha) { //handle application's generated 403 here } } }); ``` #### Captcha in a specified div container Supplying the id of a div to the `triggerCaptcha` method will use that div as the captcha container. No popup will occur, the captcha will simply be injected into the desired target div. If a `data-submit-element-id` attribute is found on the captcha container set to the id of another element, the element with the id provided will be disabled. On captcha resolve, the element will be re-enabled and the user can attempt the login again. Example of Javascript for this option: ```js $http.post(url + '/login', userObj) .then(function(response){ //success method }) .catch(function(err){ if(err.status === 403){ var isCaptcha= immunio.triggerCaptcha("captcha-container"); // if the 403 was returned by your server rather // than Immunio, isCaptcha is false, in that case // your application can handle the 403. if(!isCaptcha) { //handle application's generated 403 here } } }); ``` ```html <button id=“login">Login</button> <div id="captcha-container" data-submit-element-id="login"></div> ```