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:
- Initialize the app experience with the client key (
<CLIENT_KEY>
in the code
below). Think of this as a public SDK/API key. - 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 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.