## Introduction

### Goal

Use the Bloomreach UI Extension JavaScript Client Library to develop your own custom integrations.

### Background

Communication between a [custom integration](🔗) and the Content SaaS UI is handled by a JavaScript library provided by Bloomreach. The library hides the complexity of the `window.postMessage` communication with the Content SaaS UI and provides a stable public API.

## Include Client Library

The client library is available as an [NPM package](🔗):



The library can be used in two ways.

As a JavaScript module:



Or as a standalone ES5 script:





There may be a more recent version of the `ui-extension-saas` package, check <https://www.npmjs.com/package/@bloomreach/ui-extension-saas> for the most up to date information.

The latter creates a global object `window.UiExtension`.

## Register Extension

The `UiExtension` object needs to be registered first:



The code snippet above registers the extension with the Content SaaS application, so the latter knows the extension is ready for communication. The `register()` method returns a `Promise` that resolves with a `ui` object. The `ui` object can be used to access information about the Content SaaS environment and interact with the Content SaaS UI.

## API

### Static Properties

The `ui` object contains the following properties:

PropertyDescriptionExample value
`ui.baseUrl`The URL of the Content SaaS environment that hosts the custom integration."<https://cms.example.com>"
`ui.extension.config`The value of the custom integration's _Configuration_ field."{ apiKey: '1234' }"
`ui.locale`The locale of the Content SaaS user as selected on the login page."nl"
`ui.styling`The styling of the user interface in which the extension is shown. For page tools this is always "material" for AngularJS Material."material"
`ui.timeZone`The time zone of the Content SaaS user as selected on the login page."Europe/Amsterdam"
`ui.user.id`The username of the Content SaaS user."admin"
`ui.user.firstName`The first name of the Content SaaS user."Suzanna"
`ui.user.lastName`The last name of the Content SaaS user."Doe"
`ui.user.displayName`Concatenation of the first and last name of the Content SaaS user, or the username if both are blank."Suzanna Doe" or "admin"
`ui.version`The version of the Content SaaS environment.

### Extension-Specific Properties, Functions, and Events

The `ui` object provides several other properties, functions, and events which are specific to a type of extension and are described on the relevant pages:

  • [Develop a Document Field Integration](🔗)

  • [Use Dialogs Within Custom Integrations](🔗)