> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect embed SDK

> Embed the Catena Connect flow in your own application with one call

The Connect embed SDK connects fleet telematics to Catena from your own application. One call renders the connection flow on your page and tells you how it ended. The core package has no runtime dependencies.

There are two packages:

* `@catenaclearing/connect-sdk`, the core package, for any page.
* `@catenaclearing/connect-sdk-react`, a React wrapper around the core package.

## What you need

<Steps>
  <Step title="An invitation URL">
    The link on an [invitation](/recipes/create-invitations) you create in the Catena dashboard or through the Catena API. The origin this package trusts is derived from it.
  </Step>

  <Step title="An embed key">
    Issued by Catena. It is valid only for the origins registered against it, and the branding options apply only when it resolves.
  </Step>

  <Step title="A registered origin">
    Every page that launches the flow must be on an origin registered against your embed key. You give Catena the origins and Catena registers them. Until an origin is registered, the flow does not render in an iframe on it. The surface offers the popup instead, where the flow runs but its messages never reach your page. Registered origins must be `https`, or `http` on `localhost`, and the scheme, host and port must match exactly: `www` and the apex are different origins.
  </Step>

  <Step title="A launching page that keeps its popups">
    If the page that calls `open()` sends a `Cross-Origin-Opener-Policy` header, it must be `same-origin-allow-popups` or `unsafe-none`. With `same-origin`, the browser cuts your page off from the popup the moment it loads the flow, so the popup mode cannot report anything back. See [When you receive nothing](/get-started/connect-sdk/troubleshooting#when-you-receive-nothing).
  </Step>
</Steps>

You create invitations yourself, in the Catena dashboard or through the Catena API. Catena issues the embed key and registers the origins you provide.

If you also want to cover browsers that block popups, you need two pages for the flow to come back to, on the same origin as the page that launches it. See [If the browser blocks the popup](#if-the-browser-blocks-the-popup).

## Install

<Note>
  **Beta.** Both packages are in beta. Install them with the `@beta` tag. A plain `npm install @catenaclearing/connect-sdk` resolves to `0.0.2`, a skeleton that predates the flow, until the stable `1.0.0` is published. See [Versioning and support](/get-started/connect-sdk/versioning).
</Note>

```sh theme={null}
npm install @catenaclearing/connect-sdk@beta
```

The package page is [npmjs.com/package/@catenaclearing/connect-sdk](https://www.npmjs.com/package/@catenaclearing/connect-sdk). Copy the command from here or from that page rather than typing the name, because look-alike names exist. See [Official packages](/get-started/connect-sdk/overview#official-packages).

React apps install `@catenaclearing/connect-sdk-react@beta` instead, which wraps this package. See [React](/get-started/connect-sdk/react).

## Quick start

Launch the flow from a click:

```js theme={null}
import { open } from "@catenaclearing/connect-sdk";

button.addEventListener("click", () => {
  const connect = open({
    inviteUrl,
    embedKey,
    onSuccess: ({ connectionIds }) => continueYourFlow(connectionIds),
    onExit: ({ reason }) => offerRetry(reason),
    onClose: () => connect.destroy(),
  });
});
```

That is the whole integration for most browsers. The flow renders in an iframe on your page, or in a popup window where the browser will not allow the iframe.

### When the user presses Done

Once a provider is connected, the flow shows a success screen with a button that ends it. In the iframe the button reads **Done**. In a popup or a redirected tab it reads **Return to** followed by your name as configured in Catena. Pressing it calls `onSuccess` with the connections made in this session, and then `onClose`.

The package does not remove the overlay, the iframe or the popup window on its own. `destroy()` removes all of them. The quick start calls `destroy()` on the handle `open()` returns from `onClose`, so the surface goes away when the user presses the button.

A user can also leave without pressing the button. Your [connection webhooks](/api-reference/webhooks/overview) record every connection either way. See [Events and outcomes](/get-started/connect-sdk/events).

## If the browser blocks the popup

This section is optional. If a browser blocks both the iframe and the popup, the flow takes over the browser tab your page is in: it navigates away from your page and runs full-page. When the user finishes, the flow sends them to the success or failure URL on your invitation (`success_redirect_url` and `failure_redirect_url`), and your page's callbacks are gone.

The success URL gets `status=success` after a connection. The failure URL gets `status=failure` when the user declines consent or disconnects, and `status=integration-requested` when they request an integration or join a waitlist. In the iframe and popup modes those endings arrive as `onExit`. The flow also appends `skip_reason` on a decline with a reason, and `tsp_count`.

To get the outcome on that path, host those two pages on the same origin as the launching page, and call `resume()` on each one:

<CodeGroup>
  ```js Success page theme={null}
  import { resume } from "@catenaclearing/connect-sdk";

  resume({
    outcome: "success",
    onSuccess: ({ connectionIds }) => continueYourFlow(connectionIds),
  });
  ```

  ```js Failure page theme={null}
  import { resume } from "@catenaclearing/connect-sdk";

  resume({
    outcome: "exit",
    onExit: ({ reason }) => offerRetry(reason),
  });
  ```
</CodeGroup>

<Warning>
  These are two separate call sites, not one call with `outcome` swapped. `resume()` calls `onExit` for `"exit"`, so copying the success form and changing only `outcome` gives you a page that never receives a terminal callback.
</Warning>

`resume()` always gives an empty `connectionIds`. On the failure page, `reason` is the URL's `skip_reason` when there is one, otherwise its `status`. Your webhooks are the record.

If your invitation has no redirect URLs, the flow still completes on this path and your webhooks still fire. Whether it succeeded or not, the user stays on the flow's last screen, with no button back to your site.

None of this applies when the page that calls `open()` is itself inside a frame. The tab is not that page's to navigate, so a blocked popup leaves the surface where it is, with a message asking the user to allow pop-ups and press **Continue** again.

[How the flow runs](/get-started/connect-sdk/how-it-works) explains when each mode is used, and [resume()](/get-started/connect-sdk/javascript-reference#resume-options) has the full behaviour.

## Verify your integration

If a check fails, [Troubleshooting](/get-started/connect-sdk/troubleshooting) goes from what you see on the page to the fix.

<Steps>
  <Step title="The launching origin is registered">
    The launching page's origin is registered against your embed key. See [What you need](#what-you-need) and [When you receive nothing](/get-started/connect-sdk/troubleshooting#when-you-receive-nothing).
  </Step>

  <Step title="Popups are allowed on the launching page">
    Your page opens the popup mode's window, so popups must be allowed on the launching page, your site, and its `Cross-Origin-Opener-Policy` must not be `same-origin`. The flow opens the provider sign-in window. See [the three modes](/get-started/connect-sdk/how-it-works#the-three-modes) and [the provider window](/get-started/connect-sdk/how-it-works#the-provider-window).
  </Step>

  <Step title="Your CSP allows the connect origin to be framed">
    The page's Content Security Policy allows the connect origin in frames. [Troubleshooting](/get-started/connect-sdk/troubleshooting#symptoms) has the directive to change.
  </Step>

  <Step title="onOpen arrives">
    `onOpen` on the launching page means the origin is registered. It is the flow's own message, and it reaches a registered origin only.
  </Step>

  <Step title="If you cover the redirect path, both pages call resume()">
    The success and failure pages are on the launching origin and call `resume()` with the right `outcome`. See [If the browser blocks the popup](#if-the-browser-blocks-the-popup).
  </Step>

  <Step title="Webhooks are the record">
    Your [connection webhooks](/api-reference/webhooks/overview) are the record, and a callback is the prompt to check them. See [Events and outcomes](/get-started/connect-sdk/events).
  </Step>
</Steps>

## Official packages

<Warning>
  The only official Catena Clearing packages are published under the `@catenaclearing` scope. There are two, [`@catenaclearing/connect-sdk`](https://www.npmjs.com/package/@catenaclearing/connect-sdk) and [`@catenaclearing/connect-sdk-react`](https://www.npmjs.com/package/@catenaclearing/connect-sdk-react).

  Copy the name from the install command or the npm page rather than typing it.

  Packages under other scopes, for example `@catena`, `@catena-x` and `@catena/sdk` (which belongs to an unrelated project), are not Catena Clearing packages. Neither are unscoped names containing "catena". Accept no substitutes.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="How the flow runs" icon="route" href="/get-started/connect-sdk/how-it-works">
    The three modes, the provider window, and the redirect path.
  </Card>

  <Card title="Events and outcomes" icon="bell" href="/get-started/connect-sdk/events">
    The six callbacks, their payloads, and what each one means.
  </Card>

  <Card title="JavaScript reference" icon="brackets-curly" href="/get-started/connect-sdk/javascript-reference">
    Every option of `open()`, `resume()` and `preload()`.
  </Card>

  <Card title="React" icon="react" href="/get-started/connect-sdk/react">
    A hook, a component and a resume hook for React applications.
  </Card>

  <Card title="Without the package" icon="link" href="/get-started/connect-sdk/without-the-package">
    A plain iframe, link or window, and reading the completion messages yourself.
  </Card>

  <Card title="Troubleshooting" icon="stethoscope" href="/get-started/connect-sdk/troubleshooting">
    From what you see on the page to the cause and the fix.
  </Card>

  <Card title="Versioning and support" icon="code-branch" href="/get-started/connect-sdk/versioning">
    What the semver promise covers and which versions are supported.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.