@icanbwell/composite

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.

<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.

npm install @icanbwell/composite@<VERSION_NUMBER>

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

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.

<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).

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.

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).

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.

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

Install Pods

npx pod-install

Usage

// 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 below)

type: string

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

---

path

type:

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:

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:

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.