How to Embed Experiences

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 an embedded experience URL via API.
2. Present the embedded experience in an <iframe> or webview with the returned URL, and attach an event listener so the experience can communicate with your app.
3. Dismiss the experience by handling either the user’s tap of a “close” button in your app, or the session requesting its own dismissal, using the "DISMISS" event, because it’s complete.

Your host application retains full control, and can present and dismiss the embedded experience at any time.

Creating an embedded experience URL

To create an embedded experience URL that can be opened in a web view, call the "Create embedded experience URL" 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 an <iframe> or webview to initiate the embedded experience. To prevent unauthorized access to sensitive data or privileged actions, embedded experience URLs expire after a short period of time and can no longer be started once they have expired.

🚧

Always present an experience immediately after creating its session.

You should never create a session ahead of time, because its access URL will likely expire before the experience URL is presented in the UI. This will result in an "Expired" error appearing in the embedded <iframe> or webview.

Only create an embedded experience URL when you know you need to present it immediately.

Presenting an embedded experience

Since Everee’s embedded experience 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. See Native iOS: WKWebView to handle events..
On native Android, use WebView. See Native Android: WebView to handle events. Using React Native, use react-native-webview. See React Native: ReactNativeWebview library to handle events. Using React or native JavaScript on the web, use an iframe. See Web & React: <iframe> to handle events.

Initialize the web view with the embedded experience 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 URL, the session will be marked as “started”, and the URL cannot be used again.

We recommend presenting the embedded experience 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 embedded experience UX feel native to your application.

Dismissing an embedded experience

As with presenting an embedded experience, dismissing it depends on how it works.

Most embedded experiences can be dismissed immediately in response to a user tapping a “back” or “close” button in the host application. However, the “Worker Onboarding” experience (called ONBOARDING in the API) is designed to be fully completed before the worker is allowed to proceed back to the host application’s UX. In this case, you should wait to receive a DISMISS event from the embedded experience's <iframe> or webview.

When an embedded experience is complete (either due to a user tapping a “back” or “close” button in the experience's UX, or by reaching the end of a fixed workflow like Worker Onboarding) the <iframe> or webview will publish a DISMISS event to the host application.

The specific mechanism used to publish this event depends on the host platform. See the Handling Events documentation for details. Once the DISMISS event is received, the host application can safely dismiss the experience's <iframe> or webview and return the user to the host UX.