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

import { SafeAreaView } from 'react-native'
import { Composite } from '@icanbwell/composite/native'
// Native Module(s) to inject
import storage from '@react-native-async-storage/async-storage'

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

type: string

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

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 biometrics from 'react-native-biometrics'
import type permissions from 'react-native-permissions'
import type * as cameraRoll from '@react-native-camera-roll/camera-roll'
import type * as fileSystem from 'react-native-fs'
import type documentPicker from 'react-native-document-picker'
import type geolocation from '@react-native-community/geolocation'
import type print from 'react-native-print'
import type storage from '@react-native-async-storage/async-storage'

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.