Documentation: Guide to Everee Embed

In order to pay workers quickly and accurately, Everee needs up-to-date information about our customers’ workers, including their contact details, tax withholding elections, and other data. Keeping worker information up-to-date between multiple platforms is difficult and prone to error, so Everee provides three worker-facing user experiences our customers can embed directly into their own apps, websites, or other solutions:

  • Worker onboarding
  • Worker account management
  • Pay statement & tax form access

There are important benefits to embedding these experiences directly into the software workers already use: workers can keep their own pay information up-to-date without a complicated or manual backend process; they can access their pay statements, tax forms, and other documents directly from Everee with no extra effort; and workers can use one seamless software experience, under one account login, rather than managing two separate accounts in two platforms.

Use Cases

Embedded Everee is designed for customers who provide—or plan to provide—an app or web experience their workers will use directly. This is common in the gig staffing, delivery, transportation, entertainment, and hospitality industries among many others.

Embedded Everee supports the common ways these experiences are delivered, whether it’s native apps available through the iOS App Store or Google Play Store, or a web experience that’s customized for worker access. Everee’s UX can be inserted into any software like this to create a seamless experience for workers.

Worker onboarding
For many platforms, onboarding new workers is the most important part of the experience. Simple, straightforward, and successful worker onboarding can dramatically improve workers’ initial experience and help create loyalty and engagement from the beginning.

Worker account management
Workers’ information changes over time: people move house, update bank accounts and debit cards, and change tax withholding elections. Everee’s embedded UX makes it fast and easy for workers to manage their own information without depending on support or HR professionals.

Pay statement & tax form access
Whether it’s frequently pulling up pay statements or retrieving a Form W-2 or 1099 once per year, workers need to access accurate documentation of their pay. Accessing these documents takes only a couple of taps through Everee’s embedded UX.

How Embedding Works

In order to embed Everee’s UX into another software platform, a developer will add a small amount of custom code into the areas where the customer wants Everee’s UX to be displayed. The embedded UX is designed to be visually clean, simple, and easy to use, and feels like a native part of the software it’s inserted into.

Adding this custom code is a small amount of work, and Everee provides step-by-step instructions and samples to help make the integration process as quick and easy as possible.
Everee’s UX is typically inserted at specific points in the worker’s experience, like at the end of the initial worker onboarding process, and also in a navigation menu. The Everee UX fits neatly into the existing software, so workers will always be able to navigate through the entire experience in a consistent and familiar way.

Since Everee only captures the extra information needed to process payments, deductions, and taxes, Everee can shoulder the burden of collecting and protecting workers’ sensitive personal data.

Once the Everee UX is embedded, worker information begins to flow into the Everee platform, and workers are payable through Everee as soon as they finish onboarding. A payroll or operations administrator (or an automated API integration) can easily process payments through the Everee web app to get workers paid—every day, every week, or anything in between.

Technical Implementation Guide

Implementing Embedded Everee within existing software 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 embedded session in the context of a specific worker’s account. At a high level, the workflow looks like this:

  1. Create an embedded session via API.
  2. Present a web view or iframe with the returned session URL.
  3. Dismiss the embedded view by handling:
    the user’s tap of a “close” button (or similar), or
    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 web view at any time.

Creating a worker record
The first step is to create a Worker record in Everee. This is typically done immediately before presenting the embedded Everee onboarding experience. To create a worker, use the appropriate endpoint below.

Note: a Worker record must have been created in Everee prior to creating any embedded sessions, including an Onboarding session, because you must provide a worker ID (or “external worker ID”) that Everee knows. Use the endpoints below to create Workers prior to kicking off Onboarding.

For a 1099 contractor:

 
POST /api/v2/embedded/workers/contractor

{
	firstName: string [required]
	middleName: string
	lastName: string [required]
	phoneNumber: string [required], 10 digits
	email: string [required], email format
	hireDate: string [required], ISO8601 date
	legalWorkAddress: object [required], with shape: {
		useHomeAddress: boolean [required]
		workLocationId: number, ignored if “useHomeAddress” is “true”
	}
	homeAddress: object [required], with shape: {
		line1: string [required]
		line2: string
		city: string [required]
		state: string [required], 2-letter state abbreviation
		postalCode: string [required], 5-digit ZIP code
	}
	externalWorkerId: string
}
 

For W-2 employees:


POST /api/v2/embedded/workers/employee

{
	firstName: string [required]
	middleName: string
	lastName: string [required]
	phoneNumber: string [required], 10 digits
	email: string [required], email format
	hireDate: string [required], ISO8601 date
	legalWorkAddress: object [required], with shape: {
		useHomeAddress: boolean [required]
		workLocationId: number, ignored if “useHomeAddress” is “true”
	}
	homeAddress: object [required], with shape: {
		line1: string [required]
		line2: string
		city: string [required]
		state: string [required], 2-letter state abbreviation
		postalCode: string [required], 5-digit ZIP code
}
payType: string [required], one of: “HOURLY”, “SALARY”
payRate: object [required], Money
title: string
typicalWeeklyHours: number [required], integer in range 1-40 inclusive
	externalWorkerId: string
}

Returns:


201 Created
{
workerId: string
	externalWorkerId: string
}

Creating an embedded session
To create an embedded session that can be opened in a web view, make the following request:


POST [base URL]/api/v2/embedded/session

{
workerId: string [required if ‘externalWorkerId’ is not provided]
externalWorkerId: string [required if ‘workerId’ is not provided]
eventHandlerName: string [required]
experience: string [required], one of:
		ONBOARDING,
		PAYMENT_HISTORY,
		TAX_DOCUMENTS,
		HOME_ADDRESS,
		PAYMENT_DEPOSIT
	experienceVersion: string [required], always “V1_0”
}

Successful creation of a session will return the following response:

{
url: string
origin: string
expiresInMs: number
}

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 desired worker-facing embedded experience. To prevent unauthorized access to sensitive data or privileged actions, embedded sessions expire after a short period of time and can no longer be started once they have expired.

Important: Always create a session immediately prior to presenting it in a web view. Never create a session ahead of time because its access URL will likely expire before the worker triggers it to be presented.

See the Everee Platform API documentation for more details about performing requests against Everee’s API.

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

Initialize the web view with the session URL returned from creating the embedded 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 embedded UX 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 UX feel native to your application.

Dismissing the web view
As with presenting an embedded experience, the way an experience is dismissed depends on a few factors. 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, 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.

When an embedded experience is complete (either due to a user tapping a “back” or “close” button in the embedded 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 the “Handling events” section below for details. Once the DISMISS event is received, the host application can safely dismiss the web view and return the user to the host UX.

Handling events
The embedded Everee UX publishes events to the host application using a mechanism specific to the host platform. These events carry data payloads with the following shape:

{
eventType: string, always “DISMISS”
error: boolean
errorMessage: string [optional]
eventHandlerName: string 
}

On native iOS:

Add a custom WKScriptMessageHandler to the WKWebView’s WKUserContentController. Use the created session’s eventHandlerName as the name parameter of the WKScriptMessageHandler when adding it to the WKUserContentController. When your handler receives a WKScriptMessage, its data property will be an NSDictionary with the event shape defined above

On native Android:

Create a pair of WebMessagePorts with WebView#createMessageChannel(). Set a WebMessageCallback on the first WebMessagePort, which will receive events from the embedded UX. Wrap the second WebMessagePort in an array, then wrap that in a WebMessage to send the port to the embedded UX:


WebMessagePort[] channel = webView.createMessageChannel();
channel[0].setWebMessageCallback(webMessageCallback);
WebMessage webMessage = new WebMessage("", Array.of(channel[1]));
webView.postWebMessage(webMessage, embeddedSessionUrl);

When your callback receives a WebMessage, its getData() method will return a JSON string representing the event shape defined above.

On the web:

Use the MessageChannel API to create a new channel. You’ll use the two ports connected to the channel to communicate between your application and the Everee UX inside the iframe.


const channel = new MessageChannel();

Send port2 into the iframe embedding the Everee UX using the code>onLoad callback of the iframe element:


iframe.addEventHandler(“load”, (event) => {
iframe.contentWindow.postMessage("", "*", [channel.port2]);
});

Now that the Everee embedded experience has received port2, listen to events from the iframe on port1, the port you retained earlier:


channel.port1.addEventListener(“message”, (event) => {
// check event.data.handlerName and event.data.eventType,
// and handle messages sent from the Everee embedded UX
});