Chiama il metodo Conversion.update()
per apportare i seguenti tipi di modifiche a una o più conversioni esistenti:
- Modifica le entrate, il codice valuta o la quantità.
- Modifica l'ID ordine fornito dall'inserzionista e le eventuali variabili Floodlight personalizzate.
- Rimuovi la conversione modificando
conversion.state
daACTIVE
aREMOVED
.
Search Ads 360 non supporta la modifica dei seguenti elementi:
- La data di conversione.
- Il tipo di conversione.
- La parola chiave o la visita attribuita alla conversione.
- L'attività Floodlight o il nome dell'attività.
Tuttavia, puoi sempre contrassegnare una conversione esistente come RIMOSSA e caricarne una nuova con la data, il tipo, gli ID attribuzione o l'attività Floodlight aggiornati (assicurati di specificare anche un nuovo conversionId
).
Come per Conversion.insert()
, se la richiesta di aggiornamento specifica più conversioni, Search Ads 360 tenta di aggiornare ogni conversione secondo il criterio del massimo impegno anziché aggiornare l'intero batch come transazione tutto o niente. Se alcuni aggiornamenti in un
gruppo non vanno a buon fine, altri potrebbero riuscire. Ti consigliamo di leggere la risposta per ogni conversione aggiornata per assicurarti che l'aggiornamento sia andato a buon fine.
(Aggiornamento 2025) Ritiro di dsConversionId
Attualmente, puoi utilizzare dsConversionId
o conversionId
per identificare e modificare le conversioni. Il campo dsConversionId
verrà ritirato
nel terzo trimestre del 2025. In futuro, dovrai utilizzare conversionId
per modificare le conversioni nell'API Search Ads 360 Conversion.
Modifiche principali:
-
dsConversionId
Ritiro:dsConversionID
non sarà più supportato nell'API Search Ads 360 Reporting (indicata comeconversion.id
) o nell'interfaccia utente dei report (indicata come "ID conversione"). -
Requisito
conversionId
:conversionId
diventerà un campo obbligatorio per la modifica delle conversioni tramite l'API Search Ads 360 Conversion.
Come ottenere conversionId
:
-
API Search Ads 360 Reporting: puoi recuperare
advertiser_conversion_id
utilizzando l'API Search Ads 360 Reporting. Questo valore corrisponde alconversionId
necessario per la modifica. -
Interfaccia utente di Search Ads 360: puoi trovare "ID conversione inserzionista" nella pagina dei report sulle conversioni dell'interfaccia utente di Search Ads 360.
Inviare una richiesta di aggiornamento
La maggior parte dei campi specificati in un Conversion.update()
viene utilizzata per identificare le conversioni da aggiornare. Per identificare una conversione esistente, puoi utilizzare una delle seguenti tecniche:
- Specifica il valore
clickId
- della conversione
- Tutte le conversioni modificate devono risalire a un periodo di tempo compreso entro 60 giorni dal momento in cui viene generato l'ID clic.
- Specifica il valore
criterionId
(ID parola chiave) della conversione
Entrambe le tecniche richiedono di specificare conversionId
, conversionTimestamp
e type
della conversione.
Inoltre, se la conversione originale ha specificato revenueMicros
e currencyCode
o quantityMillis
, la richiesta di aggiornamento deve specificare questi dati anche se
non li stai modificando.
Identificare la conversione tramite l'ID clic
Se per una conversione è stato specificato inizialmente un ID clic, puoi inviare una richiesta Conversion.update()
che specifichi i seguenti campi:
clickId
conversionId
conversionTimestamp
type
state
(obbligatorio solo se vuoi impostare lo stato su RIMUOSSO o ATTIVO)quantityMillis
(solo se specificato nella conversione originale)revenueMicros
(solo se specificato nella conversione originale)currencyCode
(solo se specificato nella conversione originale)
Esempio
Ecco un esempio di due conversioni esistenti:
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId" : "test_20130906_10", "conversionTimestamp" : "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "TRANSACTION", "revenueMicros": "100000000", // 100 million revenueMicros is equivalent to $100 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "segmentationType" : "FLOODLIGHT", "segmentationName" : "Test", "type": "ACTION", "quantityMillis": "1000" }] }
La seguente richiesta aggiorna una delle conversioni dell'esempio precedente e rimuove l'altra:
JSON
Tieni presente che una richiesta Conversion.update()
utilizza il metodo HTTP PUT.
PUT https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion": [ { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site "conversionId": "test_20130906_10", "conversionTimestamp": "1378710000000", "type": "TRANSACTION", "revenueMicros": "90000000", // 90 million revenueMicros is equivalent to $90 of revenue "currencyCode": "USD" }, { "clickId": "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with data from your site "conversionId": "test_1383337059137", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "1000", "state": "REMOVED" } ] }
Java
/** * Instantiate the Doubleclicksearch service, create a conversion that updates an existing conversion, * and upload the conversions. */ public static void main(String[] args) throws Exception { Doubleclicksearch service = getService(); // See Set Up Your Application. // Set up a List to keep track of each conversion you create. List<Conversion> conversions = new Vector<Conversion>(); // Create a conversion and add it to the conversion list. // Just to get a little fancy, the updateConversionFromVisit() method can be used for all // visit conversions, including conversions that don't specify quantity, revenue, or currency. // If quantityMillis wasn't specified in the original conversion, specify -1L for the // quantityMillis parameter. Likewise, if revenueMicros wasn't specified originally, // specify -1L for the revenueMicros parameter and an empty string for currency. conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_20130906_10", // conversionId 1378710000000L, // timeStamp "TRANSACTION", // type "", // state -1L, // quantityMillis 90000000L, // revenueMicros. Equivalent to $90 of revenue "USD"); // currencyCode // Here's a conversion that needs to be removed. Just set the state parameter to "REMOVED". conversionList = updateConversionFromVisit( conversionList, "COiYmPDTv7kCFcP0KgodOzQAAA", // clickId. Replace with data from your site "test_1383337059137", // conversionId 1378710000000L, // timeStamp "ACTION", // type "REMOVED", // state 1000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode // Upload the List and handle the response. uploadConversions(conversions, service); // See an example in Add New Conversions. } /** * Create a conversion and add it to a List<Conversion>. */ private static List<Conversion> updateConversionFromVisit(List<Conversion> conversions, String clickId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency) { // Identifies the existing conversion. Conversion conversion = new Conversion() .setClickId(clickId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the revenue for one existing conversion and remove another. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion' : [{ 'clickId' : 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId' : 'test_20130906_13', 'conversionTimestamp' : '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'TRANSACTION', 'revenueMicros': '90000000', // 90 million revenueMicros is equivalent to $90 of revenue 'currencyCode': 'USD' }, { 'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with data from your site 'conversionId': 'test_1383337059137_01', 'conversionTimestamp': '1378710000000', 'segmentationType' : 'FLOODLIGHT', 'segmentationName' : 'Test', 'type': 'ACTION', 'quantityMillis': '1000', 'state': 'REMOVED' }] } ) pprint.pprint(request.execute())
Identificare la conversione in base all'ID parola chiave
Se non hai accesso a un ID clic o se una conversione è stata originariamente attribuita a una
parola chiave o a una parola chiave/un annuncio, puoi inviare una richiesta Conversion.update()
che
specifichi i seguenti campi:
criterionId
(ID parola chiave)conversionId
conversionTimestamp
type
state
(obbligatorio solo se vuoi impostare lo stato su RIMUOSSO o ATTIVO)quantityMillis
(solo se specificato nella conversione originale)revenueMicros
(solo se specificato nella conversione originale)currencyCode
(solo se specificato nella conversione originale)
Se vuoi, puoi specificare altri ID, ad esempio l'ID annuncio, l'ID campagna e così via, ma non è obbligatorio. Search Ads 360 ha bisogno solo degli ID nell'elenco riportato sopra per identificare una conversione esistente.
Esempio
Ecco un esempio di conversione esistente:
{ "kind": "doubleclicksearch#conversionList", "conversion" : [{ "agencyId": "12300000000000456", "advertiserId": "45600000000010291", "engineAccountId": "700000000042441", "campaignId": "71700000002044839", "adGroupId": "58700000032026064", "criterionId": "43700004289911004", "adId": "44700000155906860", "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "1000", "segmentationType": "FLOODLIGHT", "segmentationName": "Test" }] }
La seguente richiesta aggiorna il timestamp della conversione:
JSON
Tieni presente che una richiesta Conversion.update()
utilizza il metodo HTTP PUT.
PUT https://www.googleapis.com/doubleclicksearch/v2/conversion Authorization: Bearer your OAuth 2.0 access token Content-type: application/json { "kind": "doubleclicksearch#conversionList", "conversion": [ { "criterionId": "43700004289911004", // Replace with your ID "conversionId": "test_1383157519886", "conversionTimestamp": "1378710000000", "type": "ACTION", "quantityMillis": "3000" } ] }
Java
// Send conversion data to updateConversion, which creates a conversion and adds it // to the conversion list. conversionList = updateConversionFromKeyword(conversionList, 43700004289911004L, // criterionId. Replace with your ID "test_1383157519886", // conversionId 1378710000000L, // timeStamp "ACTION", // type "", // state 3000L, // quantityMillis -1L, // revenueMicros ""); // currencyCode private static List<Conversion> updateConversionFromKeyword(List<Conversion> conversions, Long criterionId, String conversionId, Long timeStamp, String type, String state, Long quantity, Long revenue, String currency ) { Conversion conversion = new Conversion() .setCriterionId(criterionId) .setConversionId(conversionId) .setConversionTimestamp(BigInteger.valueOf(timeStamp)) .setType(type); // Only add these fields if the value is not empty greater than -1. if(!state.isEmpty()) conversion.setState(state); if (quantity > -1L) { conversion.setQuantityMillis(quantity); } if (revenue > -1L) { conversion.setRevenueMicros(revenue); if (!currency.isEmpty()) { conversion.setCurrencyCode(currency); } else { System.err.println(String.format( "Can't add conversion %s. It specifies revenue but no currency.", conversion.getConversionId())); return conversions; } } conversions.add(conversion); return conversions; }
Python
def update_conversion(service): """Change the timestamp of a conversion. Use only the keyword id (criterionId) to identify the conversion. Args: service: An authorized Doubleclicksearch service. See Set Up Your Application. """ request = service.conversion().update( body= { 'conversion': [{ 'criterionId': '43700004289911004', // Replace with your ID 'conversionId': 'test_1383157519886', 'conversionTimestamp': '1378760000000', 'type': 'ACTION', 'quantityMillis': '1000' }] } ) pprint.pprint(request.execute())
Gestire le risposte di Search Ads 360
La risposta per una richiesta di aggiornamento è la stessa della risposta per una richiesta di inserimento: Search Ads 360 indica il successo solo se tutte le conversioni nella richiesta sono state aggiornate correttamente.
Se la richiesta va a buon fine, la risposta include la rappresentazione interna completa di Search Ads 360 per ogni conversione aggiornata, ad esempio l'ID campagna, l'ID gruppo di annunci e l'ID parola chiave (criterio).
Se la convalida o il caricamento di uno o più aggiornamenti non va a buon fine, la risposta include i messaggi di errore per ogni aggiornamento non riuscito. La risposta non contiene messaggi sulle conversioni aggiornate correttamente. Per ulteriori informazioni su questi messaggi di errore, consulta la sezione Gestire le risposte di Search Ads 360 per le richieste di inserimento.