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

هناك ثلاث طرق لقراءة بيانات العملاء المحتملين: تنزيل TSV والقراءة المجمعة وWebhooks.

الأذونات

يمكنك قراءة بيانات العملاء المحتملين أو الحصول على تحديثات فورية بواسطة:

  • باستخدام رمز وصول صفحة، مثل رمز وصول مسؤول الصفحة للصفحة. يتيح لك رمز وصول الصفحة أيضًا قراءة الحقول الخاصة بالإعلانات، مثل ad_id، campaign_id أو ما إلى ذلك، إذا كانت لديك أذونات مستوى المعلن على الأقل على الحساب الإعلاني المرتبط بإعلان تجميع بيانات العملاء المحتملين.
  • باستخدام رمز وصول المستخدم الذي ينتمي إلى مسؤول الصفحة. للوصول إلى جميع بيانات العملاء المحتملين وبيانات مستوى الإعلان، ينبغي أن يتضمن رمز الوصول نطاق manage_pages وads_management.

لاسترداد معلومات بيانات عميل محتمل بمجرد تلقي معرف بيانات عميل محتمل عبر Webhooks، فإنك تحتاج أيضًا إلى طلب الإذن leads_retrieval لواجهة API استرداد بيانات عميل محتمل وإذن manage_pages وإرسال تطبيقك إلى مراجعة التطبيق.

سنتوقف عن إرسال البيانات المُجمعة في نماذج إعلانات تجميع بيانات عملاء محتملين عبر Webhooks إلى التطبيقات في وضع التطوير. سنبدأ في تطبيق هذا التغيير بتاريخ 1 فبراير 2019.

يمكنك إدارة حقوق المستخدم من خلال أدوار الصفحة.

تنزيل TSV

يمكنك الاستعلام مباشرة عن نموذج تجميع بيانات عملاء محتملين معين. لاحظ أن الحقل يحمل الاسم leadgen_export_csv_url على الرغم من أن التنسيق الوحيد المدعوم هو TSV.

use FacebookAds\Object\LeadgenForm;

$form = new LeadgenForm(<FORM_ID>);
$form->read();
from facebookads.adobjects.leadgenform import LeadgenForm

form = LeadgenForm(<LEADGEN_FORM_ID>)
form.remote_read()
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<FORM_ID>

الاستجابة:

{
  "id": "<LEAD_GEN_FORM_ID>",
  "leadgen_export_csv_url": "https://www.facebook.com/ads/lead_gen/export_csv?type=form&amp;id=<FORM_ID>",
  "locale": "en_US",
  "name": "My Form",
  "status": "ACTIVE"
}

الفلترة

يمكنك اختياريًا فلترة استجابة عنوان URL لتنزيل بيانات عملاء محتملين من نطاق تاريخ معيّن. استخدم from_date وto_date بتنسيق وقت POSIX أو UNIX معبرًا عن عدد الثواني منذ ذلك الوقت. على سبيل المثال، لتنزيل بيانات عملاء محتملين من الفترة الزمنية التي تبدأ من 2016-01-13 18:20:31 UTC وتنتهي في 2016-01-14 18:20:31 UTC:

https://www.facebook.com/ads/lead_gen/export_csv/?id=<FORM_ID>&amp;type=form&amp;from_date=1482698431&amp;to_date=1482784831

ملاحظة:

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

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

  • يتم إنشاء بيانات العميل المحتمل من وصول عادي. is_organic في TSV يعرض 1 في هذا الحالة. وإلا فالقيمة هي 0.
  • يمكن إرسال بيانات العميل المحتمل من معاينة الإعلان.
  • أي شخص يقوم بتنزيل بيانات العملاء المحتملين يفتقر إلى امتيازات المعلنين المتاحة للحساب الإعلاني المشغِّل لإعلان تجميع بيانات عملاء محتملين.

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

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

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

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$leads = $ad->getLeads();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
leads = ad.get_leads()
APINodeList<Lead> leads = new Ad(<AD_ID>, context).getLeads()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads

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

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 \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<LEAD_ID>?fields=custom_disclaimer_responses"

الاستجابة:

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

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

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

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdReportRunFields;

$ad = new Ad(<AD_ID>);
$time_from = (new \DateTime("-1 week"))->getTimestamp();
$leads = $ad->getLeads(array(), array(
  AdReportRunFields::FILTERING => array(
    array(
      'field' => 'time_created',
      'operator' => 'GREATER_THAN',
      'value' => $time_from,
    ),
  ),
));
curl -G \
  --data-urlencode 'filtering=[ 
    { 
      "field": "time_created", 
      "operator": "GREATER_THAN", 
      "value": 1516682744 
    } 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads

الترميز

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

Webhooks

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

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

الإعداد

1. إعداد نقطة نهاية لمعالجة اختبارات الاتصال الفورية

يكون هيكل اختبار الاتصال الخاص بالتحديثات الفورية كما يلي. اقرأ المزيد على مدونة التحديثات الفورية.

يمكن إدخال عدة تغييرات من خلال اختبار الاتصال في مصفوفة التغييرات.

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/v3.1/{lead-id}/
const adsSdk = require('facebook-nodejs-ads-sdk'); const Lead = adsSdk.Lead; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.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 = { }; let sample_code = (new Lead(id)).get( fields, params ); logApiCallResult('sample_code api call complete.', sample_code);
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 = '<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 )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.lead import Lead from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print Lead(id).get( 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 = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Lead(id, context).get() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end lead = FacebookAds::Lead.get(id ,'')

الاستجابة:

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

2. تسجيل اشتراك التطبيق في أحداث leadgen

للاشتراك في حدث leadgen يتعين على الخادم الخاص بك الاستجابة من خلال طلبات HTTP GET كما هو وارد في تلقي تحديثات API الفورية من خلال Webhooks.

بعد إعداد عنوان URL الخاص برد الاتصال، اشترك في leadgen webhook في لوحة معلومات تطبيقك أو من خلال استدعاء واجهة API:

للاشتراك من خلال API تحتاج إلى رمز وصول تطبيق، وليس رمز وصول مستخدم:

curl \
-F "object=page" \
-F "callback_url=https://www.yourcallbackurl.com" \
-F "fields=leadgen" \
-F "verify_token=abc123" \
-F "access_token=<APP_ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<APP_ID>/subscriptions"

3. الحصول على رمز صفحة

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

  1. احصل على رمز مستخدم عادي.
  2. حوّله إلى رمز طويل الأجل.
  3. باستخدام رمز وصول مستخدم طويل الأجل، اطلب رمز الصفحة:
curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/{user-id}/accounts
const adsSdk = require('facebook-nodejs-ads-sdk'); const User = adsSdk.User; const Page = adsSdk.Page; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.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 = { }; let accountss = (new User(id)).getAccounts( fields, params ); logApiCallResult('accountss api call complete.', accountss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\User; use FacebookAds\Object\Page; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new User($id))->getAccounts( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.user import User from facebookads.adobjects.page import Page from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print User(id).get_accounts( 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 = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new User(id, context).getAccounts() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end user = FacebookAds::User.get(id) accountss = user.accounts({ fields: { }, })

الاستجابة:

{
  "data": [
    {
      "access_token": "[REDACTED]",
      "category": "Pet",
      "name": "Puppy",
      "id": "153125381133",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    },
  ]
}

رمز الصفحة هذا ليس له تاريخ انتهاء صلاحية ويمكنك تشفيره تشفيرًا قويًا في تكاملات RTU بسيطة للحصول على بيانات العملاء المحتملين.

4. تسجيل اشتراك الصفحة بالتطبيق

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

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

Api::instance()->call(
  '/' . <PAGE_ID> . '/subscribed_apps',
  RequestInterface::METHOD_POST);
curl \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/subscribed_apps

تطبيق فيسبوك المرتبط بالرمز الخاص بك مصادق لتحديثات الصفحة؛ لا يلزمك تحديد معرف التطبيق.

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