Client-Side JavaScript API

SignalRelay exposes the global window.signalRelay object in the browser for custom scripts and theme developers.

---

Available Methods

signalRelay.track(eventName, customData, matchData)

Dispatches an event simultaneously to the active browser pixel and the server-side REST endpoint with a synchronized, deduplicated event_id. It sends nothing until the visitor’s consent is granted.

window.signalRelay.track('Lead', {
  content_name: 'Strategic Consultation',
  value: 150.00,
  currency: 'USD'
}, {
  email: 'client@example.com',
  phone: '+14155552671'
});

• eventName (string, required): Standard or custom event name.
• customData (object, optional): Event properties (value, currency, content_name). A numeric value with no currency is sent with your site’s default currency.
• matchData (object, optional): Customer match information (email, phone, first_name, last_name, and also city, state, zip and country). It travels once, in plain text, to your own site’s endpoint, and your server normalizes and hashes it with SHA-256 before anything reaches an advertising platform.

What the server requires

The server keeps matchData only when an enabled rule for that event declares an Advanced Matching mapping, which means at least one Match row in the Event Builder (Pro). Otherwise it is dropped silently and the event goes out without customer information. On the Free plan that is always the case.

The server also delivers an event only when an enabled rule with that event name exists. Without one, the request is refused: the browser pixel still fires, but nothing is sent server-side. A Custom JS rule (Pro) is the usual way to declare an event that only your code can recognize.

Static values always win. A rule’s Static values are enforced on the server for every event with that name, track() calls included: they replace the same keys in customData, whatever your script sent.

---

signalRelay.grantConsent()

Tells the browser that the visitor accepted marketing tracking. You need it when your consent tool does not speak the WP Consent API and you control consent through the signalrelay_consent PHP filter: as soon as that filter is hooked, the browser fails closed and sends nothing until this method is called. See WP Consent API & CMP Support.

// Call when visitor accepts cookies in a custom banner
window.signalRelay.grantConsent();

---

signalRelay.revokeConsent()

Tells the browser that the visitor withdrew consent. From that moment track() and every rule on the page stop sending events. Call it from your consent tool’s “declined” or “withdrawn” callback.

window.signalRelay.revokeConsent();

What it does not do:

• It acts on the current page only.
• It does not remove cookies that are already set (sr_uid, sr_utm).
• It does not tell a Meta pixel that is already loaded: SignalRelay does not call fbq('consent', 'revoke').
• It outranks the WP Consent API. After revokeConsent(), a later grant reported by the WP Consent API does not reopen the gate on that page; only grantConsent() does. Likewise, once grantConsent() has been called, a later withdrawal reported by the WP Consent API does not close it; call revokeConsent().

---

Limits

The tracking endpoint accepts at most 120 events per minute from one IP address. Past that, further events from that address get an HTTP 429.

To also cap the whole site, return an integer from the signalrelay_global_rate_limit filter. It is off by default and is added to the per-IP limit:

add_filter('signalrelay_global_rate_limit', function (): int {
    return 3000; // events per minute, across all visitors
});

Size it well above your site’s peak events per minute: once the site passes it, every further event gets a 429 until the minute is over, and that includes real visitors’ conversions.