Đối tượng tùy chỉnh từ file khách hàng

Nhờ có API Marketing, bạn có thể tạo Đối tượng tùy chỉnh mục tiêu dựa trên thông tin khách hàng. Thông tin này bao gồm địa chỉ email, số điện thoại, tên, ngày sinh, giới tính, vị trí, ID người dùng ứng dụng, ID người dùng trong Trang, Mã nhận dạng quảng cáo của Apple (IDFA) hoặc ID quảng cáo của Android.

Bạn có thể thêm số lượng bản ghi không giới hạn cho một đối tượng. Tuy nhiên, mỗi lần bạn chỉ có thể thêm tối đa 10.000 bản ghi. Những thay đổi bạn thực hiện với Đối tượng tùy chỉnh không có hiệu lực ngay lập tức mà thường mất đến 24 giờ. Thời gian xử lý yêu cầu này tùy thuộc vào số lượng bản ghi bạn yêu cầu gỡ và/hoặc số lượng Đối tượng tùy chỉnh có trên tài khoản của bạn.

Để cải thiện cách nhà quảng cáo tạo và quản lý đối tượng của họ, những Đối tượng tùy chỉnh từ file khách hàng không được sử dụng trong bất kỳ nhóm quảng cáo đang hoạt động nào trong hơn 2 năm sẽ bị gắn cờ để xóa theo định kỳ. Bạn cần đưa ra hướng dẫn cho chúng tôi trước khi chúng tôi thực hiện bất kỳ hành động nào. Sau khi các đối tượng được chuyển sang giai đoạn "Đối tượng sắp hết hạn" và bị gắn cờ, bạn cần đưa ra hướng dẫn theo 2 cách: Thứ nhất là sử dụng đối tượng bị gắn cờ trong một nhóm quảng cáo đang hoạt động, chúng tôi sẽ xem đó là hướng dẫn giữ lại đối tượng này. Thứ hai là quyết định không sử dụng đối tượng bị gắn cờ trong một nhóm quảng cáo đang hoạt động, chúng tôi sẽ xem đó là hướng dẫn xóa đối tượng này. Để biết thêm thông tin, hãy xem tài liệu Tổng quan về Đối tượng tùy chỉnh.

Tạo Đối tượng tùy chỉnh

Bước 1: Tạo một Đối tượng tùy chỉnh trống

Chỉ định subtype=CUSTOM và customer_file_source trong lệnh gọi API của bạn.

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

Thông số

Bước 2: Chỉ định danh sách người dùng

Để chỉ định danh sách người dùng mà bạn muốn thêm vào Đối tượng tùy chỉnh, hãy gửi lệnh gọi API POST đến điểm cuối /{audience_id}/users.

Thông số

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

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

Tùy chọn xử lý dữ liệu cho người dùng tại Hoa Kỳ

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

Trường session

Phản hồi

Nếu thành công, phản hồi sẽ bao gồm đối tượng JSON cùng với các trường sau đây:

Hãy tìm hiểu thêm về cách chia sẻ Đối tượng tùy chỉnh của bạn với các đối tượng kinh doanh.

Xóa thành viên trong đối tượng

Để chỉ định danh sách người dùng bạn muốn xóa khỏi Đối tượng tùy chỉnh, hãy gửi lệnh gọi API DELETE đến điểm cuối /{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

Hoặc bạn có thể thêm thông số method rồi đặt thông số đó thành DELETE trong yêu cầu POST dùng để thêm thành viên vào đối tượng.

Bạn có thể xóa mọi người khỏi một danh sách với EXTERN_ID, nếu có.

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

Bạn có thể dùng điểm cuối này để xóa danh sách người dùng khỏi tất cả đối tượng tùy chỉnh trên tài khoản quảng cáo của bạn.

Có một số lý do khiến thông tin này không được xử lý. Chẳng hạn như trường hợp tài khoản quảng cáo không thuộc sở hữu của tài khoản kinh doanh, bạn chưa chấp nhận Điều khoản về Đối tượng tùy chỉnh hoặc thông tin không khớp với người dùng.

Để gỡ một tài khoản trong Trung tâm tài khoản, hãy thêm các trường giống như trong phần cập nhật người dùng và gửi lệnh gọi HTTP DELETE đến:

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

So khớp nhiều khóa

Để tăng tỷ lệ khớp cho các bản ghi của bạn, hãy cung cấp nhiều khóa trong một mảng gồm các khóa riêng lẻ, chẳng hạn như [EXTERN_ID, LN, FN, EMAIL]. Mặc dù không cần băm EXTERN_ID, nhưng bạn phải băm mọi thông tin nhận dạng cá nhân, chẳng hạn như email và tên. Để biết thông tin chi tiết, hãy xem phần Băm và chuẩn hóa dữ liệu.

Bạn có thể cung cấp một số hoặc tất cả các lần khớp nhiều khóa cho một bản ghi. Để biết thông tin chi tiết, hãy xem phần khớp id bên ngoài gồm nhiều khóa.

Thêm người dùng bằng cách so khớp nhiều khóa

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

Sử dụng PAGEUID

Nếu sử dụng khóa PAGEUID, bạn cũng phải thêm danh sách ID trang. Bạn chỉ có thể gửi cho chúng tôi một PAGEUID. Đây phải là mảng chứa một thành phần.

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

Băm và chuẩn hóa dữ liệu cho nhiều khóa

Bạn phải băm dữ liệu dưới dạng SHA256. Chúng tôi không hỗ trợ các cơ chế băm khác. Đây là yêu cầu bắt buộc đối với tất cả các dữ liệu, ngoại trừ Thông tin nhận dạng bên ngoài, ID người dùng ứng dụng, ID người dùng trên trang và ID nhà quảng cáo di động.

Hãy chuẩn hóa dữ liệu trước khi băm để chúng tôi có thể xử lý dữ liệu. Chỉ có Tên (FN) và Họ (LN) hỗ trợ các ký tự đặc biệt và không thuộc bảng chữ cái Latinh. Để có kết quả khớp tốt nhất, hãy cung cấp bản dịch theo bảng chữ cái Latinh mà không có ký tự đặc biệt.

Băm

Hãy cung cấp giá trị SHA256 cho các khóa đã chuẩn hóa và dạng HEX của giá trị này - sử dụng chữ thường cho các chữ cái từ A đến F. Hàm băm trong PHP sẽ chuyển đổi email và số điện thoại đã chuẩn hóa.

Thông tin nhận dạng bên ngoài

Bạn có thể so khớp mọi người cho một đối tượng bằng các thông tin nhận dạng riêng của mình, còn gọi là Thông tin nhận dạng bên ngoài (EXTERN_ID). Đây có thể là bất kỳ ID duy nhất nào nhận được từ nhà quảng cáo, chẳng hạn như ID thành viên trung thành, ID người dùng và ID cookie bên ngoài.

Để so khớp hiệu quả hơn, bạn cũng nên sử dụng cùng một định dạng khi gửi các ID này. Ví dụ: nếu bạn chọn băm bằng SHA256, hãy nhớ sử dụng chính giá trị đã băm này.

Bạn có thể sử dụng những ID này làm các khóa riêng lẻ để xóa mọi người khỏi Đối tượng tùy chỉnh hoặc tạo mới Đối tượng tùy chỉnh. Như vậy, bạn không cần tải lên lại bất kỳ khóa so khớp nào khác. Nếu bạn gắn thẻ ai đó bằng thông tin cá nhân đã băm và EXTERN_ID, chúng tôi sẽ ưu tiên ít hơn đối với EXTERN_ID khi khớp những thông tin đó với mọi người trên Facebook.

Bạn có thể sử dụng lại quy trình đối ghép EXTERN_ID để xây dựng đối tượng tùy chỉnh từ file khách hàng trong một tài khoản quảng cáo.

Nếu bạn có một đối tượng gồm các trường EXTERN_ID trong tài khoản quảng cáo của mình, hãy tạo một đối tượng mới chỉ bằng các thông tin nhận dạng sau đây.

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

Bạn cũng có thể thêm những người được gắn thẻ EXTERN_ID và thêm bằng cách so khớp nhiều khóa.

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 Thay thế người dùng

Với điểm cuối /<CUSTOM_AUDIENCE_ID>/usersreplace, bạn có thể thực hiện 2 hành động chỉ với 1 lệnh gọi API, đó là:

• Xóa hoàn toàn những người dùng hiện có khỏi một đối tượng cụ thể
• Thay thế những người dùng đó bằng nhóm người dùng mới.

Với điểm cuối /<CUSTOM_AUDIENCE_ID>/usersreplace, bạn có thể tự động xóa tất cả người dùng hiện có thay vì phải tải lên danh sách người dùng mà bạn muốn xóa. Điểm cuối này không đặt lại giai đoạn máy học của nhóm quảng cáo khi một đối tượng thuộc nhóm quảng cáo đang hoạt động khác với lệnh gọi API POST hoặc DELETE đến điểm cuối /<CUSTOM_AUDIENCE_ID>/users.

API Thay thế người dùng chỉ hoạt động với các đối tượng đáp ứng những yêu cầu sau đây:

• Số lượng người dùng hiện có trước khi chạy quy trình thay thế phải nhỏ hơn 100 triệu. Nếu đối tượng của bạn lớn hơn 100 triệu, bạn nên tận dụng điểm cuối /<CUSTOM_AUDIENCE_ID>/users để thêm và xóa người dùng.
• Loại phụ phải được đặt thành CUSTOM.
• Bạn không thể thay thế đối tượng tùy chỉnh theo giá trị từ file khách hàng bằng một đối tượng tùy chỉnh không theo giá trị từ file khách hàng hoặc ngược lại.

Bắt đầu

Trước khi bắt đầu quy trình thay thế, bạn nên:

• Đảm bảo operation_status của đối tượng là Normal.

• Không được thêm hoặc xóa người dùng thông qua /<CUSTOM_AUDIENCE_ID>/users trong khi một thao tác thay thế đang diễn ra thông qua /<CUSTOM_AUDIENCE_ID>/usersreplace. Nếu cố thực hiện một thao tác thay thế thứ hai trước khi hoàn tất thao tác đầu tiên, bạn sẽ nhận được thông báo cho biết thao tác thay thế đang diễn ra.

• Khoảng thời gian tối đa của 1 phiên thay thế là 90 phút. API này sẽ từ chối mọi lô tải lên của một phiên nhận được sau 90 phút kể từ khi phiên đó bắt đầu. Nếu cần gửi các lô trong khoảng thời gian lâu hơn 90 phút, bạn nên đợi cho đến khi thao tác thay thế của phiên đó hoàn tất, sau đó dùng thao tác thêm của điểm cuối /<CUSTOM_AUDIENCE>/users cho các quá trình tải lên còn lại.

• Sau khi đối tượng đã sẵn sàng, hãy chỉ định danh sách những người dùng bạn muốn thay thế bằng đối tượng tùy chỉnh thông qua lệnh gọi POST đến /<CUSTOM_AUDIENCE_ID>/usersreplace.

  • Sau khi bạn bắt đầu quá trình thay thế, operation_status của đối tượng sẽ chuyển thành replace_in_progress.
  • Nếu thao tác thay thế của bạn chưa hoàn tất, operation_status của đối tượng sẽ chuyển thành replace_error.

Các thông số trong lệnh gọi

Bạn có thể đưa các thông số sau vào lệnh gọi POST đến /<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>" ]
}

Trường thông tin phiên

Trường thông tin phần tải dữ liệu

Sau khi gửi yêu cầu POST, bạn sẽ nhận được phản hồi có các trường sau đây:

Lỗi thường gặp về API Thay thế

Tất cả lỗi mà điểm cuối Thay thế trả về đều có mã lỗi 2650. Dưới đây là mã phụ của một số lỗi thường gặp nhất được trả về, cũng như hướng dẫn cách khắc phục.

Thông tin và nguồn lực

Bạn có thể tạo và nhắm mục tiêu hoặc chia sẻ các loại đối tượng khác sau đây:

• Đối tượng tùy chỉnh từ trang web - Tạo một đối tượng dựa trên những người đã truy cập một trang cụ thể hoặc đã thực hiện hành động trên trang web của bạn. Hãy tạo một đối tượng dựa trên dữ liệu từ Meta Pixel trên trang web của bạn.

• Đối tượng tùy chỉnh từ ứng dụng di động - Tạo một đối tượng dựa trên những người sử dụng ứng dụng di động của bạn. Hãy tạo một đối tượng dựa trên dữ liệu từ Sự kiện trong ứng dụng.

• Đối tượng tương tự - Xác định những người bạn đã biết và quảng cáo cho những người tương tự trên ứng dụng Facebook.

• Đối tượng tùy chỉnh offline - Tạo một đối tượng dựa trên những người đã ghé thăm cửa hàng của bạn, đã gọi điện đến dịch vụ khách hàng hoặc thực hiện hành động thông qua các phương thức offline khác.

• Đối tượng tương tác với canvas - Tạo một đối tượng chứa bất kỳ người nào đã tương tác với Canvas của bạn.

Xem thêm

• Đối tượng tùy chỉnh
• Người dùng Đối tượng tùy chỉnh
• Phiên Đối tượng tùy chỉnh
• Điều khoản dịch vụ về Đối tượng tùy chỉnh