Client reference

import { loadDoola } from '@doola/js';

The package ships full TypeScript definitions with these descriptions, so your editor shows them too.

loadDoola(options)

function loadDoola(options: DoolaOptions): Promise<Doola>;

Loads doola’s loader, validates the options and resolves with the SDK instance for this page.

One instance per page. A second call with the same publishableKey resolves with the live instance and ignores the new options. A call with a different key rejects until you call destroy().
Browser only. It rejects outside a browser, so call it from a client-only path.
Rejects when the loader cannot load (a CSP, an ad blocker, the network) or an option is invalid. The message names the problem.

Options

string

required

Your pk_test_... or pk_live_... key. Its prefix selects the environment. Any other value rejects.

() => Promise<CustomerSession>

required

Called when the SDK mounts, before each session expires, and each time the iframe asks again, such as when the founder presses Try again. Calls at the same moment are merged into one. Fetch a fresh session from your session route every time, and resolve with { accessToken, expiresIn }. An expiresAt string is ignored; any other expiresAt value fails the session, so leave it out.On failure, reject with an object that carries the HTTP status of your route, and the code from its JSON body when it sent one: 401 becomes partner_session_expired, and a 409 is named by its code (E_EMAIL_IN_USE, E_RESOURCE_CONFLICT or E_CUSTOMER_REVOKED). A 409 with no code is email_in_use on the first session and renewal_failed on a renewal. Anything else becomes mint_failed or renewal_failed. See Errors.

(error: DoolaAuthError) => void

required

A session could not be created or renewed. Fires once for each failed call to fetchAccessToken, including each Try again, so keep it idempotent. See Errors.

(event: { companyId: string }) => void

required

The founder submitted the wizard, or asked to pay again for a formation that waits on payment. Open your checkout for companyId. It can fire more than once for the same company, so keep it idempotent. See Take payment.

(error: DoolaLoadError) => void

The SDK failed to load or run. The iframe shows its own error screen in most cases, so this is mainly for your logging, except for render_error. See Errors.

() => void

The first time anything, including a loading state, is visible in the iframe. Use it to remove your own placeholder.

{ mode?: 'auto' | 'fullScreen' }

default:"{ mode: 'auto' }"

auto shows the SDK inline and switches to a full-screen overlay on viewports 640px wide or narrower. fullScreen always uses the overlay. See Presentation and mobile.

string

A BCP 47 language tag. The SDK is in English (en) today.

string

Your own domain for the iframe, set up with doola in advance. Keep it a constant. See Your own domain.

The Doola instance

create()

create(): DoolaComponent;

Returns a new <doola-embed> element. Append it to mount the SDK, remove it to unmount. It takes no arguments: the iframe shows the wizard, the payment screen or the founder’s company depending on their state. To refresh, for example after you confirm payment, replace the old element with a new one (element.replaceWith(doola.create())). Each call creates a separate iframe, so never leave the old one on the page.

update(options)

update(options: { locale?: string }): void;

Changes options after load. Only locale can change. Leaving a key out keeps its value, and locale: undefined clears it.

destroy()

destroy(): void;

Drops the customer’s session from the page, removes every element and stops renewing. Call it when your user signs out of your product, never on an ordinary unmount. The instance cannot be used again: create() and update() throw afterwards. Calling destroy() twice is safe.

Types

interface CustomerSession {
  accessToken: string;
  expiresIn: number; // seconds
  expiresAt?: string;
}

interface DoolaAuthError {
  type:
    | 'partner_session_expired'
    | 'email_in_use'
    | 'external_id_conflict'
    | 'customer_revoked'
    | 'mint_failed'
    | 'renewal_failed';
  message: string;
}

interface DoolaLoadError {
  type:
    | 'api_connection_error'
    | 'authentication_error'
    | 'invalid_request_error'
    | 'render_error'
    | 'api_error';
  message: string;
}

Also exported: Doola, DoolaComponent, DoolaOptions, FetchAccessToken, Presentation and DoolaGlobal.

The element

<doola-embed> is a block element. Its iframe takes the full width of the container, reserves 160px until the first screen renders, then follows the height of its content, and keeps it while hidden with display: none. In full-screen mode it covers the viewport and locks your page’s scroll until you remove it.

Versions

@doola/js follows semantic versioning. It loads doola’s loader from https://js.doola.com/v1/doola.js, which updates in place and stays compatible with every @doola/js release in that major version, so fixes reach your site without an upgrade. See the changelog.

Get started

Integrate

Customize

Test and launch

Reference

Help

loadDoola(options)

Options

The Doola instance

create()

update(options)

destroy()

Types

The element

Versions

​loadDoola(options)

​Options

​The Doola instance

​create()

​update(options)

​destroy()

​Types

​The element

​Versions

loadDoola(options)

Options

The Doola instance

create()

update(options)

destroy()

Types

The element

Versions