Modificar conversões existentes

Chame o método Conversion.update() para fazer os seguintes tipos de mudanças em uma ou mais conversões:

O Search Ads 360 não aceita mudanças nos seguintes itens:

  • A data da conversão.
  • Tipo de conversão
  • A palavra-chave ou visita atribuída à conversão.
  • Atividade do Floodlight ou nome da atividade

No entanto, é possível marcar uma conversão atual como REMOVED e fazer o upload de uma nova com a data, o tipo, os IDs de atribuição ou a atividade do Floodlight atualizados. Não se esqueça de especificar um novo conversionId também.

É possível editar as conversões que foram enviadas pela API Search Ads 360 (conversões off-line) e as que o Search Ads 360 registrou usando tags do Floodlight (conversões on-line), de acordo com os seguintes limites de tempo:

  • Se você identificar a conversão por clickId, o ID de clique precisará ter sido gerado nos últimos 60 dias (caso contrário, o código do erro será 0x0000012F).
  • As conversões registradas por tags do Floodlight só podem ser editadas em até 28 dias após o conversionTimestamp (caso contrário, o código do erro 0x00000125 será exibido).

Assim como em Conversion.insert(), se o pedido de atualização especificar várias conversões, o Search Ads 360 tentará atualizar cada conversão da melhor forma possível, em vez de atualizar todo o lote como uma transação "tudo ou nada". Se algumas atualizações em um lote falharem, outras ainda poderão ser bem-sucedidas. Recomendamos que você leia a resposta de cada conversão atualizada para garantir que a atualização foi concluída.

Descontinuação de dsConversionId

O campo dsConversionId foi descontinuado e não pode mais ser usado para identificar conversões. Use conversionId (o ID de conversão do anunciante) para editar conversões na API Search Ads 360 Conversion. O Conversion.update() rejeita uma conversão com o código do erro 0x0000013C (Conversion editing using integer DS conversion ID is deprecated) se ela:

  • especifica o campo dsConversionId ou
  • transmite um ID de conversão do Search Ads 360 (o ID numérico de 17 dígitos que o Search Ads 360 gera para cada conversão) no campo conversionId.

Mudanças importantes:

  • dsConversionId Descontinuação: o dsConversionID não é mais compatível com a API Search Ads 360 Conversion, a API Search Ads 360 Reporting (chamada de conversion.id) ou a interface de relatórios (chamada de "ID de conversão").
  • conversionId Requisito: conversionId é um campo obrigatório para editar conversões usando a API Search Ads 360 Conversion.

Como conseguir o conversionId:

  • Conversões enviadas pela API Search Ads 360: use o conversionId que você especificou ao inserir a conversão.
  • Conversões registradas por tags do Floodlight: use o código do pedido do Floodlight (o valor ord) que a tag do Floodlight informou para a conversão, por exemplo, o ID do pedido ou o ID da transação de uma atividade de vendas do Floodlight.
  • API Search Ads 360 Reporting: é possível recuperar advertiser_conversion_id usando a API Search Ads 360 Reporting. Esse valor corresponde ao conversionId necessário para edição.
  • Interface do Search Ads 360: o "ID de conversão do anunciante" está na página de relatórios de conversão na interface do usuário do Search Ads 360. ID de conversão nos relatórios do SA360

Enviar um pedido de atualização

A maioria dos campos que você especifica em um Conversion.update() é usada para identificar as conversões que você quer atualizar. Você pode usar uma das seguintes técnicas para identificar uma conversão:

  • Especifique o clickId da conversão.
    • Todas as conversões editadas precisam estar dentro de 60 dias do momento em que o ID de clique é gerado.
  • Especifique a palavra-chave da conversão (customerId, campaignId, adGroupId e criterionId)

As duas técnicas exigem que você especifique o conversionId, o conversionTimestamp e o type da transação da conversão. O conversionTimestamp precisa ser o carimbo de data/hora da conversão atual, em milissegundos da época UTC. Se o carimbo de data/hora não corresponder à conversão atual (por exemplo, porque foi convertido de um fuso horário local), o Search Ads 360 não vai encontrar a conversão e vai retornar o código do erro 0x0000011B.

Para conversões que o Search Ads 360 registrou usando tags do Floodlight, você também precisa especificar a atividade do Floodlight da conversão (segmentationType e segmentationName ou segmentationId). Caso contrário, a solicitação vai falhar com o código do erro 0x0000010C. Recomendamos que você especifique a atividade do Floodlight em todas as solicitações de atualização.

Além disso, se a conversão original especificou revenueMicros e currencyCode ou quantityMillis, a solicitação de atualização precisa especificar esses dados, mesmo que você não os altere.

Identificar a conversão pelo ID de clique

Se uma conversão especificou originalmente um ID de clique, envie uma solicitação Conversion.update() que especifique os seguintes campos:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • segmentationType e segmentationName (ou segmentationId) (obrigatório para conversões registradas por tags do Floodlight, recomendado para todas as conversões)
  • state (obrigatório apenas se você quiser mudar o estado para REMOVED ou ACTIVE)
  • quantityMillis (somente se especificado na conversão original)
  • revenueMicros (somente se especificado na conversão original)
  • currencyCode (somente se especificado na conversão original)

Exemplo

Confira um exemplo de duas conversões:

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

A solicitação a seguir atualiza uma das conversões do exemplo anterior e remove a outra:

JSON

Uma solicitação Conversion.update() usa o 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",
   "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())

Identificar a conversão pelo ID de palavra-chave

Se você não tiver acesso a um ID de clique ou se uma conversão tiver sido originalmente atribuída a uma palavra-chave ou palavra-chave/anúncio, envie uma solicitação Conversion.update() que especifique os seguintes campos:

  • customerId, campaignId, adGroupId e criterionId (os IDs do novo Search Ads 360 que identificam a palavra-chave)
  • conversionId
  • conversionTimestamp
  • type
  • state (obrigatório apenas se você quiser mudar o estado para REMOVED ou ACTIVE)
  • quantityMillis (somente se especificado na conversão original)
  • revenueMicros (somente se especificado na conversão original)
  • currencyCode (somente se especificado na conversão original)

Os IDs de palavra-chave são exclusivos apenas em um grupo de anúncios. Portanto, é necessário especificar os quatro IDs. Se uma conversão especificar criterionId sem customerId, campaignId ou adGroupId, a atualização vai falhar com o código do erro 0x0000012E. Não é necessário especificar outros IDs, como o ID de anúncio da conversão.

Exemplo

Veja um exemplo de conversão:

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

A solicitação a seguir atualiza a quantidade da conversão:

JSON

Uma solicitação Conversion.update() usa o 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": [
  {
   "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())

Processar respostas do Search Ads 360

A resposta para uma solicitação de atualização é igual à resposta para uma solicitação de inserção: o Search Ads 360 indica sucesso somente se todas as conversões na solicitação forem atualizadas.

Se a solicitação for bem-sucedida, a resposta vai incluir a representação interna completa do novo Search Ads 360 para cada conversão atualizada, como o ID de cliente do novo Search Ads 360, o ID da campanha, o ID do grupo de anúncios e o ID da palavra-chave (critério).

Se uma ou mais atualizações não forem validadas ou enviadas, a resposta vai incluir mensagens de falha para cada atualização com falha. A resposta não contém mensagens sobre conversões que foram atualizadas. Para mais informações sobre essas mensagens de falha, consulte Processar respostas do Search Ads 360 para solicitações de inserção.