Custom Audiences auf Basis von Kundendateien

Erstelle mit unserer Marketing API deine gewünschten Custom Audiences aus Kund*inneninformationen. Zu diesen Informationen gehören E-Mail-Adressen, Telefonnummern, Namen, Geburtsdaten, Geschlecht, Standorte, App-Nutzungs-IDs, seitenbezogene Nutzungs-IDs, der Advertising Identifier (IDFA) von Apple oder die Android-Advertising-ID.

Du kannst einer Zielgruppe beliebig viele Datensätze hinzufügen, jedoch immer nur maximal 10.000 gleichzeitig. Änderungen an deinen Custom Audiences werden üblicherweise nicht sofort, sondern erst nach 24 Stunden wirksam. Die zur Verarbeitung dieser Anforderung benötigte Zeit hängt von der Anzahl der Datensätze, deren Entfernung du angefordert hast, und/oder der Anzahl der Custom Audiences in deinem Konto ab.

Um die Erstellung und Verwaltung von Zielgruppen zu verbessern, werden Custom Audiences auf Basis von Kundendateien, die seit mehr als zwei Jahren in keinen aktiven Anzeigengruppen verwendet wurden, fortlaufend zum Löschen markiert. Die weiteren Schritte hängen von dir ab. Du kannst Zielgruppen, die als ablaufend markiert wurden, in einer aktiven Anzeigengruppe verwenden, damit sie beibehalten werden. Wenn du die markierte Zielgruppe hingegen nicht in einer aktiven Anzeigengruppe nutzt, wird sie gelöscht. Weitere Informationen dazu findest du in der Dokumentation Überblick über Custom Audiences.

Custom Audience erstellen

Schritt 1: Eine leere Custom Audience erstellen

Gib in deinem API-Aufruf subtype=CUSTOM und customer_file_source an.

curl -X POST \
  -F 'name="My new Custom Audience"' \
  -F 'subtype="CUSTOM"' \
  -F 'description="People who purchased on my website"' \
  -F 'customer_file_source="USER_PROVIDED_ONLY"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/customaudiences

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My new Custom Audience',
  'subtype' : 'CUSTOM',
  'description' : 'People who purchased on my website',
  'customer_file_source' : 'USER_PROVIDED_ONLY',
};
const customaudiences = (new AdAccount(id)).createCustomAudience(
  fields,
  params
);
logApiCallResult('customaudiences api call complete.', customaudiences);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My new Custom Audience',
  'subtype' => 'CUSTOM',
  'description' => 'People who purchased on my website',
  'customer_file_source' => 'USER_PROVIDED_ONLY',
);
echo json_encode((new AdAccount($id))->createCustomAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My new Custom Audience',
  'subtype': 'CUSTOM',
  'description': 'People who purchased on my website',
  'customer_file_source': 'USER_PROVIDED_ONLY',
}
print AdAccount(id).create_custom_audience(
  fields=fields,
  params=params,
)

import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCustomAudience()
      .setName(\"My new Custom Audience\")
      .setSubtype(CustomAudience.EnumSubtype.VALUE_CUSTOM)
      .setDescription(\"People who purchased on my website\")
      .setCustomerFileSource(CustomAudience.EnumCustomerFileSource.VALUE_USER_PROVIDED_ONLY)
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
customaudiences = ad_account.customaudiences.create({
    name: 'My new Custom Audience',
    subtype: 'CUSTOM',
    description: 'People who purchased on my website',
    customer_file_source: 'USER_PROVIDED_ONLY',
})

Parameter

Schritt 2: Liste mit Nutzer*innen angeben

Sende einen POST-API-Aufruf an den /{audience_id}/users-Endpunkt, um die Liste der Nutzer*innen anzugeben, die zu deiner Custom Audience hinzugefügt werden sollen.

Parameter

{
  "session_id":9778993, 
  "batch_seq":10, 
  "last_batch_flag":true, 
  "estimated_num_total":99996 
} 

{ 
  "schema":"EMAIL_SHA256", 
  "data":
    [
      "<HASHED_DATA>", 
      "<HASHED_DATA>", 
      "<HASHED_DATA>" 
    ]
}

Datenverarbeitungsoptionen für Nutzer*innen in den USA

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           []
           ]
       ]
   }
}

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           ["LDU"]
           ]
       ]
   }
}

{
    "customer_consent": true,
    "payload": {
        "schema": [
            "EMAIL",
            "DATA_PROCESSING_OPTIONS",
            "DATA_PROCESSING_OPTIONS_COUNTRY",
            "DATA_PROCESSING_OPTIONS_STATE"
        ],
        "data": [
            [
                "<HASHED_DATA>",
                ["LDU"],
                1,
                1000
            ]
        ]
    }
}

session-Felder

Antwort

Eine erfolgreiche Antwort beinhaltet ein JSON-Objekt mit den folgenden Feldern:

Erfahre mehr darüber, wie du deine Custom Audience für Unternehmensobjekte freigibst.

Zielgruppenmitglieder entfernen

Sende einen DELETE-API-Aufruf an den /{audience_id}/users-Endpunkt, um die Liste der Nutzer*innen anzugeben, die aus deiner Custom Audience entfernt werden sollen.

curl -X DELETE \
  --data-urlencode 'payload={ 
    "schema": "EMAIL_SHA256", 
    "data": [ 
      "<HASHED_DATA>", 
      "<HASHED_DATA>", 
      "<HASHED_DATA>" 
    ] 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Alternativ kannst du in der POST-Anfrage, mit der Zielgruppenmitglieder hinzugefügt werden, den Parameter method einfügen und auf DELETE festlegen.

Mit EXTERN_ID lassen sich Personen aus einer Liste entfernen, sofern verfügbar.

curl -X DELETE \
  --data-urlencode 'payload={ 
    "schema": "EXTERN_ID", 
    "data": [ 
      "<ID>", 
      "<ID>", 
      "<ID>" 
    ] 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Du kannst mit diesem Endpunkt eine Liste mit Personen aus allen Custom Audiences in deinem Werbekonto entfernen.

Möglicherweise gibt es Gründe, die eine Verarbeitung dieser Informationen verhindern. Wenn beispielsweise das Werbekonto keinem Business-Konto gehört, du die Custom Audience-Nutzungsbedingungen noch nicht akzeptiert hast oder die Informationen keinem*keiner Nutzer*in zugeordnet werden können.

Nimm zum Entfernen eines Kontenübersichtskontos dieselben Felder auf wie für Nutzer-Update und sende einen HTTP DELETE-Aufruf an:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/usersofanyaudience

Multi-Key-Matching (Abgleich mehrerer Schlüssel)

Um die Trefferquote für deine Datensätze zu verbessern, gib mehrere Schlüssel in einem Array einzelner Schlüssel an, z. B. [EXTERN_ID, LN, FN, EMAIL]. Eine EXTERN_ID muss nicht im Hashformat angegeben werden. Alle personenbezogenen Informationen wie z. B. E-Mail-Adressen und Namen hingegen schon. Einzelheiten findest du unter Hashing und Normalisierung von Daten.

Du kannst einige oder alle Multi-Keys für einen Datensatz angeben. Einzelheiten findest du unter Multi-Key-Matching für externe IDs.

Nutzer*innen unter Verwendung von Multi-Key-Matching hinzufügen

curl \
  -F 'payload={ 
    "schema": [ 
      "FN", 
      "LN", 
      "EMAIL" 
    ], 
    "data": [ 
      [ 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ] 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Unter Verwendung von PAGEUID

Wenn du den PAGEUID-Schlüssel verwendest, musst du eine Liste der Seiten-IDs einschließen. Du kannst uns nur eine PAGEUID senden. Diese muss ein Array mit einem Element sein.

curl -X POST \
  -F 'payload={
       "schema": [
         "PAGEUID"
       ],
       "is_raw": "true",
       "page_ids": [
            "<PAGE_IDs>"
            ],
       "data": [
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ],
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ],
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ]
       ]
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Hashing und Normalisierung für Multi-Key-Matching

Du musst Daten als SHA256 hashen, da wir keinen anderen Hash-Mechanismus unterstützen. Dies ist für alle Daten mit Ausnahme von externen IDs, App-Nutzer-IDs, seitenbezogenen Nutzer-IDs und mobilen Werbekunden-IDs erforderlich.

Normalisiere deine Daten vor dem Hashen, damit wir sie verarbeiten können. Nur in Vornamen (FN) und Nachnamen (LN) werden Sonderzeichen und andere Buchstaben als die des lateinischen Alphabets unterstützt. Um optimale Übereinstimmungsergebnisse zu erzielen, gib die Übersetzung im lateinischen Alphabet ohne Sonderzeichen an.

Hashing

Gib SHA256-Werte für normalisierte Schlüssel und HEX-Darstellungen dieses Werts an. Verwende dafür die Kleinbuchstaben a bis f. Die Hashfunktion in PHP wandelt normalisierte E-Mail-Adressen und Telefonnummern um:

Externe IDs

Du kannst Personen für eine Zielgruppe mit deinen eigenen IDs abgleichen. Diese werden als „externe IDs“ oder EXTERN_ID bezeichnet. Dies kann eine beliebige eindeutige ID des Werbetreibenden sein, wie zum Beispiel IDs für Loyalitäts-Mitgliedschaften, Nutzer-IDs und externe Cookie-IDs.

Für ein besseres Matching musst du beim Senden der IDs genau dasselbe Format verwenden. Wenn du dich z. B. für das Hashen mit SHA256 entscheidest, musst du später den gleichen Hashwert verwenden.

Diese IDs können dann als individuelle Schlüssel verwendet werden, um Personen aus Custom Audiences zu löschen oder um neue Custom Audiences zu erstellen. So musst du keine anderen Abgleichsschlüssel hochladen. Wenn du jemanden mit personenbezogenen Informationen im Hashformat und EXTERN_ID markierst, erhält EXTERN_ID eine geringere Priorität, wenn wir sie mit Personen auf Facebook abgleichen.

Du kannst die EXTERN_ID-Zuordnung in einem einzelnen Werbekonto wiederverwenden, um benutzerdefinierte Zielgruppen für benutzerdefinierte Dateien zu erstellen.

Wenn dein Werbekonto eine Zielgruppe aus EXTERN_ID-Feldern enthält, erstelle eine neue Zielgruppe nur mit diesen IDs.

curl \
  -F 'payload={"schema":"EXTERN_ID","data":["<ID>","<ID>"]}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Du kannst mit EXTERN_ID getaggte Personen auch mit Multi-Key-Matching hinzufügen.

curl \
  -F 'payload={ 
    "schema": [ 
      "EXTERN_ID", 
      "FN", 
      "EMAIL", 
      "LN" 
    ], 
    "data": [ 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ] 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Replace Users API

Der /<CUSTOM_AUDIENCE_ID>/usersreplace-Endpunkt erlaubt dir, bis zu zwei Aktionen mit einem API-Aufruf durchzuführen:

• bestehende Nutzer*innen vollständig aus einer bestimmten Zielgruppe entfernen
• diese Nutzer*innen durch einen neuen Satz von Nutzer*innen ersetzen

Mit dem /<CUSTOM_AUDIENCE_ID>/usersreplace-Endpunkt kannst du alle vorhandenen Nutzer*innen automatisch löschen, anstatt eine Liste der zu löschenden Nutzer*innen hochladen zu müssen. Wenn eine Zielgruppe Teil einer aktiven Anzeigengruppe ist, setzt dieser Endpunkt die Lernphasedeiner Anzeigengruppe nicht zurück, anders als die POST oder DELETE API-Aufrufe zum /<CUSTOM_AUDIENCE_ID>/users-Endpunkt.

Die Replace Users API kann nur mit Zielgruppen mit den folgenden Voraussetzungen verwendet werden:

• Vor einer Ersetzung muss die Zahl der Nutzer unter 100 Millionen liegen. Wenn deine Zielgruppe mehr als 100 Millionen Personen enthält, empfehlen wir dir, den /<CUSTOM_AUDIENCE_ID>/users-Endpunkt zu verwenden, um Nutzer hinzuzufügen und zu entfernen.
• Der Untertyp muss auf CUSTOM festgelegt werden.
• Du kannst eine wertbasierte Kundendatei-Custom Audience nicht durch eine nicht-wertbasierte Kundendatei-Custom Audience ersetzen und umgekehrt.

Erste Schritte

Wir empfehlen dir, vor dem Ersetzen Folgendes zu prüfen:

• Stelle sicher, dass der operation_status deiner Zielgruppe normal lautet.

• Du kannst während eines laufenden Ersetzen-Vorgangs über /<CUSTOM_AUDIENCE_ID>/usersreplace keine Nutzer*innen über /<CUSTOM_AUDIENCE_ID>/users hinzufügen oder entfernen. Wenn du versuchst, einen zweiten Ersetzen-Vorgang auszuführen, bevor der erste abgeschlossen ist, gibt eine Meldung an, dass bereits ein Ersetzen-Vorgang durchgeführt wird.

• Die maximale Dauer von Batch-Sitzungen für Ersetzungen beträgt 90 Minuten. Die API lehnt alle Batches für eine Sitzung ab, die mehr als 90 Minuten nach Sitzungsstart eingehen. Wenn du länger als 90 Minuten Batches senden musst, warte, bis der Ersetzen-Vorgang für diese Sitzung abgeschlossen ist. Verwende dann für den Rest der Uploads den Hinzufügen-Vorgang des /<CUSTOM_AUDIENCE>/users-Endpunkts.

• Sobald deine Zielgruppe bereit ist, kannst du mit einem POST-Aufruf an /<CUSTOM_AUDIENCE_ID>/usersreplace eine Liste von Personen angeben, die deiner Custom Audience hinzugefügt werden sollen.

  • Sobald du den Ersetzen-Vorgang startest, wechselt der operation_status deiner Zielgruppe zu replace_in_progress.
  • Wenn dein Ersetzen-Vorgang fehlschlägt, wechselt der operation_status deiner Zielgruppe zu replace_error.

Aufrufparameter

Du kannst die folgenden Parameter in deinen POST-Aufruf an /<CUSTOM_AUDIENCE_ID>/usersreplace aufnehmen:

{
  'session_id':9778993, 
  'batch_seq':10, 
  'last_batch_flag':true, 
  'estimated_num_total':99996 
}

{ 
  "schema":"EMAIL", 
  "data":["<HASHED_EMAIL>", "<HASHED_EMAIL>", "<HASHED_EMAIL>" ]
}

Sitzungsfelder

Payload-Felder

Wenn du deine POST-Anfrage sendest, erhältst du eine Antwort mit den folgenden Feldern:

Replace API: gängige Fehler

Alle vom Replace-Endpunkt zurückgegebenen Fehler haben den Fehlercode 2650. Es folgen einige der gängigsten Fehler-Subcodes sowie Hinweise zu ihrer Behebung.

Ressourcen

Du kannst weitere Arten von Zielgruppen erstellen, ansprechen und teilen:

• Custom Audiences über deine Webseite – Erstelle eine Zielgruppe auf Basis von Personen, die eine bestimmte Seite besucht oder eine Handlung auf deiner Webseite durchgeführt haben. Erstelle eine Zielgruppe auf Basis von Daten des Meta-Pixels auf deiner Website.

• Custom Audiences über deine mobile App – Erstelle eine Audience basierend auf Personen, die deine mobile App nutzen. Erstelle eine Zielgruppe auf Basis von Daten aus App-Events.

• Lookalike Audiences – Identifiziere Personen, die du bereits kennst, und richte deine Werbeanzeigen an ähnliche Personen in der Facebook-App.

• Offline-Custom Audiences – Erstelle eine Zielgruppe auf Basis von Personen, die deinen Store besucht oder deinen Kundendienst angerufen haben oder über andere Offline-Methoden aktiv geworden sind.

• Canvas-Interaktionszielgruppen – Erstelle eine Zielgruppe mit allen Personen, die mit deinem Canvas interagiert haben.

Siehe auch

• Custom Audience
• Nutzer der Custom Audience
• Custom Audience-Sitzung
• Custom Audience-Nutzungsbedingungen