Programmatic Tracking API

Übersicht

In den allermeisten Fällen ist die API für programmatisches Tracking nicht erforderlich. Sie können Seitenaufrufe, Button-Klicks, Formularübermittlungen und E-Commerce-Events direkt erfassen, indem Sie Events bestimmten URLs zuweisen oder interaktive Elemente über Klassen ohne Entwickleraufwand kennzeichnen. Diese API ist für fortgeschrittene Anwendungsfälle konzipiert, die nicht durch Standard-Tracking abgedeckt werden können.

Wann die Programmatic API sinnvoll ist

Verwenden Sie die Programmatic Tracking API nur, wenn:

Granulare Event-Kontrolle erforderlich – Sie benötigen präzise Kontrolle darüber, wann Ereignisse gesendet werden, basierend auf komplexer Geschäftslogik, bedingten Workflows oder spezifischen Anwendungszuständen, die das automatische Tracking nicht erkennen kann.
Datenzugriff auf Anwendungsebene – Sie verfügen über Kunden- oder Produktdaten im JavaScript-Kontext Ihrer Anwendung (Benutzerobjekte, Warenkorbstatus, Sitzungsvariablen), die Sie mit Ereignissen senden möchten, ohne diese im DOM zu rendern oder entsprechenden Elementen CSS-Klassen zuzuweisen.

Die Nutzung dieser API erfordert die Einbindung von Entwicklern und JavaScript-Kenntnisse. Wenn Ihre Tracking-Anforderungen durch die Standardfunktionalität von PixelFlow erfüllt werden können, empfehlen wir, stattdessen diese Methoden zu nutzen.

Leistungsumfang dieser API

Die Programmatic Tracking API von PixelFlow stellt die Funktion trackEvent global über window.pixelFlow.trackEvent() zur Verfügung, zusammen mit Hilfsfunktionen zur Daten-Normalisierung, um sicherzustellen, dass Ihre Daten den Anforderungen der Conversions API von Meta entsprechen.

Erste Schritte

Warten Sie, bis PixelFlow initialisiert ist

Bereiten Sie Ihren Payload (benutzerdefinierte Daten) und die normalisierten Benutzerdaten vor, und rufen Sie dann die Funktion trackEvent auf:

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

Die trackEvent-Funktion

Funktionssignatur

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

Parameter

1. eventName (String, erforderlich)

Der Name des Events, das Sie tracken. Verwenden Sie die Standard-Event-Namen von Meta.

Es werden nur Standard-Meta-Events unterstützt (z. B. „Purchase“, „Lead“, „AddToCart“). Benutzerdefinierte Event-Namen werden derzeit nicht unterstützt.

2. customData (CustomData, erforderlich)

Objekt, das eventspezifische Daten wie Produktinformationen, Preise und benutzerdefinierte Eigenschaften enthält.

Häufige Eigenschaften:

{
  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
}

Übergeben Sie ein leeres Objekt {}, falls keine benutzerdefinierten Daten benötigt werden, aber übergeben Sie niemals null oder undefined.

3. userData (UserData, erforderlich)

Objekt mit Kundeninformationen für ein besseres Ad-Targeting und die Attribution.

Häufige Eigenschaften:

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

Rückgabewert

Gibt ein Promise<boolean> zurück:

true - Event erfolgreich in die Warteschlange gestellt und an Meta gesendet
false - Senden des Events fehlgeschlagen (Fehler in der Konsole prüfen)

Das Promise wird aufgelöst, sobald das Event in der Warteschlange steht, nicht erst nach Bestätigung durch die Meta-Server. Prüfen Sie den Meta Events Manager für den tatsächlichen Lieferstatus der Events.

Verfügbare Hilfsfunktionen

PixelFlow stellt Hilfsfunktionen unter window.pixelFlow.utils für die Datenvorbereitung bereit:

Funktionen zur Datennormalisierung

Verwenden Sie diese Funktionen, um Kundendaten vorzubereiten, bevor Sie diese an trackEvent übergeben:

// 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'

TypeScript-Typdefinitionen:

## 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;
  }
}

Praxisbeispiele

Beispiel 1: Benutzerdefiniertes Formular-Tracking

Szenario: Ein mehrstufiges Lead-Formular, bei dem der Abschluss erst nach einer Backend-Validierung getrackt werden soll.

// 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");
  }
}

Beispiel 2: Event einer Drittanbieter-Integration tracken

Szenario: Stripe-Zahlungswidget, bei dem das Kauf-Event nach erfolgreicher Zahlung erfasst werden muss.

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

Testen auf der Events-Seite im PixelFlow Dashboard

Überprüfen Sie immer, ob Events korrekt im PixelFlow-Event-Log erscheinen:

Senden Sie ein Event über die API
Gehen Sie zu https://dashboard.pixelflow.so/dashboard/events
Suchen Sie Ihr Event, klappen Sie die Zeile auf und prüfen Sie, ob der an Meta gesendete Event-Payload alle erwarteten Daten enthält

Programmatisch getrackte Events erscheinen neben Ihren automatischen Events im Dashboard, was die Überwachung und Fehlersuche Ihrer Implementierung erleichtert.

War das hilfreich?