@quattro-bet/embeddable-app

Install

npm i @quattro-bet/embeddable-app

or

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:

<script src="https://domain.com/embeddable-app.js"></script>

Or import embeddable-app from node_modules:

import * as app from "@quattro-bet/embeddable-app";

2.(Optional) Call app.prefetch() as early as possible (during the initial startup) in entrypoint Host application to improve resource loading:

/**
 * @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 | | widget | number | no | Prefetch a single standalone widget instead of the full application. See Widgets |

Example:

// some Host application entrypoint
app.prefetch({
 brandId: 00000,
 url: "https://domain.com",
 mobile: isMobile(), //some mobile/desktop detection
});

3. Call app.create():

/**
 * @param {Object} Create Options
 * @return {Promise} Promise with the control object
 */
var control = app.create(options);

Or via async/await:

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 | | widget | number | no | Render a single standalone widget instead of the full application. See Widgets | | 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 | string | no | Application locale, default value is tr_TR. See Supported locales | | 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.

 control.changeParams({token: "user_token"})

When the user is logged out, call change params with null.

 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.

Currency

The currency used by the embedded application is controlled via params.currency.

Pass the initial currency on app.create(). It is used as the currency for an unauthorized player, or as the player's currency when no authenticated currency is available (defaults to EUR):

var control = await app.create({
  brandId: 00000,
  url: "https://domain.com",
  elementId: "app",
  pathNamespace: "/sportsbook",
  initPath: "/sportsbook/prelive",
  onEmbeddedHistoryChange(path) {
    return router.push(path);
  },
  subscribeOnHostHistoryChange(embeddedListener) {
    listeners.push(embeddedListener);
  },
  params: {
    currency: "USD",
  },
});

Later, if you need to switch the currency (for example, the player changed it in the host application), call control::changeParams with the new currency:

control.changeParams({ currency: "EUR" })

Widgets

By default the embedded application renders the full sportsbook (the desktop or mobile bundle, depending on the mobile option). Instead of the full application, you can render a single standalone widget.

To do this, pass the widget option with the index of the widget you want to render (0, 1, 2, ...). When widget is set, the corresponding widget<N> bundle is loaded instead of desktop/mobile, and the mobile option is ignored for bundle selection.

var control = await app.create({
  brandId: 00000,
  url: "https://domain.com",
  widget: 0, // render the standalone widget №0 instead of the full application
  elementId: "app",
  pathNamespace: "/sportsbook",
  initPath: "/sportsbook/prelive",
  onEmbeddedHistoryChange(path) {
    return router.push(path);
  },
  subscribeOnHostHistoryChange(embeddedListener) {
    listeners.push(embeddedListener);
  },
});

Note: the same widget option can be passed to app.prefetch() so the correct widget bundle is prefetched ahead of time.

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:

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",
    }
  })
}

Supported locales

The locale option accepts a language_REGION code (lowercase language, uppercase region). Locales are split into two writing direction groups: LTR (left-to-right) and RTL (right-to-left). When an RTL locale is selected, the embedded application renders its layout in right-to-left direction.

RTL locales

| Locale | Language | |----------|--------------------------------| | ar_AE | Arabic (United Arab Emirates) | | ar_BH | Arabic (Bahrain) | | ar_DZ | Arabic (Algeria) | | ar_EG | Arabic (Egypt) | | ar_IQ | Arabic (Iraq) | | ar_JO | Arabic (Jordan) | | ar_KW | Arabic (Kuwait) | | ar_LB | Arabic (Lebanon) | | ar_LY | Arabic (Libya) | | ar_MA | Arabic (Morocco) | | ar_OM | Arabic (Oman) | | ar_QA | Arabic (Qatar) | | ar_SA | Arabic (Saudi Arabia) | | ar_SY | Arabic (Syria) | | ar_TN | Arabic (Tunisia) | | ar_YE | Arabic (Yemen) | | dv_MV | Dhivehi (Maldives) | | fa_IR | Persian / Farsi (Iran) | | he_IL | Hebrew (Israel) | | ku_IQ | Kurdish, Sorani (Iraq) | | ps_AR | Pashto | | syr_SY | Syriac (Syria) | | ur_PK | Urdu (Pakistan) |

LTR locales

| Locale | Language | |----------|-----------------------------------| | af_ZA | Afrikaans (South Africa) | | az_AZ | Azerbaijani (Azerbaijan) | | be_BY | Belarusian (Belarus) | | bg_BG | Bulgarian (Bulgaria) | | bs_BA | Bosnian (Bosnia and Herzegovina) | | ca_ES | Catalan (Spain) | | cs_CZ | Czech (Czech Republic) | | cy_GB | Welsh (United Kingdom) | | da_DK | Danish (Denmark) | | de_AT | German (Austria) | | de_CH | German (Switzerland) | | de_DE | German (Germany) | | de_LI | German (Liechtenstein) | | de_LU | German (Luxembourg) | | el_EL | Greek | | el_GR | Greek (Greece) | | en_AU | English (Australia) | | en_BZ | English (Belize) | | en_CA | English (Canada) | | en_CB | English (Caribbean) | | en_GB | English (United Kingdom) | | en_IE | English (Ireland) | | en_JM | English (Jamaica) | | en_NZ | English (New Zealand) | | en_PH | English (Philippines) | | en_TT | English (Trinidad and Tobago) | | en_US | English (United States) | | en_ZA | English (South Africa) | | en_ZW | English (Zimbabwe) | | es_AR | Spanish (Argentina) | | es_BO | Spanish (Bolivia) | | es_CL | Spanish (Chile) | | es_CO | Spanish (Colombia) | | es_CR | Spanish (Costa Rica) | | es_DO | Spanish (Dominican Republic) | | es_EC | Spanish (Ecuador) | | es_ES | Spanish (Spain) | | es_GT | Spanish (Guatemala) | | es_HN | Spanish (Honduras) | | es_MX | Spanish (Mexico) | | es_NI | Spanish (Nicaragua) | | es_PA | Spanish (Panama) | | es_PE | Spanish (Peru) | | es_PR | Spanish (Puerto Rico) | | es_PY | Spanish (Paraguay) | | es_SV | Spanish (El Salvador) | | es_UY | Spanish (Uruguay) | | es_VE | Spanish (Venezuela) | | et_EE | Estonian (Estonia) | | eu_ES | Basque (Spain) | | fi_FI | Finnish (Finland) | | fo_FO | Faroese (Faroe Islands) | | fr_BE | French (Belgium) | | fr_CA | French (Canada) | | fr_CH | French (Switzerland) | | fr_FR | French (France) | | fr_LU | French (Luxembourg) | | fr_MC | French (Monaco) | | gl_ES | Galician (Spain) | | gu_IN | Gujarati (India) | | hi_IN | Hindi (India) | | hr_BA | Croatian (Bosnia and Herzegovina) | | hr_HR | Croatian (Croatia) | | hu_HU | Hungarian (Hungary) | | hy_AM | Armenian (Armenia) | | id_ID | Indonesian (Indonesia) | | is_IS | Icelandic (Iceland) | | it_CH | Italian (Switzerland) | | it_IT | Italian (Italy) | | ja_JP | Japanese (Japan) | | ka_GE | Georgian (Georgia) | | kk_KZ | Kazakh (Kazakhstan) | | kn_IN | Kannada (India) | | ko_KR | Korean (South Korea) | | kok_IN | Konkani (India) | | ky_KG | Kyrgyz (Kyrgyzstan) | | lt_LT | Lithuanian (Lithuania) | | lv_LV | Latvian (Latvia) | | mi_NZ | Maori (New Zealand) | | mk_MK | Macedonian (North Macedonia) | | mn_MN | Mongolian (Mongolia) | | mr_IN | Marathi (India) | | ms_BN | Malay (Brunei) | | ms_MY | Malay (Malaysia) | | mt_MT | Maltese (Malta) | | nb_NO | Norwegian Bokmål (Norway) | | nl_BE | Dutch (Belgium) | | nl_NL | Dutch (Netherlands) | | nn_NO | Norwegian Nynorsk (Norway) | | ns_ZA | Northern Sotho (South Africa) | | pa_IN | Punjabi (India) | | pl_PL | Polish (Poland) | | pt_BR | Portuguese (Brazil) | | pt_PT | Portuguese (Portugal) | | qu_BO | Quechua (Bolivia) | | qu_EC | Quechua (Ecuador) | | qu_PE | Quechua (Peru) | | ro_RO | Romanian (Romania) | | ru_RU | Russian (Russia) | | sa_IN | Sanskrit (India) | | se_FI | Sami (Finland) | | se_NO | Sami (Norway) | | se_SE | Sami (Sweden) | | sk_SK | Slovak (Slovakia) | | sl_SI | Slovenian (Slovenia) | | sq_AL | Albanian (Albania) | | sr_BA | Serbian (Bosnia and Herzegovina) | | sr_SP | Serbian | | sv_FI | Swedish (Finland) | | sv_SE | Swedish (Sweden) | | sw_KE | Swahili (Kenya) | | ta_IN | Tamil (India) | | te_IN | Telugu (India) | | th_TH | Thai (Thailand) | | tl_PH | Tagalog (Philippines) | | tn_ZA | Tswana (South Africa) | | tr_TR | Turkish (Turkey) | | tt_RU | Tatar (Russia) | | uk_UA | Ukrainian (Ukraine) | | uz_UZ | Uzbek (Uzbekistan) | | vi_VN | Vietnamese (Vietnam) | | xh_ZA | Xhosa (South Africa) | | zh_CN | Chinese, Simplified (Mainland) | | zh_HK | Chinese, Traditional (Hong Kong) | | zh_MO | Chinese, Traditional (Macao) | | zh_SG | Chinese, Simplified (Singapore) | | zh_TW | Chinese, Traditional (Taiwan) | | zu_ZA | Zulu (South Africa) |