Pemirsa Khusus File Pelanggan

Marketing API mengizinkan Anda membuat target Pemirsa Khusus berdasarkan informasi pelanggan. Ini termasuk alamat email, nomor telepon, nama, tanggal lahir, jenis kelamin, lokasi, ID Pengguna Aplikasi, ID Pengguna Lingkup Halaman, Pengidentifikasi Periklanan Apple (IDFA), atau ID Periklanan Android.

Anda bisa menambahkan jumlah data yang terbatas ke suatu pemirsa, tetapi hanya hingga 10.000 setiap kalinya. Perubahan pada Pemirsa Khusus Anda tidak langsung terjadi dan biasanya membutuhkan waktu hingga 24 jam. Jumlah rekaman yang Anda minta untuk dihapus dan/atau jumlah Pemirsa Khusus yang ada di akun Anda akan meningkatkan jumlah waktu yang dibutuhkan untuk memproses permintaan ini.

Untuk meningkatkan cara pengiklan membuat dan mengelola pemirsa mereka, Pemirsa Khusus File Pelanggan yang belum pernah digunakan dalam set iklan aktif apa pun selama lebih dari dua tahun akan ditandai untuk dihapus secara bergilir. Anda harus memberi kami instruksi Anda sebelum kami mengambil tindakan apa pun. Setelah pemirsa dipindahkan ke tahap "Pemirsa Kedaluwarsa" dan ditandai, Anda harus memberikan instruksi dengan menggunakan pemirsa yang ditandai di set iklan aktif, yang akan kami anggap sebagai instruksi untuk mempertahankan pemirsa, atau dengan memutuskan untuk tidak menggunakan pemirsa yang ditandai di set iklan aktif, yang akan kami anggap sebagai instruksi untuk menghapus pemirsa. Untuk informasi selengkapnya, lihat dokumentasi Ringkasan Pemirsa Khusus.

Membuat Pemirsa Khusus

Langkah 1: Buat Pemirsa Khusus yang Masih Kosong

Tentukan subtype=CUSTOM dan customer_file_source dalam panggilan API Anda.

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

Langkah 2: Tentukan Daftar Pengguna

Gunakan panggilan API POST ke endpoint /{audience_id}/users endpoint untuk menentukan daftar pengguna yang ingin ditambahkan ke Pemirsa Khusus Anda.

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>" 
    ]
}

Opsi Pemrosesan Data bagi Pengguna di AS

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

Kolom session

Tanggapan

Tanggapan yang berhasil menyertakan objek JSON dengan kolom berikut:

Pelajari selengkapnya tentang membagikan Pemirsa Khusus Anda dengan objek bisnis.

Menghapus Anggota Pemirsa

Gunakan panggilan API DELETE ke endpoint /{audience_id}/users untuk menentukan daftar pengguna yang ingin dihapus dari Pemirsa Khusus Anda.

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

Atau, Anda dapat menambahkan parameter method dan mengaturnya ke DELETE dalam permintaan POST yang digunakan untuk menambahkan anggota pemirsa.

Anda juga dapat menghapus orang dari daftar dengan EXTERN_ID, jika tersedia.

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

Anda dapat menghapus daftar orang dari semua Pemirsa Khusus di seluruh akun iklan Anda menggunakan endpoint ini.

Mungkin ada beberapa alasan mengapa informasi ini tidak diproses. Contoh: jika iklan akun tidak dimiliki oleh akun bisnis, Anda belum menerima Ketentuan Pemirsa Khusus, atau informasi tidak cocok dengan pengguna.

Untuk menghapus akun Pusat Akun, sertakan kolom yang sama seperti di pembaruan pengguna dan buat panggilan HTTP DELETE ke:

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

Pencocokan Multikode

Untuk meningkatkan tingkat pencocokan bagi rekaman Anda, sediakan beberapa kode dalam array kode individu; contoh: [EXTERN_ID, LN, FN, EMAIL]. Meski tidak perlu hashing EXTERN_ID, semua informasi identifikasi pribadi, seperti email dan nama, wajib hashing. Untuk detailnya, lihat Hashing dan Normalisasi Data.

Anda dapat menyediakan sebagian atau semua multikode untuk rekaman. Untuk detailnya, lihat pencocokan ID eksternal multikode.

Menambahkan Pengguna dengan Kecocokan Multikode

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

Menggunakan PAGEUID

Jika menggunakan kode PAGEUID, Anda juga harus menyertakan daftar ID Halaman. Anda hanya bisa mengirimi kami satu PAGEUID, yang harus merupakan array dengan satu elemen.

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 dan Normalisasi untuk Multikode

Data harus di-hash sebagai SHA256; kami tidak mendukung mekanisme hashing lainnya. Ini diperlukan untuk semua data, kecuali Pengidentifikasi Eksternal, ID Pengguna Aplikasi, ID Pengguna Lingkup Halaman, dan ID Pengiklan Seluler.

Sebelum Anda meng-hashing data, normalkan data itu agar kami bisa menanganinya. Hanya Nama Depan (FN) dan Nama Belakang (LN) yang mendukung karakter khusus dan abjad non-Romawi. Untuk mendapatkan hasil kecocokan terbaik, sediakan terjemahan abjad Romawi tanpa karakter khusus apa pun.

Hashing

Sediakan nilai SHA256 untuk kode yang dinormalisasi dan perwakilan HEX dari nilai ini, menggunakan huruf kecil untuk A sampai F. Fungsi hash dalam PHP mengubah email dan nomor telepon yang dinormalisasi.

Pengidentifikasi Eksternal

Anda dapat mencocokkan orang untuk suatu pemirsa dengan pengidentifikasi Anda sendiri, yang disebut Pengidentifikasi Eksternal (EXTERN_ID). Ini bisa berupa ID unik apa pun dari pengiklan, seperti ID keanggotaan loyalitas, ID pengguna, dan ID cookie eksternal.

Untuk pencocokan yang lebih baik, Anda juga harus menggunakan format yang sama persis saat Anda mengirim ID. Contoh: jika Anda memilih untuk melakukan hash menggunakan SHA256, pastikan untuk menggunakan nilai hash yang sama.

ID ini selanjutnya dapat digunakan sebagai kode individual untuk menghapus orang dari Pemirsa Khusus atau membuat Pemirsa Khusus baru. Dengan begitu Anda tidak perlu mengunggah ulang kode kecocokan lain mana pun. Jika Anda melabeli seseorang dengan informasi pribadi yang di-hashing dan EXTERN_ID, kami memberi EXTERN_ID prioritas yang lebih rendah saat kami mencocokkannya dengan orang-orang di Facebook.

Anda dapat menggunakan ulang pemetaan EXTERN_ID untuk membuat file khusus pemirsa khusus dalam satu akun iklan.

Jika Anda memiliki pemirsa dengan kolom EXTERN_ID dalam akun iklan Anda, buatlah pemirsa baru hanya dengan pengidentifikasi ini.

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

Anda juga dapat menambahkan orang yang ditandai EXTERN_ID dan dengan pencocokan multikode.

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

API Ganti Pengguna

Endpoint /<CUSTOM_AUDIENCE_ID>/usersreplace memungkinkan Anda untuk melakukan 2 tindakan dengan satu panggilan API:

• Sepenuhnya menghapus pengguna yang ada dari pemirsa tertentu
• Menggantikan pengguna tersebut dengan satu set pengguna baru.

Menggunakan endpoint /<CUSTOM_AUDIENCE_ID>/usersreplace memungkinkan Anda untuk secara otomatis menghapus semua pengguna yang ada daripada harus mengunggah daftar pengguna yang ingin dihapus. Endpoint ini tidak mengatur ulang fase pembelajaran set iklan Anda saat pemirsa adalah bagian dari set iklan aktif, tidak seperti panggilan POST atau DELETE API ke endpoint /<CUSTOM_AUDIENCE_ID>/users.

API Ganti Pengguna hanya berfungsi dengan pemirsa yang memenuhi persyaratan berikut:

• Jumlah pengguna yang ada sebelum menjalankan proses penggantian harus lebih kecil dari 100 juta. Jika pemirsa Anda lebih besar dari 100 juta, kami sarankan untuk memanfaatkan endpoint /<CUSTOM_AUDIENCE_ID>/users untuk menambahkan dan menghapus pengguna.
• Subjenis harus diatur ke CUSTOM.
• Anda tidak dapat mengganti pemirsa khusus file pelanggan berbasis nilai dengan pemirsa khusus file pelanggan berbasis non-nilai, atau sebaliknya.

Memulai

Sebelum Anda memulai proses penggantian, kami merekomendasikan hal-hal berikut:

• Pastikan operation_status pemirsa Anda adalah Normal.

• Jangan menambah atau menghapus pengguna melalui /<CUSTOM_AUDIENCE_ID>/users selama operasi penggantian yang sedang berlangsung melalui /<CUSTOM_AUDIENCE_ID>/usersreplace. Jika Anda mencoba melakukan operasi penggantian kedua sebelum yang pertama selesai, Anda akan menerima pesan yang menunjukkan bahwa operasi penggantian sedang berlangsung.

• Termin durasi maksimum untuk 1 sesi penggantian adalah 90 menit. API akan menolak batch apa pun untuk sesi yang diterima setelah 90 menit sejak sesi dimulai. Jika Anda perlu mengirim batch untuk durasi lebih dari 90 menit, kami sarankan menunggu hingga operasi penggantian untuk sesi itu selesai, lalu gunakan operasi penambahan endpoint /<CUSTOM_AUDIENCE>/users untuk sisa unggahan Anda.

• Setelah pemirsa Anda siap, tentukan daftar pengguna yang ingin Anda ganti dengan pemirsa khusus Anda menggunakan panggilan POST ke /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Setelah Anda memulai kemajuan penggantian, operation_status pemirsa Anda beralih ke replace_in_progress.
  • Jika operasi penggantian Anda gagal, operation_status pemirsa Anda beralih ke replace_error.

Parameter Panggilan

Anda dapat menyertakan parameter berikut di panggilan POST ke /<CUSTOM_AUDIENCE_ID>/usersreplace:

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

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

Kolom Sesi

Kolom Payload

Setelah Anda membuat permintaan POST, Anda mendapatkan tanggapan dengan kolom berikut:

Kesalahan Umum API Ganti

Semua kesalahan yang diberikan dari endpoint Ganti memiliki kode kesalahan 2650. Berikut ini adalah beberapa subkode kesalahan yang paling umum ditampilkan, serta panduan tentang cara menyelesaikannya.

Sumber Informasi

Ada jenis pemirsa lainnya yang dapat Anda buat dan targetkan, atau bagikan:

• Pemirsa Khusus dari Situs Web Anda — Buatlah pemirsa berdasarkan orang yang mengunjungi halaman tertentu atau melakukan tindakan di situs web Anda. Buat pemirsa berdasarkan data dari Meta Pixel di situs Anda.

• Pemirsa Khusus dari Aplikasi Seluler Anda — Buatlah pemirsa berdasarkan orang yang menggunakan aplikasi seluler Anda. Buat pemirsa berdasarkan data dari Peristiwa Aplikasi.

• Pemirsa Serupa — Identifikasi orang yang telah Anda kenal dan iklankan ke khalayak serupa di Facebook.

• Pemirsa Khusus Offline — Buatlah pemirsa berdasarkan orang yang mengunjungi toko Anda, menelepon ke layanan pelanggan Anda, atau bertindak melalui sarana offline lainnya.

• Pemirsa Interaksi Canvas — Buatlah pemirsa yang berisi siapa saja yang berinteraksi dengan Canvas Anda.

Lihat Juga

• Pemirsa Khusus
• Pengguna Pemirsa Khusus
• Sesi Pemirsa Khusus
• Ketentuan Layanan Pemirsa Khusus