يساعدك هذا الدليل في استخدام الميزات المتقدمة لمجموعة SDK للأعمال من Meta والمصممة خصيصًا لمستخدمي واجهة API التحويلات. تتوفر الطلبات غير المتزامنة، والتجميع المتزامن، وواجهة خدمة HTTP في مجموعات SDK بلغة PHP وNodeJS وJava وPython وRuby. للتعرف على الاستخدام الأساسي لواجهة API التحويلات، ارجع إلى وثائق واجهة API للتحويلات الأساسية.
تمنحك مجموعة SDK للأعمال من Meta إمكانية الوصول إلى مجموعة من واجهات API الأعمال، ما يسمح لك بإنشاء حلول فريدة ومخصصة لخدمة الأنشطة التجارية والعملاء. إحدى واجهات API المتوفرة لدى مستخدمي مجموعة SDK هي واجهة API التحويلات.
قبل استخدام أي من الميزات المدرجة أدناه، تحتاج إلى تثبيت مجموعة SDK للأعمال من Meta. راجع بدء استخدام مجموعة SDK للأعمال من Meta أو اتبع إرشادات README
المدرجة هنا:
facebook-nodejs-business-sdk
facebook-python-business-sdk
الحد الأدنى لإصدار اللغة المطلوب لاستخدام هذه الميزات هو:
استخدم هذه الميزة إذا كنت لا تريد حظر تنفيذ البرنامج لانتظار اكتمال الطلب. باستخدام هذا النهج، يمكنك تقديم طلبك واستلام إشارة من الخادم بمجرد اكتماله. أثناء انتظار الاستجابة، يمكن للبرنامج مواصلة التنفيذ.
تتيح لك الطلبات غير المتزامنة استخدام الموارد بكفاءة أكبر، ما يؤدي إلى خفض زمن استجابة الخادم. يتيح لك هذا أيضًا التحكم بشكل أكبر في طريقة معالجة البرنامج للأخطاء الواردة من الخادم ودمج مجموعة SDK بسهولة ضمن الرموز التي يتم تشغيلها بالفعل بشكل غير متزامن.
لتنفيذ طلبات غير متزامنة، راجع عينات الرموز باللغات التالية:
use FacebookAds\Api;
use FacebookAds\Object\ServerSide\CustomData;
use FacebookAds\Object\ServerSide\Event;
use FacebookAds\Object\ServerSide\EventRequest;
use FacebookAds\Object\ServerSide\EventRequestAsync;
use FacebookAds\Object\ServerSide\UserData;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Promise;
$pixel_id = getenv('PIXEL_ID');
$access_token = getenv('ACCESS_TOKEN');
if (empty($pixel_id) || empty($access_token)) {
throw new Exception('Missing required test config. Got pixel_id: "' . $pixel_id . '", access_token: "' . $access_token . '"');
}
Api::init(null, null, $access_token, false);
function create_events($num) {
$user_data = (new UserData())
->setEmail('joe' . $num . '@eg.com')
->setClientIpAddress($_SERVER['REMOTE_ADDR'])
->setClientUserAgent($_SERVER['HTTP_USER_AGENT']);
$custom_data = (new CustomData())
->setCurrency('usd')
->setValue(123.45);
$event = (new Event())
->setEventName('Purchase')
->setEventTime(time())
->setEventSourceUrl('http://jaspers-market.com/product/123')
->setUserData($user_data)
->setCustomData($custom_data)
->setActionSource(ActionSource::WEBSITE);
return array($event);
}
function create_async_request($pixel_id, $num) {
$async_request = (new EventRequestAsync($pixel_id))
->setEvents(create_events($num));
return $async_request->execute()
->then(
null,
function (RequestException $e) {
print(
"Error!!!\n" .
$e->getMessage() . "\n" .
$e->getRequest()->getMethod() . "\n"
);
}
);
}
// Async request:
$promise = create_async_request($pixel_id, 2);
print("Request 1 state: " . $promise->getState() . "\n");
print("Async request - OK.\n");
// Async request with wait:
$promise = create_async_request($pixel_id, 3);
$response2 = $promise->wait();
print("Request 2: " . $response2->getBody() . "\n");
print("Async request with wait - OK.\n");
// Multiple async requests:
$promises = [
"Request 3" => create_async_request($pixel_id, 4),
"Request 4" => create_async_request($pixel_id, 5),
];
$response3 = Promise\unwrap($promises);
foreach ($response3 as $request_name => $response) {
print($request_name . ": " . $response->getBody()."\n");
}
print("Async - Multiple async requests OK.\n");
يستعين التجميع المتزامن بالطلبات غير المتزامنة لزيادة معدل الإرسال عن طريق استخدام الموارد بشكل أكثر كفاءة. يمكنك إنشاء طلبات مُجمّعة لدعم حالات الاستخدام مثل كائنات تنفيذ طلبات الأحداث، ووظائف cron والمزيد.
تتوفر أساليب BatchProcessor
التالية للاختيار من بينها:
الأسلوب | حالات الاستخدام |
---|---|
| استخدمه لمعالجة الأحداث التي تمتلك حقول |
| يُعد هذا الكائن أداة الإنشاء الأساسية لـ يمكن استخدامه أيضًا لمعالجة الأحداث التي تمتلك حقول |
| استخدمه لمعالجة |
| يُعد هذا الكائن أداة الإنشاء الأساسية لـ يمكن استخدامه أيضًا لمعالجة |
عند استخدام التجميع المتزامن، من المفترض أن يتم إرسال الأحداث بشكل فوري تقريبًا. لمزيد من المعلومات، راجع معدل تكرار المشاركة.
إذا كنت تستخدم مجموعة SDK للغة PHP أو Python أو Ruby، فإن الأساليب أعلاه تتطلب كائنات EventRequestAsync بدلاً من EventRequest.
لتنفيذ التجميع المتزامن، راجع عينات الرموز باللغات التالية:
use FacebookAds\Api;
use FacebookAds\Object\ServerSide\BatchProcessor;
use FacebookAds\Object\ServerSide\CustomData;
use FacebookAds\Object\ServerSide\Event;
use FacebookAds\Object\ServerSide\EventRequestAsync;
use FacebookAds\Object\ServerSide\UserData;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Promise;
$pixel_id = getenv('PIXEL_ID');
$access_token = getenv('ACCESS_TOKEN');
if (empty($pixel_id) || empty($access_token)) {
throw new Exception('Missing required test config. Got pixel_id: "' . $pixel_id . '", access_token: "' . $access_token . '"');
}
$api = Api::init(null, null, $access_token, false);
function create_event($i) {
$user_data = (new UserData())
->setEmail('joe' . $i . '@eg.com')
->setClientIpAddress($_SERVER['REMOTE_ADDR'])
->setClientUserAgent($_SERVER['HTTP_USER_AGENT']);
$custom_data = (new CustomData())
->setCurrency('usd')
->setValue(123.45);
return (new Event())
->setEventName('Purchase')
->setEventTime(time())
->setEventSourceUrl('http://jaspers-market.com/product/' . $i)
->setUserData($user_data)
->setCustomData($custom_data)
->setActionSource(ActionSource::WEBSITE);
}
function create_events($num) {
$events = [];
for ($i = 0; $i < $num; $i++) {
$events[] = create_event($i);
}
return $events;
}
function create_async_requests($pixel_id, $num) {
$requests = [];
for ($i = 0; $i < $num; $i++) {
$requests[] = (new EventRequestAsync($pixel_id))
->setUploadTag('test-tag-2')
->setEvents([create_event($i)]);
}
return $requests;
}
function run($pixel_id) {
print("Started CONVERSIONS_API_EVENT_CREATE_BATCH...\n");
$batch_processor = new BatchProcessor($pixel_id, 2, 2);
// processEvents
$events = create_events(11);
$batch_processor->processEvents(array('upload_tag' => 'test-tag-1'), $events);
// processEventRequests
$requests = create_async_requests($pixel_id, 5);
$batch_processor->processEventRequests($requests);
// processEventsGenerator
$process_events_generator = $batch_processor->processEventsGenerator(array('upload_tag' => 'test-tag-1'), $events);
foreach ($process_events_generator as $promises) {
try {
Promise\unwrap($promises);
} catch (RequestException $e) {
print('RequestException: ' . $e->getResponse()->getBody()->getContents() . "\n");
throw $e;
} catch (\Exception $e) {
print("Exception:\n");
print_r($e);
throw $e;
}
}
// processEventRequestsGenerator
$requests = create_async_requests($pixel_id, 5);
$process_event_requests_generator = $batch_processor->processEventRequestsGenerator($requests);
foreach ($process_event_requests_generator as $promises) {
try {
Promise\unwrap($promises);
} catch (RequestException $e) {
print('RequestException: ' . $e->getResponse()->getBody()->getContents() . "\n");
throw $e;
} catch (\Exception $e) {
print("Exception:\n");
print_r($e);
throw $e;
}
}
print("Finished CONVERSIONS_API_EVENT_CREATE_BATCH with no errors.\n");
}
run($pixel_id);
استخدم واجهة خدمة HTTP إذا كان لديك مجموعة محددة من المتطلبات لطبقة خدمة HTTP. من خلال هذه الميزة، يمكنك تجاوز خدمة HTTP الافتراضية لمجموعة SDK للأعمال وتنفيذ خدمتك المخصصة باستخدام الأسلوب أو المكتبة المفضلة لديك.
لتنفيذ واجهة خدمة HTTP، راجع عينات الرموز باللغات التالية:
require __DIR__ . '/../vendor/autoload.php';
use FacebookAds\Api;
use FacebookAds\Object\ServerSide\CustomData;
use FacebookAds\Object\ServerSide\Event;
use FacebookAds\Object\ServerSide\EventRequest;
use FacebookAds\Object\ServerSide\EventRequestAsync;
use FacebookAds\Object\ServerSide\HttpServiceClientConfig;
use FacebookAds\Object\ServerSide\UserData;
// Imports used by the TestHttpClient class
use FacebookAds\Object\ServerSide\HttpServiceInterface;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Handler\CurlHandler;
use GuzzleHttp\Psr7\MultipartStream;
use GuzzleHttp\Psr7\Request;
$pixel_id = getenv('PIXEL_ID');
$access_token = getenv('ACCESS_TOKEN');
if (empty($pixel_id) || empty($access_token)) {
throw new Exception('Missing required test config. Got pixel_id: "' . $pixel_id . '", access_token: "' . $access_token . '"');
}
function run($access_token, $pixel_id) {
Api::init(null, null, $access_token, false);
$request1 = getEventRequest($pixel_id, 1);
$request1->setHttpClient(new TestHttpClient());
$response1 = $request1->execute();
print("Response: " . $response1->getBody() . "\n");
print("Custom HTTP Service Request 1 - OK.\n");
// Alternatively, you can set the access_token and the HTTP Client on the HttpServiceClientConfig
Api::init(null, null, null, false);
HttpServiceClientConfig::getInstance()->setClient(new TestHttpClient());
HttpServiceClientConfig::getInstance()->setAccessToken($access_token);
$request2 = getEventRequest($pixel_id, 2);
$response2 = $request2->execute();
print("Response: " . $response2->getBody() . "\n");
print("Custom HTTP Service Request 2 - OK.\n");
}
function getEventRequest($pixel_id, $num) {
$user_data = (new UserData())
->setEmail('joe' . $num . '@eg.com')
->setClientIpAddress($_SERVER['REMOTE_ADDR'])
->setClientUserAgent($_SERVER['HTTP_USER_AGENT']);
$custom_data = (new CustomData())
->setCurrency('usd')
->setValue(123.45);
$event = (new Event())
->setEventName('Purchase')
->setEventTime(time())
->setEventSourceUrl('http://jaspers-market.com/product/123')
->setUserData($user_data)
->setCustomData($custom_data)
->setActionSource(ActionSource::WEBSITE);
return (new EventRequest($pixel_id))
->setEvents(array($event));
}
class TestHttpClient implements HttpServiceInterface {
public function executeRequest($url, $method, array $curl_options, array $headers, array $params) {
$multipart_contents = [];
foreach ($params as $key => $value) {
if ($key === 'data') {
$multipart_contents[] = [
'name' => $key,
'contents' => \GuzzleHttp\json_encode($value),
'headers' => array('Content-Type' => 'multipart/form-data'),
];
} else {
$multipart_contents[] = [
'name' => $key,
'contents' => $value,
'headers' => array('Content-Type' => 'multipart/form-data'),
];
}
}
$body = new MultipartStream($multipart_contents);
$request = new Request($method, $url, $headers, $body);
$handler_stack = HandlerStack::create(
new CurlHandler(['options' => $curl_options])
);
$client = new Client(['handler' => $handler_stack]);
return $client->send($request);
}
}
run($access_token, $pixel_id);
يمكنك اختبار طلبات الأحداث باستخدام المعلمة test_event_code
. حدّد مكان رمز الاختبار بالانتقال إلى أداة اختبار الأحداث الموجودة في مدير الأحداث ضمن مصادر البيانات > البيكسل > علامة تبويب اختبار الأحداث.
ملاحظة: يجب استبدال قيمة العينة في الرمز أدناه (أي TEST12345
) برمز الاختبار الذي تحصل عليه من علامة تبويب اختبار الأحداث.
...
$request = (new EventRequest($pixel_id))
->setTestEventCode('TEST12345')
->setEvents($events);
$response = $request->execute();
في الوقت الحالي، لا ندعم إعداد واجهة خدمة HTTP مخصصة عند إرسال طلبات مُجمّعة متزامنة أو طلبات غير متزامنة.