API de seguimiento programático

Descripción general

En la gran mayoría de los casos, no necesitas usar la API de seguimiento programático. Puedes realizar un seguimiento de las vistas de página, los clics en botones, los envíos de formularios y los eventos de comercio electrónico de forma inmediata asignando eventos a URL específicas o etiquetando elementos interactivos mediante clases, sin la intervención de ningún desarrollador. Esta API está diseñada para casos de uso avanzados que no pueden gestionarse con el seguimiento estándar.

Cuándo tiene sentido usar la API programática

Considera usar la API de seguimiento programático únicamente cuando:

Se requiere un control detallado de los eventos – Necesitas controlar con precisión cuándo se envían los eventos en función de una lógica empresarial compleja, flujos de trabajo condicionales o estados específicos de la aplicación que el seguimiento automático no puede detectar.
Acceso a datos a nivel de aplicación – Tienes datos de clientes o productos disponibles en el contexto de JavaScript de tu aplicación (objetos de usuario, estado del carrito, variables de sesión) que quieres enviar con los eventos sin representarlos en el DOM ni asignar clases CSS a los elementos correspondientes.

El uso de esta API requiere la intervención de un desarrollador y conocimientos de JavaScript. Si las necesidades de seguimiento pueden satisfacerse con la funcionalidad estándar de PixelFlow, recomendamos usar esos métodos.

Qué ofrece esta API

La API de seguimiento programático de PixelFlow expone globalmente la función trackEvent mediante window.pixelFlow.trackEvent(), junto con funciones auxiliares para normalizar datos y garantizar que cumplan los requisitos de la API de conversiones de Meta.

Primeros pasos

Esperar a que PixelFlow se inicialice

Prepara tu payload (datos personalizados) y los datos de usuario normalizados; después, llama a la función trackEvent:

// Wait for PixelFlow to initialize, then track event
const trackPurchase = async () => {
  if (
    window.pixelFlow?.trackEvent &&
    window.pixelFlow?.utils?.normalizeCustomerData
  ) {
    try {
      const normalizedCustomerData =
        await window.pixelFlow.utils.normalizeCustomerData(customerData); // normalizes data 
      window.pixelFlow.trackEvent("Purchase", payload, normalizedCustomerData);
    } catch (error) {
      console.error("PixelFlow: Error tracking Purchase event", error);
    }
  } else {
    console.warn("PixelFlow: API not ready, retrying...");
    // Retry after 1 second if not ready
    setTimeout(trackPurchase, 1000);
  }
};

La función trackEvent

Firma de la función

trackEvent(
  eventName: string,
  customData: CustomData,
  userData: UserData
): Promise<boolean>

No envíes estos campos

trackEvent acepta exactamente tres argumentos: el nombre del evento, los datos personalizados y los datos de usuario. No existe un cuarto argumento ni una opción eventID.

PixelFlow establece por sí mismo los campos indicados a continuación. No los incluyas en customData, userData ni en ningún otro lugar de la llamada:

event_id y eventID
event_time y eventTime
action_source y actionSource
fbp y fbc
external_id
client_ip_address

event_id se genera en cada llamada y se comparte entre el píxel de Meta y el evento del servidor para que Meta pueda deduplicarlos. Si el código del cliente añade su propio event_id dentro de los datos personalizados, la API devuelve HTTP 400 y no se registra nada.

Parámetros

1. eventName (string, obligatorio)

El nombre del evento cuyo seguimiento estás realizando. Usa los nombres de eventos estándar de Meta.

Solo se admiten eventos estándar de Meta (por ejemplo, "Purchase", "Lead", "AddToCart"). Los nombres de eventos personalizados no se admiten actualmente.

2. customData (CustomData, obligatorio)

Objeto que contiene datos específicos del evento, como información del producto y precios. customData solo acepta los campos indicados a continuación.

Campos aceptados:

{
  value?: number;             // Monetary value (required for Purchase, recommended for value optimization)
  currency?: string;          // ISO 4217 currency code (e.g., "USD", "EUR", "GBP")
  content_ids?: string[];     // Product SKUs or identifiers
  content_name?: string;      // Product or content name
  content_type?: 'product' | 'product_group';
  contents?: ContentItem[];   // Detailed product information
  num_items?: number;         // Quantity of items
  searchStr?: string;         // Search string (Search events only)
}

En cada elemento de contents, delivery_category solo puede ser "in_store", "curbside" o "home_delivery".

Cualquier otra propiedad no se ignora. El endpoint del evento devuelve HTTP 400 y el evento no se almacena. Esto incluye content_category: el servidor no lo acepta y, si se envía, se rechaza todo el evento.

Pasa un objeto vacío {} si no se necesitan datos personalizados, pero nunca pases null ni undefined.

3. userData (UserData, obligatorio)

Objeto que contiene información del cliente para mejorar la segmentación y la atribución de anuncios.

Propiedades comunes:

{
  em: string; // Email address (normalization required)
  ph: string; // Phone number (normalization required)
  fn: string; // First name (normalization required)
  ln: string; // Last name (normalization required)
}

Valor de retorno

Devuelve una Promise<boolean>:

true - El evento se añadió correctamente a la cola y se envió a Meta
false - No se pudo enviar el evento (comprueba la consola para ver los errores)

La promesa se resuelve después de que el evento se añade a la cola, no después de recibir la confirmación de los servidores de Meta. Consulta el Administrador de eventos de Meta para comprobar el estado real de entrega del evento.

Funciones auxiliares disponibles

PixelFlow expone funciones auxiliares en window.pixelFlow.utils para preparar datos:

Funciones de normalización de datos

Usa estas funciones para preparar los datos del cliente antes de pasarlos a trackEvent:

// Normalize entire customer data object
const normalizedData = await window.pixelFlow.utils.normalizeCustomerData({
  em: "[email protected]",
  fn: "  John  ",
  ln: "Doe",
  ph: "(555) 123-4567",
});
// Returns normalized and ready-to-use object

// Email normalization (lowercase, trim)
const normalizedEmail =
  window.pixelFlow.utils.normalizeEmail("[email protected]");
// Returns: '[email protected]'

// Name normalization (lowercase, trim)
const normalizedName = window.pixelFlow.utils.normalizeName("  John  ");
// Returns: 'john'

// Phone normalization (digits only, add country code)
const normalizedPhone = window.pixelFlow.utils.normalizePhone(
  "+1 (555) 123-4567",
  "US"
);
// Returns: '15551234567'

// Generic alphanumeric lowercase (for city, state, etc.)
const normalizedCity = window.pixelFlow.utils.normalizeAlnumLower("New York");
// Returns: 'newyork'

// Postal code normalization
const normalizedZip = window.pixelFlow.utils.normalizePostal("94103-1234");
// Returns: '94103'

// Country code normalization
const normalizedCountry =
  window.pixelFlow.utils.normalizeCountry("United States");
// Returns: 'us'

Definiciones de tipos de TypeScript:

/**
 * Content item for product details
 */
export type ContentItem = {
  /** Product ID or SKU */
  id: string;
  /** Quantity of the product */
  quantity: number;
  /** Price of the individual item */
  item_price?: number;
  /** "in_store", "curbside", or "home_delivery" */
  delivery_category?: 'in_store' | 'curbside' | 'home_delivery';
};

/**
 * CustomData type for Meta Conversions API
 * Contains event-specific data like product information and pricing.
 * Only the fields listed below are accepted. Any other property causes
 * the event endpoint to return HTTP 400 and the event is not stored.
 */
export type CustomData = {
  /** Monetary value associated with the event (required for Purchase) */
  value?: number;
  /** ISO 4217 currency code (e.g., "USD", "EUR", "GBP") */
  currency?: string;
  /** Product SKUs or identifiers */
  content_ids?: string[];
  /** Product or content name */
  content_name?: string;
  /** "product" or "product_group" */
  content_type?: 'product' | 'product_group';
  /** Array of product items with details */
  contents?: ContentItem[];
  /** Total number of items */
  num_items?: number;
  /** Search string (Search events only) */
  searchStr?: string;
};

/**
 * UserData type for Meta Conversions API
 * Customer information for better ad targeting and attribution
 * IMPORTANT: Data must be normalized before passing to trackEvent (use utils)
 * Hashing is handled automatically by the script
 */
export type UserData = {
  /**
   * Email - must be normalized (lowercase, trimmed)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "[email protected]" (normalized)
   */
  em?: string;
  /**
   * Phone - must be normalized (digits only, with country code)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "16505551212" (normalized)
   */
  ph?: string;
  /**
   * First name - must be normalized (lowercase, trimmed)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "john" (normalized)
   */
  fn?: string;
  /**
   * Last name - must be normalized (lowercase, trimmed)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "smith" (normalized)
   */
  ln?: string;
  /**
   * Client User Agent
   * Automatically captured by PixelFlow if not provided
   */
  client_user_agent?: string;
};

/**
 * PixelFlow global type for window.pixelFlow
 */
export type PixelFlow = {
  version: string;
  initialized: boolean;
  trackEvent: (eventName: string, customData: CustomData, userData: UserData) => Promise<boolean>;
  utils: {
    /** Normalize entire customer data object (required before trackEvent, hashing automatic) */
    normalizeCustomerData: (data: Partial<UserData>) => Promise<Partial<UserData>>;
    /** Normalize email: lowercase, trim whitespace */
    normalizeEmail: (email: string) => string;
    /** Normalize name: lowercase, trim whitespace */
    normalizeName: (name: string) => string;
    /** Normalize phone: digits only, add country code if needed */
    normalizePhone: (phone: string, countryCode?: string) => string;
    /** Normalize to alphanumeric lowercase */
    normalizeAlnumLower: (value: string) => string;
    /** Normalize postal code: remove spaces and dashes */
    normalizePostal: (postal: string) => string;
    /** Normalize country: 2-letter ISO code lowercase */
    normalizeCountry: (country: string) => string;
  };
};

declare global {
  interface Window {
    pixelFlow?: PixelFlow;
  }
}

Ejemplos del mundo real

Ejemplo 1: realizar un seguimiento del envío de un formulario personalizado

Escenario: Formulario de clientes potenciales de varios pasos en el que quieres realizar un seguimiento de la finalización solo después de la validación del backend.

// After form validation succeeds on server
async function onFormValidationSuccess(formData) {
  // Prepare user data from form
  const userData = await window.pixelFlow.utils.normalizeCustomerData({
    em: formData.email, 
    fn: formData.firstName, 
    ln: formData.lastName,
    ph: formData.phone,
  });

  // Prepare custom data
  const customData = {
    value: 500, // Estimated lead value
    currency: "USD",
  };

  // Track the lead event
  const success = await window.pixelFlow.trackEvent(
    "Lead",
    customData,
    userData
  );

  if (success) {
    console.log("Lead tracked successfully");
  } else {
    console.error("Failed to track lead");
  }
}

Ejemplo 2: compras con Stripe

Para Stripe Checkout, no envíes Purchase mediante trackEvent. En el panel de PixelFlow, añade un activador Purchase y selecciona Stripe Checkout. PixelFlow recibe el pago de Stripe, incluidos el correo electrónico, el teléfono y el nombre, y después compara el ID de sesión de Stripe Checkout con el de la URL de la página de confirmación. Esa URL de confirmación ya debe incluir el ID de sesión.

No actives también Purchase desde tu propio código, ya que el mismo pedido podría enviarse dos veces.

Probar en la página de eventos del panel de PixelFlow

Verifica siempre que los eventos aparezcan correctamente en el registro de eventos de PixelFlow:

Envía un evento mediante la API
Ve a https://dashboard.pixelflow.so/dashboard/events
Busca tu evento, expande la fila del evento y verifica que el payload enviado a Meta contenga todos los datos esperados

Los eventos cuyo seguimiento se realiza mediante programación aparecerán junto con tus eventos automáticos en el panel, lo que facilita la supervisión y la depuración de tu implementación.

Si aparece una vista de página, pero no aparece el Lead, AddToCart o Purchase esperado, comprueba la pestaña de red del navegador para ver el POST del evento. Una respuesta HTTP 400 significa que el payload contiene un campo que PixelFlow no acepta. Elimina ese campo. No añadas más campos de Meta para intentar solucionarlo.

¿Te fue útil?