SPA and router modes
Configure Apex SDK route observation, DOM re-evaluation, and manual activation for dynamic storefronts.
The SDK observes route and DOM changes so assignments stay correct on headless, single-page, and app-router storefronts. Keep the defaults unless you have a specific framework conflict.
Router resolution
The SDK resolves platform and router mode in this order:
| Setting | Behavior |
|---|---|
platformHint | Explicit platform wins unless it is "auto". |
profile.platform | Server-delivered platform profile is used when no explicit platform hint is set. |
| Auto detection | Detects Shopify runtime, Shopware markers, SPA root markers, or the Navigation API. |
spa.routerMode | Overrides top-level routerMode. |
routerMode: "auto" | Uses the Navigation API when available, otherwise history observation. Shopify can resolve to "none" unless DOM change mode is enabled. |
Common SPA setup
ts
import { init } from "@drip-apex/sdk";
init({
shopId: "demo-shop",
endpoint: "https://events.drip-apex.com",
platformHint: "spa",
spa: {
routerMode: "auto",
activationMode: "observer",
domChangeTrigger: true,
debounceMs: 250
}
});Use this for Next.js, Hydrogen, Remix, Nuxt, SvelteKit, Vue, or React apps where URL changes do not reload the page.
SpaSettings
| Field | Type | Default | When to use |
|---|---|---|---|
routerMode | "auto", "history", "navigation", or "none" | "auto" | Choose how route changes are detected. |
activationMode | "auto", "observer", or "manual" | "observer" | Choose mutation application behavior. "manual" applies immediately without wait observers. |
reinitOnly | boolean | false | Disable automatic route observation and rely on manual reInit() calls. |
domChangeTrigger | boolean | Auto-enabled for URL change, DOM change, and platformHint: "spa" | Re-evaluate when the DOM changes after route or component updates. |
debounceMs | number | 250 for DOM observation and post-reveal reassertion | Tune dynamic DOM re-evaluation frequency. |
allowIframes | boolean | false | Allow SDK initialization inside iframes. |
Page trigger modes
pageTrigger.defaultMode controls initial activation:
| Mode | Behavior |
|---|---|
direct | Default. Evaluate and apply on initialization. |
url_change | Use URL-change behavior and route observation. |
dom_change | Enable DOM-change activation. |
manual | Skip initial assignment application until manual trigger logic activates. |
If pageTrigger.defaultMode is "manual" or spa.reinitOnly is true, the SDK does not apply initial assignments automatically. Call reInit(true) after your app has rendered the relevant DOM.
Manual route recheck
ts
import { reInit, trackStep } from "@drip-apex/sdk";
router.events.on("routeChangeComplete", () => {
reInit(true);
trackStep("route_rendered", { oncePerSession: false });
});