Class UnbluEmbeddedAppElement

This is a custom element which can be used to integrate Unblu into a webpage at a specific location.

By itself this contains only the definition of the custom element and will load further JavaScript from the collaboration server on initialization to provide the full functionality.

To use the custom element just place a tag named "unblu-embedded-app" somewhere into the webpages body`.

...
<body>
...
    <div>
        <unblu-embedded-app></unblu-embedded-app>
    </div>
...
</body>
...

The size and positioning fully depends on the styles applied to the element by the website it is embedded into. The styling within the unblu embedded app can't be influenced by the website's styles however as a shadow root is used for its content. Unblu provides a large list of configuration properties to nicely integrate the unblu embedded app's visual appearance with the website it is embedded into.

The example above will simply add the unblu embedded app into the DOM but it won't initialize anything. To initialize the element with Unblu content at least the attribute ATTR_API_KEY or property UnbluEmbeddedAppElement.apiKey need to be defined. If UnbluEmbeddedAppElement.autoInit is set to true (default), it will automatically start the initialization, as soon as the API key is defined either via its attribute ATTR_API_KEY or property UnbluEmbeddedAppElement.apiKey. If not a call to UnbluEmbeddedAppElement.initialize has to be done to trigger the initialization.

Initializing:

Initialization can either be done manually or automatically. If the element is configured to do automatic initialization ATTR_AUTO_INIT / UnbluEmbeddedAppElement.autoInit the initialization will be automatically started as soon as at least the API key ATTR_API_KEY / UnbluEmbeddedAppElement.apiKey is defined. If you intent to define other attributes/properties relevant for the initialization these must all be set in the same JavaScript execution cycle. If automatic initialization is disabled the initialization must be done manually by calling the UnbluEmbeddedAppElement.initialize method.

There are additional attributes/properties which can be defined to define from where and how the Unblu JavaScript code is loaded from the collaboration server.

The Unblu UI inside the custom element will always fill the whole content of the unblu-embedded-app independent of what size it is given.

Note: if there already is a floating Unblu UI on the website integrated via the visitor JS API, the embedded app will automatically deinitialize it as there can always only one active instance of Unblu on the page.

See

MDN Custom Element

No Inherit Doc

Hierarchy

  • HTMLElement
    • UnbluEmbeddedAppElement

Implements

  • InitializedUnbluElement

Constructors

constructor

Properties

ATTR_ACCESS_TOKEN ATTR_API_KEY ATTR_AUTO_INIT ATTR_CONVERSATION_ID ATTR_ENTRY_PATH ATTR_FULLSCREEN ATTR_INIT_TIMEOUT ATTR_LOCALE ATTR_NAMED_AREA ATTR_SERVER_URL ATTR_VIEW_MODE

Accessors

accessToken apiKey apiState autoInit conversationId entryPath fullscreen initTimeout locale namedArea serverUrl viewMode

Methods

addEventListener deinitialize initialize removeEventListener

Events

ACTIVE_CONVERSATION_CHANGE DEINITIALIZED DEINITIALIZING ERROR FULLSCREEN_CHANGE READY STATE_CHANGE VIEW_MODE_CHANGE

Constructors

constructor

Properties

Static Readonly ATTR_ACCESS_TOKEN

ATTR_ACCESS_TOKEN: "access-token" = 'access-token'

The access token used to log the user in before initializing Unblu.

Note: Changes to this attribute trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.ATTR_AUTO_INIT is true.

See

UnbluEmbeddedAppElement.accessToken to set or get this via a property

Static Readonly ATTR_API_KEY

ATTR_API_KEY: "api-key" = 'api-key'

The API Key to connect this app with a specific Unblu account This is the minimum configuration that has to be done to trigger the initialization of Unblu.

Note: Changes to this attribute trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.ATTR_AUTO_INIT is true.

See

UnbluEmbeddedAppElement.apiKey to set or get this via a property

Static Readonly ATTR_AUTO_INIT

ATTR_AUTO_INIT: "auto-init" = 'auto-init'

Defines if Unblu automatically tries to (re-)initialize as soon as an attribute or property changes that triggers (re-)initialization.

To trigger a initialization at least the attribute ATTR_API_KEY or property UnbluEmbeddedAppElement.apiKey.

Default

true.

See

UnbluEmbeddedAppElement.autoInit to set or get this via a property

Static Readonly ATTR_CONVERSATION_ID

ATTR_CONVERSATION_ID: "conversation-id" = 'conversation-id'

Opens the conversation with the specified ID. If Unblu is not initialized yet, it will wait for the initialization and then automatically open the specified conversation. If Unblu is already initialized, the conversation will be opened directly.

If the conversation doesn't exist or the user doesn't have the right to access it, a dialog will be displayed with the respective error message.

See

  • UnbluEmbeddedAppElement.openConversation to set this value and also retrieve a promise to know, when the conversation was opened.
  • UnbluEmbeddedAppElement.conversationId to read the value as property. This will always represent the currently opened conversation.

Static Readonly ATTR_ENTRY_PATH

ATTR_ENTRY_PATH: "entry-path" = 'entry-path'

The path pointing to the root of the Unblu collaboration server.

Default

"/unblu".

**Note**: Changes to this attribute trigger a reinitialization of Unblu if {@link UnbluEmbeddedAppElement.ATTR_AUTO_INIT} is true.

See

UnbluEmbeddedAppElement.entryPath to set or get this via a property

Static Readonly ATTR_FULLSCREEN

ATTR_FULLSCREEN: "fullscreen" = 'fullscreen'

When this attribute is set to true, the embedded app will ignore the position and size set to its element and will used fixed positioning to display itself to cover the whole website.

This is useful when the user is currently in a call.

This can be set even if the API is not initialized yet. The value will then be applied on initialization.

Note: The user itself can also toggle this inside the UI.

See

UnbluEmbeddedAppElement.fullscreen to set or get this via a property

Default

false

Static Readonly ATTR_INIT_TIMEOUT

ATTR_INIT_TIMEOUT: "init-timeout" = 'init-timeout'

The timeout im milliseconds that should be waited for the Unblu integration to load.

Default

30'000 (30 seconds).

See

UnbluEmbeddedAppElement.initTimeout to set or get this via a property

Static Readonly ATTR_LOCALE

ATTR_LOCALE: "locale" = 'locale'

The locale (language) used for all Unblu UIs. If not specified this is derived from the webpage or the browser.

Note: Changes to this attribute trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.ATTR_AUTO_INIT is true.

See

Static Readonly ATTR_NAMED_AREA

ATTR_NAMED_AREA: "named-area" = 'named-area'

The named area for which the configuration should be loaded and with which new queue requests will be labeled. If not specified this can be derived from the corresponding meta tag on the webpage or the domain.

Note: Changes to this attribute trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.ATTR_AUTO_INIT is true. If this is not desired it can be prevented by changing the named area via a meta tag, however in this case this will only effect the queue routing and not the configuration. Alternatively you can disable the automatic initialization.

See

Static Readonly ATTR_SERVER_URL

ATTR_SERVER_URL: "server-url" = 'server-url'

The URL to the collaboration server.

If not specified it is assumed that the server is reachable on the domain of the current webpage at the defined UnbluEmbeddedAppElement.entryPath

Note: Changes to this attribute trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.ATTR_AUTO_INIT is true.

See

UnbluEmbeddedAppElement.serverUrl to set or get this via a property

Static Readonly ATTR_VIEW_MODE

ATTR_VIEW_MODE: "view-mode" = 'view-mode'

Sets the view mode of the embedded app element.

Depending on the view mode the UI is displayed the following way:

  • ViewMode.SPLIT: The UI will be divided into two parts. The list of conversations is displayed on the left and the active conversation on the right side.

  • ViewMode.SINGLE: Both the conversation list and the active conversation will be displayed in the same view using UI navigation to switch between them.

  • ViewMode.AUTO: The UI will automatically switch back and forth between the two other modes depending on the available width. The trigger point when to switch between the two modes can be configured on the Unblu collaboration server.

This value can be set even if the API is not initialized yet. The value will then be applied on initialization.

See

UnbluEmbeddedAppElement.viewMode to set or get this via a property

Default

{@link ViewMode.AUTO}

Accessors

accessToken

  • get accessToken(): string

  • Returns string

  • set accessToken(accessToken): void

  • The access token used to log the user in before initializing Unblu.

    Note: Changes to this property trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.autoInit is true.

    Parameters

    • accessToken: string

    Returns void

    See

    UnbluEmbeddedAppElement.ATTR_ACCESS_TOKEN to set this as an attribute

apiKey

  • get apiKey(): string

  • Returns string

  • set apiKey(apiKey): void

  • The API Key to connect this app with a specific Unblu account. This is the minimum configuration that has to be done to trigger the initialization of Unblu.

    Note: Changes to this property trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.autoInit is true.

    Parameters

    • apiKey: string

    Returns void

    See

    UnbluEmbeddedAppElement.ATTR_API_KEY to set this as an attribute

apiState

autoInit

  • get autoInit(): boolean

  • Returns boolean

  • set autoInit(autoInit): void

  • Defines if Unblu automatically tries to (re-)initialize as soon as an attribute or property changes that triggers (re-)initialization. Attributes/properties that trigger a (re-)initialization have a note in their documentation. At least the attribute ATTR_API_KEY or property UnbluEmbeddedAppElement.apiKey has to be configured to trigger an initialization.

    If this property gets set from false to true, it will automatically initialize if it is not already initialized. If it is already initialized, it will NOT deinitialize.

    Parameters

    • autoInit: boolean

    Returns void

    Default

    true.

    See

    UnbluEmbeddedAppElement.ATTR_AUTO_INIT to set this as an attribute

conversationId

  • get conversationId(): string

  • Returns string

  • set conversationId(conversationId): void

  • Opens the conversation for the given conversation ID.

    This can be set already before Unblu is initialized. The conversation will then be opened as soon as Unblu gets initialized.

    If the conversation doesn't exist or the user doesn't have the right to access it, a dialog will be displayed with the respective error message. In such a case the conversation ID will be reset to null.

    Parameters

    • conversationId: string

      The id of the conversation to open

    Returns void

    See

    UnbluEmbeddedAppElement.ATTR_CONVERSATION_ID to set this as an attribute

entryPath

  • get entryPath(): string

  • Returns string

  • set entryPath(entryPath): void

  • The entry path on the collaboration server.

    Parameters

    • entryPath: string

    Returns void

    Default

    "/unblu".

    **Note**: Changes to this property trigger a reinitialization of Unblu if {@link UnbluEmbeddedAppElement.autoInit} is true.

    See

    UnbluEmbeddedAppElement.ATTR_ENTRY_PATH to set this as an attribute

fullscreen

  • get fullscreen(): boolean

  • Returns boolean

  • set fullscreen(fullscreen): void

  • When this attribute is set to true, the embedded app element will ignore the position and size set to its element and will used fixed positioning to display itself to cover the whole website.

    This is useful when the user is currently in a call.

    This can be set even if the API is not initialized yet. The value will then be applied on initialization.

    Note: The user itself can also toggle this inside the UI.

    Parameters

    • fullscreen: boolean

      True to enable fullscreen, false otherwise.

    Returns void

    See

    Default

    false

initTimeout

  • get initTimeout(): number

  • Returns number

  • set initTimeout(initTimeout): void

  • The timeout im milliseconds that should be waited for the Unblu integration to load.

    Parameters

    • initTimeout: number

    Returns void

    Default

    30'000 (30 seconds).

    See

    UnbluEmbeddedAppElement.ATTR_INIT_TIMEOUT to set this as an attribute

locale

  • get locale(): string

  • Returns string

  • set locale(locale): void

  • The locale (language) used for all Unblu UIs. If not specified this is derived from the webpage or the browser.

    Note: Changes to this property trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.autoInit is true.

    Parameters

    • locale: string

    Returns void

    See

    UnbluEmbeddedAppElement.ATTR_LOCALE to set this as an attribute

namedArea

  • get namedArea(): string

  • Returns string

  • set namedArea(namedArea): void

  • The named area for which the configuration should be loaded and with which new queue requests will be labeled. If not specified this can be derived from meta tags on the webpage.

    Note: Changes to this property trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.autoInit is true. If this is not desired it can be prevented by changing the named area via a meta tag, however in this case this will only effect the queue routing and not the configuration. Alternatively you can disable the auto init.

    Parameters

    • namedArea: string

    Returns void

    See

    UnbluEmbeddedAppElement.ATTR_NAMED_AREA to set this as an attribute

serverUrl

  • get serverUrl(): string

  • Returns string

  • set serverUrl(serverUrl): void

  • The URL to the collaboration server.

    If not specified it is assumed that the server is reachable on the same domain of the current webpage at the defined UnbluEmbeddedAppElement.entryPath

    Note: Changes to this property trigger a reinitialization of Unblu if UnbluEmbeddedAppElement.autoInit is true.

    Parameters

    • serverUrl: string

    Returns void

    See

    UnbluEmbeddedAppElement.ATTR_SERVER_URL to set this as an attribute

viewMode

  • get viewMode(): ViewMode

  • Returns ViewMode

  • set viewMode(viewMode): void

  • Sets the view mode of the embedded app element.

    Depending on the view mode the UI is displayed the following way:

    • ViewMode.SPLIT: The UI will be divided into two parts. The list of conversations is displayed on the left and the active conversation on the right side.

    • ViewMode.SINGLE: Both the conversation list and the active conversation will be displayed in the same view using UI navigation to switch between them.

    • ViewMode.AUTO: The UI will automatically switch back and forth between the two other modes depending on the available width. The trigger point when to switch between the two modes can be configured on the Unblu collaboration server.

    This value can be set even if the API is not initialized yet. The value will then be applied on initialization.

    Parameters

    • viewMode: ViewMode

      The new view mode to use

    Returns void

    See

    Default

    {@link ViewMode.AUTO}

Methods

addEventListener

  • Registers for the UnbluEmbeddedAppElement.STATE_CHANGE event

    Parameters

    • type: "stateChange"
    • listener: ((event) => void)
    • Optional options: boolean | AddEventListenerOptions

    Returns void

  • Registers for the UnbluEmbeddedAppElement.READY event

    Parameters

    • type: "ready"
    • listener: ((event) => void)
        • (event): void

        • Parameters

          Returns void

    • Optional options: boolean | AddEventListenerOptions

    Returns void

  • Registers for the UnbluEmbeddedAppElement.ERROR event

    Parameters

    • type: "error"
    • listener: ((event) => void)
        • (event): void

        • Parameters

          Returns void

    • Optional options: boolean | AddEventListenerOptions

    Returns void

  • Registers for the UnbluEmbeddedAppElement.DEINITIALIZING event

    Parameters

    • type: "deinitializing"
    • listener: ((event) => void)
    • Optional options: boolean | AddEventListenerOptions

    Returns void

  • Registers for the UnbluEmbeddedAppElement.DEINITIALIZED event

    Parameters

    • type: "deinitialized"
    • listener: ((event) => void)
    • Optional options: boolean | AddEventListenerOptions

    Returns void

  • Registers for the UnbluEmbeddedAppElement.ACTIVE_CONVERSATION_CHANGE event

    Parameters

    • type: "activeConversationChange"
    • listener: ((event) => void)
    • Optional options: boolean | AddEventListenerOptions

    Returns void

  • Registers for the UnbluEmbeddedAppElement.FULLSCREEN_CHANGE event

    Parameters

    • type: "fullscreenChange"
    • listener: ((event) => void)
    • Optional options: boolean | AddEventListenerOptions

    Returns void

  • Registers for the UnbluEmbeddedAppElement.VIEW_MODE_CHANGE event

    Parameters

    • type: "viewModeChange"
    • listener: ((event) => void)
    • Optional options: boolean | AddEventListenerOptions

    Returns void

deinitialize

  • Deinitializes the app element and destroys all of its containing UI. By changing one of the attributes that trigger a reinitialization (e.g. UnbluEmbeddedAppElement.apiKey) the app element will be automatically initialized again (if the value is really changed).

    Note: Calling this method will not remove the element itself out of the DOM.

    Returns Promise<void>

initialize

removeEventListener

  • Removes a listener registration for the UnbluEmbeddedAppElement.STATE_CHANGE event

    Parameters

    • type: "stateChange"
    • listener: ((event) => void)

    Returns void

  • Removes a listener registration for the UnbluEmbeddedAppElement.READY event

    Parameters

    • type: "ready"
    • listener: ((event) => void)
        • (event): void

        • Parameters

          Returns void

    Returns void

  • Removes a listener registration for the UnbluEmbeddedAppElement.ERROR event

    Parameters

    • type: "error"
    • listener: ((event) => void)
        • (event): void

        • Parameters

          Returns void

    Returns void

  • Removes a listener registration for the UnbluEmbeddedAppElement.DEINITIALIZING event

    Parameters

    Returns void

  • Removes a listener registration for the UnbluEmbeddedAppElement.DEINITIALIZED event

    Parameters

    Returns void

  • Removes a listener registration for the UnbluEmbeddedAppElement.ACTIVE_CONVERSATION_CHANGE event

    Parameters

    Returns void

  • Removes a listener registration for the UnbluEmbeddedAppElement.FULLSCREEN_CHANGE event

    Parameters

    • type: "fullscreenChange"
    • listener: ((event) => void)

    Returns void

  • Removes a listener registration for the UnbluEmbeddedAppElement.VIEW_MODE_CHANGE event

    Parameters

    • type: "viewModeChange"
    • listener: ((event) => void)

    Returns void

Events

Static Readonly ACTIVE_CONVERSATION_CHANGE

ACTIVE_CONVERSATION_CHANGE: "activeConversationChange" = 'activeConversationChange'

Event emitted every time one of the conversations accessible to the current user changes or one is added or removed.

See

Static Readonly DEINITIALIZED

DEINITIALIZED: "deinitialized" = 'deinitialized'

Event emitted when the de-initialization of the API has finished.

It usually makes sense to use this event if a re-initialization is required after de-init.

See

Static Readonly DEINITIALIZING

DEINITIALIZING: "deinitializing" = 'deinitializing'

Event emitted when the de-initialization of the API is started..

It usually makes sense to use this event to clean up resources and/or unregistering of listeners so they don't try to use the API again until it is initialized again.

See

Static Readonly ERROR

ERROR: "error" = 'error'

Event emitted if the API initialization fails.

It usually makes sense to use this event if there is some general action that has to be triggered when the API initialization fails.

See

Static Readonly FULLSCREEN_CHANGE

FULLSCREEN_CHANGE: "fullscreenChange" = 'fullscreenChange'

Event emitted every time the embedded app switches to fullscreen mode or back.

See

Static Readonly READY

READY: "ready" = 'ready'

Event emitted as soon as the API is initialized.

It usually makes sense to use this event to wait for APIs on this element to be ready. E.g. the UnbluEmbeddedAppElement.personInfo or UnbluEmbeddedAppElement.agentAvailable. You will find a note in the documentation of the properties when they are only available after initialization.

See

Static Readonly STATE_CHANGE

STATE_CHANGE: "stateChange" = 'stateChange'

Event emitted whenever the API state changes

See

Static Readonly VIEW_MODE_CHANGE

VIEW_MODE_CHANGE: "viewModeChange" = 'viewModeChange'

Event emitted every time the view mode changes.

See

Settings

Member Visibility

Theme

On This Page