From 414d1e8d9cb07bef56918746455ca8817b530575 Mon Sep 17 00:00:00 2001 From: Adeola Adeyemo Date: Fri, 31 Jul 2026 09:00:48 +0000 Subject: [PATCH 1/2] docs(journeys): clarify how host page query params reach journey_context Spell out that query params do not have to be declared as context parameters in the Journey Builder, list the parameter names the Journey app reserves for itself, and point integrators at the console log they can use to verify what an embedding actually passed. Co-authored-by: Claude --- docs/journeys/sdk.md | 2 +- docs/journeys/web-components.md | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/journeys/sdk.md b/docs/journeys/sdk.md index 2166b67..c46b437 100644 --- a/docs/journeys/sdk.md +++ b/docs/journeys/sdk.md @@ -481,7 +481,7 @@ $epilot .append('#embed-target') ``` -The Journey also automatically picks up URL search parameters from the host page. Values passed via `.contextData()` take precedence when keys overlap. +The Journey also automatically picks up URL search parameters from the host page, whether or not they are declared as context parameters in the Journey Builder, and includes them in the submission's `journey_context`. Values passed via `.contextData()` take precedence when keys overlap. Parameters reserved by the Journey app (`journeyId`, `journeyToken`, `previewId`, `nonce`, `asOrganizationId`, `embedSource`, `dataInjectionOptions`, `mode`, `lang`, `topBar`, `isEmbedded`, `debug`, `preview`) are consumed by the app instead of being forwarded. ## Data Injection diff --git a/docs/journeys/web-components.md b/docs/journeys/web-components.md index 4ba792a..f3bd7f1 100644 --- a/docs/journeys/web-components.md +++ b/docs/journeys/web-components.md @@ -166,6 +166,12 @@ Numeric values are coerced to strings internally. The Journey also automatically picks up **URL search query parameters** from the host page and includes them as context data. For example, if the page URL is `https://example.com/energy?utm_source=google&campaign=summer`, the `utm_source` and `campaign` values will be included in the context data automatically. Values passed explicitly via the `context-data` attribute take precedence over query parameters when keys overlap. +Query parameters do **not** need to be declared as context parameters in the Journey Builder to be picked up — any parameter of the host page URL ends up in the submission's `journey_context`. The exception are parameters reserved by the Journey app itself, which are consumed instead of being forwarded: `journeyId`, `journeyToken`, `previewId`, `nonce`, `asOrganizationId`, `embedSource`, `dataInjectionOptions`, `mode`, `lang`, `topBar`, `isEmbedded`, `debug` and `preview`. Pick a distinct name for tracking parameters to avoid the collision. + +:::tip +Open the browser console on the embedding page to verify what the Journey received. On initialization it logs `Initialized or updated Journey with id: with following parameters`, including the resolved context data and query parameters. +::: + ## Data Injection Data injection allows you to pre-fill Journey fields with data and optionally start from a specific step. This is useful when your website has already collected some information (e.g. a product selection or address) and you want to carry it into the Journey. From 03bc83d61264a723bf56fa8e6ca69968df1bd4b2 Mon Sep 17 00:00:00 2001 From: Adeola Adeyemo Date: Fri, 31 Jul 2026 09:17:23 +0000 Subject: [PATCH 2/2] docs(journeys): document context data behaviour for iframe embeds The iframe embedding page had no Context Data section at all, even though the same merge rules and reserved parameter names apply there. Add one, and record the fix in the changelog of all three embedding pages. Co-authored-by: Claude --- docs/journeys/embedding.md | 27 +++++++++++++++++++++++++++ docs/journeys/sdk.md | 4 ++++ docs/journeys/web-components.md | 5 +++++ 3 files changed, 36 insertions(+) diff --git a/docs/journeys/embedding.md b/docs/journeys/embedding.md index 4bdd25d..76aea4b 100644 --- a/docs/journeys/embedding.md +++ b/docs/journeys/embedding.md @@ -327,6 +327,28 @@ if (__epilot.isInitialized('123') === true) { } ``` +## Context Data + +Pass `contextData` in `__epilot.init()` to attach additional key-value pairs to the Journey. The data is included with the submission's `journey_context` and can be used for tracking, attribution, or pre-configuring behavior. + +```typescript title="Passing context data" +__epilot.init([ + { + journeyId: '123', + mode: 'inline', + contextData: { source: 'landing-page', campaign: 'summer-2025' } + } +]) +``` + +The Journey also automatically picks up the **URL search query parameters** of the embedding page and includes them as context data. For example, on `https://example.com/energy?utm_source=google`, `utm_source` ends up in `journey_context` without any extra configuration. Values passed explicitly via `contextData` take precedence over query parameters when keys overlap. + +Query parameters do **not** need to be declared as context parameters in the Journey Builder to be picked up. The exception are parameters reserved by the Journey app itself, which are consumed instead of being forwarded: `journeyId`, `journeyToken`, `previewId`, `nonce`, `asOrganizationId`, `embedSource`, `dataInjectionOptions`, `mode`, `lang`, `topBar`, `isEmbedded`, `debug` and `preview`. Pick a distinct name for tracking parameters to avoid the collision. + +:::tip +Open the browser console to verify what the Journey received. On initialization it logs `Initialized or updated Journey with id: with following parameters`, including the resolved context data and query parameters. +::: + ## Scenarios ### Full-Screen @@ -424,6 +446,11 @@ See the [SDK documentation](/docs/journeys/sdk) for setup, the full API referenc ## Changelog +### 2026-07-31 + +- Fixed: passing `contextData` no longer discards the embedding page's URL query parameters. Both are now merged into `journey_context`, with `contextData` taking precedence only on overlapping keys. Previously any `contextData` value replaced the query parameters that were not declared as context parameters in the Journey Builder. +- Added a new [Context Data](#context-data) section documenting how `contextData` and the page's query parameters reach the submission, and which parameter names the Journey app reserves for itself. + ### 2026-06-11 - Data injection now documents stable **block IDs** as the recommended form: `initialState` keyed by block ID, `initialStepId` for the starting step, and `blocksDisplaySettings` targeting blocks by `blockId`. Block IDs are unique journey-wide and resilient to block renames and step reordering. The legacy step-index + block-name forms remain supported but are deprecated. diff --git a/docs/journeys/sdk.md b/docs/journeys/sdk.md index c46b437..7dd3c78 100644 --- a/docs/journeys/sdk.md +++ b/docs/journeys/sdk.md @@ -800,6 +800,10 @@ Some `OptionsInit` fields from the legacy script have no SDK equivalent: ## Changelog +### 2026-07-31 + +- Fixed: `.contextData()` no longer discards the host page's URL query parameters. Both are merged into `journey_context`, with `.contextData()` taking precedence only on overlapping keys. The `.asWebComponent()` backend was affected worst, losing every query parameter; `.asIframe()` kept the ones declared as context parameters in the Journey Builder but lost the rest. + ### 2026-06-11 - Data injection now documents stable **block IDs** as the recommended form: `.dataInjectionOptions()` accepts `initialState` keyed by block ID, `initialStepId` for the starting step, and `blocksDisplaySettings` targeting blocks by `blockId`. Block IDs are unique journey-wide and resilient to block renames and step reordering. The legacy step-index + block-name forms remain supported but are deprecated. diff --git a/docs/journeys/web-components.md b/docs/journeys/web-components.md index f3bd7f1..da102b3 100644 --- a/docs/journeys/web-components.md +++ b/docs/journeys/web-components.md @@ -500,6 +500,11 @@ The attribute names on the Web Component map directly to the options you previou ## Changelog +### 2026-07-31 + +- Fixed: setting the `context-data` attribute no longer discards the host page's URL query parameters. Both are merged into `journey_context`, with `context-data` taking precedence only on overlapping keys. Previously any `context-data` value dropped every query parameter, since the attribute is the web component's only context source. +- The resolved configuration is now logged to the browser console on initialization, matching iframe embeds. Invalid attributes are reported there too, and no longer prevent the element from rendering. + ### 2026-06-11 - Data injection now documents stable **block IDs** as the recommended form: `initialState` is keyed by block ID, `initialStepId` selects the starting step, and `blocksDisplaySettings` targets blocks by `blockId`. Block IDs are unique journey-wide and resilient to block renames and step reordering. The legacy step-index + block-name forms remain supported but are deprecated.