Skip to main content
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

1

An invitation URL

The link on an invitation you create in the Catena dashboard or through the Catena API. The origin this package trusts is derived from it.
2

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.
3

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.
4

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.
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.

​
Install

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.
The package page is 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. React apps install @catenaclearing/connect-sdk-react@beta instead, which wraps this package. See React.

​
Quick start

Launch the flow from a click:
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 record every connection either way. See Events and outcomes.

​
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:
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.
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 explains when each mode is used, and resume() has the full behaviour.

​
Verify your integration

If a check fails, Troubleshooting goes from what you see on the page to the fix.
1

The launching origin is registered

The launching page’s origin is registered against your embed key. See What you need and When you receive nothing.
2

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 and the provider window.
3

Your CSP allows the connect origin to be framed

The page’s Content Security Policy allows the connect origin in frames. Troubleshooting has the directive to change.
4

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.
5

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.
6

Webhooks are the record

Your connection webhooks are the record, and a callback is the prompt to check them. See Events and outcomes.

​
Official packages

The only official Catena Clearing packages are published under the @catenaclearing scope. There are two, @catenaclearing/connect-sdk and @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.

​
Next steps

How the flow runs

The three modes, the provider window, and the redirect path.

Events and outcomes

The six callbacks, their payloads, and what each one means.

JavaScript reference

Every option of open(), resume() and preload().

React

A hook, a component and a resume hook for React applications.

Without the package

A plain iframe, link or window, and reading the completion messages yourself.

Troubleshooting

From what you see on the page to the cause and the fix.

Versioning and support

What the semver promise covers and which versions are supported.