From 9afea3daeb4b9716bde90b73465d66023d4d6df4 Mon Sep 17 00:00:00 2001 From: Adeola Adeyemo Date: Wed, 22 Apr 2026 10:36:39 +0100 Subject: [PATCH] chore: update sdk docs with npm package install Signed-off-by: Adeola Adeyemo --- docs/journeys/sdk.md | 383 ++++++++++++++++++++++++++++++------------- 1 file changed, 266 insertions(+), 117 deletions(-) diff --git a/docs/journeys/sdk.md b/docs/journeys/sdk.md index 55f90e4..81e8632 100644 --- a/docs/journeys/sdk.md +++ b/docs/journeys/sdk.md @@ -4,10 +4,10 @@ sidebar_position: 5 # Journey Embed SDK (Beta) -The Journey Embed SDK is the new embedding architecture for epilot Journeys. It unifies two backends behind a single, chainable JavaScript API: +The Journey Embed SDK is a chainable JavaScript API for rendering epilot Journeys. One SDK, two backends: -- A **rewritten iframe engine** that replaces the legacy embedding [`__epilot` script](./embedding) with a faster, cleaner host integration. -- The [`` Web Component](./web-components) — a drop-in custom HTML element that renders in Shadow DOM. +- A **rewritten iframe engine** that replaces the legacy [`__epilot` script](./embedding) with a faster, cleaner host integration. +- The [`` Web Component](./web-components), a custom HTML element that renders in Shadow DOM. :::info Beta @@ -17,27 +17,106 @@ The SDK is in beta. Test it before rolling out to production. Existing embeds us :::tip When to use the SDK -For iframe embedding, the SDK is the new default — it replaces the legacy `__epilot` script. +For iframe embedding, the SDK is the new default. It replaces the legacy `__epilot` script. -For web components, use the SDK or drop the [``](./web-components) element directly into your HTML — whichever fits your integration. +For web components, use the SDK or drop the [``](./web-components) element directly into your HTML, whichever fits your integration. ::: -## Quick Start +## Installation + +You can install the SDK three ways. Pick the one that matches your setup. -### 1. Add the SDK script +### Option 1: Synchronous CDN -The SDK is a single script that exposes `$epilot` on `window`. When using `.asWebComponent()`, the SDK **automatically loads** the web component script — no additional ` ``` -When using `.asIframe()`, the SDK is entirely self-contained — no web component script is loaded. +### Option 2: Asynchronous CDN (with `onReady`) + +Load the SDK asynchronously to avoid blocking your page. Drop this stub in your ``. It places a tiny `$epilot.onReady()` queue on `window` and loads the real bundle in the background: + +```html title="Async CDN (drop in )" + +``` + +Then call `onReady` anywhere on the page. Your callback runs as soon as the SDK finishes loading: + +```html title="Embed once the SDK is ready" +
+ + +``` + +:::info How it works + +Before the bundle loads, `onReady(cb)` pushes `cb` onto a queue. When the bundle finishes loading, it replaces the stub, drains the queue, and invokes each callback. Callbacks registered later run synchronously. + +::: + +### Option 3: npm package + +For bundler-based apps (Next.js, Vite, Webpack, etc.), install the SDK from npm. You'll get full TypeScript types and autocomplete: + +```bash +npm install @epilot/journey-embed-sdk +# or +yarn add @epilot/journey-embed-sdk +# or +pnpm add @epilot/journey-embed-sdk +``` + +```ts title="ESM usage" +import { Epilot } from '@epilot/journey-embed-sdk' + +// Options are optional. Defaults to the production Journey app. +const epilot = new Epilot({ + // baseUrl: 'https://journey.staging.epilot.io', // override per environment +}) -### 2. Embed a Journey +epilot + .embed('') + .asWebComponent() + .mode('inline') + .append('#embed-target') +``` -Call `$epilot.embed()` after the DOM is ready and chain your configuration options. End the chain with an injection method (`append`, `prepend`, `before`, or `after`) to insert the Journey into the page: +The npm package does **not** use `window.$epilot`. You create your own instance. Its only runtime dependency is `iframe-resizer`. + +## Quick Start + +With the SDK installed via any of the options above, call `$epilot.embed()` (or your own instance) and chain configuration options. End the chain with an injection method (`append`, `prepend`, `before`, or `after`): ```html title="Inline embed via SDK"
@@ -55,31 +134,20 @@ Call `$epilot.embed()` after the DOM is ready and chain your configuration optio ``` -### 3. You're all set - The Journey is injected into `#embed-target`. Read on for the full API reference and advanced scenarios. -## Live Examples - -Browse interactive, runnable examples for every SDK scenario: - -- **[SDK Storybook](https://embed.journey.epilot.io/stories/?path=/docs/next-sdk--docs)** — inline, full-screen, inline-to-fullscreen, launcher, data injection, and more — with both iframe and web component backends. -- **[Web Component Storybook](https://embed.journey.epilot.io/stories/?path=/docs/next-web-component--docs)** — the same scenarios using raw `` attributes (no SDK). - -Use the **Controls** panel in Storybook to switch between backends and change options in real time. These examples work with **public Journeys** only — enter your own `journey-id` in the controls to see it in action. - ## Embed Targets The SDK supports two rendering backends. Choose one by calling the corresponding method in your chain: | Method | Backend | Notes | | ------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| `.asWebComponent()` | `` custom element | Recommended. Uses Shadow DOM — better performance and accessibility. The web component script is auto-loaded. | +| `.asWebComponent()` | `` custom element | Recommended. Uses Shadow DOM for better performance and accessibility. The web component script is auto-loaded. | | `.asIframe()` | `