API de JavaScript del Cliente

SignalRelay expone el objeto global window.signalRelay en el navegador para desarrolladores y scripts personalizados.

---

Métodos Disponibles

signalRelay.track(eventName, customData, matchData)

Dispara un evento que será sincronizado simultáneamente en el píxel del navegador y en el endpoint REST server-side con su event_id único deduplicado. No envía nada hasta que el visitante otorga su consentimiento.

window.signalRelay.track('Lead', {
  content_name: 'Consultoría Estratégica',
  value: 150.00,
  currency: 'USD'
}, {
  email: 'usuario@ejemplo.com',
  phone: '+5491122334455'
});

• eventName (string, requerido): Nombre del evento estándar o personalizado.
• customData (object, opcional): Parámetros del evento (value, currency, etc.). Un value numérico sin currency se envía con la moneda por defecto de tu sitio.
• matchData (object, opcional): Información del cliente para el cálculo del Event Match Quality (email, phone, first_name, last_name, y también city, state, zip y country). Viaja una sola vez, en texto plano, al endpoint de tu propio sitio, y tu servidor la normaliza y la hashea con SHA-256 antes de que llegue a cualquier plataforma publicitaria.

Lo que exige el servidor

El servidor conserva matchData solo si una regla activa para ese evento declara un mapeo de Advanced Matching, es decir, al menos una fila Match en el Event Builder (Pro). Si no, se descarta en silencio y el evento sale sin información del cliente. En el plan Free siempre ocurre esto.

Además, el servidor entrega un evento únicamente si existe una regla activa con ese nombre de evento. Sin ella, la solicitud se rechaza: el píxel del navegador igual dispara, pero no se envía nada server-side. Una regla Custom JS (Pro) es la forma habitual de declarar un evento que solo tu código puede reconocer.

Los valores Static siempre ganan. Los valores Static de una regla se aplican en el servidor a todos los eventos con ese nombre, incluidas las llamadas a track(): reemplazan las mismas claves de customData, sin importar lo que haya enviado tu script.

---

signalRelay.grantConsent()

Le avisa al navegador que el visitante aceptó el seguimiento de marketing. Lo necesitás cuando tu herramienta de consentimiento no habla la WP Consent API y controlás el consentimiento con el filtro de PHP signalrelay_consent: apenas ese filtro tiene un hook, el navegador falla cerrado y no envía nada hasta que se llama a este método. Ver Compatible con WP Consent API y CMPs.

// Llamar cuando el visitante acepta las cookies en un banner personalizado
window.signalRelay.grantConsent();

---

signalRelay.revokeConsent()

Le avisa al navegador que el visitante retiró su consentimiento. Desde ese momento, track() y todas las reglas de la página dejan de enviar eventos. Llamalo desde el callback de “rechazado” o “retirado” de tu herramienta de consentimiento.

window.signalRelay.revokeConsent();

Lo que no hace:

• Actúa solo sobre la página actual.
• No elimina las cookies que ya están guardadas (sr_uid, sr_utm).
• No le avisa a un píxel de Meta que ya está cargado: SignalRelay no llama a fbq('consent', 'revoke').
• Tiene prioridad sobre la WP Consent API. Después de revokeConsent(), un nuevo consentimiento informado por la WP Consent API no reabre la puerta en esa página; solo lo hace grantConsent(). Del mismo modo, una vez que se llamó a grantConsent(), un retiro posterior informado por la WP Consent API no la cierra; hay que llamar a revokeConsent().

---

Límites

El endpoint de tracking acepta como máximo 120 eventos por minuto desde una misma dirección IP. Pasado ese tope, los eventos siguientes de esa dirección reciben un HTTP 429.

Para limitar también el sitio completo, devolvé un entero desde el filtro signalrelay_global_rate_limit. Viene desactivado por defecto y se suma al límite por IP:

add_filter('signalrelay_global_rate_limit', function (): int {
    return 3000; // eventos por minuto, entre todos los visitantes
});

Elegí un valor bien por encima del pico de eventos por minuto de tu sitio: cuando el sitio lo supera, cada evento siguiente recibe un 429 hasta que termina el minuto, y eso incluye las conversiones de visitantes reales.