API Insights

Offre un'interfaccia unica e coerente per il recupero delle statistiche delle inserzioni.

• Dettagli: raggruppamento dei risultati.
• Dettagli delle azioni: informazioni sulle risposte dai dettagli delle azioni.
• Processi asincroni: usali per le richieste che restituiscono un grande volume di risultati.
• Limiti e best practice: limiti delle chiamate, filtri e best practice.

Prima di poter acquisire i dati sulle prestazioni delle tue inserzioni, devi configurarle per il monitoraggio delle metriche che ti interessano. Per tale scopo, puoi usare tag URL, il pixel di Meta e l'API Conversions.

Prima di iniziare

Ecco cosa ti servirà:

• Autorizzazione ads_read.
• Un'app. Per maggiori informazioni, consulta Sviluppo di app di Meta.

Statistiche della campagna

Per ottenere le statistiche delle prestazioni della campagna negli ultimi 7 giorni:

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

Per scoprire di più, consulta il riferimento agli insight sulle inserzioni.

Effettuare chiamate

L'API Insights è disponibile come segmento in qualsiasi oggetto pubblicitario.

Richiesta

Puoi richiedere campi specifici con una lista separata da virgole nei parametri fields. Ad esempio:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"
    

Risposta

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Livelli

Aggrega i risultati a un determinato livello dell'oggetto. In questo modo, i dati vengono deduplicati automaticamente.

Richiesta

Ad esempio, puoi ottenere gli insight di una campagna a livello dell'inserzione.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/CAMPAIGN_ID/insights"

Risposta

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Se non hai accesso a tutti gli oggetti pubblicitari al livello richiesto, la chiamata per gli insight non restituisce alcun dato. Ad esempio, in caso di richiesta di insight con level impostato su ad, se non hai accesso a uno o più oggetti nell'ambito dell'account pubblicitario, questa chiamata all'API restituirà un errore di autorizzazione.

Finestre di attribuzione

La finestra di attribuzione delle conversioni offre intervalli di tempo che definiscono il momento in cui un evento viene attribuito a un'inserzione su un'app Meta. Per maggiori informazioni, consulta il Centro assistenza per le aziende di Meta per informazioni sulle finestre di attribuzione. Vengono misurate le azioni che si verificano in caso di un evento di conversione e vengono recuperati i dati passati di 1 e 7 giorni. Per visualizzare le azioni attribuite a diverse finestre di attribuzione, effettua una richiesta a /{ad-account-id}/insights. Se non fornisci l'elemento action_attribution_windows, viene utilizzato 7d_click, quindi viene fornito in value.

Ad esempio, specifica action_attribution_windows e "value" è fisso sulla finestra di attribuzione di 7d_click. Effettua una richiesta a act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] e ottieni questo risultato:

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Espansione dei campi

Richiedi i campi a livello del nodo e per i campi specificati nell'espansione dei campi.

Richiesta

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_ID"

Risposta

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Ordinamento

Ordina i risultati fornendo il parametro sort con {fieldname}_descending o {fieldname}_ascending:

Richiesta

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID/insights"

Risposta

{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Etichette delle inserzioni

Statistiche di tutte le etichette i cui nomi risultano identici. Vengono aggregate in un unico valore a livello di un oggetto pubblicitario. Consulta il riferimento alle etichette delle inserzioni per maggiori informazioni.

Richiesta

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

Risposta

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

Definizione dei clic

Per capire meglio le metriche sui clic offerte oggi da Meta, leggi le definizioni e l'uso di ognuna di esse qui sotto:

• Clic sui link, actions:link_click: il numero di clic sui link dell'inserzione che rimandano a determinate destinazioni o esperienze, all'interno o all'esterno delle proprietà di Meta. Consulta il Centro assistenza per le inserzioni, Clic sul link.

• Clic (tutti), clicks: la metrica calcola diversi tipi di clic sulla tua inserzione, compresi alcuni tipi di interazioni con il contenitore inserzione, link che rimandano ad altre destinazioni e link che rimandano a esperienze pubblicitarie più estese. Consulta il Centro assistenza per le inserzioni, Clic (tutti).

Oggetti eliminati e archiviati

Le unità pubblicitarie possono essere DELETED o ARCHIVED. Le statistiche degli oggetti eliminati o archiviati vengono visualizzate quando esegui query sui relativi elementi principali. Ciò significa che se esegui query su impressions al livello del gruppo di inserzioni, i risultati includono le impressions di tutte le inserzioni del gruppo, indipendentemente che le inserzioni siano state eliminate o archiviate. Consulta anche le best practice per la memorizzazione e il recupero degli oggetti pubblicitari.

Tuttavia, se esegui una query usando l'applicazione di filtri, il filtro per lo stato sarà applicato per impostazione predefinita in modo che vengano restituiti solo gli oggetti con stato Attivo. Di conseguenza, le statistiche totali del nodo principale potrebbero essere maggiori di quelle dei nodi secondari.

Puoi comunque ottenere le statistiche degli oggetti ARCHIVED dai nodi principali fornendo un parametro filtering aggiuntivo.

Richiesta

Per ottenere tutte le statistiche di tutte le inserzioni ARCHIVED in un account pubblicitario, elencate una per una:

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/insights/"

Risposta

Tieni presente che nella risposta vengono restituiti solo gli oggetti archiviati.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Insight degli oggetti eliminati

Puoi eseguire query sugli insight per gli oggetti eliminati se disponi dei relativi ID o usando il filtro ad.effective_status.

Richiesta

Ad esempio, se disponi dell'ID del gruppo di inserzioni:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID"
    

In questo esempio, eseguiamo una query con ad.effective_status:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Risposta

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Risoluzione dei problemi

Timeout

I problemi più comuni che determinano errori nell'endpoint riguardano il numero eccessivo di risposte e timeout:

• Nelle richieste /GET o sincrone, puoi ricevere errori di memoria esaurita o timeout.
• Nelle richieste /POST o asincrone, puoi ricevere errori di timeout. Per le richieste asincrone, il completamento delle richieste con tentativi ripetuti può richiedere fino a un'ora. Ad esempio, nel caso di una query che prova a recuperare un grande volume di dati per molti oggetti a livello dell'inserzione.

Consigli

• Non esiste un limite che definisce il momento in cui le query generano un errore. Al timeout, prova a filtrare la query suddividendola in query più piccole, ad esempio per intervalli di date.
• L'elaborazione delle metriche uniche richiede molto tempo. Prova a effettuare query sulle metriche uniche in una chiamata separata per migliorare le prestazioni relative alle metriche non uniche.

Rate limiting

L'API Insights di Meta usa il rate limiting per garantire report ottimali per tutti i nostri partner. Per maggiori informazioni e suggerimenti, consulta Limiti e best practice per l'API Insights.

Discrepanza con Gestione inserzioni

Il comportamento predefinito dell'API è diverso da quello predefinito in Gestione inserzioni. Se desideri osservare lo stesso comportamento di Gestione inserzioni, imposta il campo use_account_attribution_setting su true.

Per saperne di più

• Insight dell'account pubblicitario
• Insight della campagna pubblicitaria
• Insight del gruppo di inserzioni
• Insight delle inserzioni

L'API non copre gli endpoint che non sono inclusi nella lista sopra riportata. Se prevedi di includere report da Meta nella tua soluzione, consulta Condizioni della Piattaforma Facebook e Normative per gli sviluppatori per l'API Marketing.