Track events and consent

The Signals browser API is available as window.signalq after you install the generated v3 pixel. Calls made before the asynchronous script loads remain in the queue. Connect signalq to your consent-management platform. Send the current advertising consent state after initialization and whenever the visitor changes it.

await signalq("consent", {
  consent_basis: "consent",
  consent: {
    ad_storage: "granted",
    ad_user_data: "granted",
    ad_personalization: "granted",
    captured_at: new Date().toISOString(),
    source: "your_cmp"
  }
});

// If the visitor later withdraws consent:
await signalq("consent", {
  consent_basis: "consent",
  withdrawn: true
});

Each permission accepts granted, denied, or unknown. Missing or unrecognized permissions remain unknown; PlainRouter never upgrades them to a grant. You can provide one or more supported consent adapters:

Input	Use
`consent`	Send PlainRouter’s explicit three-permission snapshot.
`consent_mode`	Map Google Consent Mode v2 fields.
`tcf`	Map a TCF v2 string and optional capture time.

When you provide more than one adapter, their derived permission states must agree.

Do not infer consent. Leave each permission unknown until your consent-management platform has an explicit choice.

PlainRouter sends browser events only when all three permissions are granted. Granting ad_storage alone can permit local visitor state, but no event is transmitted while either downstream advertising permission is denied or unknown. A complete grant creates or refreshes the first-party identifiers used for session joins and eligible destination delivery. Denied storage, malformed input, or explicit withdrawal clears PlainRouter’s visitor and click identifiers. Send the latest structured state whenever the visitor’s choice changes. On a returning page, initialization stays fail-closed while your consent platform restores its decision: PlainRouter neither reads identifiers nor sends measurement during that undecided period. It also does not erase identifiers left by the visitor’s previous grant merely because the consent platform has not answered yet. An explicit denial, malformed consent update, or withdrawal still clears them.

Track an event

Call track with an event name and an optional payload:

const eventId = await signalq("track", "purchase", {
  value: "49.00",
  currency: "EUR",
  order_id: "ORDER-1042",
  num_items: 2
});

The promise resolves to the collector-accepted event ID. It resolves to null if collection fails after one retry.

Send monetary value as a decimal string, such as "49.00". This avoids floating-point ambiguity.

Standard event names

Common names are normalized to Meta’s standard spelling. For example, page_view becomes PageView and initiate_checkout becomes InitiateCheckout. Frequently used standard events include:

PageView
ViewContent
Search
AddToCart
AddToWishlist
InitiateCheckout
AddPaymentInfo
Purchase
Lead
CompleteRegistration
Contact
Schedule
Subscribe

Custom event names are trimmed and otherwise preserved.

Payload fields

These convenience fields move into the event’s value data automatically:

Field	Purpose	Example
`value`	Monetary value as a decimal string.	`"49.00"`
`currency`	ISO 4217 currency code.	`"EUR"`
`order_id`	Your unique order or transaction reference.	`"ORDER-1042"`
`contents`	Products or items associated with the event.	`[{ id: "SKU-1", quantity: 2 }]`
`num_items`	Total item count.	`2`

You can also provide a value_data object directly. Other custom fields remain on the event and are available to supported destinations.

Identify a consenting visitor

Call identify only after your consent policy permits advertising identity use:

const identified = await signalq("identify", {
  email: " Buyer@Example.com ",
  phone: "+358 (40) 123-4567"
});

The browser normalizes and SHA-256 hashes the values before sending them. PlainRouter never sends the raw email or phone in the identity request.

Email is trimmed and lowercased.
International phone numbers must start with + and include 8–15 digits after normalization.
Finnish local numbers require defaultPhoneRegion: "FI" in the initialization configuration.
Identification returns false on an insecure page where browser cryptography is unavailable.

<script>
  window.signalq = window.signalq || function () {
    (window.signalq.q = window.signalq.q || []).push(arguments);
  };
  signalq("init", {
    key: "YOUR_PUBLISHABLE_KEY",
    defaultPhoneRegion: "FI"
  });
</script>

Read the visitor ID

getVisitorId returns the current first-party visitor ID after consent is granted. It returns null while consent is pending or denied.

const visitorId = signalq("getVisitorId");

One use is attaching the value to a checkout session so a later server webhook can join the purchase to the browser visit:

await fetch("/create-checkout-session", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ visitor_id: signalq("getVisitorId") })
});

Your server must copy the value into the payment or checkout metadata used by its integration.

Verify Stripe Checkout settlement

If PlainRouter is configured to receive Stripe webhooks for your Signal, copy the browser visitor ID into the Checkout Session’s metadata.visitor_id. This lets the settled server-side purchase join the consenting browser visit. Configure the Stripe webhook endpoint to receive:

checkout.session.completed
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
refund.created and charge.refunded when you track refunds

PlainRouter creates Stripe Checkout revenue only after Stripe confirms an exact payment_status of paid:

Stripe state	Signals result
`checkout.session.completed` with `payment_status=paid`	Creates one canonical `Purchase`.
`checkout.session.completed` with `payment_status=unpaid`	Records no `Purchase` and waits for asynchronous success.
`checkout.session.async_payment_succeeded` with `payment_status=paid`	Creates the canonical `Purchase` at the asynchronous settlement time.
`checkout.session.async_payment_failed`	Creates no `Purchase` or `Refund`.
`payment_status=no_payment_required`	Creates no revenue event.
Missing, unknown, or malformed payment status	Fails closed and creates no `Purchase`.

Duplicate or out-of-order paid webhooks for the same Checkout Session converge on one Purchase. PlainRouter uses the settlement-confirming webhook time as the event time. Until settlement is confirmed, the Checkout Session does not enter Signals rollups or Meta delivery. Stripe refund webhooks create idempotent custom Refund events with a negative refunded value. PlainRouter links the refund to its known purchase when the order lineage is available.

Reliability behavior

Event requests use browser keepalive where available.
A granted event still in flight during pagehide is also sent as a text beacon.
Network failures and 503 responses receive one retry.
The snippet captures supported landing click IDs in memory and persists them only after consent is granted.
First-party browser identifiers can still have shorter lifetimes when a browser applies its own storage restrictions.

Avoid duplicate Meta events

After you connect Meta, continue to track through signalq. The managed browser Pixel and PlainRouter server delivery share one event ID. Remove other Pixel or CAPI integrations that send the same event to the same dataset after you confirm the managed flow is working.

Get started

Signals

Launcher

Actions

Reference

Track events and consent

Track an event

Standard event names

Payload fields

Identify a consenting visitor

Read the visitor ID

Verify Stripe Checkout settlement

Reliability behavior

Avoid duplicate Meta events

​Set consent

​Track an event

​Standard event names

​Payload fields

​Identify a consenting visitor

​Read the visitor ID

​Verify Stripe Checkout settlement

​Reliability behavior

​Avoid duplicate Meta events

Set consent

Track an event

Standard event names

Payload fields

Identify a consenting visitor

Read the visitor ID

Verify Stripe Checkout settlement

Reliability behavior

Avoid duplicate Meta events