Come configurare CAPI Facebook con PHP

È già da un pò che si sente parlare di Conversion API di Facebook (o Meta), e nella maggior parte dei casi viene installato tramite plugin appositi senza dover scrivere alcuna riga di codice.

Se è vero che l’implementazione tramite plugin è molto più semplificata porta con se anche degli svantaggi. I vantaggi di un’integrazione custom del CAPI di Facebook sono i seguenti:

Elevata possibilità di personalizzazione;
Nessun costo aggiuntivo;
Possibilità di integrarlo a qualsiasi programma di generazione cookie banner per essere GDPR Compliant.

Partiamo subito dall’installazione della libreria Facebook SDK. Sei pronto? Si parte 😉

Installare la libreria Facebook SDK per il Conversion API

La prima cosa da fare se vogliamo installare il Conversion API di Facebook tramite codice PHP è quella di installare le librerie Facebook SDK che faranno funzionare la nostra integrazione.

Andiamo sull’apposita pagina di Meta for developers e selezioniamo la libreria con cui vogliamo effettuare l’integrazione.

Come detto fin dall’inizio io utilizzerò PHP, ma voi potete scegliere di utilizzare: PHP, Node.js, Java, Python o Ruby. Il procedimento per l’installazione della libreria sarà lo stesso, l’unica cosa che cambia è il codice di implementazione.

Assicuratevi di star utilizzando la versione minima indicata, dopodiché andate sul vostro hosting, effettuate la connessione via SSH o entrate direttamente nel pannello di amministrazione (ad esempio cPanel) per poi utilizzare il terminale.

Terminale del cPanel per installare librerie CAPI Facebook

Puoi verificare la versione PHP della tua piattaforma andando sul tuo hosting, entrando nel pannello di amministrazione e cercando nelle voci PHP.

Ora lancia i seguenti comandi di linea fino a quando non arrivi sotto la tua public_html o dove hai installato WordPress. Il comando ls ti permette di vedere tutti i file e le cartelle contenute in quella posizione, il comando cd seguito dal nome preciso della directory ti permette di entrare nella directory (cartella), mkdir ti permette di creare una directory e infine vim è il comando che ti permette di visualizzare e volendo modificare un file.

ls
cd directory
ls
cd directory
mkdir fb-api
cd fb-api
vim composer.json

Adesso che sei dentro il file composer.json seleziona la lettera “i” nella tastiera, questo ti permetterà di modificare il file. Aggiungi le seguenti righe:

{
    "require": {
        "facebook/php-business-sdk": "12.0.*"
    }
}

Ora clicca nella tastiera “esc” e poi “:wq” e invio. Questo salverà e chiuderà il file. Adesso esegui il seguente comando composer:

composer require php-http/guzzle6-adapter

Se ricevi qualche errore o avviso molto probabilmente è perché non hai ancora installato il composer, per farlo utilizza l’apposita guida nella documentazione composer.

Se vogliamo (te lo consiglio) possiamo utilizzare dotenv per far si che il nostro pixel ID, ma specialmente il token per il Conversion API sia più protetto.

Anche qui dovremo installare una libreria apposita. Torna sotto public_html o dove hai installato WordPress e invia la seguente linea:

mkdir dotenv
cd dotenv
vim composer.json

Adesso dentro il file composer.json aggiungi il relativo codice:

{
    "require": {
        "vlucas/phpdotenv": "^5.4"
    }
}

Ora seleziona “esc”, poi “:wq” e invia. Adesso esegui il comando composer:

composer require vlucas/phpdotenv

Infine crea il file .env sempre sotto public_html o la cartella dove hai installato WordPress e inserisci il nome delle variabili e il relativo valore con questo formato:

PIXEL_ID = 'XXXXXXXXXXXXXXX'
ACCESS_TOKEN = 'XXXXXXXXXXXXXXXXXXXXXXXXXXX.....'

Ottimo, ora dovresti aver appena installato tutte le librerie di cui abbiamo bisogno!

Implementare evento PageView Conversion API tramite PHP

Adesso che abbiamo installato la libreria SDK possiamo iniziare a scrivere il codice che richiamerà l’evento da noi voluto. Partiamo dall’evento PageView, ok?

Per l’implementazione in questione viene utilizzato un sito WordPress, dunque se si utilizza un sito completamente custom o qualsiasi altro CMS bisogna riadattare ciò che vedrai sotto. Inoltre se non vuoi perdere queste modifiche ti consiglio di installare un tema child.

Ti consiglio di iniziare ad utilizzare un vero editor di codice come Atom o Visual Studio Code tramite connessione SFTP o FTP. Tranquillo, sono tutti e due gratis.

Vai nel file header.php del tuo tema figlio e aggiungi la seguente riga di codice tra i tag di apertura e chiusura PHP:

<?php
include get_template_directory() . '/event-fb-api/page-view.php';
?>

Questa linea di codice ci permette di richiamare un altro file che avrà tutto il codice per l’implementazione dell’evento PageView lato server. Volendo possiamo scrivere il codice anche al posto dell’include, ma io ti consiglio di utilizzarlo per avere un ambiente di lavoro il più pulito possibile.

Crea la cartella event-fb-api con al proprio interno il file page-view.php proprio sotto la cartella del tuo tema figlio e iniziamo a richiamare alcune parti delle librerie installate:

<?php
/*--------------------------------------
 * Richiama dipendenze necessarie per configurazione CAPI di Facebook
-------------------------------------*/
require getcwd() . '/fb-api/vendor/autoload.php';
require getcwd() . '/dotenv/vendor/autoload.php';
use FacebookAds\Api;
use FacebookAds\Object\ServerSide\CustomData;
use FacebookAds\Object\ServerSide\ActionSource;
use FacebookAds\Object\ServerSide\Event;
use FacebookAds\Object\ServerSide\EventRequest;
use FacebookAds\Object\ServerSide\EventRequestAsync;
use FacebookAds\Object\ServerSide\UserData;
// Imports used by the TestHttpClient class
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Promise;

Ora solo se stai utilizzando Cookiebot come servizio di generazione cookie banner puoi utilizzare il seguente codice per far partire il CAPI di Facebook solo se vengono accettati anche i cookie di marketing. Nella documentazione per sviluppatori di cookiebot trovi il codice utilizzato.

È importante dire che il Conversion API non utilizza alcun cookie, ma non esistendo ancora un metodo per tutelare il visitatore da questa tipologia di tracciamento l’unico sistema che abbiamo per tutelarlo è quello di utilizzare il consenso alla cookie banner.

Dunque sempre dentro il file page-view.php aggiungiamo:

/*-------------------------------------- 
 * Controllo custom per consenso GDPR CookieBot lato marketing
-------------------------------------*/
if (isset($_COOKIE["CookieConsent"])) {
  switch ($_COOKIE["CookieConsent"]) {
    case "-1":
      //L'utente non è in una regione che richiede consenso - tutti i cookie sono accettati
      break;
    default: //L'utente ha dato il consenso
      //Leggi il consenso dell'utente attuale nel formato codificato JavaScript
      $valid_php_json = preg_replace('/\s*:\s*([a-zA-Z0-9_]+?)([}\[,])/', ':"$1"$2', preg_replace('/([{\[,])\s*([a-zA-Z0-9_]+?):/', '$1"$2":', str_replace("'", '"',stripslashes($_COOKIE["CookieConsent"]))));
      $CookieConsent = json_decode($valid_php_json);
      if (!filter_var($CookieConsent->preferences, FILTER_VALIDATE_BOOLEAN) && !filter_var($CookieConsent->statistics, FILTER_VALIDATE_BOOLEAN) && !filter_var($CookieConsent->marketing, FILTER_VALIDATE_BOOLEAN)) {
        //L'utente ha disattivato i cookie; impostare solo i cookie strettamente necessari
      } else {
        if (filter_var($CookieConsent->preferences, FILTER_VALIDATE_BOOLEAN)) {
          //L'utente corrente accetta cookie di preferenza
        } else {
          //L'utente corrente NON accetta cookie di preferenza
        }
        if (filter_var($CookieConsent->statistics, FILTER_VALIDATE_BOOLEAN)) {
          //L'utente corrente accetta cookie di statistica
        } else {
          //L'utente corrente NON accetta cookie di statistica
        }
        if (filter_var($CookieConsent->marketing, FILTER_VALIDATE_BOOLEAN)) {
         // Qui dobbiamo aggiungere il codice per l'evento server side CAPI
        } else {
          //L'utente corrente NON accetta cookie di marketing
        }
      }
    }
}
?>

Non ci resta altro che aggiungere la parte di codice che andrà a richiamare l’evento voluto (in questo caso PageView) subito sotto o al posto del commento “Qui dobbiamo aggiungere il codice per l’evento server side CAPI”:

/*---------------------------
  * Richiamare il valore Pixel ID e Token utilizzando dotenv
---------------------------*/
$dotenv = Dotenv\Dotenv::createImmutable('/home/jbxuinjk/weraigo.it/');
$dotenv->safeLoad();
$access_token = $_ENV['ACCESS_TOKEN'];
$pixel_id = $_ENV['PIXEL_ID'];

/*---------------------------
  * Qui inizia il codice che fa funzionare l'evento server side
---------------------------*/
// Generazione un eccezione nel caso in cui uno o entrambi tra il pixel e il token sono vuoti
if (empty($pixel_id) || empty($access_token)) {
  throw new Exception('Missing required test config. Got pixel_id: "' . $pixel_id . '", access_token: "' . $access_token . '"');
}

// Inizializza
Api::init(null, null, $access_token, false);

// Crea l'evento
function create_events() {
  $user_data = (new UserData())
  ->setClientIpAddress($_SERVER['REMOTE_ADDR'])
  ->setClientUserAgent($_SERVER['HTTP_USER_AGENT']);

  $custom_data = (new CustomData())
  ->setContentName(get_the_title())
  ->setContentType(get_post_type(get_the_ID()));

  $event = (new Event())
  ->setEventName('PageView')
  ->setEventTime(time())
  ->setEventSourceUrl(get_URL_page())
  ->setUserData($user_data)
  ->setCustomData($custom_data)
  ->setActionSource(ActionSource::WEBSITE);

  return array($event);
}

// Crea la richiesta in modo asincrono
function create_async_request($pixel_id) {
  $async_request = (new EventRequestAsync($pixel_id))
  //->setTestEventCode('TEST34639')
  ->setEvents(create_events());
  return $async_request->execute()
  ->then(
    null,
    function (RequestException $e) {
      print(
        "Error!!!\n" .
        $e->getMessage() . "\n" .
        $e->getRequest()->getMethod() . "\n"
      );
    }
  );
}

// Funzione che recupera l'URL della pagina visualizzata
function get_URL_page(){
  if(isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on')
    $link = "https";
  else
    $link = "http";

  // Here append the common URL characters.
  $link .= "://";

  // Append the host(domain name, ip) to the URL.
  $link .= $_SERVER['HTTP_HOST'];

  // Append the requested resource location to the URL
  $link .= $_SERVER['REQUEST_URI'];
 
  // Print the link
  return $link;
}

// Chiama la richiesta asincrona
$promise = create_async_request($pixel_id);

Utilizza le 4 righe di codice iniziali solamente nel caso in cui tu abbia deciso di utilizzare dotenv. Se per qualsiasi ragione hai deciso di non utilizzarlo rimuovi le prime due righe e sostituisci i valori a variabile con i valori effettivi.

Bene, ora se header.php è presente su ogni pagina del tuo sito l’evento PageView dovrebbe attivarsi su qualsiasi pagina. Nel caso in cui possiedi delle pagine che non hanno header.php ti basterà inserire l’include iniziale. Comodo, vero?

Implementare qualsiasi tipo di evento con Conversion API tramite PHP

Abbiamo visto come utilizzare l’evento server side PageView, ma come utilizzare un qualsiasi altro evento standard o anche custom? Il metodo è lo stesso, semplicemente nella funzione create_events() andrà modificato il tipo di evento.

function create_events() {
  $user_data = (new UserData())
  ->setEmail($email)
  ->setClientIpAddress($_SERVER['REMOTE_ADDR'])
  ->setClientUserAgent($_SERVER['HTTP_USER_AGENT']);

  $custom_data = (new CustomData())
  ->setContentName(get_the_title())
  ->setContentType(get_post_type(get_the_ID()));

  $event = (new Event())
  ->setEventName('Lead') // Lead per generazione contatto o Purchase nel caso di un acquisto
  ->setEventTime(time())
  ->setEventSourceUrl(get_URL_page())
  ->setUserData($user_data)
  ->setCustomData($custom_data)
  ->setActionSource(ActionSource::WEBSITE);

  return array($event);
}

Oppure ancora nel caso di un evento custom:

function create_events() {
  $user_data = (new UserData())
  ->setClientIpAddress($_SERVER['REMOTE_ADDR'])
  ->setClientUserAgent($_SERVER['HTTP_USER_AGENT']);

  $custom_data = (new CustomData())
  ->setStatus($social_cliccato)
  ->setContentName(get_the_title($id_post))
  ->setContentType(get_post_type($id_post));

  $event = (new Event())
  ->setEventName('condivisione') // Evento custom condivisione per misurare gli eventi di condivisione di una pagina
  ->setEventTime(time())
  ->setEventSourceUrl(get_permalink($id_post))
  ->setUserData($user_data)
  ->setCustomData($custom_data)
  ->setActionSource(ActionSource::WEBSITE);

  return array($event);
}

Testare gli event server side CAPI di Facebook

Come possiamo verificare che gli eventi server side funzionino correttamente?

È molto semplice. Basta aggiungere nella funzione create_async_request sopra o sotto ->setEvents(create_events()); la seguente riga di codice:

->setTestEventCode('TESTXXXXX')

Nel codice indicato sopra è già presente. Ti basterà rimuovere il commento (le due slash all’inizio della riga) e inserire il tuo test event code.

Al posto di TESTXXXXX dovrai inserire il tuo test_event_code che puoi trovare andando sul business manager specifico, gestione eventi, pixel prescelto e infine testa gli eventi.

Testare gli eventi Meta Facebook del pixel e Conversion API

Una volta fatto, sempre su questa pagina, inserisci l’URL della pagina dove vuoi testare l’evento e verifica che funzioni tutto.

Conclusioni

Alla fine non è poi così complicato, giusto? Una volta installate le librerie basterà applicare lo stesso codice e cambiare solo il nome dell’evento e le relative informazioni.

Ma se hai avuto qualsiasi tipo di problema o hai richieste specifiche che ti piacerebbe delegare io sono qui apposta. Scrivimi all’email [email protected].

Per il momento ti saluto e noi ci vediamo alla prossima guida! 😉

Come configurare il Conversion API di Facebook tramite PHP