How to Embed Components

Implementing Embed Components in your apps is very simple. We use a web-based UX that can be presented within a native “web view” or iframe, and a straightforward API to create each Component session in the context of a specific worker’s account. At a high level, the workflow looks like this:

1. Create a Component session via API.
2. Present a Component in a web view or iframe with the returned session URL.
3. Dismiss the Component by handling:
   a. the user’s tap of a “close” button (or similar), or
   b. the session requesting its own dismissal because it’s complete.

The host application retains full control of the experience, and can present and dismiss the Component at any time.

Creating a Component session

To create a Component session that can be opened in a web view, call the "Create Component session" API endpoint.

The url property of the response data is a pre-built URL that uniquely identifies the newly-created session and can be accessed directly in a web view to initiate the Component's experience. To prevent unauthorized access to sensitive data or privileged actions, Component sessions expire after a short period of time and can no longer be started once they have expired.

🚧

Always present a Component immediately after creating its session.

You should never create a session ahead of time, because its access URL will likely expire before the Component is triggered to be presented in the UI. This will result in an "Expired" error appearing in the Component webview.

Presenting a Component

Since Everee’s Component UX is web-based, it can be presented in any “web view” container native to the host app’s platform.

On native iOS, use WKWebView.
On native Android, use WebView.
On React Native, use React Native WebView.
On the web, use an iframe.

Initialize the web view with the Component session URL returned from creating the session, and display it using any interface and presentation style that fits your design approach. Once the web view requests the session URL, the session will be marked as “started”, and the session URL cannot be used again.

We recommend presenting the Everee Component modally, and not inline or alongside other content. On larger screens, present it within a fixed-size container that holds focus and must be dismissed to return to the presenting screen (we recommend a size of approximately 390px x 844px). On smaller screens, present it in a full-size view equivalent to other full-size views in your application, and use a presentation animation that matches your navigation style when possible.

Following these interface guidelines will help the Component UX feel native to your application.

Dismissing a Component

As with presenting a Component, the way dismissing a Component depends on a few factors. Most Components can be dismissed immediately in response to a user tapping a “back” or “close” button in the host application. However, the “Worker Onboarding” Component, for example, is designed to be fully completed before the worker is allowed to proceed back to the host application’s UX. In these cases, you should wait to receive a DISMISS event from the Component.

When a Component's experience is complete (either due to a user tapping a “back” or “close” button in the Component's UX, or by reaching the end of a fixed workflow) the web view will publish a DISMISS event to the host application. The specific mechanism used to publish this event depends on the host platform; see Handling Events for details. Once the DISMISS event is received, the host application can safely dismiss the Component's web view and return the user to the host UX.