Questa guida descrive le funzioni avanzate dell'SDK Business di Meta progettate appositamente per gli utenti dell'API Conversions. Richieste asincrone, creazione di batch contemporanei e interfaccia del servizio HTTP sono disponibili negli SDK di PHP, NodeJS, Java, Python e Ruby. Per l'uso di base dell'API Conversions, consulta la relativa documentazione principale.
L'SDK Business di Meta ti dà accesso alla nostra suite di API business che ti consentono di creare soluzioni uniche e personalizzate per servire le tue aziende e i tuoi clienti. Una delle API disponibile per gli utenti dell'SDK è l'API Conversions.
Prima di usare una delle funzioni elencate di seguito, devi aver installato l'SDK Business di Meta. Consulta Primi passi con l'SDK Business di Meta o segui le istruzioni README
riportate di seguito:
facebook-nodejs-business-sdk
facebook-python-business-sdk
Versione minima del linguaggio necessaria per usare queste funzioni:
Utilizza questa funzionalità se non vuoi bloccare l'esecuzione del tuo programma in attesa del completamento di una richiesta. In questo modo, puoi effettuare la richiesta e ricevere un segnale dal server una volta completata. In attesa della risposta, il programma rimane in esecuzione.
Le richieste asincrone consentono di utilizzare le tue risorse in modo più efficiente, determinando una diminuzione del tempo di risposta del server. Questo consente anche di avere più controllo su come il tuo programma gestisce gli errori provenienti dal server e di integrare facilmente l'SDK nel codice che già viene eseguito in modo asincrono.
Per implementare le richieste asincrone, consulta gli esempi di codice nei linguaggi seguenti:
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");
La creazione di batch contemporanei sfrutta le richieste asincrone per aumentare il throughput utilizzando le risorse in modo più efficiente. Puoi creare richieste in batch per supportare casi d'uso come lavoratori di richieste di eventi, cron job e altro ancora.
Puoi scegliere tra i metodi BatchProcessor
seguenti:
Metodo | Quando utilizzarlo |
---|---|
| Usalo per elaborare gli eventi che hanno gli stessi campi di primo livello |
| Questo è il generatore di base per Può essere usato anche per elaborare eventi con gli stessi campi di primo livello |
| Usalo per elaborare |
| Questo è il generatore di base per Può essere usato anche per elaborare |
Quando utilizzi la creazione di batch simultanei, gli eventi devono essere inviati il più vicino possibile al tempo reale. Per ulteriori informazioni, consulta Frequenza di condivisione.
Se usi gli SDK di PHP, Python o Ruby, i metodi sopra richiedono uno o più oggetti EventRequestAsync anziché un EventRequest.
Per implementare la creazione di batch simultanei, consulta gli esempi di codice nei seguenti linguaggi:
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);
Utilizza l'interfaccia del servizio HTTP se hai un insieme specifico di requisiti per il livello del servizio HTTP. Con questa funzione, puoi sovrascrivere il servizio HTTP predefinito dell'SDK Business e implementare il tuo servizio personalizzato con il metodo o la libreria che preferisci.
Per implementare la tua interfaccia del servizio HTTP, consulta gli esempi di codice nei linguaggi seguenti:
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);
Puoi testare le tue richieste di evento con il parametro test_event_code
. Il codice di test è reperibile nello strumento Testa gli eventi disponibile in Gestione eventi nella tab Origini dei dati > Il tuo pixel > Testa gli eventi.
Nota: devi sostituire il valore di esempio nel codice sotto (ovvero TEST12345
) con il codice di test che ottieni dalla tab Testa gli eventi.
...
$request = (new EventRequest($pixel_id))
->setTestEventCode('TEST12345')
->setEvents($events);
$response = $request->execute();
Attualmente la configurazione di un'interfaccia del servizio HTTP personalizzata per le richieste di batch simultanei o le richieste asincrone non è supportata.