@dxv-systems/conversions

DXV AI Marketing conversion tracking SDK. Captures click IDs (gclid, fbclid, utm_*) on landing and emits signed server-side conversion events to the Marketing Portal's relay endpoint.

Install

npm install @dxv-systems/conversions

Onboarding

The DXV AI Marketing operator creates a customer in the Portal and provisions you with three values:

• customerId — integer, identifies your customer record in the Portal
• relaySecret — HMAC signing key (treat as a credential)
• relayUrl — Portal endpoint base, typically https://marketing.dxvagentic.com

Store these as environment variables in your webshop's deployment.

Client side: capture click IDs on landing

In your landing-page handler (Next.js middleware, Express handler, anywhere):

import { captureClickIds, parseClickIdsCookie, serializeClickIdsCookie } from "@dxv-systems/conversions/client";

// On every request to a public page:
const url = new URL(request.url);
const captured = captureClickIds(url.searchParams);

if (captured) {
  // First-touch wins: don't overwrite an existing valid cookie.
  const existing = parseClickIdsCookie(request.cookies.get("dxv_click_ids")?.value);
  if (!existing) {
    response.cookies.set("dxv_click_ids", serializeClickIdsCookie(captured), {
      maxAge: 30 * 24 * 60 * 60, // 30 days
      httpOnly: false,           // intentionally readable from client (analytics)
      sameSite: "lax",
      secure: true,
    });
  }
}

Server side: emit purchase event

In your order-completed handler (Stripe webhook, etc.):

import { emitPurchase } from "@dxv-systems/conversions/server";
import { parseClickIdsCookie } from "@dxv-systems/conversions/client";

await emitPurchase({
  customerId: Number(process.env.DXV_CUSTOMER_ID),
  relaySecret: process.env.DXV_CONVERSIONS_RELAY_SECRET!,
  relayUrl: process.env.DXV_CONVERSIONS_RELAY_URL!,
  order: {
    id: order.id,
    totalCents: order.totalCents,
    currency: "EUR",
  },
  clickIds: parseClickIdsCookie(cookies.get("dxv_click_ids")),
  customer: {
    email: order.customer.email,    // plaintext; package hashes per Meta CAPI spec
    phone: order.customer.phone,
  },
});

emitPurchase retries 3 times on 5xx with exponential backoff. It throws typed errors:

• InvalidConfig — missing/empty relaySecret, relayUrl, or customerId. Thrown synchronously before any network call.
• RelayBadRequest — Portal returned 4xx (likely a stale relaySecret or wrong customerId). Not retried.
• RelayUnavailable — Portal unreachable after 3 attempts.

Conventions

• Money in cents (integer). The Portal validates totalCents > 0.
• Currency as ISO 4217 (e.g. EUR, USD).
• PII (email, phone) is hashed in-memory before the network call and never persisted by the Portal.
• Click-ID cookie is first-touch wins for 30 days — do not overwrite if a valid cookie already exists.

License

MIT