API Offline Conversions

Usa l'API Offline Conversions per inviare eventi di conversione offline e scoprire quanti clienti hanno visualizzato le tue inserzioni di Meta o cliccato su di esse prima di una conversione.

Prima di iniziare

Per usare questa API, hai bisogno di:

1. Business Manager di Meta

Se non hai ancora un account, creane uno.

2. ID dell'app di Meta

Per l'accesso all'API Marketing. Per creare un'app di Meta:

• Accedi a Business Manager > Impostazioni business.
• Seleziona App.
• Clicca su Aggiungi nuova app e segui le istruzioni.

3. Analisi dell'app e autorizzazioni

Le regole relative all'analisi dell'app e alle autorizzazioni dipendono da come implementi l'API:

4. Utente di sistema di Business Manager e token

Con l'accesso come utente di sistema, la tua app può inviare dati a Meta usando l'API. Per crearlo:

• Accedi a Business Manager > Impostazioni business.
• Seleziona Utenti di sistema.
• Clicca su Aggiungi nuovo utente di sistema.
• Seleziona Utente di sistema amministratore come ruolo per l'utente di sistema.

Un token d'accesso consente di accedere ai dati di Meta. Per creare token d'accesso dell'utente di sistema:

• Accedi a Business Manager > Impostazioni business.
• Seleziona Utenti di sistema.
• Seleziona l'utente di sistema e clicca su Genera nuovo token.
• Seleziona l'app > per scope, seleziona ads_management.

5. Account pubblicitario

Per pubblicare campagne pubblicitarie su Meta, hai bisogno di un account pubblicitario. Per crearne uno, consulta la documentazione sull'API Marketing o l'articolo del Centro assistenza per le aziende "Informazioni sulle impostazioni business di Business Manager di Meta".

6. Accesso all'account pubblicitario per l'utente di sistema

Concedi all'utente di sistema l'accesso al tuo account pubblicitario.

• Accedi a Business Manager > Impostazioni business.
• Seleziona Utenti di sistema.
• Seleziona l'utente di sistema e clicca su Assegna risorse.
• Seleziona il tuo account pubblicitario.

7. Insieme di eventi offline

Si tratta di file caricati con i dati delle conversioni offline. Quando crei un'inserzione, imposta tracking_spec sull'ID dell'insieme di eventi offline per un'attribuzione corretta degli eventi. Puoi quindi creare insiemi di eventi, visualizzare le statistiche per le tue importazioni ed eliminare e modificare questi dati in Business Manager.

Con le implementazioni precedenti, potevi eseguire operazioni CRUD sugli insiemi di eventi offline al livello di Business Manager per condividere insiemi di eventi con altri oggetti ed entità.

Caricamento dei dati degli eventi

Devi specificare l'accesso per creare insiemi di eventi offline e caricare o visualizzare i dati per un insieme di eventi. Devi disporre dell'accesso anche per assegnare queste autorizzazioni a un account pubblicitario. Devi avere uno dei seguenti ruoli:

• Amministratore di Business Manager
• Utente di sistema amministratore che ha creato l'insieme di eventi offline
• Amministratore sull'ad_account associato all'insieme di eventi offline

Consulta il riferimento per l'insieme di eventi di conversione offline.

1. Creazione di un insieme di eventi offline

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Effettua una chiamata HTTP POST:

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

La risposta include un id dell'insieme di eventi:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parametri

2. Assegnazione delle autorizzazioni a un account pubblicitario

Per assegnare autorizzazioni di monitoraggio e lettura a un account pubblicitario:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parametri

3. Impostazione del monitoraggio delle inserzioni

Quando aggiorni l'elemento tracking_spec, noi lo sovrascriviamo. Assicurati innanzitutto di inviare una richiesta GET, quindi allega l'elemento String associato per l'insieme di eventi offline alla tracking_spec esistente. Consulta Gestione delle inserzioni o usa Gestione inserzioni. Ad esempio, fornisci una specifica di monitoraggio appropriata:

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

Per aggiornare la specifica di monitoraggio dell'inserzione:

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parametri

4. Caricamento di eventi offline

Devi caricare la transazione entro 62 giorni dalla conversione. Carica i dati di conversione:

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

Per inviare conversioni, effettua una chiamata HTTP POST:

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

Parametri

Usa lo stesso upload_tag per tutte le chiamate API con caricamento degli eventi nello stesso batch per raggrupparle. In questo modo, puoi eseguire il debug dei caricamenti; devi usarlo per tutti i caricamenti degli eventi effettuati in più di una chiamata API.

I parametri contenuti in data includono:

Ad esempio, puoi caricare informazioni con il campo data:

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

Usa lo stesso upload_tag per tutte le chiamate all'API di caricamento degli eventi nello stesso batch per raggrupparle. In questo modo, puoi eseguire il debug dei caricamenti degli eventi; deve essere usato per tutti i caricamenti degli eventi in più di una chiamata API.

Chiavi di corrispondenza

L'elemento match_keys è un insieme di identificativi che permette di trovare le corrispondenze tra le persone per l'attribuzione. Consulta Pubblico personalizzato dai dati CRM per normalizzare e sottoporre a procedura di hashing i tuoi dati. Solo l'algoritmo SHA256 è supportato e non vengono accettati dati non sottoposti alla procedura di hashing.

Risposta:

Negli errori, vedrai un'eccezione che include le voci non valide e il relativo motivo. Correggi gli errori o ignora le righe di dati con errori e riprova a eseguire la chiamata API.

Visualizzazione delle statistiche dei caricamenti

L'amministratore di Business Manager o l'utente di sistema che ha creato l'insieme di eventi offline può recuperare le statistiche dei caricamenti. Anche gli amministratori dell'ad_account collegato all'insieme di eventi offline possono leggere questi dati.

Per visualizzare le statistiche sugli insiemi di eventi offline come le voci valide e quelle per cui sono state trovate corrispondenze:

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

Visualizza i dettagli giornalieri degli eventi offline su Offline Events Manager in Business Manager. Per dettagli più precisi, effettua questa chiamata:

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

Parametri

Creare conversioni personalizzate offline

Per le conversioni personalizzate offline al momento non viene eseguito il backfill. Non attribuiamo i dati da caricamenti degli eventi effettuati prima che tu abbia creato la conversione personalizzata. Non puoi usare i dati delle conversioni offline personalizzate per l'ottimizzazione della pubblicazione delle inserzioni. Consulta il riferimento per le conversioni personalizzate.

Per creare una conversione personalizzata usando i tuoi eventi offline, esegui una richiesta POST:

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

Parametri:

La risposta in caso di azione eseguita correttamente:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Misurazione con i dati personalizzati

Puoi usare il campo custom_data per creare regole che in seguito determineranno se una conversione viene o meno conteggiata. È simile al pubblico personalizzato offline. Il numero massimo di conversioni personalizzate che puoi usare per ogni account pubblicitario è pari a 40.

Ad esempio, includi la categoria dei prodotti nei caricamenti con custom_data:

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

Usa quindi custom_data.{YOUR_CUSTOM_PARAM} per creare una regola per la conversione personalizzata:

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

Conversioni offline per i partner

Per attribuire gli eventi di conversione offline all'inserzione del tuo cliente, segui questi passaggi. Le chiamate API per la maggior parte di questi passaggi sono le stesse di quando qualcuno gestisce il suo insieme di eventi offline e la sua campagna.

1. Partner: creazione di un insieme di eventi offline
2. Partner: condivisione dell'insieme di eventi con il Business Manager del cliente
3. Cliente: assegnazione dell'autorizzazione per il monitoraggio offline dell'account pubblicitario
4. Cliente: impostazione del monitoraggio offline per le inserzioni
5. Partner: caricamento degli eventi offline e visualizzazione delle statistiche
6. Partner: presentazione degli insight sulle inserzioni al cliente

Questi passaggi variano in base a come vengono impostate le autorizzazioni per il tuo partner o la tua agenzia negli account pubblicitari del cliente:

• Potresti controllare tutti gli account pubblicitari, gli insiemi di eventi o altre risorse del tuo cliente.
• Potresti avere l'autorizzazione per eseguire determinate azioni sulle risorse del tuo cliente.

Per configurare queste autorizzazioni, consulta Gestione delle risorse di Business Manager.

Partner: condivisione dell'insieme di eventi

Condividi l'insieme di eventi con il Business Manager del tuo cliente, il quale può usarlo per il monitoraggio delle inserzioni.

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

Parametri

Cliente: assegnazione dell'autorizzazione per il monitoraggio offline dell'account pubblicitario

Condivi gli insiemi di eventi offline creati da un partner con il cliente. Devi essere l'amministratore di Business Manager o l'utente di sistema amministratore che ha creato l'insieme di eventi offline per abilitare il monitoraggio delle inserzioni in un account pubblicitario. Puoi farlo anche se sei amministratore dell'account pubblicitario connesso all'insieme di eventi offline. Per effettuare questa chiamata API, il Business Manager nella chiamata deve avere accesso all'insieme di eventi offline.

Con questa chiamata, puoi assegnare il monitoraggio degli eventi offline e la visualizzazione delle autorizzazioni a un account pubblicitario:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parametri

Fornitura di ID esterni

In alcuni casi, potresti dover usare il tuo ID esterno per rappresentare un cliente e trovare una corrispondenza con qualcuno. Per farlo, usa l'elemento extern_id seguendo queste linee guida.

I partner dati sottoposti alla procedura di ricerca delle corrispondenze possono usare l'ID partner come ID spazio dei nomi e extern_id come il tuo tpid.

Fornire solo match_keys

Usiamo match_keys per provare a determinare se i dati di conversione che hai condiviso possono essere abbinati a un utente di Meta. Se fornisci match_keys, non puoi fornire anche un parametro namespace_id.

Fornire match_keys ed extern_id

Usiamo il parametro match_keys per provare a trovare persone su Meta e trasmettere le mappature da {dataset_id, extern_id} a {facebook_user_id}. Se fornisci match_keys e extern_id, non puoi fornire anche namespace_id.

Fornire solo extern_id

Se hai già inviato i dati con i parametri match_keys e extern_id, Meta usa {dataset_id, extern_id} per recuperare un {facebook_user_id}.

Fornire namespace_id

Il parametro namespace_id si applica all'intera chiamata API. Puoi usarlo per fare riferimento a un altro insieme di eventi offline accessibile o controllato da un ID Business Manager o un ID del profilo partner. Se hai già inviato i dati con i parametri match_keys e extern_id, Meta usa {namespace_id, extern_id} per recuperare un {facebook_user_id}. Devi fornire solo un parametro extern_id per ogni riga di dati.

Insight e attribuzione

Vedi gli eventi offline attribuiti a un'inserzione che qualcuno ha visualizzato o su cui ha cliccato. Attribuiamo le conversioni offline dopo più di un giorno. Ciò significa che devi impostare la tua finestra di attribuzione su 28d_view o action_attribution_windows=['28d_view']', altrimenti non vedrai conversioni nei report. Consulta API Insights e la guida agli insight.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

Parametri

I risultati si presentano così:

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

Ad esempio, per visualizzare l'attribuzione:

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

Il risultato si presenta così:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Opzioni di elaborazione dei dati per gli utenti negli Stati Uniti

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

Scopri di più sulle opzioni per il trattamento dei dati.