กลุ่มเป้าหมายที่กำหนดเองจากไฟล์ของลูกค้า

API การตลาดช่วยให้คุณสามารถสร้างกลุ่มเป้าหมายที่กำหนดเองจากข้อมูลของลูกค้าได้ ซึ่งประกอบด้วยอีเมล, หมายเลขโทรศัพท์, ชื่อ, วันเกิด, เพศ, ตำแหน่งที่ตั้ง, ID ผู้ใช้แอพ, ID ผู้ใช้ในเพจ, ตัวระบุการโฆษณาของ Apple (IDFA) หรือ ID การโฆษณาของ Android

ในฐานะเจ้าของข้อมูลธุรกิจของคุณเอง คุณจะต้องรับผิดชอบในการสร้างและจัดการข้อมูลนี้ ซึ่งรวมถึงข้อมูลจากระบบการจัดการด้านลูกค้าสัมพันธ์ (CRM) ของคุณ หากต้องการสร้างกลุ่มเป้าหมาย คุณจะต้องแชร์ข้อมูลของคุณในรูปแบบแฮชเพื่อรักษาความเป็นส่วนตัวไว้ โปรดดูการแฮชข้อมูลและการทำข้อมูลให้เป็นมาตรฐาน Meta จะเปรียบเทียบข้อมูลนี้กับข้อมูลที่แฮชของเราเพื่อดูว่าเราควรเพิ่มบุคคลบน Facebook ลงในกลุ่มเป้าหมายของโฆษณาของคุณหรือไม่

ซึ่งคุณสามารถเพิ่มรายการข้อมูลลงในกลุ่มเป้าหมายได้ไม่จำกัดจำนวน แต่สูงสุดครั้งละ 10,000 รายการเท่านั้น การเปลี่ยนแปลงต่อกลุ่มเป้าหมายที่กำหนดเองจะไม่เกิดขึ้นในทันทีและมักใช้เวลาไม่เกิน 24 ชั่วโมง โดยจำนวนรายการข้อมูลที่คุณส่งคำขอให้ลบออกและ/หรือจำนวนกลุ่มเป้าหมายที่กำหนดเองที่บัญชีของคุณมีอยู่จะทำให้การประมวลผลคำขอนี้ใช้ระยะเวลามากยิ่งขึ้น

เพื่อให้ผู้ลงโฆษณาสร้างและจัดการกลุ่มเป้าหมายของตนได้ดียิ่งขึ้น กลุ่มเป้าหมายที่กำหนดเองจากไฟล์ของลูกค้าที่ไม่ได้ใช้ในชุดโฆษณาที่ทำงานอยู่เป็นระยะเวลาเกิน 2 ปีจะถูกตั้งค่าสถานะให้ลบเป็นรอบๆ คุณจะต้องให้คำแนะนำแก่เราก่อนที่เราจะดำเนินการใดๆ เมื่อกลุ่มเป้าหมายถูกย้ายไปอยู่ขั้น "กลุ่มเป้าหมายที่หมดอายุ" และถูกตั้งค่าสถานะแล้ว คุณจะต้องให้คำแนะนำแก่เราในการดำเนินการ หากคุณต้องการให้เรารักษากลุ่มเป้าหมายดังกล่าวไว้ คุณจะต้องใช้กลุ่มเป้าหมายที่ถูกตั้งค่าสถานะในชุดโฆษณาที่ใช้งานอยู่ แต่หากคุณตัดสินใจไม่ใช้กลุ่มเป้าหมายที่ถูกตั้งค่าสถานะในชุดโฆษณาที่ใช้งานอยู่ เราจะลบกลุ่มเป้าหมายดังกล่าวออก โปรดดูข้อมูลเพิ่มเติมที่เอกสารประกอบเรื่องภาพรวมของกลุ่มเป้าหมายที่กำหนดเอง

หากคุณแชร์เหตุการณ์คอนเวอร์ชั่นโดยใช้ API คอนเวอร์ชั่น คุณสามารถสร้างเว็บไซต์สำหรับกลุ่มเป้าหมายที่กำหนดเองได้โดยไม่ต้องอัพโหลดข้อมูลเพิ่มเติม อย่างไรก็ตาม คุณสามารถอัพโหลดข้อมูลลูกค้าที่รองรับต่อไปได้เพื่อสร้างกลุ่มเป้าหมายที่กำหนดเองจากไฟล์ของลูกค้า

โปรดใช้ API การแทนที่ใหม่ของเราเพื่อลบผู้ใช้ที่มีอยู่ออกจากกลุ่มเป้าหมายทั้งหมดและแทนที่ด้วยผู้ใช้กลุ่มใหม่ การอัพเดตกลุ่มเป้าหมายโดยใช้ API การแทนที่จะไม่ย้ายชุดโฆษณาของคุณกลับไปยังช่วงการเรียนรู้

สร้างกลุ่มเป้าหมายที่กำหนดเอง

ขั้นตอนที่ 1: สร้างกลุ่มเป้าหมายที่กำหนดเองแบบว่างเปล่า

ระบุ subtype=CUSTOM และ customer_file_source ในการเรียกใช้ API ของคุณ

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', })

พารามิเตอร์

ชื่อคำอธิบาย

customer_file_source
สตริง enum

อธิบายว่าข้อมูลลูกค้าในกลุ่มเป้าหมายที่กำหนดเองของคุณได้รับการรวบรวมอย่างไรในตอนแรก
ค่า:

  • USER_PROVIDED_ONLY
    ผู้ลงโฆษณารวบรวมข้อมูลจากลูกค้าโดยตรง
  • PARTNER_PROVIDED_ONLY
    ผู้ลงโฆษณาค้นหาข้อมูลจากพาร์ทเนอร์โดยตรง (เช่น ตัวแทนหรือผู้ให้บริการข้อมูล)
  • BOTH_USER_AND_PARTNER_PROVIDED
    ผู้ลงโฆษณารวบรวมข้อมูลจากลูกค้าโดยตรง และยังเป็นข้อมูลที่ได้รับมาจากพาร์ทเนอร์อีกด้วย (เช่น ตัวแทน)

name
สตริง

ชื่อกลุ่มเป้าหมายที่กำหนดเอง

description
สตริง

คำอธิบายกลุ่มเป้าหมายที่กำหนดเอง

subtype
สตริง

ประเภทของกลุ่มเป้าหมายที่กำหนดเอง

ขั้นตอนที่ 2: ระบุรายชื่อผู้ใช้

ใช้การเรียกใช้ API POST ไปยังตำแหน่งข้อมูล /{audience_id}/users เพื่อระบุรายชื่อผู้ใช้ที่คุณต้องการเพิ่มลงในกลุ่มเป้าหมายที่กำหนดเอง

พารามิเตอร์

ชื่อคำอธิบาย

session
อ็อบเจ็กต์ JSON

จำเป็นต้องระบุ
ใช้พารามิเตอร์ session เพื่อติดตามว่ามีการอัพโหลดกลุ่มผู้ใช้แบตช์ใดแบตช์หนึ่งหรือไม่
หากการอัพโหลดของคุณมีผู้ใช้มากกว่า 10,000 ราย คุณต้องแยกผู้ใช้ออกเป็นแบตช์ต่างๆ โดยแต่ละคำขอสามารถรองรับผู้ใช้ได้สูงสุด 10,000 ราย


ตัวอย่าง

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

payload
อ็อบเจ็กต์ JSON

จำเป็นต้องระบุ
ระบุ schema และ data เอาไว้ด้วย

ตัวอย่าง

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

ตัวเลือกการประมวลผลข้อมูลสำหรับผู้ใช้ในสหรัฐฯ

หากคุณต้องการเปิดใช้งาน "การใช้ข้อมูลแบบจำกัด" สำหรับผู้คนที่อยู่ในรัฐแคลิฟอร์เนียผ่านกลุ่มเป้าหมายที่กำหนดเองจากรายชื่อลูกค้าตั้งแต่วันที่ 1 มิถุนายน 2023 เป็นต้นไป คุณจะต้องอัพโหลดกลุ่มเป้าหมายใหม่หรืออัพเดตกลุ่มเป้าหมายที่มีอยู่ของคุณให้มีแฟล็ก "การใช้ข้อมูลแบบจำกัด" โดยคุณสามารถอัพเดตและรักษาสถานะ "การใช้ข้อมูลแบบจำกัด" ของกลุ่มเป้าหมายและผู้คนได้อย่างสม่ำเสมอตามที่ต้องการ

โปรดทราบว่าแฟล็ก "การใช้ข้อมูลแบบจำกัด" ที่ใช้กับผู้ใช้ในกลุ่มเป้าหมายหนึ่งจะไม่มีผลกับกลุ่มเป้าหมายอื่นๆ โดยอัตโนมัติ ในทำนองเดียวกัน ผู้ลงโฆษณาต้องจัดการกลุ่มเป้าหมายที่กำหนดเองจากรายชื่อลูกค้าแต่ละกลุ่มที่มีอยู่แบบแยกกันตามเกณฑ์ที่ตนเลือก โดยจะต้องใช้แฟล็ก "การใช้ข้อมูลแบบจำกัด" แบบแยกกันกับกลุ่มเป้าหมายแต่ละกลุ่มที่ตนใช้ในการโฆษณา

หากต้องการไม่เปิดใช้งาน LDU อย่างชัดแจ้งสำหรับรายการข้อมูล คุณสามารถส่งอาร์เรย์ data_processing_options ว่างหรือลบช่องในเพย์โหลดออก ตัวอย่างอาร์เรย์ว่าง:

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

หากต้องการไม่เปิดใช้งาน LDU อย่างชัดแจ้งและให้ Meta ทำการระบุตำแหน่งทางภูมิศาสตร์ (โดยไม่รวมรัฐและประเทศของรายการข้อมูลนั้นๆ) ให้ระบุอาร์เรย์ที่มี LDU สำหรับรายการข้อมูลแต่ละรายการ:

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

หากต้องการเปิดใช้งาน 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

ชื่อคำอธิบาย

session_id
จำนวนเต็มบวก 64 บิต

จำเป็นต้องระบุ
ตัวระบุที่ใช้ในการติดตามเซสชั่น จำนวนนี้จะต้องสร้างขึ้นโดยผู้ลงโฆษณา และต้องไม่ซ้ำกันภายในบัญชีโฆษณานั้นๆ

batch_seq
จำนวนเต็มบวก

จำเป็นต้องระบุ
ตัวเลขที่ระบุคำขอที่แสดงในเซสชั่นปัจจุบัน โดยตัวเลขนี้จะต้องเรียงตามลำดับและเริ่มจาก 1

last_batch_flag
บูลีน

จำเป็นต้องระบุ

ระบุให้ระบบของเราทราบว่าคุณได้ระบุแบตช์ครบทั้งหมดแล้วสำหรับเซสชั่นการแทนที่ซึ่งกำลังดำเนินอยู่ เมื่อตั้งค่าเป็น true แสดงว่าคำขอปัจจุบันเป็นคำขอล่าสุดจากเซสชั่นปัจจุบัน และเราจะไม่ยอมรับแบตช์ใดๆ เพิ่มเติมสำหรับเซสชั่นนั้นๆ แต่หากคุณไม่ส่งแฟล็กนี้ เราจะยุติเซสชั่นดังกล่าวโดยอัตโนมัติหลังจากที่เราได้รับแบตช์แรกของคุณไปแล้ว 90 นาที โดยระบบจะทิ้งแบตช์ทั้งหมดที่ได้รับหลังพ้นช่วง 90 นาทีไปแล้วเช่นกัน คุณต้องทำเครื่องหมายกำกับคำขอล่าสุดเพื่อให้ Meta รู้ว่าคำขอนั้นเป็นแบตช์ล่าสุด

estimated_num_total
จำนวนเต็ม

ระบุหรือไม่ก็ได้
จำนวนผู้ใช้ทั้งหมดโดยประมาณที่จะอัพโหลดในเซสชั่นนี้ ช่องนี้ใช้เพื่อปรับปรุงการประมวลผลของเซสชั่นนี้

การตอบกลับ

การตอบกลับที่สำเร็จจะมีอ็อบเจ็กต์ JSON พร้อมช่องต่อไปนี้

ชื่อคำอธิบาย

audience_id
สตริงตัวเลข

ตัวระบุกลุ่มเป้าหมาย

session_id
จำนวนเต็ม

ID เซสชั่นที่คุณส่งไป

num_received
จำนวนเต็ม

จำนวนผู้ใช้ทั้งหมดที่ได้รับในเซสชั่นนี้จนถึงปัจจุบัน

num_invalid_entries
จำนวนเต็ม

จำนวนรายการที่ส่งซึ่งมีการแฮชไม่ถูกต้อง รายการเหล่านั้นไม่ส่งคืนรายการจับคู่ที่ตรงกัน และระบบจะไม่เพิ่มลงในกลุ่มเป้าหมายที่กำหนดเอง ตัวเลขนี้ไม่ใช่จำนวนที่แน่นอน แต่แสดงถึงช่วงจำนวนของผู้ใช้ที่ไม่สามารถจับคู่ได้

invalid_entry_samples
อาร์เรย์ JSON ของสตริงหรือการแมป {string: string}

รายการที่ไม่ถูกต้องสูงสุด 100 ตัวอย่างที่พบในคำขอปัจจุบัน

เรียนรู้เพิ่มเติมเกี่ยวกับการแชร์กลุ่มเป้าหมายที่กำหนดเองของคุณด้วยอ็อบเจ็กต์ธุรกิจ

ลบสมาชิกของกลุ่มเป้าหมาย

ใช้การเรียกใช้ API DELETE ไปยังตำแหน่งข้อมูล /{audience_id}/users เพื่อระบุรายชื่อผู้ใช้ที่คุณต้องการลบออกจากกลุ่มเป้าหมายที่กำหนดเอง

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

หรือคุณอาจเพิ่มพารามิเตอร์ method และตั้งค่าเป็น DELETE ในคำขอ POST ที่ใช้ในการเพิ่มสมาชิกของกลุ่มเป้าหมายก็ได้

คุณสามารถลบผู้คนออกจากรายการได้ด้วย EXTERN_ID (หากใช้งานได้)

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

คุณสามารถลบรายชื่อผู้คนออกจากกลุ่มเป้าหมายที่กำหนดเองทั้งหมดในบัญชีโฆษณาของคุณได้โดยใช้ตำแหน่งข้อมูลนี้

การที่ระบบไม่ประมวลผลข้อมูลนี้อาจเกิดจากสาเหตุบางประการ เช่น หากบัญชีโฆษณาไม่ได้เป็นของบัญชีธุรกิจ แสดงว่าคุณยังไม่ได้ยอมรับข้อกำหนดของกลุ่มเป้าหมายที่กำหนดเอง หรือข้อมูลดังกล่าวไม่ตรงกับผู้ใช้

หากต้องการลบบัญชีในศูนย์บัญชี ให้ใส่ช่องเดียวกันกับที่อยู่ในการอัพเดตผู้ใช้และทำการเรียกใช้ HTTP DELETE ไปยัง

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

การจับคู่แบบหลายคีย์

หากต้องการเพิ่มอัตราการตรงกันสำหรับรายการบันทึกของคุณ ให้ระบุหลายๆ คีย์ในรูปแบบอาร์เรย์ของคีย์เดี่ยว เช่น [EXTERN_ID, LN, FN, EMAIL] แม้ว่าคุณไม่ต้องแฮช EXTERN_ID แต่คุณจะต้องแฮชข้อมูลระบุตัวบุคคลทั้งหมด เช่น อีเมลและชื่อ โปรดดูรายละเอียดที่การแฮชข้อมูลและการทำข้อมูลให้เป็นมาตรฐาน

คุณสามารถระบุคีย์แบบหลายคีย์เป็นบางส่วนหรือทั้งหมดสำหรับรายการข้อมูลได้ โปรดดูรายละเอียดที่การจับคู่ ID ภายนอกแบบหลายคีย์

เพิ่มผู้ใช้ด้วยการจับคู่แบบหลายคีย์

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

การใช้ PAGEUID

หากคุณใช้คีย์ PAGEUID คุณจะต้องระบุรายการ ID ของเพจด้วย คุณสามารถส่ง PAGEUID ให้กับเราได้เพียงรายการเดียวเท่านั้น โดยควรเป็นอาร์เรย์ที่มีองค์ประกอบเดียว

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

การแฮชและการปรับให้เป็นมาตรฐานสำหรับคีย์แบบหลายคีย์

คุณต้องแฮชข้อมูลให้เป็น SHA256 เนื่องจากเราไม่รองรับกลไกการแฮชรูปแบบอื่น ข้อมูลทั้งหมดจำเป็นต้องผ่านกระบวนการดังกล่าวยกเว้นตัวระบุจากภายนอก, ID ผู้ใช้แอพ, ID ผู้ใช้ในเพจ และ ID ผู้โฆษณาบนมือถือ

ก่อนแฮชข้อมูลของคุณ โปรดทำข้อมูลให้เป็นมาตรฐานก่อนเพื่อที่เราจะได้รองรับข้อมูลนั้นได้ เฉพาะชื่อ (FN) และนามสกุล (LN) เท่านั้นที่รองรับอักขระพิเศษและตัวอักษรที่ไม่ใช่ตัวอักษรโรมัน โปรดแปลเป็นตัวอักษรโรมันแบบไม่มีอักขระพิเศษเพื่อให้ได้ผลลัพธ์การจับคู่ที่ดีที่สุด

โปรดดาวน์โหลดไฟล์ CSV นี้

หากต้องการดูตัวอย่างข้อมูลที่แฮชและทำให้เป็นมาตรฐานอย่างเหมาะสมสำหรับพารามิเตอร์ด้านล่าง



ดาวน์โหลด (คลิกขวา > บันทึกลิงก์เป็น)
คีย์แนวทาง

EMAIL
เกณฑ์: อีเมล

ต้องมีการแฮช
ตัดช่องว่างด้านหน้าและด้านหลังออกและแปลงอักขระทั้งหมดเป็นตัวพิมพ์เล็ก

PHONE
เกณฑ์: หมายเลขโทรศัพท์

ต้องมีการแฮช
ลบสัญลักษณ์ ตัวอักษร และเลขศูนย์ที่อยู่นำหน้าออก คุณควรใส่รหัสประเทศไว้ด้านหน้า หากไม่มีการระบุช่อง COUNTRY

GEN
เกณฑ์: เพศ

ต้องมีการแฮช
ใช้ค่าเหล่านี้: m สำหรับเพศชายและ f สำหรับเพศหญิง

DOBY
เกณฑ์: ปีเกิด

ต้องมีการแฮช
ใช้รูปแบบ ปปปป: 1900 ถึงปีปัจจุบัน

DOBM
เกณฑ์: เดือนเกิด

ต้องมีการแฮช
ใช้รูปแบบ ดด: 01 ถึง 12

DOBD
เกณฑ์: วันเกิด

ต้องมีการแฮช
ใช้รูปแบบ วว: 01 ถึง 31

LN และ FN
เกณฑ์: นามสกุลและชื่อ

ต้องมีการแฮช
ใช้ a-z เท่านั้น ตัวพิมพ์เล็กเท่านั้น ไม่ใช้เครื่องหมายวรรคตอน และอักขระพิเศษในรูปแบบ UTF-8

FI
เกณฑ์: อักษรขึ้นต้นของชื่อ

ต้องมีการแฮช
ใช้ a-z เท่านั้น ตัวพิมพ์เล็กเท่านั้น และอักขระพิเศษในรูปแบบ UTF-8

ST
เกณฑ์: รัฐในสหรัฐฯ

ต้องมีการแฮช
ใช้รหัสย่อ ANSI ที่มี 2 อักขระ โดยเป็นตัวพิมพ์เล็ก ปรับชื่อรัฐที่อยู่นอกสหรัฐฯ ให้เป็นมาตรฐานโดยใช้ตัวพิมพ์เล็ก ไม่มีเครื่องหมายวรรคตอน ไม่มีอักขระพิเศษ และไม่มีการเว้นวรรค

CT
เกณฑ์: เมือง

ต้องมีการแฮช
ใช้ a-z เท่านั้น ตัวพิมพ์เล็กเท่านั้น ไม่มีเครื่องหมายวรรคตอน ไม่มีอักขระพิเศษ และไม่เว้นช่องว่าง

ZIP
เกณฑ์: รหัสไปรษณีย์

ต้องมีการแฮช
ใช้ตัวพิมพ์เล็กและไม่เว้นช่องว่าง สำหรับสหรัฐฯ ให้ใช้เฉพาะตัวเลข 5 หลักแรก สำหรับสหราชอาณาจักร ให้ใช้รูปแบบพื้นที่/เขต/ภาคส่วน

COUNTRY
เกณฑ์: รหัสประเทศ

ต้องมีการแฮช

ใช้รหัสประเทศตัวพิมพ์เล็ก 2 ตัวอักษรตามมาตรฐาน ISO 3166-1 alpha-2

MADID
เกณฑ์: ID ผู้ลงโฆษณาบนมือถือ

ไม่จำเป็นต้องมีการแฮช

ใช้ตัวพิมพ์เล็กทั้งหมดและเก็บขีดกลางไว้

การแฮช

ระบุค่า SHA256 ให้กับคีย์มาตรฐานและการแทนรหัส HEX ของค่านี้ โดยใช้ตัวพิมพ์เล็กสำหรับ A ถึง F ทั้งนี้ ฟังก์ชั่นแฮชใน PHP จะแปลงอีเมลและหมายเลขโทรศัพท์ที่ผ่านการทำให้เป็นมาตรฐานแล้ว

ตัวอย่างผลลัพธ์

hash("sha256", "mary@example.com")

f1904cf1a9d73a55fa5de0ac823c4403ded71afd4c3248d00bdcd0866552bb79

hash("sha256", "15559876543")

1ef970831d7963307784fa8688e8fce101a15685d62aa765fed23f3a2c576a4e

ตัวระบุจากภายนอก

คุณสามารถจับคู่ผู้คนสำหรับกลุ่มเป้าหมายได้ด้วยตัวระบุของคุณเอง หรือที่เรียกว่าตัวระบุจากภายนอก (EXTERN_ID) ซึ่งอาจเป็น ID ที่ไม่ซ้ำกันจากผู้ลงโฆษณา เช่น ID สมาชิกที่เหนียวแน่น, ID ผู้ใช้ และ ID คุกกี้ภายนอก

แม้ว่าคุณจะไม่จำเป็นต้องแฮช ID นี้ แต่คุณจะต้องแฮชข้อมูลระบุตัวบุคคล (PII) ทั้งหมดที่คุณส่งไปกับ EXTERN_ID

คุณควรใช้รูปแบบเดียวกันกับที่คุณใช้ส่ง ID ทุกประการเพื่อให้จับคู่ได้ดียิ่งขึ้น เช่น หากคุณเลือกแฮชโดยใช้ SHA256 โปรดตรวจสอบให้แน่ใจว่าได้ใช้ค่าเดียวกันที่ผ่านการแฮชแล้ว

คุณสามารถใช้ ID เหล่านี้เป็นคีย์เดี่ยวเพื่อลบผู้คนออกจากกลุ่มเป้าหมายที่กำหนดเองหรือสร้างกลุ่มเป้าหมายที่กำหนดเองใหม่ก็ได้ วิธีการนี้ช่วยให้คุณไม่จำเป็นต้องอัพโหลดคีย์อื่นๆ ที่ตรงกันอีกครั้ง หากคุณแท็กบุคคลด้วยข้อมูลส่วนตัวที่แฮชไว้และ EXTERN_ID เราจะให้ความสำคัญกับ EXTERN_ID น้อยกว่า เมื่อเรานำไปจับคู่กับผู้คนบน Facebook

ระยะเวลาการเก็บรักษาข้อมูลสำหรับ EXTERN_ID คือ 90 วัน

คุณสามารถใช้การแมป EXTERN_ID ซ้ำเพื่อสร้างกลุ่มเป้าหมายที่กำหนดเองจากไฟล์ของลูกค้าได้ภายในบัญชีโฆษณาเดียว

หากคุณมีกลุ่มเป้าหมายสำหรับช่อง EXTERN_ID ในบัญชีโฆษณาของคุณ ให้สร้างกลุ่มเป้าหมายใหม่โดยใช้เพียงตัวระบุเหล่านี้

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

นอกจากนั้น คุณยังสามารถเพิ่มผู้คนที่มีการแท็ก EXTERN_ID และมีการจับคู่แบบหลายคีย์ได้อีกด้วย

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

เรารองรับพารามิเตอร์ EXTERN_ID สำหรับแต่ละบัญชีโฆษณา โดยเราไม่สามารถใช้ค่าต่างๆ ในบัญชีโฆษณาหนึ่งกับบัญชีโฆษณาอื่นได้ แม้ว่าบัญชีดังกล่าวจะเป็นของบุคคลเดียวกันก็ตาม

API การแทนที่ผู้ใช้

ตำแหน่งข้อมูล /<CUSTOM_AUDIENCE_ID>/usersreplace ช่วยให้คุณสามารถดำเนินการ 2 อย่างในการเรียกใช้ API ครั้งเดียวได้ดังนี้

  • ลบผู้ใช้ที่มีอยู่ออกจากกลุ่มเป้าหมายที่ต้องการทั้งหมด
  • แทนที่ผู้ใช้เหล่านั้นด้วยผู้ใช้กลุ่มใหม่

การใช้ตำแหน่งข้อมูล /<CUSTOM_AUDIENCE_ID>/usersreplace ช่วยให้คุณสามารถลบผู้ใช้ที่มีอยู่ทั้งหมดได้โดยอัตโนมัติ แทนที่จะต้องอัพโหลดรายชื่อผู้ใช้ที่คุณต้องการลบ ตำแหน่งข้อมูลนี้จะไม่รีเซ็ตช่วงการเรียนรู้ของชุดโฆษณาของคุณเมื่อกลุ่มเป้าหมายเป็นส่วนหนึ่งของชุดโฆษณาที่ทำงานอยู่ ซึ่งแตกต่างจากการเรียกใช้ API POST หรือ DELETE ไปยังตำแหน่งข้อมูล /<CUSTOM_AUDIENCE_ID>/users

API การแทนที่ผู้ใช้จะใช้ได้เฉพาะกับกลุ่มเป้าหมายที่ตรงตามข้อกำหนดต่อไปนี้:

  • จำนวนผู้ใช้ที่มีอยู่ก่อนเริ่มกระบวนการแทนที่ต้องน้อยกว่า 100 ล้านราย หากกลุ่มเป้าหมายของคุณมีมากกว่า 100 ล้านราย เราขอแนะนำให้ใช้ตำแหน่งข้อมูล /<CUSTOM_AUDIENCE_ID>/users เพื่อเพิ่มและลบผู้ใช้
  • ประเภทย่อยต้องได้รับการตั้งค่าเป็น CUSTOM
  • คุณไม่สามารถแทนที่กลุ่มเป้าหมายที่กำหนดเองจากไฟล์ของลูกค้าแบบอิงตามค่าด้วยกลุ่มเป้าหมายที่กำหนดเองจากไฟล์ของลูกค้าแบบไม่ได้อิงตามค่า หรือแทนที่สลับกันได้

เริ่มต้น

ก่อนที่คุณจะเริ่มกระบวนการแทนที่ เราขอแนะนำให้ดำเนินการดังต่อไปนี้

  • ตรวจสอบให้แน่ใจว่า operation_status ของกลุ่มเป้าหมายของคุณเป็น Normal

คุณไม่สามารถดำเนินการแทนที่ได้ หากมีการแทนที่รายการหนึ่งกำลังดำเนินการอยู่แล้ว

  • อย่าเพิ่มหรือลบผู้ใช้ผ่าน /<CUSTOM_AUDIENCE_ID>/users ในระหว่างที่กำลังดำเนินการแทนที่ผ่าน /<CUSTOM_AUDIENCE_ID>/usersreplace หากคุณลองดำเนินการแทนที่ครั้งที่ 2 ก่อนที่การดำเนินการครั้งแรกจะเสร็จสมบูรณ์ คุณจะได้รับข้อความแจ้งว่ากำลังมีการดำเนินการแทนที่อยู่

  • ช่วงระยะเวลาสูงสุดของเซสชั่นการแทนที่ครั้งที่ 1 จะอยู่ที่ 90 นาที โดย API จะปฏิเสธแบตช์ทั้งหมดสำหรับเซสชั่นหนึ่งๆ ที่ได้รับหลังพ้นช่วง 90 นาทีนับตั้งแต่ที่เริ่มเซสชั่นไปแล้ว หากคุณจำเป็นต้องส่งแบตช์ต่างๆ เป็นเวลานานกว่า 90 นาที ให้รอจนกว่าการดำเนินการแทนที่สำหรับเซสชั่นนั้นๆ จะเสร็จสิ้น จากนั้นให้ใช้การดำเนินการเพิ่มของตำแหน่งข้อมูล /<CUSTOM_AUDIENCE>/users เพื่ออัพโหลดส่วนที่เหลือของคุณ

  • เมื่อมีกลุ่มเป้าหมายพร้อมแล้ว โปรดระบุรายชื่อผู้ใช้ที่คุณต้องการแทนที่ด้วยกลุ่มเป้าหมายที่กำหนดเองโดยใช้การเรียกใช้ POST ไปยัง /<CUSTOM_AUDIENCE_ID>/usersreplace

    • เมื่อคุณเริ่มดำเนินการแทนที่แล้ว operation_status ของกลุ่มเป้าหมายของคุณจะเปลี่ยนเป็น replace_in_progress
    • หากการดำเนินการแทนที่ของคุณไม่เสร็จสมบูรณ์ operation_status ของกลุ่มเป้าหมายของคุณจะเปลี่ยนเป็น replace_error

พารามิเตอร์สำหรับการเรียก

คุณสามารถใส่พารามิเตอร์ต่อไปนี้ในการเรียก POST ไปยัง /<CUSTOM_AUDIENCE_ID>/usersreplace ได้:

ชื่อคำอธิบาย

session

ประเภท: อ็อบเจ็กต์ JSON

จำเป็นต้องระบุ

ใช้เพื่อติดตามว่ามีการอัพโหลดกลุ่มผู้ใช้ที่ระบุหรือไม่ ต้องมี ID เซสชั่นและข้อมูลของกลุ่ม โปรดดูช่องเซสชั่น


คุณสามารถเพิ่มจำนวนผู้คนไปยังกลุ่มเป้าหมายได้สูงสุด 10,000 รายภายในช่วงเวลาที่กำหนด หากคุณมีจำนวนผู้คนมากกว่า 10,000 ราย ให้แบ่งเซสชั่นของคุณออกเป็นหลายๆ แบตช์ ซึ่งทั้งหมดควรมี ID เซสชั่นจำนวน 1 ID


ตัวอย่าง:

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

payload

ประเภท: อ็อบเจ็กต์ JSON

จำเป็นต้องระบุ

ใช้เพื่อระบุข้อมูลที่คุณต้องการอัพโหลดไปยังกลุ่มเป้าหมายของคุณ โดยต้องมีสกีมาและข้อมูล โปรดดูข้อมูลเพิ่มเติมที่ช่องเพย์โหลด


ตัวอย่าง:

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

ช่องเซสชั่น

ชื่อคำอธิบาย

session_id

ประเภท: จำนวนเต็ม 64 บิต

จำเป็นต้องระบุ

ใช้เพื่อติดตามเซสชั่น คุณต้องสร้างตัวระบุนี้และหมายเลขจะต้องไม่ซ้ำกันภายในบัญชีโฆษณาเดียวกัน

batch_seq

ประเภท: จำนวนเต็ม

จำเป็นต้องระบุ ต้องเริ่มที่ 1
เซสชั่นการแทนที่ใหม่จะเริ่มเมื่อเราได้รับ batch_seq ที่มีค่าเป็น 1 เราขอแนะนำว่าอย่าส่งแบตช์ที่ซ้ำกันและมีลำดับเป็น 1 สำหรับ session_id ที่กำหนด
การติดป้ายกำกับว่าเป็นแบตช์แรกนั้นมีความสำคัญ โดยแบตช์ที่เหลือของเซสชั่นสามารถซ้ำกันได้หรือมีลำดับใดก็ได้ยกเว้น 1 เนื่องจากเราใช้พารามิเตอร์นี้ในการระบุจุดเริ่มต้นของเซสชั่นดังกล่าว โดยคุณควรส่งแบตช์ที่ไม่ใช่ลำดับแรกทั้งหมดของเซสชั่นหลังจากแบตช์แรก เลือกกลุ่มแรกให้เป็นทริกเกอร์/ขั้นตอนเบื้องต้นสำหรับการดำเนินการแทนที่

last_batch_flag

ประเภท: บูลีน

ระบุหรือไม่ก็ได้

ระบุว่าคุณได้ระบุแบตช์ครบทั้งหมดแล้วสำหรับเซสชั่นการแทนที่ซึ่งกำลังดำเนินอยู่ เมื่อตั้งค่าเป็น true ระบบจะไม่ยอมรับแบตช์ใดๆ อีกสำหรับเซสชั่นนั้นๆ แต่หากคุณไม่ตั้งค่าแฟล็กนี้ ระบบจะยุติเซสชั่นดังกล่าวโดยอัตโนมัติหลังจากที่ได้รับแบตช์แรกไปแล้ว 90 นาที โดยระบบจะทิ้งแบตช์ทั้งหมดที่ได้รับหลังพ้นช่วง 90 นาทีไปแล้วเช่นกัน

estimated_num_total

ประเภท: จำนวนเต็ม

ระบุหรือไม่ก็ได้

จำนวนผู้ใช้ทั้งหมดโดยประมาณที่จะอัพโหลดในเซสชั่นนี้ ระบบของเรานำมาใช้เพื่อปรับปรุงการประมวลผลของเซสชั่น

ช่องเพย์โหลด

ชื่อคำอธิบาย

schema

ประเภท: สตริงหรือ JSON_Array_of_string

จำเป็นต้องระบุ

ระบุประเภทข้อมูลที่คุณจะใส่ ซึ่งอาจเป็นคีย์เดียวหรือหลายคีย์จากรายการต่อไปนี้

  • EMAIL
  • PHONE
  • GEN
  • DOBY
  • DOBM
  • DOBD
  • LN
  • FN
  • FI
  • CT
  • ST
  • ZIP
  • COUNTRY
  • MADID
  • ["hash1", "hash2", ...] ตัวอย่างเช่น ["PHONE", "LN”, “FN”, “ZIP”, “DOBYM"]

data

ประเภท: JSON_Array

จำเป็นต้องระบุ

รายการข้อมูลที่สอดคล้องกับ schema


ตัวอย่าง:

  • หากสกีมาเป็น "EMAIL" ข้อมูลควรเป็นรายการแฮชแบบ sha256 ของอีเมล
  • หากสกีมาเป็นรายการแฮชตามตัวอย่างก่อนหน้า ข้อมูลควรเป็นแบบ "phone_hash_value" และ "LN_FN_ZIP_DOBYM"

เมื่อคุณส่งคำขอ POST คุณจะได้รับการตอบกลับที่มีช่องต่อไปนี้

ชื่อคำอธิบาย

account_id

ประเภท: จำนวนเต็ม

ตัวระบุบัญชี

session_id

ประเภท: จำนวนเต็ม

ID เซสชั่นที่คุณระบุไว้ก่อนหน้านี้

num_received

ประเภท: จำนวนเต็ม

จำนวนผู้ใช้ทั้งหมดที่ได้รับในเซสชั่นนี้จนถึงปัจจุบัน

num_invalid_entries

ประเภท: จำนวนเต็ม

จำนวนผู้ใช้ทั้งหมดที่มีรูปแบบไม่ถูกต้องหรือไม่สามารถนำมาถอดรหัสได้ หากจำนวนนี้ไม่ใช่ 0 โปรดตรวจสอบข้อมูลของคุณอีกครั้ง

invalid_entry_samples ประเภท: อาร์เรย์สตริง JSON

คำขอปัจจุบันมีรายการที่ไม่ถูกต้องสูงถึง 100 ตัวอย่าง โปรดตรวจสอบข้อมูลของคุณอีกครั้ง

ข้อผิดพลาดที่พบบ่อยของ API การแทนที่

ข้อผิดพลาดทั้งหมดที่ตำแหน่งข้อมูลการแทนที่ส่งคืนมานั้นจะมีรหัสข้อผิดพลาด 2650 อยู่ ต่อไปนี้เป็นรหัสย่อยบางส่วนของข้อผิดพลาดต่างๆ ที่พบบ่อยที่สุดซึ่งระบบจะส่งคืนมา รวมถึงแนวทางในการแก้ไขปัญหาเหล่านี้

รหัสย่อยของข้อผิดพลาดคำอธิบายสิ่งที่ต้องดำเนินการ

1870145

การอัพเดตกลุ่มเป้าหมายอยู่ระหว่างดำเนินการ

คุณไม่สามารถแทนที่กลุ่มเป้าหมายที่กำหนดเองจากรายชื่อลูกค้าซึ่งกำลังอยู่ระหว่างการอัพเดตได้ โปรดรอให้กลุ่มเป้าหมายมีความพร้อมใช้งานเป็น "ปกติ" แล้วค่อยลองอีกครั้ง

1870158

เซสชั่นการแทนที่หมดเวลาแล้ว

เซสชั่นการแทนที่แบตช์ของคุณใช้เวลาครบ 90 นาทีตามที่กำหนดไว้แล้ว ระบบจะแทนที่กลุ่มเป้าหมายที่กำหนดเองจากรายชื่อลูกค้าของคุณด้วยข้อมูลเท่าที่คุณอัพโหลดมาจนถึงตอนนี้ หากต้องการเพิ่มข้อมูลเพิ่มเติมในกลุ่มเป้าหมายที่กำหนดเอง ให้รอจนกว่ากระบวนการแทนที่จะเสร็จสิ้น แล้วใช้การดำเนินการ ADD

1870147

การอัพโหลดแบตช์สำหรับการแทนที่ไม่ถูกต้อง

batch_seq รายการแรกไม่ได้ถูกลบออก คุณจะต้องเริ่ม batch_seq จากจำนวนเต็ม 1

1870159

เซสชั่นการแทนที่เสร็จสิ้นแล้ว

การดำเนินการแทนที่เสร็จสิ้นไปแล้ว เนื่องจากอัพโหลดแบตช์ที่มี last_batch_flag==true หากต้องการเพิ่มแบตช์เพิ่มเติมในกลุ่มเป้าหมายที่กำหนดเอง ให้รอจนกว่ากระบวนการแทนที่จะเสร็จสิ้น แล้วใช้การดำเนินการ ADD

1870148

เกิดข้อผิดพลาด

รายชื่อลูกค้าของคุณไม่ได้รับการอัพเดตโดยสมบูรณ์ หากกลุ่มเป้าหมายของคุณมีขนาดต่างจากที่คาดไว้มาก โปรดลองใหม่อีกครั้ง

1870144

ระบบไม่รองรับขนาดของ DFCA สำหรับการแทนที่

คุณไม่สามารถแทนที่กลุ่มเป้าหมายที่กำหนดเองจากรายชื่อลูกค้า ซึ่งมีขนาดอยู่ที่ 100 ล้านรายหรือมากกว่านั้นได้

แหล่งข้อมูล

กลุ่มเป้าหมายประเภทอื่นๆ ที่คุณสามารถสร้างและกำหนดเป้าหมาย หรือแชร์ได้มีดังนี้