{"id":22093214,"url":"https://github.com/iadvize/boxed-tag","last_synced_at":"2025-03-24T00:27:05.394Z","repository":{"id":154828972,"uuid":"632434987","full_name":"iadvize/boxed-tag","owner":"iadvize","description":null,"archived":false,"fork":false,"pushed_at":"2023-06-01T14:49:03.000Z","size":237,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-04-27T07:14:10.181Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iadvize.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-25T12:00:40.000Z","updated_at":"2023-05-04T07:55:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"aa39a767-f77e-4e1d-96ca-ffabe7101197","html_url":"https://github.com/iadvize/boxed-tag","commit_stats":null,"previous_names":["iadvize/sandboxed-tag"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iadvize%2Fboxed-tag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iadvize%2Fboxed-tag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iadvize%2Fboxed-tag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iadvize%2Fboxed-tag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iadvize","download_url":"https://codeload.github.com/iadvize/boxed-tag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244989590,"owners_count":20543548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-01T03:13:17.893Z","updated_at":"2025-03-24T00:27:05.357Z","avatar_url":"https://github.com/iadvize.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boxed tag\n\nThe “iAdvize Boxed Tag” is a way to include the iAdvize Tag in the most secure way, without it having access to the client’s website.\n\nWith this solution, the iAdvize tag can be loaded in an isolated box (a sandboxed iframe).\nThis way, the main page context cannot be accessed by the iAdvize tag: the main page only sends controlled, relevant data to the boxed tag.\n\n# Simple installation\nThis is the simplest way too add the iAdvize Boxed Tag to a website with the default configuration.\n\n## 1 - Serve this HTML file\n\nServe a HTML file. We will use the name `iadvize-boxed-iframe.html`, but any name can be chosen.\nThis file needs to be served on the same top domain as the page it will be included in.\nReplace `\u003cyour-sid\u003e` with your own sid.\n\nEx : \n- Web page : https://hostpage.brand-domain.com\n- Iframe : https://static.brand-domain.com/iadvize-boxed-iframe.html\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003cbody\u003e\n   \u003cscript src=\"https://static.iadvize.com/boxed-tag/1.4.4/index.js\" integrity=\"sha512-NS7M2FyNHaefJ42ilas6W+t/qJleeGTWIyhM2pj2Pn+t7PgWRH/HarBqV8HT+RFDi6JVS1ReAeF2Afz5dwpBjQ==\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n    \u003cscript\u003e\n      window.iAdvizeBoxedTag.initIAdvizeIframe(\u003cyour-sid\u003e, \"halc\");\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## 2 - Add the following script\n\nAdd the following script (in your frontend code, or in your tag manager), replacing `https://static.brand-domain.com/iadvize-boxed-iframe.html` with the actual URL of the iframe : \n\n```javascript\n// Change this URL with the actual URL of the iframe\nconst iAdvizeIframeUrl = \"https://static.brand-domain.com/iadvize-boxed-iframe.html\";\n\nconst style = document.createElement(\"style\");\nstyle.innerHTML = `\n  #iAdvizeSandboxedIframe {\n    border: none;\n    position: fixed;\n    bottom: 0;\n    right: 0;\n    width: 100vw;\n    height: 100vh;\n    pointer-events: none;\n    z-index: 2147483647;\n  }\n`;\ndocument.body.append(style);\n\nconst boxedTagScript = document.createElement(\"script\");\nboxedTagScript.src =\n  \"https://static.iadvize.com/boxed-tag/1.4.4/index.js\";\nboxedTagScript.integrity =\n\"sha512-NS7M2FyNHaefJ42ilas6W+t/qJleeGTWIyhM2pj2Pn+t7PgWRH/HarBqV8HT+RFDi6JVS1ReAeF2Afz5dwpBjQ==\";\nboxedTagScript.crossOrigin = \"anonymous\";\n\nconst iAdvizeSandboxedIframe = document.createElement(\"iframe\");\niAdvizeSandboxedIframe.sandbox = \"allow-scripts allow-same-origin allow-popups allow-forms\";\niAdvizeSandboxedIframe.allow = \"camera;microphone;autoplay\";\niAdvizeSandboxedIframe.src = iAdvizeIframeUrl;\niAdvizeSandboxedIframe.id = \"iAdvizeSandboxedIframe\";\ndocument.body.append(iAdvizeSandboxedIframe);\n\nboxedTagScript.onload = function () {\n  window.iAdvizeBoxedTag.initIAdvizeHost(\"iAdvizeSandboxedIframe\");\n};\n\ndocument.body.append(boxedTagScript);\n```\n\n# Advanced installation\nThis is a more advanced installation, allowing : \n- a custom configuration,\n- the use of WebSDK methods (see https://developers.iadvize.com/documentation/javascript-web-sdk#javascript-web-sdk).\n\n## Install the lib on your project\n\n```\nnpm install @iadvize-oss/boxed-tag\n```\n\n## Create the iframe script\n\nCreate a js file that will import the iframe script.\nThen call `initIAdvizeIframe` to listen the host messages.\nThe `initIAdvizeIframe` comes with 2 arguments :\n\n- `sid` : your iAdvize sid.\n- `iAdvizePlatform` : the iadvize platform (default: ha).\n\n```js\nimport { initIAdvizeIframe } from '@iadvize-oss/boxed-tag';\n\ninitIAdvizeIframe(\u003csid\u003e, \u003ciAdvizePlatform\u003e);\n```\n\n## Add a boxed iframe\n\nAdd a boxed iframe on your site's main page.\n\n```html\n\u003ciframe\n  title=\"iAdvize chat notification frame\"\n  sandbox=\"allow-scripts allow-same-origin allow-popups allow-forms\"\n  allow=\"camera;microphone;autoplay\"\n  src=\"https://my-iframe-script-url\"\n  id=\"myIframeId\"\n\u003e\u003c/iframe\u003e\n```\nThe iframe is set with the following sandbox parameters:\n| sandbox param     | description                                                    |\n|-------------------|----------------------------------------------------------------|\n| allow-scripts     | Allows the page to run iAdvize tag script.                     |\n| allow-same-origin | Allows the iAdvize tag to access the host cookies and storages |\n| allow-popups      | Allows the iAdvize tag to open links sent by the agent         |\n| allow-forms       | Allows the iAdvize tag to submit the visitor email if needed   |\n\nAnd the following allow parameters:\n| allow param       | description                                                             |\n|-------------------|-------------------------------------------------------------------------|\n| camera            | Allows the boxed tag to ask the camera permission (for video calls)     |\n| microphone        | Allows the boxed tag to ask the microphone permission (for video calls) |\n| autoplay          | Allows the boxed tag to launch the video stream automatically           |\n\n## Add the host script on your site's main page\n\nCreate a js file with the host lib import, then call `initIAdvizeHost` to listen to the iframe messages.\n\n```js\nimport { initIAdvizeHost } from '@iadvize-oss/boxed-tag';\n\ninitIAdvizeHost('myIframeId');\n```\n\n# Communication\nThe only way to start a communication between the host and the sandboxed iframe is the `window.postMessage` method provided by the navigators (see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).\n\n\u003e **warning**\n\u003e The postMessage data is serialized, so functions cannot be sent (see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#parameters).\n\nThen, the target of the postMessage calls can listen to the events using `window.addEventListener('message')`.\n\n\u003e **warning**\n\u003e The source of the event should be checked to avoid conflicts and security concerns (see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns).\n\n\n\n## Call iAdvize WebSDK methods from host\n\nWebSDK methods cannot be called from the host context because the iAdvize tag is isolated in the iframe : we need to communicate to the iframe what we want to call.  \n\nAfter having called `initIAdvizeHost`, a `iAdvizeBoxedInterface` object is available in the host window context.  \nThis object sends the `method` name and `args` to the iframe, that will call the webSDK.\nThe `activate`, `get` and `on` methods can return a value to the host :  \nto retrieve it, add a `window.addEventListener(\"message\")` and check the `e.data.method` property to recognize the method called.\n\n### Navigate\n```js\n// WebSDK navigate\nwindow.iAdvizeBoxedInterface.push({\n  method: 'navigate',\n  args: [window.location.href],\n});\n```\n\n### Activate\nThe host can listen to the result of the `activate` call.\n\nFor an anonymous authentication: \n\n```js\n// WebSDK activate anonymous\nwindow.iAdvizeBoxedInterface.push({\n  method: 'activate',\n  args: {\n    authenticationOption: { type: 'ANONYMOUS' },\n  },\n});\n\n// Listen to activate result\nwindow.addEventListener('message', ({ data: { method, activation } }) =\u003e {\n  if (method === 'activate') {\n    console.log(activation); // activation return object : success or failure\n  }\n});\n```\n\nFor a secured authentication, the JWE token should be generated on the host side and sent to the iframe : \n - the host should listen a `get-activate-auth-token` message initiated by the iframe.\n - the backend api then gets the JWE token,\n - the token is then sent to the iframe inside a `set-activate-auth-token` message.\n\nThe `get-activate-auth-token` listener allows the iframe to ask for a token refresh if needed.\n\nExample of secured authentication implementation: \n```js\n// WebSDK activate secured auth\nconst getJweToken = Promise.resolve('myJWEToken');// your backend logic to generate a JWE\n\nwindow.iAdvizeBoxedInterface.push({\n  method: 'activate',\n  args: {\n    authenticationOption: {\n      type: 'SECURED_AUTHENTICATION',\n    },\n  },\n});\n\n// Listen to activate result\nwindow.addEventListener('message', ({ data: { method, activation } }) =\u003e {\n  // Handle authentication token\n  if (method === 'get-activate-auth-token') {\n    getJweToken().then((token) =\u003e\n      window.iAdvizeBoxedInterface.push({\n        method: 'set-activate-auth-token',\n        args: `${token}`,\n      }),\n    );\n  }\n  if (method === 'activate') {\n    console.log(activation); // activation return object : success or failure\n  }\n});\n\n```\n\n### Logout\nThe host can listen to the result of the `logout` call.\n\nExample of implementation:\n```js\n// WebSDK logout\nwindow.iAdvizeBoxedInterface.push({\n  method: 'logout',\n});\n\n// Listen to logout\nwindow.addEventListener('message', ({ data: { method } }) =\u003e {\n  if (method === 'logout') {\n    // Do something after logout\n  }\n});\n```\n\n### On\nThe host can listen to the result of the `on` call.\n\nExample of implementation:\n```js\n// WebSDK on\nwindow.iAdvizeBoxedInterface.push({\n  method: 'on',\n  args: ['visitor:cookiesConsentChanged'],\n});\n\n// Listen to cookiesConsentChanged result\nwindow.addEventListener('message', ({ data: { method, args, value } }) =\u003e {\n  if (method === 'on' \u0026\u0026 args.includes('visitor:cookiesConsentChanged')) {\n    console.log(value); // cookiesConsentChanged value\n  }\n});\n```\n\n### Off\n```js\n// WebSDK off\nwindow.iAdvizeBoxedInterface.push({\n  method: 'off',\n  args: ['visitor:cookiesConsentChanged'],\n});\n```\n### Set\n```js\n// WebSDK set\nwindow.iAdvizeBoxedInterface.push({\n  method: 'set',\n  args: ['visitor:GDPRConsent', true],\n});\n```\n### Get\nThe host can listen to the result of the `get` call.\n\nExample of implementation:\n```js\n// WebSDK get\nwindow.iAdvizeBoxedInterface.push({\n  method: 'get',\n  args: ['visitor:cookiesConsent'],\n});\n\n// Listen to cookiesConsent get\nwindow.addEventListener('message', ({ data: { method, args, value } }) =\u003e {\n  if (method === 'get' \u0026\u0026 args.includes('visitor:cookiesConsent')) {\n    console.log(value); // cookiesConsent value\n  }\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiadvize%2Fboxed-tag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiadvize%2Fboxed-tag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiadvize%2Fboxed-tag/lists"}