You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
/** the display options to be passed to the journey, for now it is used to disable some fields */
62
64
blocksDisplaySettings?:BlockDisplaySetting[]
63
65
}
@@ -74,9 +76,7 @@ export type BlockDisplaySetting = {
74
76
}
75
77
```
76
78
77
-
The **recommended** form keys `initialState` by **block ID** — the block's stable, journey-wide identifier. Block IDs are unique across the whole journey and are unaffected by block renames or by reordering steps, so an embed keyed by block ID keeps working even after the journey is restructured. To find a block's ID, open the journey in **debug mode** (see video below) and copy the block IDs from the journey state.
The **recommended** form keys `initialState` by **block ID** — the block's stable, journey-wide identifier. Block IDs are unique across the whole journey and are unaffected by block renames or by reordering steps, so an embed keyed by block ID keeps working even after the journey is restructured. To find a block's ID, open the block configurator in the Journey builder.
80
80
81
81
A complete example combines all three: start the journey at a step by its stable `initialStepId`, prefill `initialState` keyed by block ID, and disable a block by `blockId`. Pass `dataInjectionOptions` alongside the rest of the options in `__epilot.init()`:
82
82
@@ -102,37 +102,39 @@ __epilot.init([
102
102
])
103
103
```
104
104
105
-
With the block-ID form you only list the blocks you actually want to prefill — there is no need to pad earlier steps with empty objects, and the mapping is unaffected by block renames or step reordering.
105
+
With the block-ID form you only list the blocks you actually want to prefill — there is no need to pad earlier steps with empty objects, and the mapping is unaffected by block renames or step reordering. To find a block's ID, open the block configurator in the Journey builder.
106
+
107
+
### Data Injection builder (preview)
108
+
109
+
You don't have to hand-write block IDs. The Journey Builder includes a **Data Injection (preview)** tool that lets you build the configuration visually: pick the blocks and fields to prefill, set their pre-fill values, mark blocks as read-only, choose the starting step, then copy the generated snippet straight into your `__epilot.init()` call.
The earlier array form of `initialState` (one entry per step indexed by **step position**, keyed by block **name**, with empty `{}` objects for steps you don't prefill) and the `blockName` + `stepIndex` form of `blocksDisplaySettings` are **deprecated but still supported** for backward compatibility. They break silently when blocks are renamed or steps are reordered, so prefer the block-ID form for new integrations.
110
116
111
117
```typescripttitle="Injecting data by step index + block name (deprecated)"
112
-
initialState: [
113
-
{},
114
-
{
115
-
"Binary Input":false
118
+
initialState: [
119
+
{},
120
+
{
121
+
'Binary Input':false,
122
+
},
123
+
{
124
+
'Personal Data Input': {
125
+
salutation:'Ms. / Mrs.',
126
+
firstName:'Test Name',
127
+
_isValid:false,
116
128
},
117
-
{
118
-
"Personal Data Input": {
119
-
"salutation":"Ms. / Mrs.",
120
-
"firstName":"Test Name",
121
-
"_isValid":false
122
-
}
123
-
}
124
-
]
129
+
},
130
+
]
125
131
```
126
132
127
-
:::
128
-
129
-
### Data Injection builder (preview)
133
+
Open your Journey in **debug mode** from the Journey Builder and inspect the state for each step. See below:
130
134
131
-
You don't have to hand-write block IDs. The Journey Builder includes a **Data Injection (preview)** tool that lets you build the configuration visually: pick the blocks and fields to prefill, set their pre-fill values, mark blocks as read-only, choose the starting step, then copy the generated snippet straight into your `__epilot.init()` call.
@@ -555,11 +557,13 @@ The same `.dataInjectionOptions({ ... })` call works with either backend — swa
555
557
556
558
### Populating `initialState`
557
559
558
-
The recommended form keys `initialState` by **block ID**. Each entry is an object of the field values for that block. Because the state is keyed by block ID, you only list the blocks you actually want to prefill — no per-step ordering or empty `{}` placeholders are needed, and the mapping is unaffected by block renames or step reordering.
560
+
The recommended form keys `initialState` by **block ID**. Each entry is an object of the field values for that block. Because the state is keyed by block ID, you only list the blocks you actually want to prefill — no per-step ordering or empty `{}` placeholders are needed, and the mapping is unaffected by block renames or step reordering. To find a block's ID, open the block configurator in the Journey builder.
559
561
560
-
To discover the correct block IDs and field structure, open your Journey in **debug mode** from the Journey Builder and inspect the state for each step. See below:
You don't have to hand-write block IDs. The Journey Builder includes a **Data Injection (preview)** tool that lets you build the configuration visually: pick the blocks and fields to prefill, set their pre-fill values, mark blocks as read-only, choose the starting step, then copy the generated options straight into your `.dataInjectionOptions()` call.
Open your Journey in **debug mode** from the Journey Builder and inspect the state for each step. See below:
586
601
587
-
You don't have to hand-write block IDs. The Journey Builder includes a **Data Injection (preview)** tool that lets you build the configuration visually: pick the blocks and fields to prefill, set their pre-fill values, mark blocks as read-only, choose the starting step, then copy the generated options straight into your `.dataInjectionOptions()` call.
Copy file name to clipboardExpand all lines: docs/journeys/web-components.md
+39-27Lines changed: 39 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -64,21 +64,21 @@ The Journey will render inline on your page. Read on for the full attribute refe
64
64
65
65
All attributes are set as standard HTML attributes on the `<epilot-journey>` element. Boolean attributes accept `"true"` or `"false"` as string values.
|`journey-id`|`string`| — |**Required.** The ID of the Journey to render. |
70
-
|`mode`|`"inline"`\|`"full-screen"`|`"full-screen"`| The display mode. `inline` renders the Journey within the page flow. `full-screen` renders it as an overlay. |
71
-
|`lang`|`"de"`\|`"en"`\|`"fr"`|`"de"`| Overrides the UI language. This affects UI labels and copy, but does not automatically translate static content configured in the Journey Builder. |
72
-
|`top-bar`|`"true"`\|`"false"`|`"true"`| Whether to show the top navigation bar. Only applies in `inline` mode — in `full-screen` mode the top bar is always visible and cannot be hidden. |
73
-
|`scroll-to-top`|`"true"`\|`"false"`|`"true"`| Whether to scroll the page to the top of the Journey when the user navigates to a new step. |
74
-
|`close-button`|`"true"`\|`"false"`|`"true"`| Whether to show the close button in the top bar. |
75
-
|`context-data`| JSON string | — | Additional contextual data passed to the Journey and included with the submission. Must be a JSON-encoded string of key-value pairs. See [Context Data](#context-data). |
76
-
|`data-injection-options`| JSON string | — | Pre-fill Journey fields and control the starting step. Must be a JSON-encoded string. See [Data Injection](#data-injection). |
77
-
|`journey-token`|`string`| — | A JWT token used for [post-qualification Journeys](./post-qualification.md). |
|`journey-id`|`string`| — |**Required.** The ID of the Journey to render. |
70
+
|`mode`|`"inline"`\|`"full-screen"`|`"full-screen"`| The display mode. `inline` renders the Journey within the page flow. `full-screen` renders it as an overlay. |
71
+
|`lang`|`"de"`\|`"en"`\|`"fr"`|`"de"`| Overrides the UI language. This affects UI labels and copy, but does not automatically translate static content configured in the Journey Builder. |
72
+
|`top-bar`|`"true"`\|`"false"`|`"true"`| Whether to show the top navigation bar. Only applies in `inline` mode — in `full-screen` mode the top bar is always visible and cannot be hidden. |
73
+
|`scroll-to-top`|`"true"`\|`"false"`|`"true"`| Whether to scroll the page to the top of the Journey when the user navigates to a new step. |
74
+
|`close-button`|`"true"`\|`"false"`|`"true"`| Whether to show the close button in the top bar. |
75
+
|`context-data`| JSON string | — | Additional contextual data passed to the Journey and included with the submission. Must be a JSON-encoded string of key-value pairs. See [Context Data](#context-data). |
76
+
|`data-injection-options`| JSON string | — | Pre-fill Journey fields and control the starting step. Must be a JSON-encoded string. See [Data Injection](#data-injection). |
77
+
|`journey-token`|`string`| — | A JWT token used for [post-qualification Journeys](./post-qualification.md). |
78
78
|`as-organization-id`|`string`| — | Organization ID to use as the Journey's organization context. Sent as the `x-epilot-org-id` header on entity requests. Useful in partner / shared-entities scenarios where the Journey needs to access data owned by a different organization. |
79
-
|`is-full-screen-entered`|`"true"`\|`"false"`|`"false"`| Controls whether a full-screen Journey is visible. Set to `"true"` to open it. Only applies when `mode` is `"full-screen"`. |
80
-
|`is-embedded`|`"true"`\|`"false"`|`"false"`| Indicates the Journey is embedded on a host app. |
81
-
|`debug`|`"true"`\|`"false"`|`"false"`| Enables debug mode for development and troubleshooting. |
79
+
|`is-full-screen-entered`|`"true"`\|`"false"`|`"false"`| Controls whether a full-screen Journey is visible. Set to `"true"` to open it. Only applies when `mode` is `"full-screen"`. |
80
+
|`is-embedded`|`"true"`\|`"false"`|`"false"`| Indicates the Journey is embedded on a host app. |
81
+
|`debug`|`"true"`\|`"false"`|`"false"`| Enables debug mode for development and troubleshooting. |
82
82
83
83
:::tip Accessible name
84
84
@@ -190,7 +190,9 @@ type DataInjectionOptions = {
190
190
* - recommended: an object keyed by stable block id -> block value
191
191
* - deprecated (legacy): an array indexed by step position, each entry keyed by block name
The recommended form keys `initialState` by **block ID**. Each entry is an object of the field values for that block. Because the state is keyed by block ID, you only list the blocks you actually want to prefill — no per-step ordering or empty `{}` placeholders are needed, and the mapping is unaffected by block renames or step reordering.
250
252
251
-
To discover the correct block IDs and field structure, open your Journey in **debug mode** from the Journey Builder and inspect the state for each step. See below:
You don't have to hand-write block IDs. The Journey Builder includes a **Data Injection (preview)** tool that lets you build the configuration visually: pick the blocks and fields to prefill, set their pre-fill values, mark blocks as read-only, choose the starting step, then copy the generated `data-injection-options` snippet straight onto your `<epilot-journey>` element.
Open your Journey in **debug mode** from the Journey Builder and inspect the state for each step. See below:
273
290
274
-
### Data Injection builder (preview)
275
-
276
-
You don't have to hand-write block IDs. The Journey Builder includes a **Data Injection (preview)** tool that lets you build the configuration visually: pick the blocks and fields to prefill, set their pre-fill values, mark blocks as read-only, choose the starting step, then copy the generated `data-injection-options` snippet straight onto your `<epilot-journey>` element.
0 commit comments