Marketing API

Status deines Werbeobjekts verwalten

Werbekampagnen, Anzeigengruppen und Werbeanzeigen haben einen der folgenden Statustypen:

  • Live
  • Archiviert
  • Gelöscht

Mehr Informationen dazu findest du im Entwickler-Blog für Werbung, Vergleich zwischen Gelöscht und Archiviert.

Live

Live-Werbeobjekte können die folgenden Statustypen aufweisen:

  • ACTIVE
  • PAUSED
  • PENDING_REVIEW
  • CREDIT_CARD_NEEDED
  • PREAPPROVED
  • DISABLED
  • PENDING_PROCESS
  • WITH_ISSUES

Archiviert

Setze den Werbeobjektstatus auf ARCHIVED, indem du das Statusfeld status auf ARCHIVED setzt. Wenn ein Objektstatus auf ARCHIVED gesetzt ist, kannst du die Details und Statistiken weiterhin basierend auf der Objekt-ID abfragen. Du kannst aber nur eine begrenzte Anzahl von Objekten archivieren. Du solltest diese Beschränkung beachten und den Status in DELETED ändern, wenn du ein Objekt nicht mehr benötigst.

Ein ARCHIVED-Objekt weist nur zwei änderbare Felder auf: name und status. Du kannst auch status in DELETED ändern.

Gelöscht

Du kannst den Objektstatus auf DELETED setzen, indem du entweder das Statusfeld status auf DELETED setzt oder eine HTTP DELETE-Anfrage an dieses Objekt sendest. Nachdem ein Objektstatus auf DELETED gesetzt wurde, kann er nicht mehr in ARCHIVED zurückgeändert werden.

Wenn du die ID des gelöschten Objekts beibehältst, kannst du weiterhin die Statistiken oder Objektdetails abrufen, indem du die Objekt-ID abfragst. Du kannst die gelöschten Objekte allerdings nicht als Verbindungsobjekt von einem nicht gelöschten Node oder Objekt abrufen. <API_VERSION>/<AD_ID>/insights funktioniert beispielsweise für ein gelöschtes Objekt, <API_VERSION>/act_<AD_ACCOUNT_ID>/insights?level=ad gibt aber keine Statistiken für das gelöschte Objekt zurück.

Wenn du eine Werbeanzeige löschst, verfolgt diese gegebenenfalls Werbeanzeige für weitere 28 Tage nach ihrem letzten Auslieferungsdatum Impressionen, Klicks und Handlungen. Du kannst für DELETED-Objekte Insights abfragen, indem du den Filter ad.effective_status verwendest.

Wenn du eine Anzeigengruppe mit zwei Werbeanzeigen hast und eine dieser Werbeanzeigen löschst, geben die folgenden zwei Abfragen nicht dieselben Ergebnisse zurück:

https://graph.facebook.com/v19.0/<AD_SET_ID>/insights
https://graph.facebook.com/v19.0/<AD_ID>/insights

Die Anzeigengruppe gibt Statistiken für die enthaltenen gelöschten und nicht gelöschten Werbeanzeigen zurück. Wenn du jedoch Abfragen für Werbeanzeigen on der Anzeigengruppe tätigst, siehst du nur eine Werbeanzeige.

https://graph.facebook.com/v19.0/<AD_SET_ID>/ads

Um dieses Szenario zu vermeiden, solltest du Werbeanzeigen 28 Tage nach dem letzten Auslieferungsdatum löschen, damit sich Statistiken nicht mehr ändern. Außerdem solltest du die Statistiken oder IDs dieser Objekte in deinem eigenen System speichern, bevor du sie löschst. Diese Empfehlung ist optional:

  • Falls deine App die Aufschlüsselung der Statistiken nicht anzeigt oder
  • falls es dich nicht stört, wenn die Summe der Statistik-Aufschlüsselung nicht mit der des übergeordneten Objekts übereinstimmt, weil einige untergeordnete Objekte gelöscht wurden.

Du kannst für ein DELETED-Objekt in keinem Feld Änderungen vornehmen, mit Ausnahme von name.

Status verwalten

So verwaltest du normalerweise den Objektstatus:

  • Du erstellst Werbeobjekte, diese werden live geschaltet und liefern Ergebnisse.
  • Wenn du ein Objekt löschst, löschen wir es automatisch.
  • Wenn du die Grenze für archivierte Objekte erreichst, kannst du keine weiteren Objekte mehr archivieren.
  • Du musst diese archivierten gelöschten Objekte in den Status deleted versetzen, um die Begrenzung zu unterschreiten.

Der Status für Anzeigenobjekte funktioniert für die Hierarchie von Anzeigenobjekte auf diese Weise:

  • Wenn der Status für eine Kampagne auf with_issues, paused, archived oder deleted festgelegt ist, werden alle Objekte darunter ebenfalls auf den jeweiligen Status gesetzt.
  • Wenn du eine Werbekampagne zum deleted festgelegt hast, kannst du die Anzeigengruppen oder die Werbeanzeigen unter dieser Kampagne nicht mehr abrufen, ohne die IDs explizit anzugeben.
  • Wenn der Status einer Anzeige auf with_issues, paused, archived oder deleted festgelegt ist, behält die Anzeigengruppe oder die Werbekampagne, die diesen Banner enthält, seinen ursprünglichen Status und ist für die Wiedergabe verfügbar.

Die folgenden Begrenzungen gelten für ARCHIVED-Objekte für ein Werbekonto:

  • 100.000 für Werbekampagnen
  • 100.000 für Anzeigengruppen
  • 100.000 für Werbeanzeigen

Wenn du Edges mit dem Status archived liest, musst du konkret nach den archivierten Objekten filtern, da wir diese nicht standardmäßig zurückgeben. Wenn du Statistiken für ein Anzeigenobjekt liest, nehmen wir die Statistiken aller untergeordneten Objekte mit auf, unabhängig davon, ob diese den Status active, archived oder deleted haben. Daher benötigst du keinen Filter für Statistiken für untergeordnete Objekte.

Vergleiche von unterschiedlichen Statusangaben

Objekte mit einem Status wie zum Beispiel ACTIVE oder PAUSED unterscheiden sich von solchen mit einem Status wie ARCHIVED oder DELETED. Nachstehend sind die wichtigsten Unterschiede aufgeführt.

Abfrage Live ARCHIVED DELETED

In Datenbank vorhanden

Ja

Ja

Ja

Maximale Anzahl pro Werbekonto

Mit Begrenzungen

100.000

Keine Begrenzung

Als Edges ohne Filter abfragen

Ja

Nein

Nein

Als Edges mit Statusfilter abfragen

Ja, bei Objekten, deren Status im Filter enthalten ist

Ja, wenn der Statusfilter ARCHIVED enthält.

Nein, wenn der Statusfilter DELETED nicht enthält, und Fehler, wenn er es enthält.

Nach eigener ID abfragen

Ja

Ja

Ja

In /<PARENT_OBJECT_ID>/insights aggregierte Statistiken

Ja

Ja

Ja

In der Ergebnisliste von /<PARENT_OBJECT_ID>/insights?level=<OBJECT_LEVEL> enthaltene Statistiken

Ja

Nein

Nein

In der Ergebnisliste von /<PARENT_OBJECT_ID>/insights enthaltene Statistiken mit delivery_info-Filterung

Ja, bei Objekten, deren Status im Filter enthalten ist

Ja, bei Objekten, deren Status im Filter enthalten ist

Nein

Mit /<OBJECT_ID>/insights angezeigte Statistiken

Ja

Ja

Ja

Status kann geändert werden in

jeden beliebigen Status

DELETED

Keine Änderung möglich

So legst du die Archivierung für eine Werbeanzeige fest:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->archive();
from facebookads.adobjects.ad import Ad

ad = Ad(ad_id)
ad.remote_archive()
new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_ARCHIVED)
  .execute();
curl \
  -F 'status=ARCHIVED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>

So löscht du eine Werbeanzeige:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->deleteSelf();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad.remote_delete()
new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_DELETED)
  .execute();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/

So rufst du Live-Unterobjekte eines Live-Objekts ab (z. B. alle Live-Werbeanzeigen einer Werbekampagne, ohne ARCHIVED- oder DELETED-Werbeanzeigen):

curl -X GET \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_CAMPAIGN_ID>/ads
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Campaign = bizSdk.Campaign;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_CAMPAIGN_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
  'name',
];
params = {
};
const adss = (new Campaign(id)).getAds(
  fields,
  params
);
logApiCallResult('adss api call complete.', adss);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_CAMPAIGN_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'name',
);
$params = array(
);
echo json_encode((new Campaign($id))->getAds(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.campaign import Campaign
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'name',
]
params = {
}
print Campaign(id).get_ads(
  fields=fields,
  params=params,
)
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_CAMPAIGN_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Campaign(id, context).getAds()
      .requestNameField()
      .execute();

  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

campaign = FacebookAds::Campaign.get(id)
adss = campaign.ads({
    fields: { 'name' },
})

So rufst du ARCHIVED-Unterobjekte eines Live-Objekts ab, z. B. alle ARCHIVED-Werbeanzeigen einer Anzeigengruppe (erfordert den Statusfilter):

curl -X GET \
  -d 'effective_status=[
       "ARCHIVED"
     ]' \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_CAMPAIGN_ID>/ads
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Campaign = bizSdk.Campaign;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_CAMPAIGN_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
  'name',
];
params = {
  'effective_status' : ['ARCHIVED'],
};
const adss = (new Campaign(id)).getAds(
  fields,
  params
);
logApiCallResult('adss api call complete.', adss);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_CAMPAIGN_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'name',
);
$params = array(
  'effective_status' => array('ARCHIVED'),
);
echo json_encode((new Campaign($id))->getAds(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.campaign import Campaign
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'name',
]
params = {
  'effective_status': ['ARCHIVED'],
}
print Campaign(id).get_ads(
  fields=fields,
  params=params,
)
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_CAMPAIGN_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Campaign(id, context).getAds()
      .setEffectiveStatus(\"[\\"ARCHIVED\\"]\")
      .requestNameField()
      .execute();

  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_CAMPAIGN_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

campaign = FacebookAds::Campaign.get(id)
adss = campaign.ads({
    fields: { 'name' },
    effective_status: ['ARCHIVED'],
})