npm package: @quattro-bet/embeddable-app
Description: ```bash npm i @quattro-bet/embeddable-app ``` or  ```bash yarn add @quattro-bet/embeddable-app ``` ### Terms: - Host application - JavaScript application which runs Embedded application. - Embedded application - JavaScript application which runs in host a
Latest version: 0.2.9

# @quattro-bet/embeddable-app
## Install
```bash
npm i @quattro-bet/embeddable-app
```
or 
```bash
yarn add @quattro-bet/embeddable-app
```
### Terms:
- Host application - JavaScript application which runs Embedded application.
- Embedded application - JavaScript application which runs in host application.

### Usage
#### 1. Add javascript file `embeddable-app.js` from dist to your page:
```html
<script src="https://domain.com/embeddable-app.js"></script>
```
Or import `embeddable-app` from `node_modules`:
```javascript
import * as app from "@quattro-bet/embeddable-app";
```

#### 2.(Optional) Call `app.prefetch()` <u>as early as possible</u> (during the initial startup) in entrypoint Host application to improve resource loading:
```javascript
/**
 * @param {Object} Prefetch Options
 * @returns {void}
 */
app.prefetch(options);
````
##### Prefetch Options
| Name          | Type    | Required | Description                                             
|---------------|---------|----------|---------------------------------------------------------|
| siteName      | string  | no       | > **Deprecated:** use `brandId` instead. Host site name |
| brandId       | number  | no       | Host brand id                                           |
| url           | string  | yes      | Embedded application API URL                            |
| dnsDomainName | string  | no       | Dns domain name queried by the embedded application     |
| mobile        | boolean | no       | Mobile or desktop version, default value is `false`     |
##### Example:
```javascript
// some Host application entrypoint
app.prefetch({
 brandId: 00000,
 url: "https://domain.com",
 mobile: isMobile(), //some mobile/desktop detection
});
````

#### 3. Call `app.create()`: 
```javascript
/**
 * @param {Object} Create Options
 * @return {Promise} Promise with the control object
 */
var control = app.create(options);
```
Or via async/await:
```javascript
async function foo() {
  var control = await app.create(options);
}
```
#### Create Options
| Name                         | Type               | Required | Description                                                                                                        
|------------------------------|--------------------|----------|--------------------------------------------------------------------------------------------------------------------|
| siteName                     | string             | no       | > **Deprecated:** use `brandId` instead. Host site name                                                            |
| brandId                      | number             | no       | Host brand id                                                                                                      |
| url                          | string             | yes      | Embedded application API URL                                                                                       |
| elementId                    | string             | yes      | id of a DOM element, in which the embedded application will be built                                               |
| pathNamespace                | string             | yes      | Namespace path, in which the embedded application is launched                                                      |
| initPath                     | string             | yes      | Path, in which the embedded application is launched                                                                |
| dnsDomainName                | string             | no       | Dns domain name queried by the embedded application                                                                |
| mobile                       | boolean            | no       | Mobile or desktop version, default value is `false`                                                                |
| onEmbeddedHistoryChange      | function           | yes      | Callback that will be called by changing the path in the embedded application                                      |
| subscribeOnHostHistoryChange | function           | yes      | Function that will be called by an embedded application to subscribe on path changes                               |  
| sbNavEnabled                 | boolean            | no       | Show sb navigation menu, default value is `true`                                                                   |
| params                       |
| token                        | string             | no       | Partner system player token may be omitted when a player is not logged                                             |
| locale                       | `tr_TR` or `en_US` | no       | Application locale, default value is `tr_TR`                                                                       |
| defaultCurrency              | string             | no       | > **Deprecated:** use `currency` instead. The default currency for unauthorized player, default value is `EUR`     |
| currency                     | string             | no       | The default currency for an unauthorized player, or the player’s currency if available. The default value is `EUR` |
| timeZoneOffset               | number             | no       | Timezone offset in milliseconds, browser timezone by default                                                       |
| theme                        | string             | no       | It's possible to set a color theme, for example: light, dark                                                       |
#### Control methods:
    changeParams(params: Object): void   - Change params.
    destroy(): void   - Force destroy embedded application.
#### Login/logout
For login & logout players use `params.token`.
When you want to create an application but the user is not logged, you should omit a token field. 
When the user is logged, call:
 `control::changeParams` with token field.
```javascript
 control.changeParams({token: "user_token"})
```
When the user is logged out, call change params with null.
```javascript
 control.changeParams({token: null})
```
A call `control::changeParams` with an empty object doesn't affect the application. 
If you want to delete some fields or a certain field, you should set its value equal to null.
#### URL path synchronization  
Embedded application doesn't change the browser history directly. Instead, it provides callbacks 
`onEmbeddedHistoryChange` and `subscribeOnHostHistoryChange` for history synchronization. 
 
Host application should subscribe to changes of path in embedded app via the `onEmbeddedHistoryChange` callback.
This callback will be called when the path has been changed in the embedded app. 
Embedded app expects that host app changes path via HistoryApi.  

When the host app changes, URI (for instance, user clicks on the link outside of the embedded app but this route is controlled by the embedded app)
This event should be propagated to the embedded app via call listener registered in `subscribeOnHostHistoryChange`.
When a new path starts with `pathNamespace`, the path will be routed via internal router in the embedded app.
If the route doesn't match `pathNamespace` , the embedded app will be destroyed.  

It means that the link received to the control object at the time of initialization will be relevant.
When the host application dispatch changes history with path that controlled via embedded app, the embedded app will be restored.  

It's important that host application should add a node with `elementId` to the DOM tree, provided in options. 
Embedded app will observe the DOM tree with a node `elementId`.
When this node will be added to the DOM tree, the application will be created.
#### Example:
```javascript
var router = new Router(); // some partner router

const listeners = [];

router.onChange(function(path) {
  listeners.forEach(function (listener){ 
    listener(path);
  });
});

async function foo() {
  var control = await app.create({
    brandId: 00000,
    url: "https://domain.com",
    elementId: "app",
    pathNamespace: "/sportsbook",
    initPath: "/sportsbook/prelive",
    onEmbeddedHistoryChange(path) { 
      // when the embedded app changes route, the (`onHistoryChange`) function will be called
      // host application should change path using HistoryApi
     return router.push(path);
    },
    subscribeOnHostHistoryChange(embeddedListener) {
      // embedded application listener
      // when the host application changes route, the `embeddedListener` should be called with new path argument
      listeners.push(embeddedListener)
    },
    params: {
     token: "n3add69a9-f2c1-4029-ba3b-946a12263c4a",
     locale: "tr_TR",
     currency: "USD",
    }
  })
}
```