Modificar las conversiones existentes

Llama al método Conversion.update() para realizar los siguientes tipos de cambios en una o más conversiones existentes:

• Modifica los ingresos, el código de moneda o la cantidad.
• Modifica el ID de pedido proporcionado por el anunciante y cualquier variable de Floodlight personalizada.
• Para quitar la conversión, cambia la conversion.state de ACTIVE a REMOVED.

Search Ads 360 no permite cambiar los siguientes elementos:

• Es la fecha de conversión.
• El tipo de conversión.
• La palabra clave, el anuncio o la visita que se atribuyeron a la conversión
• La actividad de Floodlight o el nombre de la actividad

Sin embargo, siempre puedes marcar una conversión existente como REMOVED y subir una nueva con la fecha, el tipo, los IDs de atribución o la actividad de Floodlight actualizados (asegúrate de especificar también un conversionId nuevo).

Al igual que con Conversion.insert(), si la solicitud de actualización especifica varias conversiones, Search Ads 360 intenta actualizar cada conversión según el criterio del mejor esfuerzo, en lugar de actualizar todo el lote como una transacción de todo o nada. Si algunas actualizaciones fallan en un lote, otras pueden seguir ejecutándose de forma correcta. Te recomendamos que lees la respuesta para cada conversión actualizada a fin de asegurarte de que se realice de forma correcta.

Envía una solicitud de actualización

La mayoría de los campos que especificas en un Conversion.update() se usan para identificar las conversiones que deseas actualizar. Puedes usar cualquiera de las siguientes técnicas para identificar una conversión existente:

• Especifica el clickId de la conversión.
  • Todas las conversiones editadas deben realizarse en un plazo de 60 días desde el momento en que se generó el ID de clic.
• Especifica el criterionId (ID de palabra clave) de la conversión

Ambas técnicas requieren que especifiques el conversionId, el conversionTimestamp y la transacción type de la conversión.

Además, si la conversión original especificó revenueMicros y currencyCode o quantityMillis, la solicitud de actualización debe especificar estos datos, incluso si no los cambias.

Cómo identificar la conversión por ID de clic

Si una conversión especificó originalmente un ID de clic, puedes enviar una solicitud Conversion.update() que especifique los siguientes campos:

• clickId
• conversionId
• conversionTimestamp
• type
• state (es obligatorio solo si desea cambiar el estado a REMOVED o ACTIVE)
• quantityMillis (solo si se especifica en la conversión original)
• revenueMicros (solo si se especifica en la conversión original)
• currencyCode (solo si se especifica en la conversión original)

Ejemplo

A continuación, se incluye un ejemplo de dos conversiones existentes:

{
 "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"
  }]
}     

En la siguiente solicitud, se actualiza una de las conversiones del ejemplo anterior y se quita la otra:

JSON

Ten en cuenta que una solicitud Conversion.update() usa el método 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"
  }
 ]
}        

Usa la secuencia de comandos de utilidad de Search Ads 360 para enviar esta solicitud

Para enviar una solicitud POST de JSON sin procesar, puedes usar la secuencia de comandos sa360Api.py de la siguiente manera:

1. Copia el objeto JSON de ejemplo (todo entre las dos llaves inclusive) en un archivo de texto nuevo llamado request.txt.
2. Cambia el ID de la agencia que aparece en el código JSON por el ID de tu agencia.
3. Quita cualquier comentario, por ejemplo // The date column segments the report by individual days.
4. Organiza tus credenciales de OAuth 2.0 en una sola string separada por comas de la siguiente manera:
   client-ID,client-secret,refresh-token
   (Esta es la misma string que muestra sa360Api.py cuando ejecutas sa360Api.py --login, como se describe en Configura la autorización).
5. Invoca sa360Api.py de la siguiente manera:
   sa360Api.py --cred CREDENTIALS --server API-method --put < request.txt
   En el comando anterior, sustituye la cadena que creaste en el paso anterior por CREDENTIALS.
   Sustituye el nombre del método PUT en el cuadro de abajo por API-method.

   Por ejemplo:
   sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --put < request.txt

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())

Cómo identificar la conversión por ID de palabra clave

Si no tienes acceso a un ID de clic, o si una conversión se atribuyó originalmente a una palabra clave, una palabra clave o un anuncio, puedes enviar una solicitud Conversion.update() que especifique los siguientes campos:

• criterionId (ID de palabra clave)
• conversionId
• conversionTimestamp
• type
• state (es obligatorio solo si desea cambiar el estado a REMOVED o ACTIVE)
• quantityMillis (solo si se especifica en la conversión original)
• revenueMicros (solo si se especifica en la conversión original)
• currencyCode (solo si se especifica en la conversión original)

De forma opcional, puedes especificar otros IDs, como el ID del anuncio de la conversión, el ID de la campaña, etc., pero no es necesario que lo hagas. Search Ads 360 solo necesita los IDs de la lista anterior para identificar una conversión existente.

Ejemplo

A continuación, presentamos un ejemplo de una conversión existente:

{
 "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 siguiente solicitud actualiza la marca de tiempo de la conversión:

JSON

Ten en cuenta que una solicitud Conversion.update() usa el método HTTP PUT.

Usa la secuencia de comandos de utilidad de Search Ads 360 para enviar esta solicitud

Para enviar una solicitud POST de JSON sin procesar, puedes usar la secuencia de comandos sa360Api.py de la siguiente manera:

1. Copia el objeto JSON de ejemplo (todo entre las dos llaves inclusive) en un archivo de texto nuevo llamado request.txt.
2. Cambia el ID de la agencia que aparece en el código JSON por el ID de tu agencia.
3. Quita cualquier comentario, por ejemplo // The date column segments the report by individual days.
4. Organiza tus credenciales de OAuth 2.0 en una sola string separada por comas de la siguiente manera:
   client-ID,client-secret,refresh-token
   (Esta es la misma string que muestra sa360Api.py cuando ejecutas sa360Api.py --login, como se describe en Configura la autorización).
5. Invoca sa360Api.py de la siguiente manera:
   sa360Api.py --cred CREDENTIALS --server API-method --put < request.txt
   En el comando anterior, sustituye la cadena que creaste en el paso anterior por CREDENTIALS.
   Sustituye el nombre del método PUT en el cuadro de abajo por API-method.

   Por ejemplo:
   sa360Api.py --cred 123456789123.apps.googleusercontent.com,ABCDEFGHIJKLMNOPQR_abcdef,1/HIJklM01OPQR23NOP456rst890uvw --server https://www.googleapis.com/doubleclicksearch/v2/conversion --put < request.txt

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())

Cómo procesar las respuestas de Search Ads 360

La respuesta a una solicitud de actualización es la misma que la respuesta a una solicitud de inserción: Search Ads 360 indica el éxito solo si todas las conversiones de la solicitud se actualizaron correctamente.

Si la solicitud se realiza correctamente, la respuesta incluye la representación interna completa de Search Ads 360 para cada conversión actualizada, como el ID de campaña, el ID de grupo de anuncios y el ID de palabra clave (criterio).

Si una o más actualizaciones no se validan o no se suben, la respuesta incluye mensajes de error para cada actualización con errores. La respuesta no contiene mensajes sobre las conversiones que se actualizaron correctamente. Para obtener más información sobre estos mensajes de error, consulta Administra las respuestas de Search Ads 360 para las solicitudes de inserción.