Gestione dello stato dell'oggetto pubblicitario

La campagna pubblicitaria, il gruppo di inserzioni e le inserzioni stesse hanno uno dei seguenti tipi di stato:

Pubblicato
Archiviato
Eliminato

Per informazioni generali, consulta il Blog per gli sviluppatori di inserzioni, Eliminato vs. Archiviato.

Pubblicato

Gli oggetti pubblicitari pubblicati possono avere lo stato seguente:

ACTIVE
PAUSED
PENDING_REVIEW
CREDIT_CARD_NEEDED
PREAPPROVED
DISABLED
PENDING_PROCESS
WITH_ISSUES

Archiviato

Imposta l'oggetto pubblicitario su ARCHIVED impostando il campo status su ARCHIVED. Quando lo stato di un oggetto viene impostato su ARCHIVED, puoi continuare a eseguire query relativamente a dettagli e statistiche in base all'ID oggetto. Tuttavia, è previsto un limite massimo al numero di oggetti che puoi archiviare. Pertanto, devi rispettare tale limite e modificare lo stato in DELETED quando un oggetto non è più necessario.

Un oggetto ARCHIVED contiene solo 2 campi modificabili: name e status. Puoi anche modificare solo status in DELETED.

Eliminato

Imposta lo stato dell'oggetto pubblicitario su DELETED impostando il campo status su DELETED o inviando una richiesta HTTP DELETE a tale oggetto. Dopo che lo stato di un oggetto viene impostato su DELETED, non è più reimpostabile su ARCHIVED.

Se conservi l'ID dell'oggetto eliminato, puoi continuare a recuperare le statistiche o i dettagli dell'oggetto, effettuando query all'ID oggetto. Tuttavia, non puoi recuperare gli oggetti eliminati come oggetto di connessione da un nodo/oggetto non eliminato. Ad esempio, <API_VERSION>/<AD_ID>/insights funziona per un oggetto eliminato, ma <API_VERSION>/act_<AD_ACCOUNT_ID>/insights?level=ad non restituisce statistiche per esso.

Se elimini un'inserzione, questa potrebbe continuare comunque a monitorare impression, clic e azioni per 28 giorni dalla data dell'ultima pubblicazione. Puoi eseguire query sui dati statistici per oggetti DELETED usando il filtro ad.effective_status.

Se hai un gruppo di inserzioni contenente 2 inserzioni ed elimini una di esse, le 2 query seguenti non restituiranno gli stessi risultati:

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

Il gruppo di inserzioni restituisce statistiche sia per le inserzioni eliminate sia per quelle rimaste al suo interno. Tuttavia, quando effettui query per inserzioni nel gruppo di inserzioni, vedi solo un'inserzione:

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

Per evitare questa situazione, devi eliminare le inserzioni 28 giorni dopo l'ultima data di pubblicazione, in modo che le statistiche non subiscano altre modifiche. Inoltre, devi memorizzare le statistiche o gli ID di questi oggetti nel tuo sistema personale prima di procedere con l'eliminazione. Questo consiglio è opzionale:

se la tua app non mostra i dettagli delle statistiche, oppure
se per te non è un problema il fatto che la somma dei dettagli delle statistiche non corrisponda a quella dell'oggetto principale, a causa degli oggetti secondari eliminati.

Non puoi modificare alcun campo, ad eccezione di name, per un oggetto DELETED.

Gestione dello stato

Questo è il modo in cui di solito gestisci lo stato degli oggetti:

Crei gli oggetti pubblicitari che poi vengono pubblicati e iniziano a essere visualizzati.
Quando elimini un oggetto, l'eliminazione avviene automaticamente.
Quando raggiungi il limite per gli oggetti archiviati, non puoi più archiviarne altri.
Per ridurre il limite, sposta gli oggetti eliminati archiviati sullo stato deleted.

Lo stato sugli oggetti pubblicitari funziona in questo modo per la gerarchia degli oggetti pubblicitari:

Se lo stato di una campagna è impostato su with_issues, paused, archived o deleted per una campagna, tutti gli oggetti subordinati ereditano tale stato in modo automatico.
Se imposti una campagna pubblicitaria su deleted, non puoi recuperare i gruppi di inserzioni o le singole inserzioni subordinati a tale campagna senza specificare in modo esplicito gli ID.
Se lo stato di un'inserzione è impostato su with_issues, paused, archived o deleted, il gruppo di inserzioni o la campagna pubblicitaria contenente tale inserzione mantiene lo stato originale, restando recuperabile.

Per un dato account pubblicitario, valgono i seguenti limiti per gli oggetti ARCHIVED:

100 000 per le campagne pubblicitarie
100 000 per i gruppi di inserzioni
100 000 per le inserzioni

Se leggi segmenti archived, devi filtrare specificamente in base agli oggetti archiviati, poiché non vengono restituiti per impostazione predefinita. Se leggi le statistiche di un oggetto pubblicitario, vengono incluse le statistiche di tutti gli oggetti secondari, indipendentemente dal fatto che siano active, archived o deleted. Pertanto, non hai bisogno di alcun filtro per i dati di statistici sugli oggetti secondari.

Confronti tra stati diversi

Gli oggetti con stati come ACTIVE, PAUSED differiscono da quelli con stato ARCHIVED e DELETED. Ecco le differenze principali.

Query	Pubblicato	Archiviato	Eliminato
Esistente in database	Sì	Sì	Sì
Numero massimo per account pubblicitario	Con limiti	100 000	Nessun limite
Query come segmenti senza filtro	Sì	No	No
Query come segmenti con filtro di stato	Sì per oggetti con stato contenuto nel filtro	Sì, se il filtro di stato contiene `ARCHIVED`.	No, se il filtro di stato non contiene `DELETED` ed errore se lo contiene.
Query per il proprio ID	Sì	Sì	Sì
Statistiche aggregate in `/<PARENT_OBJECT_ID>/insights`	Sì	Sì	Sì
Statistiche incluse nella lista di risultati di `/<PARENT_OBJECT_ID>/insights?level=<OBJECT_LEVEL>`	Sì	No	No
Statistiche incluse nella lista di risultati di `/<PARENT_OBJECT_ID>/insights` con filtro di delivery_info	Sì per oggetti con stato contenuto nel filtro	Sì per oggetti con stato contenuto nel filtro	No
Dati statistici mostrati con `/<OBJECT_ID>/insights`	Sì	Sì	Sì
Lo stato è modificabile in	Qualsiasi stato valido	`DELETED`	Non è modificabile

Per impostare un'inserzione per l'archiviazione:

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>

Per eliminare un'inserzione:

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>/

Per recuperare gli oggetti secondari pubblicati di un oggetto pubblicato, ad esempio tutte le inserzioni pubblicate di una campagna pubblicitaria, a esclusione delle inserzioni ARCHIVED o DELETED:


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' },
})

Per recuperare gli oggetti secondari ARCHIVED di un oggetto pubblicato, ad esempio tutte le inserzioni ARCHIVED di un gruppo di inserzioni, è necessario il filtro di stato:


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'],
})