‏API التسويق‏

استرداد بيانات العملاء المحتملين

يمكنك قراءة بيانات العملاء المحتملين باستخدام Webhooks أو القراءة المجمعة.

قبل البدء

لقراءة حقول معينة في الإعلان، مثل ad_id وcampaign_id، ستحتاج إلى:

لقراءة كل بيانات العملاء المحتملين والبيانات على مستوى الإعلان، ستحتاج إلى ما يلي:

ملاحظة: إذا لم يسبق لمسؤول هذه الصفحة تخصيص بيانات العملاء المحتملين، أو الحصول على إذن للوصول من خلال مدير الوصول إلى بيانات العملاء المحتملين، فسيحصل كل مسؤولي الصفحة إذن بالوصول إلى بيانات العملاء المحتملين. إذا خصص مسؤولو مدير أعمال إذنًا للوصول إلى بيانات العملاء المحتملين، فسيعتمد ذلك على تكوين مسؤول مدير الأعمال وما إذا كان مسؤول الصفحة الأساسي يتمتع بإذن الوصول إلى بيانات العملاء المحتملين أم لا.

تقييدات معدلات الاستدعاء

تقييد معدلات الاستدعاء يعادل 200 مضروبة في 24 مضروبًا في عدد نماذج بيانات العملاء المحتملين التي تم إنشاؤها خلال آخر 90 يومًا لصفحة فيسبوك. وإذا أجريت استدعاءات تتجاوز الاستدعاءات التي تم إجراؤها خلال فترة زمنية مدتها 24 ساعة، فستُرجع طلباتك خطأ.

الفلترة حسب نطاق التاريخ

يمكنك إرسال طلب GET إلى نقطة نهاية /ads/lead_gen/export_csv/ حيث تكون تنسيقات التاريخ عبارة عن طابع زمني POSIX أو UNIX:

curl -i -X GET "https://www.facebook.com/ads/lead_gen/export_csv/
    ?id=<FORM_ID>
    &type=form
    &from_date=1482698431
    &to_date=1482784831"

التنبيهات

  • في حالة عدم تعيين from_date أو كانت أقل من وقت إنشاء النموذج، يتم استخدام وقت إنشاء النموذج.

  • في حالة عدم تعيين to_date أو كانت أكبر من الوقت الحاضر، يتم استخدام الوقت الحالي.

  • إذا كانت أي إدخالات تفتقر إلى معرفات الإعلانات أو معرفات المجموعات الإعلانية في TSV، فقد يرجع ذلك إلى الأسباب التالية:

    • يتم إنشاء بيانات العميل المحتمل من الوصول العادي. في هذه الحالة، يعرض is_organic في ملف TSV القيمة 1؛ وبخلاف ذلك، تكون القيمة 0.
    • يمكن إرسال بيانات العميل المحتمل من معاينة الإعلان.
    • لا يتمتع الشخص الذي يطلب بيانات العملاء المحتملين بامتيازات المُعلِن في الحساب الإعلاني.

Webhooks

احصل على تحديثات فورية حول إعلانات تجميع بيانات العملاء المحتملين.

الخطوة الأولى: بدء الاستخدام

قم بزيارة دليل بدء استخدام Webhooks لإعداد نقطة النهاية وتكوين webhook لديك.

الخطوة الثانية: الحصول على رمز وصول الصفحة طويل الأجل

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

الخطوة الثالثة: تثبيت تطبيقك على الصفحة

قم بزيارة دليل Webhooks للصفحات للتعرف على كيفية تثبيت تطبيقك على صفحة ما.

استجابة حدث Webhook

عند إنشاء تجميع بيانات العملاء المحتملين، يتلقى تطبيقك استجابة webhook التالية:

array(
  "object" => "page",
  "entry" => array(
    "0" => array(
      "id" => 153125381133,
      "time" => 1438292065,
      "changes" => array(
        "0" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123123,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        ),
        "1" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123124,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        )
      )
    )
  )
)

يمكنك استخدام المعرف leadgen_id لاسترداد البيانات المرتبطة ببيانات العميل المحتمل:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{lead-id}/
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<LEAD_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 = {
};
const sample_code = (new Lead(id)).get(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

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

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

$fields = array(
);
$params = array(
);
echo json_encode((new Lead($id))->getSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

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

fields = [
]
params = {
}
print Lead(id).get(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
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 = \"<LEAD_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Lead(id, context).get()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

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

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

lead = FacebookAds::Lead.get(id ,'')
Open In Graph API Explorer

عند نجاح العملية، يتلقى تطبيقك الاستجابة التالية:

{
  "created_time": "2015-02-28T08:49:14+0000", 
  "id": "<LEAD_ID>", 
  "ad_id": "<AD_ID>",
  "form_id": "<FORM_ID>",
  "field_data": [{
    "name": "car_make",
    "values": [
      "Honda"
    ]
  }, 
  {
    "name": "full_name", 
    "values": [
      "Joe Example"
    ]
  }, 
  {
    "name": "email", 
    "values": [
      "joe@example.com"
    ]
  },
  {
    "name": "selected_dealer", 
    "values": [
      "99213450"
    ]
  }],
  ...
}

معرفة المزيد

يمكنك الاطلاع على مثال لهذا التنفيذ في مستودع Github.

القراءة المجمّعة

يتم إجبار التطبيقات التي تم إنشاؤها بعد 2 يوليو 2018 على استخدام الإذن leads_retrieval لقراءة بيانات العملاء المحتملين.

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

للقراءة المجمّعة حسب الإعلان:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_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 = {
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

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

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

$fields = array(
);
$params = array(
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

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

fields = [
]
params = {
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
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_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

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

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

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
})
Open In Graph API Explorer

للقراءة حسب النموذج:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

الاستجابة:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

قراءة قيمة سؤال محدد مواقع المتاجر

لا يختلف سؤال محدد مواقع المتاجر عن أي سؤال آخر. سيتضمن سؤال محدد مواقع المتاجر معرف حقل سيتم تعيينه مقابله أثناء إنشاء النموذج. كما سيتم إرسالها بطريقة مماثلة لأسئلة أخرى. تكون القيمة التي يتم تمريرها واردة من رقم المتجر للموقع المحدد.

على سبيل المثال، لنفترض أن لديك سؤال محدد موقع المتاجر يتضمن selected_dealer كمعرف حقل. وللحصول على جميع بيانات العملاء المحتملين، يمكنك استدعاء ما يلي:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

الاستجابة:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
        {
          "name": "selected_dealer", 
          "values": [
            "99213450"
          ]
        }
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

قراءة استجابات إخلاء المسؤولية المخصصة

لا يحتوي field_data على الاستجابات لمربعات اختيار إخلاء المسؤولية المخصص الاختيارية التي كان المستخدم قد قام بملئها. لاسترداد الاستجابات، استخدم الحقل custom_disclaimer_responses.

curl -X GET \
"https://graph.facebook.com/<API_VERSION>/<LEADGEN_ID>?
fields=custom_disclaimer_responses"

الاستجابة:

{
  "custom_disclaimer_responses": [
    {
      "checkbox_key": "optional_1",
      "is_checked": "1"
    },
    {
      "checkbox_key": "optional_2",
      "is_checked": ""
    }
  ],
  "id": "1231231231"
}

فلترة بيانات العملاء المحتملين

في هذا المثال، تتم فلترة بيانات العملاء المحتملين بناءً على الطوابع الزمنية. يجب أن تكون الطوابع الزمنية طابعًا زمنيًا بتنسيق Unix.

curl -X GET \
  -d 'filtering=[
       {
         "field": "time_created",
         "operator": "GREATER_THAN",
         "value": 1729974463
       }
     ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_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 = {
  'filtering' : [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

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

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

$fields = array(
);
$params = array(
  'filtering' => array(array('field' => 'time_created','operator' => 'GREATER_THAN','value' => 1721709809)),
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

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

fields = [
]
params = {
  'filtering': [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
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_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .setParam(\"filtering\", \"[{\\"field\\":\\"time_created\\",\\"operator\\":\\"GREATER_THAN\\",\\"value\\":1721709809}]\")
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

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

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

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
    filtering: [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
})
Open In Graph API Explorer

يأخذ operator إحدى القيم التالية.

عامل التشغيلالمعنى

LESS_THAN

يمكن فلترة القيم الأقل من الطابع الزمني.

GREATER_THAN

يمكن فلترة القيم الأكبر من الطابع الزمني.

GREATER_THAN_OR_EQUAL

يمكن فلترة القيم الأكبر من الطابع الزمني أو المساوية له.

استخدام الرموز المميزة

إذا كان النموذج يحتوي على معرفات حقول مخصصة، فستكون الحقول والقيم التي يتم إرجاعها هي الحقول والقيم المحددة.

المصادر