Ce guide vous aide à naviguer dans les fonctionnalités avancées du SDK Meta Business, conçues spécialement pour les utilisateur·ices de l’API Conversions. Requêtes asynchrones, Regroupement des lots et Interface du service HTTP sont disponibles dans les SDK PHP, NodeJS, Java, Python et Ruby. Pour une utilisation de base de l’API Conversions, consultez la documentation relative à l’API Conversions.
Le SDK Meta Business vous donne accès à notre suite d’API d’entreprise afin de vous permettre de créer des solutions uniques et personnalisées pour vos entreprises et votre clientèle. L’API Conversions fait partie des API disponibles pour les utilisateur·ices du SDK.
Avant d’utiliser l’une des fonctionnalités énumérées ci-dessous, vous devez avoir installé le SDK Meta Business. Consultez la page Premiers pas avec le SDK Meta Business ou suivez les instructions README
ci-dessous :
facebook-nodejs-business-sdk
facebook-java-business-sdk
facebook-python-business-sdk
facebook-ruby-business-sdk
Version minimale du langage requise pour l’utilisation de ces fonctionnalités :
Utilisez cette fonctionnalité si vous ne souhaitez pas bloquer l’exécution de votre programme pour attendre la fin de la requête. Avec cette méthode, vous envoyez votre requête et recevez un signal du serveur une fois qu’elle a été traitée. Dans l’attente de la réponse, l’exécution du programme se poursuit.
Les requêtes asynchrones vous permettent d’utiliser vos ressources de manière plus efficace, ce qui améliore le délai de réponse du serveur. Vous disposez par ailleurs d’un meilleur contrôle sur la façon dont votre programme gère les erreurs du serveur, et pouvez intégrer facilement le SDK dans le code qui s’exécute déjà de manière asynchrone.
Pour implémenter les requêtes asynchrones, consultez les exemples de code dans les langages suivants :
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");
Le regroupement des lots tire parti des requêtes asynchrones pour augmenter le débit grâce à une utilisation plus efficace des ressources. Vous pouvez créer des requêtes groupées pour gérer des cas d’utilisation tels que les workers de requêtes d’évènement, les tâches cron, et bien plus encore.
Vous disposez des méthodes BatchProcessor
suivantes :
Méthode | Quand l’utiliser |
---|---|
| Utilisez-la pour traiter les évènements dotés des mêmes champs |
| Générateur sous-jacent pour Utilisez-la également pour traiter les évènements dotés des mêmes champs |
| Utilisez cette méthode pour traiter simultanément les requêtes |
| Générateur sous-jacent pour Utilisez-la également pour traiter des requêtes |
Lorsque vous utilisez le regroupement des lots, les évènements doivent être envoyés dans des délais se rapprochant le plus du temps réel. Pour en savoir plus, consultez Fréquence de partage.
Si vous utilisez les SDK PHP, Python ou Ruby, vous devez remplacer EventRequest par des objets EventRequestAsync dans les méthodes ci-dessus.
Pour mettre en œuvre le regroupement des lots, consultez les exemples de code dans les langages suivants :
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);
Utilisez l’interface de service HTTP si la couche de service HTTP est associée à un ensemble spécifique de conditions. Cette fonctionnalité vous permet de remplacer le service HTTP par défaut du SDK Business et d’implémenter votre propre service avec la méthode ou la bibliothèque de votre choix.
Pour implémenter votre propre interface de service HTTP, consultez les exemples de code dans les langages suivants :
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);
Vous pouvez tester vos requêtes d’évènement à l’aide du paramètre test_event_code
. Localisez le code de test en accédant à l’outil de test d’évènements disponible dans le Gestionnaire d’évènements dans l’onglet Sources de données > Your Pixel (Votre pixel) > Test Events (Test d’évènements).
Remarque : Vous devez remplacer la valeur donnée en exemple dans le code ci-dessous (à savoir TEST12345
) par le code de test fourni dans l’onglet Test Events (Test d’évènements).
...
$request = (new EventRequest($pixel_id))
->setTestEventCode('TEST12345')
->setEvents($events);
$response = $request->execute();
Actuellement, il n’est pas possible de définir une interface de service HTTP personnalisée avec des requêtes groupées ou asynchrones.