الجماهير المخصصة لملف العميل

تتيح لك API التسويق إنشاء جماهير مخصصة مستهدفة من معلومات العميل. يتضمن ذلك عناوين البريد الإلكتروني أو أرقام الهواتف أو الأسماء أو تواريخ الميلاد أو الجنس أو المواقع أو معرفات مستخدمي التطبيق أو معرفات المستخدمين على مستوى الصفحة أو معرفات إعلانات Apple‏ (IDFA) أو معرف إعلانات Android.

يمكنك إضافة عدد غير محدود من السجلات إلى الجمهور، ولكن بحد أقصى 10000 سجل في المرة الواحدة. لا تحدث التغييرات في "الجماهير المخصصة" لديك على الفور وتستغرق عادةً 24 ساعة كحد أقصى. وسيزيد عدد السجلات التي تطلب إزالتها و/أو عدد الجماهير المخصصة الذي يحتوي عليه حسابك من مقدار الوقت المُستغرق لمعالجة هذا الطلب.

لتحسين كيفية إنشاء المعلنين لجماهيرهم وإدارتها، سيتم تمييز الجماهير المخصصة لملف العميل التي لم يتم استخدامها في أي مجموعات إعلانية نشطة منذ أكثر من عامين للحذف على أساس مستمر. وستحتاج إلى تزويدنا بتعليماتك قبل أن نتخذ أي إجراء. بمجرد انتقال الجماهير إلى مرحلة "انتهاء صلاحية الجمهور" وتمييزها، ستحتاج إلى أن تقدم لنا تعليمات إما من خلال استخدام الجمهور الذي تم تمييزه في مجموعة إعلانية نشطة، وهو ما سنعتبره إحدى التعليمات التي تشير إلى الاحتفاظ بالجمهور أو من خلال اتخاذ قرار عدم استخدام الجمهور الذي تم تمييزه في أي مجموعة إعلانية نشطة، وهو ما سنعتبره إحدى التعليمات التي تشير إلى نية حذف الجمهور. لمزيد من المعلومات، اطّلع على وثائق نظرة عامة على الجماهير المخصصة.

إنشاء جمهور مخصص

الخطوة الأولى: إنشاء جمهور مخصص فارغ

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

المعلمات

الخطوة الثانية: تحديد قائمة المستخدمين

استخدم استدعاء API POST/{audience_id}/users إلى نقطة النهاية لتحديد قائمة المستخدمين التي تريد إضافتها إلى الجمهور المخصص.

المعلمات

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

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

خيارات معالجة البيانات لمستخدمي الولايات المتحدة

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

الاستجابة

تتضمن الاستجابة الناجحة كائنًا بلغة JSON مع الحقول التالية:

تعرف على المزيد حول مشاركة الجمهور المخصص مع كائنات الأنشطة التجارية.

إزالة أعضاء الجمهور

استخدم استدعاء 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، فإنه يجب تجزئة كل معلومات تحديد الهوية الشخصية، مثل عناوين البريد الإلكتروني والأسماء. لمزيد من التفاصيل، يمكنك الرجوع إلى تجزئة البيانات وتسويتها.

يمكنك توفير كل المفاتيح المتعددة الخاصة بأي سجل أو بعضها. وللحصول على التفاصيل، يمكنك الرجوع إلى مطابقة extern 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، فعليك أيضًا تضمين قائمة معرفات الصفحة. ويمكنك فقط إرسال معرف 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؛ حيث إننا لا تدعم آليات التجزئة الأخرى. ويكون ذلك مطلوبًا لكل البيانات باستثناء المعرفات الخارجية ومعرفات مستخدم التطبيق ومعرفات المستخدم على مستوى الصفحة ومعرفات المُعلن على الهاتف المحمول.

وقبل تجزئة البيانات الخاصة بك، قم بتسويتها بحيث نتمكّن من معالجتها. ولا يدعم الاسم الأول (FN) والاسم الأخير (LN) إلا الأحرف الخاصة والأبجدية غير الرومانية. وللحصول على أفضل نتائج للمطابقة، قم بترجمة الأبجدية الرومانية مع عدم وجود أحرف خاصة.

التجزئة

أدخل القيم SHA256 للمفاتيح التي تمت تسويتها وعمليات تمثيل HEX لهذه القيمة باستخدام الأحرف بالحالة الصغيرة من A إلى F. وتعمل وظيفة التجزئة في PHP على تحويل عناوين البريد الإلكتروني وأرقام الهواتف التي تمت تسويتها.

المعرفات الخارجية

يمكنك مطابقة الأشخاص لجمهور مع معرفاتك الخاصة والمعروفة باسم المعرفات الخارجية (EXTERN_ID). ويمكن أن تمثل أي معرف فريد من المُعلن، مثل معرفات عضوية الولاء ومعرفات المستخدمين ومعرفات ملفات تعريف الارتباط الخارجية.

وللحصول على مطابقة أفضل، يجب أيضًا أن تستخدم التنسيق ذاته عندما ترسل المعرفات. فعلى سبيل المثال، إذا اخترت التجزئة باستخدام SHA256، فتأكد من استخدام القيمة المجزأة نفسها.

يمكنك استخدام هذه المعرفات كمفاتيح فردية لحذف الأشخاص من الجماهير المخصصة أو إنشاء جماهير مخصصة جديدة. وعند اتباع هذه الطريقة، لا تحتاج إلى إعادة تحميل أي مفاتيح مطابقة أخرى. إذا قمت بالإشارة إلى شخص بمعلومات شخصية تمت تجزئتها والمعرف EXTERN_ID، فنحن نمنح أولوية أقل للمعرف EXTERN_ID عند المطابقة مع الأشخاص على فيسبوك.

يمكنك إعادة استخدام تعيين 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

API استبدال المستخدمين

تسمح نقطة النهاية /<CUSTOM_AUDIENCE_ID>/usersreplace بتنفيذ إجراءين من خلال استدعاء API واحد:

• إزالة المستخدمين الحاليين تمامًا من جمهور محدد
• استبدال هؤلاء المستخدمين بمجموعة جديدة من المستخدمين.

يتيح لك استخدام نقطة النهاية /<CUSTOM_AUDIENCE_ID>/usersreplace حذف كل المستخدمين الموجودين تلقائيًا بدلاً من الاضطرار إلى تحميل قائمة المستخدمين الذين تريد حذفهم. لا تعمل نقطة النهاية هذه على إعادة تعيين مرحلة التعلُّم للمجموعة الإعلانية لديك عندما يكون الجمهور جزءًا من مجموعات إعلانية نشطة، على عكس استدعاءات POST أو DELETE لـ API التي يتم إرسالها إلى نقطة النهاية /<CUSTOM_AUDIENCE_ID>/users.

لا تعمل واجهة API استبدال المستخدمين إلا مع الجماهير التي تلبي المتطلبات التالية:

• يجب أن يكون عدد المستخدمين الموجودين قبل تشغيل عملية الاستبدال أقل من 100 مليون. وإذا كان جمهورك أكبر من 100 مليون، فنقترح عليك الاستفادة من نقطة النهاية /<CUSTOM_AUDIENCE_ID>/users لإضافة المستخدمين وإزالتهم.
• يجب تعيين النوع الفرعي إلى CUSTOM.
• لا يمكنك استبدال جمهور مخصص لملف عميل مستند إلى القيمة بجمهور مخصص لملف عميل غير مستند إلى القيمة، أو العكس.

بدء الاستخدام

قبل بدء عملية الاستبدال، نوصي بإجراء ما يلي:

• تأكد من أن operation_status للجماهير هي Normal.

• لا تقم بإضافة مستخدمين أو إزالتهم عبر /<CUSTOM_AUDIENCE_ID>/users أثناء وجود عملية استبدال قيد التقدم عبر /<CUSTOM_AUDIENCE_ID>/usersreplace. إذا كنت تحاول إجراء عملية استبدال ثانية قبل اكتمال الأولى، فستتلقى رسالة توضح وجود عملية استبدال قيد التقدم بالفعل.

• تستغرق أقصى فترة زمنية لجلسة الاستبدال الواحدة 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_id':9778993, 
  'batch_seq':10, 
  'last_batch_flag':true, 
  'estimated_num_total':99996 
}

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

حقول الجلسة

حقول حمولة البيانات

بمجرد إرسال طلب POST، ستحصل على استجابة بالحقول التالية:

الأخطاء الشائعة في API الاستبدال

يتوفر لدى كل الأخطاء التي تم إرجاعها من نقطة النهاية الاستبدال رمز الخطاء 2650. فيما يلي بعض رموز الأخطاء الفرعية الأكثر شيوعًا التي تم إرجاعها، بالإضافة إلى إرشادات حول كيفية حلها.

الموارد

فيما يلي أنواع أخرى من الجماهير التي يمكنك إنشاؤها واستهدافها أو مشاركتها:

• الجماهير المخصصة من موقعك على الويب — يمكنك إنشاء جمهور بناءً على الأشخاص الذين زاروا صفحة محددة أو اتخذوا إجراءً على موقعك على الويب. ويمكنك إنشاء جمهور بناءً على البيانات الواردة من بيكسل Meta على موقعك.

• الجماهير المخصصة من تطبيق الهاتف المحمول — يمكنك إنشاء جمهور بناءً على الأشخاص الذين يستخدمون تطبيق الهاتف المحمول. ويمكنك إنشاء جمهور بناءً على البيانات الواردة من أحداث التطبيق.

• الجماهير المشابهة — يمكنك تحديد الأشخاص الذين تعرفهم بالفعل وعرض الإعلان على أشخاص مشابهة على تطبيق فيسبوك.

• الجماهير المخصصة غير المتصلة — يمكنك إنشاء جمهور بناءً على الأشخاص الذين زاروا متجرك أو قاموا بإجراء مكالمات مع خدمة العملاء أو اتخذوا إجراءات من خلال وسائل أخرى غير متصلة بالإنترنت.

• جماهير التفاعل مع اللوحات — يمكنك إنشاء جمهور يتضمن أي شخص تفاعل مع لوحتك.

راجع أيضًا

• الجمهور المخصص
• مستخدمو الجمهور المخصص
• جلسة الجمهور المخصص
• شروط خدمة الجمهور المخصص