Utilizza le mappature nelle tabelle per mappare i metodi e i campi dell'API Google Ads ai loro equivalenti IngestEventsRequest nell'API Data Manager.
Autenticazione
L'API Data Manager richiede credenziali con un ambito diverso rispetto all'API Google Ads. Segui i passaggi descritti in Configura l'accesso API per generare nuove credenziali che includono l'ambito dell'API Data Manager.
Metodi dell'API
L'API Data Manager ti consente di caricare ogni gruppo di eventi di vendita in negozio in un unico
IngestEventsRequest.
Al contrario, l'API Google Ads richiedeva una procedura in tre passaggi utilizzando
OfflineUserDataJobService:
- Crea un job utilizzando
CreateOfflineUserDataJob - Aggiungi operazioni al job utilizzando
AddOfflineUserDataJobOperations - Esegui il job utilizzando
RunOfflineUserDataJob
Campi di richiesta
Ogni IngestEventsRequest è soggetto a
limiti di richieste. Se il numero di operazioni nella richiesta AddOfflineUserDataJobOperations supera questi limiti, devi suddividerla in più richieste di importazione dell'API Data Manager.
Ecco come i campi delle richieste API Google Ads vengono mappati all'API Data Manager.
CreateOfflineUserDataJobRequest
La tabella seguente mostra come i campi di un CreateOfflineUserDataJobRequest
vengono mappati a un IngestEventsRequest.
CreateOfflineUserDataJobRequest (API Google Ads) |
IngestEventsRequest (API Data Manager) |
Note |
|---|---|---|
customer_id |
destinations.operating_account |
Consulta i campi relativi ai clienti e alle azioni di conversione. |
|
destinations |
Consulta i campi relativi ai clienti e alle azioni di conversione. |
|
Diagnostica | Utilizza l'elemento request_id restituito in IngestEventsResponse per recuperare la diagnostica relativa al caricamento delle conversioni. |
job.id |
request_id |
Utilizza l'elemento request_id restituito in IngestEventsResponse per recuperare la diagnostica relativa al caricamento delle conversioni. |
job.external_id |
Nessun equivalente | |
job.type |
Nessun equivalente | |
job.store_sales_metadata.third_party_metadata.partner_id |
destinations.login_account |
Un partner di dati che carica le conversioni per le vendite in negozio verrà identificato dal login_account di una destinazione. Per maggiori dettagli, consulta Configura le destinazioni. |
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time |
Nessun equivalente | |
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction |
Nessun equivalente | |
job.store_sales_metadata.third_party_metadata.partner_match_fraction |
Nessun equivalente | |
job.store_sales_metadata.third_party_metadata.partner_upload_fraction |
Nessun equivalente | |
job.store_sales_metadata.third_party_metadata.bridge_map_version_id |
Nessun equivalente | |
job.store_sales_metadata.loyalty_fraction |
Nessun equivalente | |
job.store_sales_metadata.transaction_upload_fraction |
Nessun equivalente | |
job.store_sales_metadata.custom_key |
|
Esegui la mappatura al campo variable di un CustomVariable a livello di evento o di un ItemCustomVariable a livello di articolo. |
enable_match_rate_range_preview |
Nessun equivalente | |
validate_only |
validate_only |
|
| Nessun equivalente | consent |
L'API Google Ads supporta solo la specifica di consent a livello di evento in UserData. Per l'API Data Manager, puoi specificare il consenso per tutti gli eventi di una richiesta impostando il campo consent su IngestEventsRequest. Puoi eseguire l'override di questo valore per un singolo evento impostando il campo consent di Event. |
| Nessun equivalente | encoding |
Obbligatorio per i caricamenti di UserData. Impostato sul valore Encoding utilizzato per i valori UserIdentifier. |
| Nessun equivalente | encryption_info |
Impostato se la richiesta contiene identificatori dell'utente UserData criptati. Per maggiori dettagli, consulta Crittografia. |
AddOfflineUserDataJobOperationsRequest
La tabella seguente mostra come i campi di un AddOfflineUserDataJobOperationsRequest
vengono mappati a un IngestEventsRequest.
AddOfflineUserDataJobOperationsRequest (API Google Ads) |
IngestEventsRequest (API Data Manager) |
Note |
|---|---|---|
|
destinations |
Consulta i campi relativi ai clienti e alle azioni di conversione. |
resource_name |
Nessun equivalente | L'API Data Manager non richiede l'aggiornamento di una risorsa job. |
enable_partial_failure |
Nessun equivalente | Se l'operazione IngestEventsRequest va a buon fine, eventuali errori che si verificano durante l'elaborazione downstream vengono gestiti a livello di evento, il che può comportare un esito positivo parziale. Utilizza Diagnostica per recuperare lo stato del caricamento, nonché gli errori e gli avvisi relativi ai singoli eventi. Se l'operazione IngestEventsRequest non va a buon fine (ad esempio a causa di un errore BadRequest), non viene elaborato alcun evento e dovrai risolvere l'errore e riprovare a inviare la richiesta. Per saperne di più, consulta Informazioni sugli errori relativi alle API. |
enable_warnings |
Nessun equivalente | Utilizza Diagnostica per recuperare gli avvisi relativi alla richiesta API Data Manager. Non è necessario attivarlo. |
operations |
events |
L'operazione OfflineUserDataJobOperation.create equivale all'invio di un IngestEventsRequest. L'API Data Manager non supporta la rimozione degli eventi. |
validate_only |
validate_only |
|
| Nessun equivalente | consent |
L'API Google Ads supporta solo la specifica di consent a livello di evento in UserData. Per l'API Data Manager, puoi specificare il consenso per tutti gli eventi di una richiesta impostando il campo consent su IngestEventsRequest. Puoi eseguire l'override di questo valore per un singolo evento impostando il campo consent di Event. |
| Nessun equivalente | encoding |
Obbligatorio per i caricamenti di UserData. Impostato sul valore Encoding utilizzato per i valori UserIdentifier. |
| Nessun equivalente | encryption_info |
Impostato se la richiesta contiene identificatori dell'utente UserData criptati. Per maggiori dettagli, consulta Crittografia. |
Campi delle azioni di conversione e dei clienti
L'API Google Ads richiede l'intestazione della richiesta developer-token e devi impostare le intestazioni della richiesta login-customer-id e linked-customer-id per i diversi scenari di autenticazione.
L'API Data Manager non richiede un token sviluppatore e i dati del cliente collegato e di accesso vengono specificati utilizzando i campi di un Destination anziché le intestazioni della richiesta. Per saperne di più sulle destinazioni, consulta Configura le destinazioni.
| API Google Ads | Destination (API Data Manager) |
Note |
|---|---|---|
customer_id della richiesta |
operating_account |
Imposta account_id sull'ID cliente dell'account di conversione Google Ads. Imposta account_type di operating_account su GOOGLE_ADS. |
Intestazione della richiesta developer-token |
Nessun equivalente | Per l'API Data Manager non è richiesto un token sviluppatore. |
Intestazione della richiesta login-customer-id |
login_account |
Imposta account_id sull'ID cliente dell'account di accesso. Imposta account_type su GOOGLE_ADS se l'account di accesso è un account Google Ads o su DATA_PARTNER se l'account di accesso è un account partner di dati. |
Intestazione della richiesta linked-customer-id |
linked_account |
Se accedi alla operating_account utilizzando un link partner, imposta account_id sull'ID cliente dell'account collegato e imposta account_type su DATA_PARTNER. In caso contrario, non impostare il campo linked_account. |
conversion_action |
product_destination_id |
Imposta l'ID numerico dell'azione di conversione. Non utilizzare il nome della risorsa. |
Campi evento
La tabella seguente mostra come i campi di una conversione per le vendite in negozio vengono mappati tra le due API.
A differenza dell'API Google Ads, che supporta l'inclusione di un solo articolo per transazione utilizzando ItemAttribute, l'API Data Manager supporta l'inclusione di più articoli per evento in CartData.
OfflineUserDataJobOperation.create (API Google Ads) |
Event (API Data Manager) |
Note |
|---|---|---|
| Nessun equivalente | event_source |
Obbligatorio Imposta su IN_STORE per le conversioni per le vendite in negozio. |
transaction_attribute.conversion_action |
destinations.product_destination_id |
Consulta i campi relativi ai clienti e alle azioni di conversione. Utilizza l'ID numerico dell'azione di conversione anziché il nome della risorsa. |
transaction_attribute.transaction_date_time |
event_timestamp |
Per maggiori dettagli, consulta Formato del timestamp. |
transaction_attribute.transaction_amount_micros |
|
Impostato sul valore della valuta, non sul valore in micro. Ad esempio, per un valore di conversione di 5,23 $, utilizza il valore 5.23. |
transaction_attribute.currency_code |
currency |
Obbligatorio. |
transaction_attribute.order_id |
transaction_id |
Obbligatorio. |
transaction_attribute.store_attribute.store_code |
event_location.store_id |
Obbligatorio Imposta il codice negozio nel campo store_id nell'oggetto EventLocation. |
transaction_attribute.custom_value |
|
Esegui la mappatura al campo value di un CustomVariable a livello di evento o di un ItemCustomVariable a livello di articolo. |
transaction_attribute.item_attribute.item_id |
cart_data.items[].merchant_product_id |
|
transaction_attribute.item_attribute.merchant_id |
|
Se imposti cart_data.merchant_id, questo valore viene utilizzato come predefinito per tutti gli articoli, ma puoi eseguirne l'override per singoli articoli. |
transaction_attribute.item_attribute.country_code |
|
Se imposti cart_data.merchant_feed_label, questo valore viene utilizzato come predefinito per tutti gli articoli, ma puoi eseguirne l'override per i singoli articoli. |
transaction_attribute.item_attribute.language_code |
|
Se imposti cart_data.merchant_feed_language_code, questo valore viene utilizzato come predefinito per tutti gli articoli, ma puoi eseguirne l'override per i singoli articoli. |
transaction_attribute.item_attribute.quantity |
cart_data.items[].quantity |
|
| Nessun equivalente | cart_data.items[].unit_price |
Imposta il prezzo unitario al netto di tasse, spese di spedizione e sconti basati sugli eventi (a livello di transazione) per questo articolo. |
user_identifiers |
|
Required.
|
consent |
consent |
Entrambe le API utilizzano un oggetto Consent simile (ad_user_data, ad_personalization). Per l'API Data Manager, puoi anche impostare il consenso per tutti gli eventi in una richiesta impostando il campo consent su IngestEventsRequest. |
Campi identificatore dell'utente
UserIdentifier (API Google Ads) |
UserIdentifier (API Data Manager) |
Note |
|---|---|---|
user_identifier_source |
L'origine determina quale campo compilare nell'API Data Manager
|
|
hashed_email |
email_address |
Imposta l'indirizzo email formattato e sottoposto ad hashing. Puoi anche criptare l'indirizzo email sottoposto ad hashing. |
hashed_phone_number |
phone_number |
Imposta il numero di telefono formattato e sottoposto ad hashing. Puoi anche criptare il numero di telefono sottoposto ad hashing. |
address_info |
address |
Impostato su un oggetto AddressInfo. Segui le linee guida sulla formattazione e sull'hashing. Puoi anche criptare gli attributi con hash di un indirizzo. |
address_info.hashed_first_name |
address.given_name |
|
address_info.hashed_last_name |
address.family_name |
|
address_info.country_code |
address.region_code |
|
address_info.postal_code |
address.postal_code |
|
address_info.city |
Nessun equivalente | Non supportato per le destinazioni Google Ads. |
address_info.state |
Nessun equivalente | Non supportato per le destinazioni Google Ads. |
address_info.hashed_street_address |
Nessun equivalente | Non supportato per le destinazioni Google Ads. |