Modifica conversioni esistenti

Chiama il metodo Conversion.update() per apportare i seguenti tipi di modifiche a una o più conversioni esistenti:

In Search Ads 360, non è possibile modificare quanto segue:

  • La data della 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 REMOVED e caricare una nuova conversione con la data, il tipo, gli ID attribuzione o l'attività Floodlight aggiornati (assicurati di specificare anche un nuovo conversionId).

Puoi modificare sia le conversioni caricate tramite l'API Search Ads 360 (conversioni offline) sia quelle registrate da Search Ads 360 tramite i tag Floodlight (conversioni online), nel rispetto dei seguenti limiti di tempo:

  • Se identifichi la conversione tramite clickId, l'ID clic deve essere stato generato negli ultimi 60 giorni (altrimenti viene visualizzato il codice di errore 0x0000012F).
  • Le conversioni registrate tramite i tag Floodlight possono essere modificate solo entro 28 giorni dalla data della conversionTimestamp (altrimenti viene visualizzato il codice di errore 0x00000125).

Come per Conversion.insert(), se la richiesta di aggiornamento specifica più conversioni, Search Ads 360 tenta di aggiornare ogni conversione nel miglior modo possibile, anziché aggiornare l'intero batch come transazione "tutto o niente". Se alcuni aggiornamenti di un batch non vanno a buon fine, altri potrebbero comunque riuscire. Ti consigliamo di leggere la risposta per ogni conversione aggiornata per assicurarti che l'aggiornamento sia andato a buon fine.

Ritiro di dsConversionId

Il campo dsConversionId è stato ritirato e non può più essere utilizzato per identificare le conversioni. Per modificare le conversioni nell'API Search Ads 360 Conversion, devi utilizzare conversionId (l'ID conversione inserzionista). Conversion.update() rifiuta una conversione con il codice di errore 0x0000013C (Conversion editing using integer DS conversion ID is deprecated) se la conversione:

  • specifica il campo dsConversionId oppure
  • Passa un ID conversione di Search Ads 360 (l'ID numerico di 17 cifre che Search Ads 360 genera per ogni conversione) nel campo conversionId.

Modifiche principali:

  • Ritiro di dsConversionId: dsConversionID non è più supportato nell'API Search Ads 360 Conversion, nell'API Search Ads 360 Reporting (indicato come conversion.id) o nell'UI dei report (indicato come "ID conversione").
  • conversionId Requisito: conversionId è un campo obbligatorio per la modifica delle conversioni tramite l'API Search Ads 360 Conversion.

Come ottenere conversionId:

  • Conversioni caricate tramite l'API Search Ads 360: utilizza il valore conversionId specificato quando hai inserito la conversione.
  • Conversioni registrate tramite i tag Floodlight: utilizza l'ID ordine Floodlight (il valore ord) registrato dal tag Floodlight per la conversione, ad esempio l'ID ordine o ID transazione di un'attività di vendita Floodlight.
  • API Search Ads 360 Reporting: puoi recuperare advertiser_conversion_id utilizzando l'API Search Ads 360 Reporting. Questo valore corrisponde al campo conversionId obbligatorio per la modifica.
  • UI di Search Ads 360: puoi trovare "ID conversione inserzionista" nella pagina dei report sulle conversioni nell'interfaccia utente di Search Ads 360. ID conversione nei report di SA360

Invia 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 essere state generate entro 60 giorni dalla data di generazione dell'ID clic.
  • Specifica la parola chiave della conversione (customerId, campaignId, adGroupId e criterionId)

Entrambe le tecniche richiedono di specificare conversionId, conversionTimestamp e type della transazione della conversione. conversionTimestamp deve essere il timestamp della conversione esistente, in millisecondi UTC epoch. Se il timestamp non corrisponde alla conversione esistente (ad esempio, perché è stato convertito da un fuso orario locale), Search Ads 360 non riesce a trovare la conversione e restituisce il codice di errore 0x0000011B.

Per le conversioni registrate da Search Ads 360 tramite i tag Floodlight, devi anche specificare l'attività Floodlight della conversione (segmentationType e segmentationName o segmentationId). In caso contrario, la richiesta non va a buon fine e viene restituito il codice di errore 0x0000010C. Ti consigliamo di specificare l'attività Floodlight in ogni richiesta di aggiornamento.

Inoltre, se la conversione originale specificava revenueMicros e currencyCode o quantityMillis, la richiesta di aggiornamento deve specificare questi dati anche se non li stai modificando.

Identifica la conversione in base all'ID clic

Se una conversione originariamente specificava un ID clic, puoi inviare una richiesta Conversion.update() che specifica i seguenti campi:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • segmentationType e segmentationName (o segmentationId) (obbligatorio per le conversioni registrate tramite i tag Floodlight, consigliato per tutte le conversioni)
  • state (obbligatorio solo se vuoi modificare lo stato in REMOVED o ACTIVE)
  • 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",
   "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",
   "conversionTimestamp": "1378710000000",
   "segmentationType" : "FLOODLIGHT",
   "segmentationName" : "Test",
   "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. This sample hard-codes the segmentation name.
    Conversion conversion = new Conversion()
        .setClickId(clickId)
        .setConversionId(conversionId)
        .setConversionTimestamp(BigInteger.valueOf(timeStamp))
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .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())

Identifica 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 specifica i seguenti campi:

  • customerId, campaignId, adGroupId e criterionId (i nuovi ID Search Ads 360 che identificano la parola chiave)
  • conversionId
  • conversionTimestamp
  • type
  • state (obbligatorio solo se vuoi modificare lo stato in REMOVED o ACTIVE)
  • quantityMillis (solo se specificato nella conversione originale)
  • revenueMicros (solo se specificato nella conversione originale)
  • currencyCode (solo se specificato nella conversione originale)

Gli ID parola chiave sono univoci solo all'interno di un gruppo di annunci, pertanto devi specificare tutti e quattro gli ID. Se una conversione specifica criterionId senza customerId, campaignId o adGroupId, l'aggiornamento non va a buon fine e restituisce il codice di errore 0x0000012E. Non è necessario specificare altri ID, ad esempio l'ID annuncio della conversione.

Esempio

Ecco un esempio di conversione esistente:

{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
   "customerId": "123-456-7890",
   "campaignId": "14660344555",
   "adGroupId": "105138634255",
   "criterionId": "948710340465",
   "conversionId": "test_1383157519886",
   "conversionTimestamp": "1378710000000",
   "type": "ACTION",
   "quantityMillis": "1000",
   "segmentationType": "FLOODLIGHT",
   "segmentationName": "Test"
  }]
}     

La seguente richiesta aggiorna la quantità 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": [
  {
   "customerId": "123-456-7890", // Replace with your ID
   "campaignId": "14660344555", // Replace with your ID
   "adGroupId": "105138634255", // Replace with your ID
   "criterionId": "948710340465", // 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,
        "123-456-7890",       // customerId. Replace with your ID
        14660344555L,         // campaignId. Replace with your ID
        105138634255L,        // adGroupId. Replace with your ID
        948710340465L,        // 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,
       String customerId,
       Long campaignId,
       Long adGroupId,
       Long criterionId,
       String conversionId,
       Long timeStamp,
       String type,
       String state,
       Long quantity,
       Long revenue,
       String currency
    ) {

   Conversion conversion = new Conversion()
   .setCustomerId(customerId)
   .setCampaignId(campaignId)
   .setAdGroupId(adGroupId)
   .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 quantity of a conversion. Use the keyword's IDs (customerId,
  campaignId, adGroupId, and criterionId) to identify the conversion.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().update(
      body=
      {
          'conversion': [{
              'customerId': '123-456-7890', // Replace with your ID
              'campaignId': '14660344555', // Replace with your ID
              'adGroupId': '105138634255', // Replace with your ID
              'criterionId': '948710340465', // Replace with your ID
              'conversionId': 'test_1383157519886',
              'conversionTimestamp': '1378710000000',
              'type': 'ACTION',
              'quantityMillis': '3000'
            }]
      }
  )

  pprint.pprint(request.execute())

Gestisci le risposte di Search Ads 360

La risposta a una richiesta di aggiornamento è la stessa della risposta a una richiesta di inserimento: Search Ads 360 indica l'esito positivo 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 il nuovo ID cliente, ID campagna, ID gruppo di annunci e ID parola chiave (criterio) di Search Ads 360.

Se la convalida o il caricamento di uno o più aggiornamenti non va a buon fine, la risposta include messaggi di errore per ogni aggiornamento non riuscito. La risposta non contiene messaggi relativi alle conversioni aggiornate correttamente. Per saperne di più su questi messaggi di errore, consulta Gestisci le risposte di Search Ads 360 per le richieste di inserimento.