Clarify how host page query params reach journey_context

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: <journey-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.

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
 
@@ -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.

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: <journey-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.
@@ -494,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.