Im Rahmen der ersten virtuellen Allfacebook Marketing Conference 2020 habe ich in meinem Homeoffice über die Programmierschnittstelle von Facebook gesprochen.
In Wahrheit ist es ja gar nicht eine einzige Marketing API, sondern Facebook bietet eine ganze Reihe von unterschiedlichen, allesamt spannenden Interfaces an, um sowohl Informationen/Daten aus Facebook abzusaugen, als auch hochzuladen. In diesem Artikel zeige ich alle Codebeispiele in PHP.
Vorbereitungsarbeiten
- Zuerst installieren wir uns XAMPP. Ein kleiner, aber feiner Apache Webserver, der nichts kostet und rasch installiert ist. Perfekt für lokales Testen von Webanwendungen – die Domain im Testbetrieb heißt dann https://localhost/
- Dann holen wir uns Composer. Den brauchen wir, um die aktuellste Version des graph-sdk und des php-business-sdk auf unseren Rechner zu bringen.
- PHP kann man grundsätzlich auch in jedem Windows-Editor eintippseln. Der kostenlose Visual Studio Code von Microsoft ist aber in jedem Fall empfehlenswert. Das farbliche Syntax Highlighting, die optischen Schleifenstrukturen und das Autocomplete für Variablen/Funktionen ist sehr praktisch.
- Jetzt können wir unsere erste Facebook App anlegen – ohne einer solchen App können wir später die API nicht nutzen.
Access Token
Facebook verwendet für eine standardisierte und sichere API-Autorisierung in Desktop-, Web- und Mobile-Anwendungen Open Authorization (=OAuth).
Klarerweise können maximal Rechte autorisiert werden, die der Resource Owner selbst innehat.
Achtung: die meisten Ad-relevanten Berechtigungen werden von Facebook nur auf Anfrage freigeschaltet – das kann manchmal Tage/Wochen dauern. Im Testbetrieb kann man trotzdem den benötigten Zugriffsschlüssel ganz einfach erzeugen und verwenden. Im späteren Echtbetrieb müssen wir das dann über OAuth anfordern: getAccessToken()
Codebeispiel 1: Einsatz der Graph API
Wir lesen den Namen und die Profilbild-URL eines bestimmten Users aus und geben das am Schirm aus. 2stufiger Aufbau: In login.php ist die Authentifizierung mit Redirect und in index.php steht der restliche Code.
<?php
// Simples Beispiel, wie der Authentifizierungsprozess von Facebook angestoßen wird
// Datum: 19.03.2020
// Autor: Thomas Thaler
// Datei: login.php
require_once(‚../../vendor/autoload.php‘);
session_start();
$fb = new Facebook\Facebook([
‚app_id‘ => ‚3292890580740206‘, // Unsere APP-ID
‚app_secret‘ => ‚7534fef1d75f9b78be82eccf1871c8e9‘, // Unser Geheimcode
‚default_graph_version‘ => ‚v6.0‘,
]);
$helper = $fb->getRedirectLoginHelper();
// Alle möglichen Permissionen findet man unter https://developers.facebook.com/docs/facebook-login/permissions
// Sie werden jeweils mit Komma getrennt, also zB [‚email,user_hometown‘]
$permissions = [‚email,business_management,ads_read,ads_management,attribution_read‘];
// Achtung: die meisten Ad-relevanten Berechtigungen werden von Facebook nur auf Anfrage erteilt.
// Wir können aber zum Entwicklen jederzeit die Testumgebung nutzen
$loginUrl = $helper->getLoginUrl(‚https://localhost/afbmc2020/index.php‘, $permissions);
?>
<!DOCTYPE html>
<html>
<head>
<title>
Token holen – im Rahmen der AFBMC Advanced
</title>
</head>
<body>
<h1>Namen meines FB Profils auslesen:</h1>
<?php
// Ganz simples Beispiel, wie man sich ein Token besorgt und den Namen eines FB Profils ausliest
// Datum: 19.03.2020
// Autor: Thomas Thaler
// Datei: index.php
require_once(‚../../vendor/autoload.php‘);
session_start();
$fb = new Facebook\Facebook([
‚app_id‘ => ‚3292890580740206‘, // Unsere APP-ID
‚app_secret‘ => ‚7534fef1d75f9b78be82eccf1871c8e9‘,
‚default_graph_version‘ => ‚v6.0‘,
]);
$helper = $fb->getRedirectLoginHelper();
try { // Gibt es bereits ein Access-Token?
$accessToken = $helper->getAccessToken();
}
// Exceptions Handling
catch(Facebook\Exceptions\FacebookResponseException $e) {
echo ‚Der Open Graph macht beim Access Token wieder mal nicht, was er soll: ‚ . $e->getMessage();
exit;
}
catch(Facebook\Exceptions\FacebookSDKException $e) {
echo ‚Das Facebook SDK macht beim Access Token schon wieder Zicken: ‚ . $e->getMessage();
exit;
}
if (! isset($accessToken)) {
if ($helper->getError()) {
header(‚HTTP/1.0 401 Unauthorized‘);
echo „Error: „ . $helper->getError() . „\n„;
echo „Error Code: „ . $helper->getErrorCode() . „\n„;
echo „Error Reason: „ . $helper->getErrorReason() . „\n„;
echo „Error Description: „ . $helper->getErrorDescription() . „\n„;
}
else {
header(‚HTTP/1.0 400 Bad Request‘);
echo ‚Bad request‘;
}
exit;
}
// Ab hier sind wir eingelogt und startbereit
try {
$response = $fb->get(‚/100000069810168?scope=email‘, $accessToken);
// Verweis auf das FB-Profil von Thomas Thaler nun in der Variable RESPONSE
}
catch(\Facebook\Exceptions\FacebookResponseException $e) {
echo ‚Der Open Graph macht bei fb->get wieder mal nicht, was er soll: ‚ . $e->getMessage();
exit;
}
catch(\Facebook\Exceptions\FacebookSDKException $e) {
echo ‚Das Facebook SDK macht bei fb->get schon wieder Zicken: ‚ . $e->getMessage();
exit;
}
// Verweis auf die Facebook\GraphNodes\GraphUser collection in der Variable GRAPH
// Hier stehen alle Zugriffsfunktionen auf die Collection: https://developers.facebook.com/docs/php/GraphNode/5.0.0#user-instance-methods
$graph = $response->getGraphUser();
echo ‚<h3> Mein Name ist:‘ . $graph->getName() . ‚</h3>‘; // Name ausgeben
echo ‚<br> URL meines Profilbildes: ‚.‚https://graph.facebook.com/‘.$graph->getId().‚/picture?width=300‘.‚</br>‘;
?>
</body>
</html>
Codebeispiel 2: Reports mit der Business API erstellen
Wir stellen mit einem (dank Test-Umgebung bereits fertigen) Token die Verbindung mit einem Werbekonto her. Dann laden wir alle aktiven Kampagnen und deren AdSets und Ads. Holen uns Impressionen, Reichweite und Ausgaben von jedem Ad und transferieren diese Werte via Zapier in ein GoogleSheet.
Webhooks werden für Echtzeit-Benachrichtigungen verwendet, sind in der Regel HTTP Callback Points. In diesem Fall: Sobald die Zapier-Webhook-URL später durch unser PHP-Script mit Parametern aufgerufen wird, werden diese Werte automatisch in die aktuelle Zeile eines zuvor definierten Googlesheet eingetragen.
<!DOCTYPE html>
<html>
<head>
<title>
Einfache Ad-Reports – im Rahmen der AFBMC Advanced
</title>
</head>
<body>
<h1>Einfache Ad-Reports zum Selbermachen:</h1>
<?php
// Simples Beispiel, wie man Kampagnenergebnisse aus einem Facebook Werbekonto ausliest und an ein GoogleSheet übergibt
// Datum: 19.03.2020
// Autor: Thomas Thaler
// Datei: reports.php
require_once(‚../../vendor/autoload.php‘);
session_start();
$fb = new Facebook\Facebook([
‚app_id‘ => ‚3292890580740206‘, // Unsere APP-ID
‚app_secret‘ => ‚7534fef1d75f9b78be82eccf1871c8e9‘, // Geheimer APP-Code
‚default_graph_version‘ => ‚v6.0‘,
]);
// Das frisch angelegte Objekt $fb gibt uns nun in der Zugriff auf den Facebook Objektbaum
$fbApp = $fb->getApp();
// Hier werden die verwendeten globalen Facebook Klassen importiert – die kommen vom SDK.
// Damit haben wir Zugriff auf alle dort deklarierten Funktionen und Konstanten
use FacebookAds\Api;
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Campaign;
use FacebookAds\Object\AdSet;
use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\CampaignFields;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\AdFields;
use FacebookAds\Object\Fields\InsightsFields;
use FacebookAds\Object\Values\InsightsResultDatePresetValues;
// Den OAuth-Token kopieren wir uns aus der Testumgebung von Facebook.
$accessToken=‚EAAuy3dVZAaG4BAtNumWQ6OuAy7AxZB8FFoBjAMQkH0owGLhXtNvUOAL9Yb3GZBfcZCjGfk0axvH4SJ74cUZD‘;
$account_id = ‚act_1084216258275099‘; // Die ID des gewünschten Werbekontos. Immer beginnend mit act_
// Über den OAuth-Token stellen wir nun die Verbindung zu Facebook her
$api = Api::init($fbApp->getId(), $fbApp->getSecret(), $accessToken);
// Das frisch angelegte Objekt $adaccount gibt uns nun Zugriff auf das gewünschte Werbekonto
$adaccount = new AdAccount($account_id);
// Die gesamte Referenz zur API 6.0 gibt es unter https://developers.facebook.com/docs/marketing-api/reference/v6.0
// Wenn wir uns unsicher sind, einfach in der Datei FacebookAds\Object\Fields\CampaignFields.php nachschauen, welche Felder es gibt.
// Die FB Hilfe ist manchmal ein wenig gaga 😉
$fields = array(‚id‘,’name‘,’status‘);
$params = array(
‚time_interval‘ => array(
‚day_start‘ => array(‚year‘ =>‚2020‘, ‚month‘=> ‚2‘, ‚day‘=>‚1‘),
‚day_stop‘ => array( ‚year‘=>‚2020‘, ‚month‘=>‚2‘, ‚day‘=>’29‘)
),
‚effective_status‘ => array(‚ACTIVE‘)
// ‚effective_status‘ => array(‚ACTIVE‘,’PAUSED‘) // Für einen kompletten Report sollten wir immer aktive und pausierte Kampagnen berücksichtigen
);
// Es können später nur Spalten ausgewertet werden, die bei der Kreation des Objektes angefragt wurden
$AllCampaigns = $adaccount->getCampaigns($fields,$params);
// Praktisch: der HTML Tag <pre> baut schöne Struktur, print_r gibt Variablen-Informationen (auch ganze Objekte) in lesbarer Form aus
// echo ‚<pre>‘;
// print_r($AllCampaigns);
foreach ($AllCampaigns as $currentCampaign) {
// Die Variable $currentCampaign zeigt in der Schleife jeweils auf den Objektbaum der aktuell betrachteten Kampagne
echo ‚<br> Wir schauen uns nun folgende Kampagnen-ID an: ‚.$currentCampaign->{CampaignFields::ID}.“ Kampagnenname: „.$currentCampaign->{CampaignFields::NAME}.“ Status: „.$currentCampaign->{CampaignFields::STATUS}.‚</br>‘;
$fields = array(‚id‘,’name‘,’status‘);
$params = array(‚campaign_id‘ => $currentCampaign->{CampaignFields::ID});
$AllAdSets = $currentCampaign->getAdSets($fields,$params);
foreach ($AllAdSets as $currentAdSet) {
echo ‚<br>-> Wir schauen uns nun folgende AdSet-ID an: ‚.$currentAdSet->{AdSetFields::ID}.“ AdSetname: „.$currentAdSet->{AdSetFields::NAME}.“ Status: „.$currentAdSet->{AdSetFields::STATUS}.‚</br>‘;
$fields = array(‚id‘,’name‘,’status‘);
$params = array(‚campaign_id‘ => $currentCampaign->{CampaignFields::ID},‚adset_id‘ => $currentAdSet->{AdSetFields::ID});
$AllAds = $currentAdSet->getAds($fields,$params);
foreach ($AllAds as $currentAd) {
echo ‚<br>—> Wir schauen uns nun folgende Ad-ID an: ‚.$currentAd->{AdFields::ID}.‚</br>‘;
$fields = array(
InsightsFields::IMPRESSIONS,
InsightsFields::REACH,
InsightsFields::SPEND,
);
$params = array(‚date_preset‘ => InsightsResultDatePresetValues::LAST_7D); // Zeitraum des Reports einstellen
// Ergebnisse des aktuell betrachteten Ads in das Array $insights laden
// Achtung: Es werden immer nur diejenigen Felder befüllt, die wir vorhin in der Variable $fields definiert haben. Der Rest ist leer.
$insights = $currentAd->getInsights($fields, $params)[0]->getData();
echo ‚<br>—–> Impressionen: ‚.$insights{InsightsFields::IMPRESSIONS}.‚</br>‘;
echo ‚<br>—–> Reach: ‚.$insights{InsightsFields::REACH}.‚</br>‘;
echo ‚<br>—–> Spend: ‚.$insights{InsightsFields::SPEND}.‚</br>‘;
// Jetzt übergeben wir die frisch geladenen Werte an den zuvor in Zapier definierten Webhook. Es wird eine frische Zeile im GoogleSheet angelegt.
$handle = fopen(‚https://hooks.zapier.com/hooks/catch/2054552/odm4w6a/?AdName=‘ . $currentAd->{AdFields::ID} . ‚&Impressions=‘. $insights{InsightsFields::IMPRESSIONS} .‚&Reach=‘ . $insights{InsightsFields::REACH} .‚&Spend=‘. $insights{InsightsFields::SPEND}, ‚r‘);
fclose($handle);
}
}
}
?>
</body>
</html>
Codebeispiel 3: Automatisiert Kampagnen erstellen
Wir definieren eine neue Kampagne und legen die automatisch in einem Werbekonto an. Unter dieser Kampagne keieren wir ein frisches AdSet (simples Targeting, Start/Ende, Gebote) und lassen das ebenfalls im Werbekonto anlegen.
<!DOCTYPE html>
<html>
<head>
<title>
Automatisiert Kampagnen und AdSets anlegen – im Rahmen der AFBMC Advanced
</title>
</head>
<body>
<h1>Automatisiert Kampagnen und AdSets anlegen:</h1>
<?php
// Simples Beispiel, wie automatisiert Kampagnen und AdSets in einem Facebook Werbekonto erstellt
// Datum: 19.03.2020
// Autor: Thomas Thaler
// Datei: bulkanlegen.php
require_once(‚../../vendor/autoload.php‘);
session_start();
$fb = new Facebook\Facebook([
‚app_id‘ => ‚3292890580740206‘, // Unsere APP-ID
‚app_secret‘ => ‚7534fef1d75f9b78be82eccf1871c8e9‘, // Geheimer APP-Code
‚default_graph_version‘ => ‚v6.0‘,
]);
// Das frisch angelegte Objekt $fb gibt uns nun in der Zugriff auf den Facebook Objektbaum
$fbApp = $fb->getApp();
// Hier werden die verwendeten globalen Facebook Klassen importiert – die kommen vom SDK.
// Damit haben wir Zugriff auf alle dort deklarierten Funktionen und Konstanten
use FacebookAds\Api;
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Campaign;
use FacebookAds\Object\AdSet;
use FacebookAds\Object\Ad;
use FacebookAds\Object\Targeting;
use FacebookAds\Object\Fields\CampaignFields;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\AdFields;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Values\CampaignObjectiveValues;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;
use FacebookAds\Object\Values\AdSetBillingEventValues;
// Den OAuth-Token kopieren wir uns aus der Testumgebung von Facebook.
$accessToken=‚EAAuy3dVZAaG4BAClAPBiGEdwGLhXtNvUOAL9Yb3GZBfcZCjGfk0axvH4SJ74cUZD‘;
$account_id = ‚act_49753873‘; // Die ID des gewünschten Werbekontos. Immer beginnend mit act_
// Über den OAuth-Token stellen wir nun die Verbindung zu Facebook her
$api = Api::init($fbApp->getId(), $fbApp->getSecret(), $accessToken);
// Das frisch angelegte Objekt $adaccount gibt uns nun Zugriff auf das gewünschte Werbekonto
$adaccount = new AdAccount($account_id);
echo “ Eine neue Kampagne wird angelegt <br /><br /> „;
// Die gesamte Referenz zur API 6.0 gibt es unter https://developers.facebook.com/docs/marketing-api/reference/v6.0
// Details zu Kampagnen gibt es unter https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group
// Wenn wir uns unsicher sind, einfach in der Datei FacebookAds\Object\Fields\CampaignFields.php nachschauen, welche Felder es gibt.
// Die FB Hilfe ist manchmal ein wenig gaga 😉
$fields = array();
$params = array(
’name‘ => ‚AFBMC Auto Anlage Kampagne – V1‘,
‚objective‘ => ‚POST_ENGAGEMENT‘,
’status‘ => ‚PAUSED‘,
’special_ad_category‘ => ‚NONE‘
);
// Mit den gerade eben definierten Werten wird nun eine neue Kampagne erzeugt und in der Variable $campaign gespeichert
$campaign = $adaccount->createCampaign($fields,$params);
$campaignid = $campaign->{CampaignFields::ID};
echo json_encode($campaign->exportAllData(), JSON_PRETTY_PRINT); // Formatierte Ausgabe
echo “ Eine neues AdSet wird angelegt <br /><br /> „;
$targeting = array(
‚geo_locations‘ => array(‚countries‘ => array(‚AT‘)), // Mal ganz simpel auf ganz Österreich
‚age_min‘ => 20, // Alter zwischen 20 und 30 Jahren
‚age_max‘ => 40
);
$fields = array();
$params = array(
AdSetFields::NAME => ‚AFBMC Auto Anlage AdSet – V1‘,
AdSetFields::CAMPAIGN_ID => $campaignid,
// Achtung: Das Tagesbudget steht hier ohne Komma, dh 1500 = 15,00€
AdSetFields::DAILY_BUDGET => ‚1500‘,
AdSetFields::OPTIMIZATION_GOAL => ‚POST_ENGAGEMENT‘,
AdSetFields::BILLING_EVENT => ‚IMPRESSIONS‘,
// Achtung: Das manuelle Gebot steht hier ohne Komma, dh 8 = 0,08€ pro Beitragsinteraktionen
AdSetFields::BID_AMOUNT => 8,
AdSetFields::TARGETING => $targeting,
AdSetFields::START_TIME => (new \DateTime(„+1 week“))->format(\DateTime::ISO8601),
AdSetFields::END_TIME => (new \DateTime(„+2 week“))->format(\DateTime::ISO8601)
);
// Mit den gerade eben definierten Werten wird nun ein neues AdSet unter der frischen Kampagne erzeugt und in der Variable $adset gespeichert
$adset = $adaccount->createAdSet($fields,$params);
echo “ Alles fertig. Das AdSet wurde angelegt <br /><br /> „;
?>
</body>
</html>
