Conversions API

Parameter-Builder-Bibliothek

Meta stellt eine Liste von Bibliotheks-SDKs sowohl auf der Clientseite (JavaScript) als auch auf der Serverseite (PHP, Java, Python, NodeJS, Ruby) bereit. Diese SDK-Bibliotheken sollen Entwickler*innen dabei unterstützen, die Qualität der Parameter von Conversions API-Events (z. B. fbc, fbp, client_ip_address und andere Parameter für Kund*inneninformationen wie em und ph) zu verbessern und Werbetreibende in die Lage versetzen, die Best Practices von Meta für die Erstellung dieser Parameter einzuhalten.

Dieses Dokument enthält einen Überblick über beide Bibliotheken, eine Anleitung, welche Bibliothek zu verwenden ist, sowie Anwendungsbeispiele.

Überblick über die Bibliothek

Clientseitig: Die Bibliothek und die Events befinden sich im Frontend auf der Browserseite. Die Bibliotheken sind in JavaScript implementiert. Entwickler*innen können sie direkt in ihre Webseite integrieren.

Serverseitig: Die Bibliotheken und Events befinden sich im Backend auf der Serverseite. Je nachdem, welche Sprache das Backend verwendet, stellt Meta Bibliotheken in verschiedenen Sprachen zur Verfügung (PHP, Java, Python, NodeJS und Ruby).

Auswahl einer Bibliothek

Alle Bibliotheken können unabhängig voneinander verwendet werden. Um das Potenzial für dich oder deine Kund*innen zu maximieren, solltest du die hier aufgeführten Empfehlungen durchgehen.

Parambuilder hält sich an die Best Practices aus der Entwicklungsdokumentation von Meta. Er ist auf der Clientseite (JavaScript) und auf der Serverseite (PHP, Java, Python, NodeJS, Ruby) implementiert.

Anwendungsbeispiele als Referenz

Bei der Entwicklung der Lösung solltest du die folgenden Anwendungsbeispiele berücksichtigen.

Empfohlen: Serverseitiger Parameter-Builder und clientseitiger Parameter-Builder

Die Kombination des serverseitigen Parameter-Builders und des clientseitigen Parameter-Builders kann dir dabei helfen, eine hohe fbc- und IPv6-Abdeckung zu erzielen.

Dazu musst du zwei Bibliotheken zusammen integrieren: den serverseitigen Parameter-Builder und den clientseitigen Parameter-Builder.




Beispiel-Workflow

  • Die Client-App des*der Werbetreibenden lädt den clientseitigen Parameter-Builder und ruft den bereitgestellten API-Prozess „processAndCollectAllParams“ mit einem Funktionszeiger „getIpFn“ auf.
  • Die angegebene getIpFn wird aufgerufen und ruft IPv6 von einem von einem Werbetreibenden konfigurierten Endpunkt ab, je nach tatsächlicher getIpFn-Implementierung.
  • Die IPv6-Adresse wird vom vom Werbetreibenden konfigurierten Endpunkt zurückgegeben und an den clientseitigen Parameter-Builder aus dem Rückgabewert von getIpFn weitergegeben. Das abgerufene IPv6 wird im Cookie mit dem Schlüssel „_fbi“ für eine spätere Abfrage gespeichert.
  • Starte auf der Clientseite deine übliche Kommunikation mit dem Backend-Server über die Abruf-API (oder eine andere Front-Back-End-Kommunikation) mit den Erstanbieter-Cookies.
  • Integriere die serverseitige Bibliothek anhand deiner Sprachwahl im Empfänger-Endpunkt (z. B. ExampleController) und rufe die bereitgestellte API processRequest auf, um die Anfrage zu verarbeiten.
  • Die processRequest API gibt eine Liste der Cookies zurück, die auf dem Client aktualisiert werden sollten.
  • Setze empfohlene Cookies in Antwort-Headern, um den Browser des Clients zum Speichern zu veranlassen.
  • Rufe verschiedene bereitgestellte APIs wie getFbc(), getFbp(), getClientIpAddress() und getNormalizedAndHashedPII() auf.
  • Das SDK gibt verschiedene Werte wie fbc, fbp, client_ip_address, email und phone number zurück.
  • Sende diese abgerufenen Werte über die Conversions API wieder zurück an Meta.
// Example Controller which processes all requests to example.com
// Start process
ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList('example.com', 'yourDomain.com'));
// Input the request's full URL, such as: example.com?fbclid=xxxxx
// Process and get recommended updated cookie
List<CookieSetting> updatedCookieList =
        paramBuilder.processRequest(
            request.getHeader("host"),  // example.com
            request.getParameterMap(), // {'fbclid':['xxxxx']}
            cookieMap, 
            request.getHeader("referer"),
request.getHeader("X-Forwarded-For"),
request.getRemoteAddr(),
); // optional: referer full url


// Save cookie from server side
for (CookieSetting updatedCookie : updatedCookieList) {
      Cookie cookie = new Cookie(updatedCookie.getName(), updatedCookie.getValue());
      cookie.setMaxAge(updatedCookie.getMaxAge());
      cookie.setDomain(updatedCookie.getDomain());
      response.addCookie(cookie);
 }

// Get fbc, fbp, client_ip_address
String fbc = paramBuilder.getFbc();
String fbp = paramBuilder.getFbp();
String client_ip_address = paramBuilder.getClientIpAddress();

// Get Normalized and Hashed PII like email and phone number
String normalizedAndHashedEmail = paramBuilder.getNormalizedAndHashedPII(‘John_Smith@gmail.com’,’email’);
String normalizedAndHashedPhone = paramBuilder.getNormalizedAndHashedPII(‘(650)555-1212’,’phone’);

// Call CAPI endpoint
.....
.setFbc(fbc)
.setFbp(fbp)
.setClientIpAddress(client_ip_address)
.setEmail(normalizedAndHashedEmail)
.setPhone(normalizedAndHashedPhone)
....

Nur serverseitiger ParamBuilder

Detaillierte Beispiele findest du im Einführungsleitfaden für den serverseitigen Parameter-Builder oder in den darin verlinkten README-Dateien.

Beispiel-Workflow

  • Importiere im Endpunkt des Servers die ParamBuilder-Bibliothek, die auf der jeweiligen Sprache und dem jeweiligen Framework basiert.
  • Rufe paramBuilder.processRequest auf, um eine Liste der empfohlenen aktualisierten Cookies zu erhalten.
  • Setze Cookies auf deine Antwort.
  • Lege fbc, fbp, client_ip_address und andere personenbezogene Informationen wie E-Mail und Telefonnummer für den Aufruf der Conversions API fest, indem du paramBuilder.getFbc(), paramBuilder.getFbp(), paramBuilder.getClientIpAddress() bzw. paramBuilder.getNormalizedAndHashedPII() verwendest.

Nur clientseitiger ParamBuilder

Detaillierte Beispiele findest du im Einführungsleitfaden für den clientseitigen Parameter-Builder oder in den darin verlinkten README-Dateien.

Beispiel-Workflow

  • Beim Laden der Landingpage wird „clientParamBuilder.processAndCollectAllParams(url, getIpFnl)“ aufgerufen.
  • Die Anfrage wird dann an die Serverseite gesendet. Der Server kann dann fbc, fbp und client_ip_address aus dem Cookie mit den Schlüsseln _fbc, _fbp bzw. _fbi lesen.
    • Hinweis: Wenn die Landing-URL keine fbclid enthält, fehlt fbc möglicherweise. Es handelt sich dabei nicht um einen Fehler.

Nützliche Links

Primärer GitHub-Link

Vergewissere dich, dass du die aktuelle Version verwendest.

Best Practices

  • Stelle sicher, dass du die Cookies _fbp und _fbc so früh wie möglich in der Customer Journey auf deiner Webseite speicherst. Idealerweise rufst du die Cookies _fbp und _fbc beim Laden deiner Landingpage ab. Es ist nicht empfehlenswert, sie nur bei Events im unteren Funnel oder bei Auslösung bestimmter Events abzurufen.
  • Setze die Cookies _fbc und _fbp nicht außer Kraft und passe sie nicht an. Bei _fbc wird zwischen Groß- und Kleinschreibung unterschieden; normalisiere oder formatiere _fbc nicht in Kleinbuchstaben.
  • Vergewissere dich, dass die Bibliotheken auf alle Oberflächen, z. B. Mobilgeräte, Desktops, Browser und Domains, die du nachverfolgen möchtest, angewendet werden.
  • Die serverseitige Bibliothek ist für die Backend-Seite und die clientseitige Bibliothek ist für die Frontend-Browserseite. Entwickler*innen können die clientseitige Bibliothek direkt in ihre Webseite integrieren, während die serverseitigen Bibliotheken im Server, also im Backend, aufgerufen werden. Beachte, dass die clientseitige Bibliothek nur in JavaScript verfügbar ist, während die serverseitige Bibliothek Unterstützung für verschiedene Sprachen (PHP, Java, Python, NodeJS und Ruby) bietet.
  • Beim Implementieren der getIpFn-Funktionalität solltest du zuerst die IPv6-Adresse abrufen und dann auf die IPv4-Adresse zurückgreifen, wenn die Funktion zum Abrufen der IPv6-Adresse auf der Clientseite des*der Nutzer*in nicht verfügbar ist.
  • Wir empfehlen dir, sowohl den Client- als auch den Server-Parameter-Builder zu integrieren, um eine optimale Performance zu erzielen. Du kannst den clientseitigen Parameter-Builder verwenden, um client_ip_address abzurufen und in einem Cookie zu speichern. Später kannst du den serverseitigen Parameter-Builder verwenden, um die bestmögliche client_ip_address aus Cookie und Anfrage abzurufen und an Meta zu senden.
  • Wir empfehlen, Normalisierung und Hashing für Kundeninformationsparameter nur einmal anzuwenden – entweder auf der Client- oder der Serverseite –, bevor sie über die Conversions API an Meta gesendet werden.
  • Für alle vom Parameter-Builder zurückgegebenen Werte der Parameterfelder für Kund*inneninformationen wird zwischen Groß- und Kleinschreibung unterschieden. Du kannst diese Werte über die Conversions API ohne Normalisierung (z. B. Kleinbuchstaben) an Meta senden, da dies im Prozess automatisch vom parambuilder SDK vorgenommen wurde.

Siehe auch