Programmatische Tracking-API

Übersicht

In den allermeisten Fällen müssen Sie die programmatische Tracking-API nicht verwenden. Sie können Seitenaufrufe, Klicks auf Schaltflächen, Formularübermittlungen und E-Commerce-Ereignisse direkt nach der Installation tracken, indem Sie Ereignisse bestimmten URLs zuweisen oder interaktive Elemente über Klassen markieren, ohne dass ein Entwickler eingreifen muss. Diese API ist für fortgeschrittene Anwendungsfälle konzipiert, die nicht durch Standard-Tracking abgedeckt werden können.

Wann die programmatische API sinnvoll ist

Erwägen Sie die Verwendung der programmatischen Tracking-API nur, wenn:

Granulare Ereignissteuerung erforderlich – Sie benötigen eine 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 sie im DOM zu rendern und entsprechenden Elementen CSS-Klassen zuzuweisen.

Die Verwendung 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 verwenden.

Was diese API bietet

Die programmatische Tracking-API von PixelFlow macht die Funktion trackEvent global über window.pixelFlow.trackEvent() verfügbar, zusammen mit Hilfsfunktionen zur Datennormalisierung, 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 Funktion trackEvent

Funktionssignatur

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

Parameter

1. eventName (string, erforderlich)

Der Name des Ereignisses, das Sie tracken. Verwenden Sie die Standard-Ereignisnamen von Meta.

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

2. customData (CustomData, erforderlich)

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

Gängige 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 {}, wenn keine benutzerdefinierten Daten benötigt werden, aber übergeben Sie niemals null oder undefined.

3. userData (UserData, erforderlich)

Objekt mit Kundeninformationen für bessere Werbeausrichtung und Attribution.

Gängige 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 - Ereignis erfolgreich in die Warteschlange gestellt und an Meta gesendet
false - Senden des Ereignisses fehlgeschlagen (Fehler in der Konsole prüfen)

Das Promise wird aufgelöst, nachdem das Ereignis in die Warteschlange gestellt wurde, nicht erst nach der Bestätigung durch die Server von Meta. Überprüfen Sie den Meta Events Manager auf den tatsächlichen Status der Ereignisübermittlung.

Verfügbare Hilfsfunktionen

PixelFlow stellt Hilfsfunktionen unter window.pixelFlow.utils zur Datenvorbereitung bereit:

Datennormalisierungsfunktionen

Verwenden Sie diese Funktionen, um Kundendaten vor der Übergabe an trackEvent vorzubereiten:

// 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: Mehrstufiges Lead-Formular, bei dem Sie den Abschluss nur nach einer Backend-Validierung tracken möchten.

// 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-Tracking für Drittanbieter-Integrationen

Szenario: Stripe-Zahlungs-Widget, bei dem Sie das Kaufereignis nach erfolgreicher Zahlung tracken müssen.

// 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 Ereignisseite im PixelFlow-Dashboard

Überprüfen Sie immer, ob Ereignisse korrekt im PixelFlow-Ereignisprotokoll erscheinen:

Senden Sie ein Ereignis über die API
Gehen Sie zu https://dashboard.pixelflow.so/dashboard/events
Suchen Sie Ihr Ereignis, erweitern Sie die Ereigniszeile und überprüfen Sie, ob der an Meta gesendete Payload alle erwarteten Daten enthält

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

War das hilfreich?