From eb9d9060c97aec3e90a1bd753c227bae2d87a263 Mon Sep 17 00:00:00 2001 From: Adeola Adeyemo Date: Mon, 24 Mar 2025 17:10:32 +0000 Subject: [PATCH] update: add new init param to journey embed docs Signed-off-by: Adeola Adeyemo --- docs/journeys/embedding.md | 135 +++++++++++++++++++++++++------------ 1 file changed, 92 insertions(+), 43 deletions(-) diff --git a/docs/journeys/embedding.md b/docs/journeys/embedding.md index be15125..871c1ab 100644 --- a/docs/journeys/embedding.md +++ b/docs/journeys/embedding.md @@ -10,22 +10,26 @@ Journeys can easily be embedded on any website by placing an embed script tag pr An embed script is a simple way to publish an epilot journey on your website. The script loads the journey using a Journey ID and a secure token to embed the journey securely on your website. -This page guides you through the different options available to embed a Journey into your web page. +This page guides you through the different options available to embed a Journey into your web page. ## Embed Configurator + Configure and copy the embed script via the Journey Builders' Embed Configurator after saving the Journey. You can choose: -* Whether the Journey should be shown in a full-screen overlay, or inline to your website (Default: Fullscreen) -* The language of the journey (Default: German DE) -* The label of the button that suppose to open the journey (Default: Inhalt anzeigen) -* The alignment of the button, left, right, or center (Default: Left) -* Overwride the journey option to scroll the user to the top of the new step once the end user clicks on the next button in any step (Default: ON) + +- Whether the Journey should be shown in a full-screen overlay, or inline to your website (Default: Fullscreen) +- The language of the journey (Default: German DE) +- The label of the button that suppose to open the journey (Default: Inhalt anzeigen) +- The alignment of the button, left, right, or center (Default: Left) +- Overwride the journey option to scroll the user to the top of the new step once the end user clicks on the next button in any step (Default: ON) Depending on the embedding type, you can change additional settings. ![Embedding Configuration](../../static/img/journey-builder-embed.png) ## Journey Data Injection + It is possible by using the Embed Script to modify the initial state of the journey. There are the following posibilities: + 1. Setting an intial data for the journey: doing this will prefill the blocks with data. 2. Starting the journey from a specific step: doing this will start the journey from the specified step if it was combined with the initial data, one can achieve a case when a product is selection is done in an external website, injected into the journey, then the in journey selection step skipped. 3. Set display options for the journey fields (for now disabling fields) @@ -33,6 +37,7 @@ It is possible by using the Embed Script to modify the initial state of the jour The following DataInjectionOptions type shows what is possible. However we ask devs to go to our [epilot Journey SDK](https://github.com/epilot-dev/epilot-journey-sdk) project which includes more documentation supported with examples. **Type Definition** + ```typescript export type DataInjectionOptions = { /** the initial step index of the journey. aka, where to start the journey from */ @@ -42,17 +47,20 @@ export type DataInjectionOptions = { /** the display options to be passed to the journey, for now it is used to disable some fields */ blocksDisplaySettings?: BlockDisplaySetting[] } -`````` +``` ## Configuration Possibilities + For more advanced configuration options, you can modify the embed script yourself, as it adds an interface to your website to interact with the journey: `__epilot` Below we explain all possibile configuration options ### init + **Description** Used to initialize one or more journeys given individual options. Multiple Journeys with different configurations can be passed **Type Definition** + ```typescript type Init = (options?: OptionsInit[] | undefined, initOnLoad?: boolean) => void type JourneyMode = 'inline' | 'full-screen' @@ -87,42 +95,49 @@ type OptionsInit = { lang?: string /** the data injext options that will be passed to the journey */ dataInjectionOptions?: DataInjectionOptions + /** + * Used as iframe name/title attribute if provided + */ + name?: string } ``` **Usage** + ```typescript -__epilot.init([ - { journeyId: '123', mode: 'full-screen', topBar: false } -]) +__epilot.init([{ journeyId: '123', mode: 'full-screen', topBar: false }]) ``` ### update + **Description** Used to update an initialized journey by passed options. - **Type Definition** + ```typescript type Update = (journeyId: string, payload?: OptionsUpdate) => void type OptionsUpdate = Omit ``` **Usage** + ```typescript -__epilot.update("123", { journeyId: '123', mode: 'full-screen', topBar: false }) +__epilot.update('123', { journeyId: '123', mode: 'full-screen', topBar: false }) ``` - ### on + **Description** Sets up an event listener to execute custom logic based on journey events. **Uses cases:** + - Execute logging, or tracking - Adjust website CSS, e.g. if full screen exited **Type Definition** + ```typescript type JourneyEvent = | 'init' @@ -131,63 +146,83 @@ type JourneyEvent = | 'closeJourney' | 'formChange' -type On = (eventName: JourneyEvent, cb: (payload: Record, event: CustomEvent) => void) => void +type On = ( + eventName: JourneyEvent, + cb: (payload: Record, event: CustomEvent) => void +) => void ``` **Usage** + ```typescript -__epilot.on('init', function({ journeys }) { - console.log("Journey Initialized") +__epilot.on('init', function ({ journeys }) { + console.log('Journey Initialized') }) ``` ### enterFullScreen + **Description** If a journey is initialized in full-screen mode, executes the command to open the journey. - **Type Definition** + ```typescript -type EnterFullScreen = (journeyId: string, payload?: Record | undefined) => void +type EnterFullScreen = ( + journeyId: string, + payload?: Record | undefined +) => void ``` **Usage** + ```typescript -__epilot.enterFullScreen("123") +__epilot.enterFullScreen('123') ``` - ### exitFullScreen + **Description** -If a journey is in full-screen mode, executes the command to close the journey. It is also internally used at the Journeys “Close button”. +If a journey is in full-screen mode, executes the command to close the journey. It is also internally used at the Journeys “Close button”. **Type Definition** + ```typescript -type ExitFullScreen = (journeyId: string, payload?: Record | undefined) => void +type ExitFullScreen = ( + journeyId: string, + payload?: Record | undefined +) => void ``` **Usage** + ```typescript -__epilot.exitFullScreen("123") +__epilot.exitFullScreen('123') ``` ### isInitialized + **Description** Checks whether a journey is initialized already initialized or not. **Type Definition** + ```typescript type IsInitialized = (journeyId: string) => boolean ``` **Usage** + ```typescript -if(__epilot.isInitialized('123') === true) { - __epilot.enterFullScreen('123') +if (__epilot.isInitialized('123') === true) { + __epilot.enterFullScreen('123') } ``` + ## Scenarios + ### Full-Screen + The default embed method covers most of the use cases. A button will be placed on your website which opens the journey, covering the complete screen when clicked. **Code Snippet** @@ -195,22 +230,28 @@ The below code snippet provides the configured embed script and a button opening ```html - + - + ``` **Attributes explained** `data-ep-mode` - sets the mode the journey runs in `data-ep-journeyIds` the journey to be created via it’s id -**Outcome** +**Outcome** ![Embedding Fullscreen Outcome](../../static/img/journey-embed-outcome-full-screen.gif) - ### Inline + This method will place the journey into a provided container element, or, if not provided, at the end of the web page. The height of the journey will automatically be recalculated based on the current content. In order to provide a better user experience, navigating to a different step will cause the browser to move back to the top position of the journey. The close button of the top bar is hidden. **Code Snippet** @@ -221,40 +262,48 @@ The below code snippet provides the configured embed script required to set up t
- + ``` **Attributes explained** `data-ep-mode` - sets the mode the journey runs in `data-ep-journeyIds` the journey to be created via it’s id -**Outcome** +**Outcome** ![Embedding Inline Outcome](../../static/img/journey-embed-outcome-inline.gif) - ### Multiple Journeys + The best way to embed multiple journeys is to use the `__epilot` interface described [here](#init). Simply pass multiple items to the `init` function -**Code Snippet** +**Code Snippet** + ```html - - + + ``` **Attributes explained** In this example, we dont need any `data-ep-` attributes, as we use the `__epilot` interface to initialize the Journeys -**Outcome** +**Outcome** ![Embedding Multiple Outcome](../../static/img/journey-embed-outcome-multiple.gif) -