<!-- Space: NBKB -->
<!-- Layout: article -->
<!-- Type: page -->
<!-- Parent: How-to articles -->
<!-- Title: How to Install Embeddables -->

# Composite

Composite embeddable bwell component. The composite can be embedded in either a
web or React Native context.

## Web

### Integration

The composite web component can be integrated via either script tag _or_ npm
module

#### Script

If using the script tag, you'll need to add the below to your web page. This
will pull in the required scripts and define the bwell composite web component.

```html
<script src="https://embeddables.prod.icanbwell.com/composite/<VERSION_NUMBER>/loader/index.js"></script>
```

#### Module

Alternatively, if you use NPM, the bwell composite can be added to your project
with the following command.

```sh
npm install @icanbwell/composite@<VERSION_NUMBER>
```

Once that's done, make sure to do a direct import of the module somewhere within
your appliction.

```ts
import '@icanbwell/composite';
```

### Usage

In both cases above, replace `<VERSION_NUMBER>` with the desired version number.
The composite can then be integrated into your web UI as a traditional HTML tag.

```html
<bwell-composite />
```

#### Initialization

The embeddable is initialized in two steps:

1. Initialize the app experience with the client key (`<CLIENT_KEY>` in the code
   below). Think of this as a public SDK/API key.
2. Initialize the user context with the user token (`<USER_TOKEN>` in the code
   below).

```js
async function onInit() {
  await bwell.init(<CLIENT_KEY>)
  const userInfo = await bwell.setUserToken(<USER_TOKEN>)
}
```

#### Updating Document Title

The bwell composite introduces a global `bwell` object off of the `window`. Via
this global object, events can be subscribed and unsubscribed. One of these
events is `pagetransition` and can be used to update your web application's
document title to best reflect the current screen being shown within the
embeddable. An example of such an approach can be seen below.

```js
bwell.on(
  'pagetransition',
  (pageInfo) => (document.title = pageInfo.pageTitle || ''),
);
```

## React Native

The bwell composite also supports integration into React Native via a react
native scoped export. Before integrating, installation requires adding some peer
dependencies of the `@icanbwell/composite` module.

### Installation

Install module plus peer dependencies (only required they are not already
installed).

```sh
npm install \
  react \
  react-native \
  react-native-webview \
  @react-native-async-storage/async-storage
```

#### Optional Native Dependencies

The following native dependencies are optional and may be required dependent on
the features that are enabled for your specific client.

```sh
npm install \
  react-native-biometrics \
  react-native-permissions \
  @react-native-camera-roll/camera-roll \
  @react-native-camera-roll/camera-roll \
  @react-native-documents/picker \
  @react-native-community/geolocation \
  react-native-print
```

#### Install Pods

```sh
npx pod-install
```

### Usage

```tsx
// Native Module(s) to inject
import storage from '@react-native-async-storage/async-storage';
import { SafeAreaView } from 'react-native';

import { Composite } from '@icanbwell/composite/native';

export default function App() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <Composite
        clientKey='<CLIENT_KEY>'
        userToken='<USER_TOKEN>'
        nativeModules={{
          storage,
        }}
      />
    </SafeAreaView>
  );
}
```

## Properties

---

#### `clientKey`

_required_

**type:** `string`

Client key.

---

#### `userToken`

_required_

**type:** `string`

User token for SSO.

---

#### `initialPath` (deprecated; prefer [`path`](#path) below)

**type:** `string`

Optional property that tells the composite what page to start on. Use this to
deeplink into the embeddable application.

---

#### `path`

**type:**

```ts
type Path = {
  value: string;
  onResetValue: () => void;
};
```

Optional property that tells the composite what page to initially render. Use
this to have the `Composite` render a specific screen. Pass the intended path in
via the `value` property (for example `value: '/intended/path'`). Use the
`onResetValue` callback to clear the value that is passed to `path` (set it to
an empty string/`undefined`). `onResetValue` is called immediately after the
passed in path `value` is rendered within the `Composite` component. This is
required in order to accommodate passing in the same path `value` sequentially
and having the underlying component recognize there's been a change. It is
possible the user navigates elsewhere in between sequential path `value`
updates. NOTE: Make sure to omit the hash segment of a path if it exists. For
example: `#/intended/path` would be `/intended/path`.

---

#### `onEvent`

**type:**

```ts
type OnAuthSuccessEventData = {
  user: {
    id: string;
  };
};

type ErrorEventData = {
  name: string;
  message: string;
  errorCode: string;
};

type EventData =
  | {
      key: 'onauthsuccess';
      data: OnAuthSuccessEventData;
    }
  | {
      key: 'error';
      data: ErrorEventData;
    };

type OnEventCallback = (event: EventData) => void;
```

Callback property that allows for listening to internal events of the
embeddable.

---

### `nativeModules`

_required_

**type:**

```ts
import type storage from '@react-native-async-storage/async-storage';
import type * as cameraRoll from '@react-native-camera-roll/camera-roll';
import type geolocation from '@react-native-community/geolocation';
import type biometrics from 'react-native-biometrics';
import type documentPicker from 'react-native-document-picker';
import type * as fileSystem from 'react-native-fs';
import type permissions from 'react-native-permissions';
import type print from 'react-native-print';

type NativeModuleMap = {
  biometrics?: typeof biometrics;
  permissions?: typeof permissions;
  cameraRoll?: typeof cameraRoll;
  fileSystem?: typeof fileSystem;
  documentPicker?: typeof documentPicker;
  geolocation?: typeof geolocation;
  print?: typeof print;
  storage?: typeof storage;
};
```

Property used to inject native dependencies into the composite. At minimum
`storage` is required.
