API de Seguimiento Programático

Descripción general

En la gran mayoría de los casos, no es necesario utilizar la API de Seguimiento Programático. Puede realizar el seguimiento de visitas a páginas, clics en botones, envíos de formularios y eventos de comercio electrónico de forma predeterminada, asignando eventos a URLs específicas o etiquetando elementos interactivos mediante clases sin necesidad de intervención de un desarrollador. Esta API está diseñada para casos de uso avanzados que no pueden ser gestionados por el seguimiento estándar.

Cuándo tiene sentido usar la API Programática

Considere usar la API de Seguimiento Programático solo cuando:

Requiere Control Granular de Eventos – Necesita un control preciso sobre cuándo se envían los eventos basándose en una lógica de negocio 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 – Dispone de datos de clientes o productos en el contexto de JavaScript de su aplicación (objetos de usuario, estado del carrito, variables de sesión) que desea enviar con los eventos sin tener que renderizarlos 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 sus necesidades de seguimiento pueden satisfacerse con la funcionalidad estándar de PixelFlow, le recomendamos utilizar esos métodos en su lugar.

Qué proporciona esta API

La API de Seguimiento Programático de PixelFlow expone la función trackEvent de forma global a través de window.pixelFlow.trackEvent(), junto con funciones de utilidad para la normalización de datos para asegurar que su información cumpla con los requisitos de la API de Conversiones de Meta.

Primeros pasos

Espere hasta que PixelFlow se inicialice

Prepare su carga útil (datos personalizados) y los datos de usuario normalizados, luego llame 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>

Parámetros

1. eventName (string, requerido)

El nombre del evento que está rastreando. Utilice 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 en este momento.

2. customData (CustomData, requerido)

Objeto que contiene datos específicos del evento, como información del producto, precios y propiedades personalizadas.

Propiedades comunes:

{
  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: string;       // "product" or "product_group"
  contents: ContentItem[];    // Detailed product information
  num_items: number;          // Quantity of items
}

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

3. userData (UserData, requerido)

Objeto que contiene información del cliente para una mejor segmentación publicitaria y atribución.

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 - Evento puesto en cola y enviado a Meta con éxito
false - Error al enviar el evento (consulte la consola para ver los errores)

La promesa se resuelve después de que el evento se pone en cola, no después de la confirmación de los servidores de Meta. Consulte el Administrador de Eventos de Meta para conocer el estado real de entrega de los eventos.

Funciones de utilidad disponibles

PixelFlow expone funciones de utilidad en window.pixelFlow.utils para el procesamiento de datos:

Funciones de Normalización de Datos

Utilice 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:

## TypeScript Type Definitions

/**
 * 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;
};

/**
 * CustomData type for Meta Conversions API
 * Contains event-specific data like product information and pricing
 * @see https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/custom-data
 */
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 category */
  content_category?: 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;
  /** Custom parameters - allows additional properties */
  [key: string]: any;
};

/**
 * 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
 * @see https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
 */
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: Seguimiento de envío de formulario personalizado

Escenario: Formulario de clientes potenciales de varios pasos donde desea realizar el 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: Seguimiento de evento de integración con terceros

Escenario: Widget de pago de Stripe donde necesita rastrear el evento de compra tras un pago exitoso.

// Stripe checkout success handler
stripe.on("checkout.session.completed", async (session) => {
  // Extract purchase data from Stripe session
  const purchaseData = {
    value: session.amount_total / 100, // Convert cents to dollars
    currency: session.currency,
    contents: session.line_items.data.map((item) => ({
      id: item.price.product,
      quantity: item.quantity,
      item_price: item.price.unit_amount / 100,
    })),
    num_items: session.line_items.data.reduce(
      (sum, item) => sum + item.quantity,
      0
    ),
  };

  // Extract customer data
  const userData = await window.pixelFlow.utils.normalizeCustomerData({
    em: session.customer_email,
    fn: session.customer_details.name?.split(" ")[0],
    ln: session.customer_details.name?.split(" ").slice(1).join(" "),
  });

  // Track purchase event
  await window.pixelFlow.trackEvent("Purchase", purchaseData, userData);
});

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

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

Envíe un evento utilizando la API
Vaya a https://dashboard.pixelflow.so/dashboard/events
Busque su evento, expanda la fila del evento y verifique que la carga útil del evento enviada a Meta contenga todos los datos esperados

Los eventos rastreados mediante programación aparecerán junto con sus eventos automáticos en el panel de control, lo que facilita la monitorización y depuración de su implementación.

¿Te fue útil?