XeniaXenia Docs

SDK reference

PreviousNext

Every entry point, function, hook and helper in @xenia-martech/sdk-js.

The SDK is fully typed. Types can be imported from any entry point.

import type { XeniaConfig, TrackOptions, WebhookResponse, XeniaAction } from "@xenia-martech/sdk-js";

Browser client

@xenia-martech/sdk-js/client, no framework dependency.

createXeniaClient(config) returns a XeniaClient:

MethodReturnsNotes
init() / destroy()Start identity and auto-tracking, or tear them down
track(eventName, props?, opts?)opts.trigger, opts.eventId, opts.identity, opts.context. See Events
identify(visitorId, { customerId?, email? }?)Sets the visitor id and links it to a customer
consent(state){ analytics, marketing, personalization }
setJourneyId(id)Overrides the journey taken from utm_id
request(triggerId, data?, { apply?, method? })WebhookResponseCalls a webhook trigger and applies the reply's actions
getResponse(key)WebhookResponseThe last saved reply
resolve(contentKey, { data?, locale?, merge? })ResolveResultRequires a token
resolveBatch(items, opts?)ResolveBatchResult[]Up to 50 keys. Requires a token
submitWidgetForm(formSubmit, fields, opts?)WidgetSubmitResponseSubmits a widget's captured fields
swapContent(target, { html? | text? })Replaces an element's content
hideContent(target) / showContent(target)Hides or shows an element
applyActions(actions)Applies a set of actions yourself
on(event, callback)"event", "response", "actions", "error", "identify"

The client also exposes api, identity (for example xenia.identity.getDeviceId()) and responses.

Standalone helpers, usable without a client: swapContent, hideContent, showContent, resolveTarget, parseDataAttribute, readSlotMeta, parseActions, spliceSlots, extractContentSwaps, generateUlid.

React

@xenia-martech/sdk-js/client/react, requires React 18 or later. Re-exports everything from /client.

ExportReturns
<XeniaProvider {...config} client?>Creates one client, or reuses client
useXenia()The XeniaClient
useTrack()(eventName, props?, opts?) => void
useWebhook(triggerId){ send, response, isLoading, error }
useXeniaResponse(key)The last saved reply for a key
usePersonalizationResolve(contentKey, opts?){ data, isLoading, error }
usePersonalizationResolveSlots(items, opts?){ data, isLoading, error }
usePersonalization(triggerId, data?){ data, isLoading, error }
usePersonalizationSlots(triggerId, slots, data?){ data, isLoading, error }
<XeniaTrack event on? props? as?>Tracks on click, view or mount
<XeniaMessage actions={[…]} />Applies actions on mount
reactMessageComponent(Component)A messageComponent from a React component

Server

@xenia-martech/sdk-js/server, for Node, SSR and React Server Components.

createXeniaServer(config) returns a XeniaServer:

MethodReturnsNotes
track(eventName, opts?)AnalyticsIngestResponseSent immediately. Pass consent on every call
webhook(triggerId, data?, opts?)WebhookResponseopts.identity, opts.context, opts.fallback
resolve(contentKey, opts?)ResolveResultopts.fallback returns it instead of throwing
resolveBatch(items, opts?)ResolveBatchResult[]Same
identify(body)IdentifyResponseLinks the bound visitor to a customer

Tokens and cookies:

ExportNotes
createTokenRoute({ sdkToken })A route handler that serves short-lived tokens to the browser
refreshSdkToken(opts)The same exchange, for any HTTP handler. Returns { token, expiresAt }
getVisitorId(cookieHeader, prefix?)Reads the browser's visitor id
getConsent(cookieHeader, prefix?)Reads the browser's consent
parseCookies(header)Parses a Cookie header
visitorCookieName(prefix?) / consentCookieName(prefix?)Cookie names for a custom prefix
VISITOR_COOKIE / CONSENT_COOKIE"xenia_vid" and "xenia_consent", the default names

Next.js

@xenia-martech/sdk-js/next, for the App Router in Next.js 15 and later.

ExportNotes
xeniaProxy(request, { headers?, prefix?, cookie? })Use in proxy.ts. Sets the visitor cookie and stamps the page URL on the request
xeniaServerFromNext(config)A XeniaServer bound to this request's visitor and page
consentFromNext(prefix?)This request's consent

Core

@xenia-martech/sdk-js, works anywhere. Rarely needed directly.

ExportNotes
contextFromUrl(url, referrer?)Page context for a server client: path, query, url, referrer, UTMs
consentCookie(state, prefix?)The consent cookie string, for your own banner
generateUlid()A sortable unique id, handy as an eventId
toEventId(raw)Folds any key into a stable 26 character event id
parseActions(body)Reads xeniaActions from a reply
spliceSlots(slots, swaps) / extractContentSwaps(body)Applies xeniaContentSwaps yourself
HttpError, CircuitOpenErrorErrors you can catch
isBrowser()Guards code that must not run during SSR
XeniaApiThe low-level endpoint client