misc: Update the documentation to add a "simple" instalation paragraph

iadvize · May 25, 2023 · c8c7670 · c8c7670
1 parent 0ac77c4
commit c8c7670
Show file tree

Hide file tree

Showing 2 changed files with 102 additions and 68 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.3]
+
+### Fixed
+Update the documentation with a simplified installation
+
 ## [1.4.2]
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -5,12 +5,83 @@ The “iAdvize Boxed Tag” is a way to include the iAdvize Tag in the most secu
 With this solution, the iAdvize tag can be loaded in an isolated box (a sandboxed iframe).
 This way, the main page context cannot be accessed by the iAdvize tag: the main page only sends controlled, relevant data to the boxed tag.
 
-# Installation
+# Simple installation
+This is the simplest way too add the iAdvize Boxed Tag to a website with the default configuration.
+
+## 1 - Serve this HTML file
+
+Serve a HTML file. We will use the name `iadvize-boxed-iframe.html`, but any name can be chosen.
+This file needs to be served on the same top domain as the page it will be included in.
+Replace `<your-sid>` with your own sid.
+
+Ex : 
+- Web page : https://hostpage.brand-domain.com
+- Iframe : https://static.brand-domain.com/iadvize-boxed-iframe.html
+
+```html
+<!DOCTYPE html>
+<html>
+  <body>
+   <script src="https://static.iadvize.com/boxed-tag/1.4.2/index.js" integrity="sha512-NS7M2FyNHaefJ42ilas6W+t/qJleeGTWIyhM2pj2Pn+t7PgWRH/HarBqV8HT+RFDi6JVS1ReAeF2Afz5dwpBjQ==" crossorigin="anonymous"></script>
+    <script>
+      window.iAdvizeBoxedTag.initIAdvizeIframe(<your-sid>, "halc");
+    </script>
+  </body>
+</html>
+```
+
+## 2 - Add the following script
+
+Add 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 : 
+
+```javascript
+// Change this URL with the actual URL of the iframe
+const iAdvizeIframeUrl = "https://static.brand-domain.com/iadvize-boxed-iframe.html";
+
+const style = document.createElement("style");
+style.innerHTML = `
+  #iAdvizeSandboxedIframe {
+    border: none;
+    position: fixed;
+    bottom: 0;
+    right: 0;
+    width: 100vw;
+    height: 100vh;
+    pointer-events: none;
+  }
+`;
+document.body.append(style);
+
+const boxedTagScript = document.createElement("script");
+boxedTagScript.src =
+  "https://static.iadvize.com/boxed-tag/1.4.2/index.js";
+boxedTagScript.integrity =
+"sha512-NS7M2FyNHaefJ42ilas6W+t/qJleeGTWIyhM2pj2Pn+t7PgWRH/HarBqV8HT+RFDi6JVS1ReAeF2Afz5dwpBjQ==";
+boxedTagScript.crossOrigin = "anonymous";
+
+const iAdvizeSandboxedIframe = document.createElement("iframe");
+iAdvizeSandboxedIframe.sandbox = "allow-scripts allow-same-origin allow-popups allow-forms";
+iAdvizeSandboxedIframe.allow = "camera;microphone;autoplay";
+iAdvizeSandboxedIframe.src = iAdvizeIframeUrl;
+iAdvizeSandboxedIframe.id = "iAdvizeSandboxedIframe";
+document.body.append(iAdvizeSandboxedIframe);
+
+boxedTagScript.onload = function () {
+  window.iAdvizeBoxedTag.initIAdvizeHost("iAdvizeSandboxedIframe");
+};
+
+document.body.append(boxedTagScript);
+```
+
+# Advanced installation
+This is a more advanced installation, allowing : 
+- a custom configuration,
+- the use of WebSDK methods (see https://developers.iadvize.com/documentation/javascript-web-sdk#javascript-web-sdk).
 
 ## Install the lib on your project
 
 ```
-npm i @iadvize-oss/boxed-tag
+npm install @iadvize-oss/boxed-tag
 ```
 
 ## Create the iframe script
@@ -50,16 +121,15 @@ The iframe is set with the following sandbox parameters:
 | allow-forms       | Allows the iAdvize tag to submit the visitor email if needed   |
 
 And the following allow parameters:
-| allow param       | description                                                    |
-|-------------------|----------------------------------------------------------------|
-| camera            | Allows the boxed tag to ask the camera permission (for video calls) |
+| allow param       | description                                                             |
+|-------------------|-------------------------------------------------------------------------|
+| camera            | Allows the boxed tag to ask the camera permission (for video calls)     |
 | microphone        | Allows the boxed tag to ask the microphone permission (for video calls) |
-| autoplay          | Allows the boxed tag to launch the video stream automatically  |
+| autoplay          | Allows the boxed tag to launch the video stream automatically           |
 
 ## Add the host script on your site's main page
 
-Create a js file with the host lib import.
-Then call `initIAdvizeHost` to listen the iframe messages.
+Create a js file with the host lib import, then call `initIAdvizeHost` to listen to the iframe messages.
 
 ```js
 import { initIAdvizeHost } from '@iadvize-oss/boxed-tag';
@@ -69,69 +139,29 @@ initIAdvizeHost('myIframeId');
 
 # Communication
 The 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).
+
 > **warning**
 > The postMessage data is serialized, so functions cannot be sent (see https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#parameters).
 
-Then, the target of the postMessage calls can listen the events with `window.addEventListener('message')`.
+Then, the target of the postMessage calls can listen to the events using `window.addEventListener('message')`.
+
 > **warning**
 > 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).
 
 
-## From host to iframe
-
-Sending message from the host window to the isolated boxed iframe.
-
-```js
-const iAdvizeSandbox = document.getElementById('myIframeId');
 
-iAdvizeSandbox.onload = function () {
-  iAdvizeSandbox.contentWindow.postMessage({ foo: 'bar' }, '*');
-};
-```
-
-Receiving message on the iframe
-
-```js
-window.addEventListener('message', ({ data: { foo }, origin }) => {
-  if (origin !== "https://myHostUrl") return;
-  // Do something with the data sent
-});
-```
-
-## From iframe to host
-
-Sending message from the isolated boxed iframe to the host window.
-Use the `iAdvizeInterface` to add callbacks, that will be handled once the iadvize tag is loaded.
-
-```js
-window.iAdvizeInterface.push(function () {
-  window.parent.postMessage({ foo: 'bar' });
-});
-```
-
-Receiving message on the main host page.
-
-```js
-window.addEventListener('message', ({ data: { foo }, origin }) => {
-  if (origin !== "https://myIframeUrl") return;
-
-  if (foo) {
-    // Do something with the data sent
-  }
-});
-```
+## Call iAdvize WebSDK methods from host
 
-## Call web SDK methods from host
+WebSDK 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.  
 
-Web SDK methods cannot be called from host context because the iAdvize tag is isolated in the iframe. So we need to tell the iframe what we want to call.  
 After having called `initIAdvizeHost`, a `iAdvizeBoxedInterface` object is available in the host window context.  
-This object sends the `method` name and `args` to the iframe, that will call the web SDK.
-The `activate` and `get` and `on` methods can return a value to the host :  
+This object sends the `method` name and `args` to the iframe, that will call the webSDK.
+The `activate`, `get` and `on` methods can return a value to the host :  
 to retrieve it, add a `window.addEventListener("message")` and check the `e.data.method` property to recognize the method called.
 
 ### Navigate
 ```js
-// Web SDK navigate
+// WebSDK navigate
 window.iAdvizeBoxedInterface.push({
   method: 'navigate',
   args: [window.location.href],
@@ -144,7 +174,7 @@ The host can listen to the result of the `activate` call.
 For an anonymous authentication: 
 
 ```js
-// Web SDK activate anonymous
+// WebSDK activate anonymous
 window.iAdvizeBoxedInterface.push({
   method: 'activate',
   args: {
@@ -160,17 +190,16 @@ window.addEventListener('message', ({ data: { method, activation } }) => {
 });
 ```
 
-For a secured authentication:  
-The JWE token should be generated on the host side and sent to the iframe. 
- - The host should listen a `get-activate-auth-token` message initiated by the iframe.
- - Then call your backend api to get the JWE token,
- - Then send the token to the iframe as a `set-activate-auth-token` message.
+For a secured authentication, the JWE token should be generated on the host side and sent to the iframe : 
+ - the host should listen a `get-activate-auth-token` message initiated by the iframe.
+ - the backend api then gets the JWE token,
+ - the token is then sent to the iframe inside a `set-activate-auth-token` message.
 
 The `get-activate-auth-token` listener allows the iframe to ask for a token refresh if needed.
 
 Example of secured authentication implementation: 
 ```js
-// Web SDK activate secured auth
+// WebSDK activate secured auth
 const getJweToken = Promise.resolve('myJWEToken');// your backend logic to generate a JWE
 
 window.iAdvizeBoxedInterface.push({
@@ -205,7 +234,7 @@ The host can listen to the result of the `logout` call.
 
 Example of implementation:
 ```js
-// Web SDK logout
+// WebSDK logout
 window.iAdvizeBoxedInterface.push({
   method: 'logout',
 });
@@ -223,7 +252,7 @@ The host can listen to the result of the `on` call.
 
 Example of implementation:
 ```js
-// Web SDK on
+// WebSDK on
 window.iAdvizeBoxedInterface.push({
   method: 'on',
   args: ['visitor:cookiesConsentChanged'],
@@ -239,15 +268,15 @@ window.addEventListener('message', ({ data: { method, args, value } }) => {
 
 ### Off
 ```js
-// Web SDK off
+// WebSDK off
 window.iAdvizeBoxedInterface.push({
   method: 'off',
   args: ['visitor:cookiesConsentChanged'],
 });
 ```
 ### Set
 ```js
-// Web SDK set
+// WebSDK set
 window.iAdvizeBoxedInterface.push({
   method: 'set',
   args: ['visitor:GDPRConsent', true],
@@ -258,7 +287,7 @@ The host can listen to the result of the `get` call.
 
 Example of implementation:
 ```js
-// Web SDK get
+// WebSDK get
 window.iAdvizeBoxedInterface.push({
   method: 'get',
   args: ['visitor:cookiesConsent'],