@epilot/journey-embed-sdk

v0.3.0

Published

4 days ago

Fluent builder SDK for embedding epilot Journeys on external websites — supports <iframe> and <epilot-journey> web component backends.

@epilot/journey-embed-sdk

Fluent builder SDK for embedding epilot Journeys on external websites. Supports two rendering backends behind a single chainable API:

<iframe> — stronger style isolation, multiple Journeys per page.
<epilot-journey> web component — renders in Shadow DOM, better performance and accessibility.

Install

npm install @epilot/journey-embed-sdk
# or
yarn add @epilot/journey-embed-sdk
# or
pnpm add @epilot/journey-embed-sdk

Usage

Bundler (ESM / CJS)

import { Epilot } from '@epilot/journey-embed-sdk'

const $epilot = new Epilot()

$epilot
  .embed('<your-journey-id>')
  .asWebComponent()
  .mode('inline')
  .append('#embed-target')

React (with refs)

Placement methods (append, prepend, before, after) accept either a CSS selector or a direct HTMLElement. That means you can pass ref.current without having to give your target an id or class.

import { useEffect, useRef } from 'react'
import { Epilot, type Embedding } from '@epilot/journey-embed-sdk'

const $epilot = new Epilot()

export function JourneyEmbed({ journeyId }: { journeyId: string }) {
  const targetRef = useRef<HTMLDivElement | null>(null)
  const embeddingRef = useRef<Embedding | null>(null)

  useEffect(() => {
    if (!targetRef.current) return

    embeddingRef.current = $epilot
      .embed(journeyId)
      .asWebComponent()
      .mode('inline')
      .append(targetRef.current)

    return () => {
      embeddingRef.current?.remove()
      embeddingRef.current = null
    }
  }, [journeyId])

  return <div ref={targetRef} />
}

The .remove() call in the cleanup detaches the element and tears down all SDK listeners, so the component is safe to mount, unmount, and remount without leaks.

Browser via CDN

Synchronous:

<script src="https://embed.journey.epilot.io/sdk/bundle.js"></script>
<script>
  $epilot.embed('<your-journey-id>').asWebComponent().append('#embed-target')
</script>

Asynchronous — use the onReady queue so your page can load the SDK without blocking:

<head>
  <script>
    ;(function (h, o, u, n, d) {
      h = h[d] = h[d] || {
        q: [],
        onReady: function (c) {
          h.q.push(c)
        }
      }
      d = o.createElement(u)
      d.async = 1
      d.src = n
      n = o.getElementsByTagName(u)[0]
      n.parentNode.insertBefore(d, n)
    })(
      window,
      document,
      'script',
      'https://embed.journey.epilot.io/sdk/bundle.js',
      '$epilot'
    )
  </script>
</head>
<body>
  <!-- rest of your page -->
  <script>
    window.$epilot.onReady(function (epilot) {
      epilot.embed('<your-journey-id>').asWebComponent().append('#embed-target')
    })
  </script>
</body>

API

See the full documentation at docs.epilot.io/docs/journeys/sdk.

Quick reference

| Method | Purpose | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | .asIframe() / .asWebComponent() | Pick the backend. | | .mode('inline' \| 'full-screen') | Display mode. Defaults to inline. | | .topBar(bool) | Show/hide the Journey top bar. | | .scrollToTop(bool) | Scroll to top on step navigation. | | .closeButton(bool) | Show/hide the close button. | | .contextData({...}) | Key/value data forwarded to the Journey. Accepts string or number values (numbers are coerced to strings). | | .dataInjectionOptions({...}) | Pre-fill fields and/or set the starting step. | | .name(string) | Accessible name for the embedded element. | | .testId(string) | Sets data-testid on the element for tests. | | .id(string) | Sets id on the element. Call before placement. | | .isFullScreenEntered(bool) | Enter/exit full-screen programmatically. | | .append / .prepend / .before / .after | DOM placement — end of the chain. | | .el() | Returns the injected element. | | .remove() | Remove the element and tear down listeners. |

Configuration

new Epilot(options?) accepts:

| Option | Type | Default | Purpose | | ----------------------- | --------- | ----------------------------- | ----------------------------------------------------------------------------- | | baseUrl | string | 'https://journey.epilot.io' | Base URL of the Journey app. | | webComponentScriptUrl | string | — | Explicit override for the <epilot-journey> script URL. Useful in local dev. | | debug | boolean | false | Enable iframe-resizer verbose logging. |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@epilot/journey-embed-sdk

Install

Usage

Bundler (ESM / CJS)

React (with refs)

Browser via CDN

API

Quick reference

Configuration

License