Adicionar novas conversões

Quando posso usar os dados enviados?

Se você especificar um conversionTimestamp de hoje ou de ontem para uma conversão, as métricas dela vão aparecer na interface do Search Ads 360 em até uma hora após o upload. Se você especificar um conversionTimestamp anterior a ontem, as métricas serão atualizadas em várias horas.

Converta todos os carimbos de data/hora das conversões em Horário de época (também conhecido como horário Unix).

Posso criar atividades do Floodlight usando a API?

Se o anunciante ainda não tiver criado uma atividade do Floodlight para rastrear conversões off-line, use a API Campaign Manager para criar uma. Não é possível usar a API para especificar que uma atividade do Floodlight é usada principalmente para conversões off-line, o que é uma prática recomendada quando as estratégias de lances vão usar dados da conversão.

Recomendamos que, depois de usar a API para criar uma atividade do Floodlight, um usuário do Search Ads 360 faça login no Search Ads 360 e mude a configuração da atividade para indicar que a origem principal das conversões é a atividade off-line.

Práticas recomendadas para adicionar conversões

Recomendamos as seguintes práticas recomendadas para adicionar conversões:

1. Peça a um usuário do Search Ads 360 para fazer login no Search Ads 360 e mudar as configurações de cada atividade do Floodlight usada para informar conversões off-line. As configurações precisam indicar que a principal fonte de conversões é a atividade off-line. Consulte a Central de Ajuda do Search Ads 360 para ver instruções.

2. Faça o upload das conversões assim que elas estiverem disponíveis. Se você atribuir conversões a visitas específicas, aguarde pelo menos 6 horas após a visita para fazer upload da conversão. Talvez o Search Ads 360 não reconheça o ID de clique de uma visita se você fizer upload em menos de 6 horas após o acesso. Em casos raros, talvez seja necessário aguardar até 24 horas para que o Search Ads 360 reconheça o clickID.

   Verifique se cada upload contém as conversões mais recentes. Em uma única solicitação de upload, não há problema se as entradas estiverem fora da ordem cronológica. No entanto, talvez as estratégias de lances não considerem as conversões mais antigas que você enviar por upload mais tarde em outra solicitação.

Enviar uma solicitação de inserção

Você pode enviar uma solicitação Conversion.insert() para fazer o seguinte:

• Atribuir uma conversão a uma visita específica
• Atribuir uma conversão apenas a uma palavra-chave

Os campos obrigatórios em uma solicitação Conversion.insert() dependem do evento ou item a que você está atribuindo a conversão. As seções a seguir listam os campos obrigatórios e opcionais para cada evento ou item a que você pode atribuir uma conversão.

Atribuir uma conversão a uma visita específica

Quando um cliente clica em um ou mais anúncios e acessa o site de um anunciante, o Search Ads 360 considera a sessão do usuário no site do anunciante como uma visita. Para atribuir uma conversão a uma visita, especifique o seguinte na solicitação Conversion.insert():

Campos obrigatórios

• clickId: o ID de clique da visita, que diferencia maiúsculas de minúsculas. Procure o ID de clique ou as conversões da lista nos registros da Web do anunciante e use um ID de clique de outra conversão. O Search Ads 360 vai atribuir a conversão à palavra-chave, ao anúncio e a outros objetos do Search Ads 360 que foram responsáveis por gerar a visita.
  Aguarde pelo menos 6 horas depois que o Search Ads 360 gerar um ID de clique para fazer o upload das conversões. Se você receber um erro "O ID do clique não foi encontrado", aguarde 24 horas e faça o upload das conversões novamente. Todas as conversões precisam ser enviadas em até 90 dias após a geração do ID de clique. Caso contrário, a API Search Ads 360 pode não reconhecer a visita.
• conversionId: para conversões off-line, os anunciantes fornecem esse ID. Os anunciantes podem especificar qualquer ID que seja relevante para eles. Cada conversão em uma solicitação precisa especificar um ID exclusivo, e a combinação de ID e carimbo de data/hora precisa ser única entre todas as conversões do anunciante. Para conversões on-line, o Search Ads 360 copia o dsConversionId ou o floodlightOrderId para essa propriedade, dependendo das instruções do Floodlight do anunciante.
• conversionTimestamp: indica a data e a hora em que a conversão ocorreu. Por exemplo, se a conversão ocorrer em 05 de agosto de 2016, às 11h53min22s (horário de verão do leste dos EUA, GMT -4:00), especifique o carimbo de data/hora em milissegundos do Epoch: 1470412402000.
• segmentationType: especifica o tipo de sistema de conversão para o qual você está fazendo o upload da conversão. No momento, apenas as conversões do Floodlight são compatíveis. Portanto, esse campo é sempre necessário para especificar FLOODLIGHT.
• segmentationName: o nome da atividade do Floodlight que o anunciante está usando para informar a conversão.

  Se o anunciante tiver atividades com o mesmo nome (isso pode acontecer se as atividades pertencerem a grupos diferentes do Floodlight), a ação recomendada é renomear uma delas.

  Como alternativa, se você souber o ID que o Search Ads 360 atribuiu a uma atividade do Floodlight, especifique o ID em segmentationId em vez de especificar o nome no campo segmentationName. O Campaign Manager também atribui um ID à atividade do Floodlight, mas o ID do Campaign Manager é diferente do ID do Search Ads 360 e não pode ser usado para atribuir conversões. Para conferir o ID do Search Ads 360 de uma atividade do Floodlight, faça o download de um relatório de conversões na interface do Search Ads 360 ou na API de relatórios. Se pelo menos uma conversão tiver sido atribuída à atividade do Floodlight durante o período do relatório, o ID do Search Ads 360 vai aparecer no relatório.

• type: o tipo de conversão, ou seja, ACTION ou TRANSACTION. Uma conversão de AÇÃO não tem valor monetário, enquanto uma conversão de TRANSAÇÃO tem. Exemplos são inscrições em listas de e-mail (AÇÃO) em comparação com compras de e-commerce (TRANSAÇÃO).

  Se você especificar TRANSACTION, também precisará especificar o seguinte campo:

  • revenueMicros: o valor monetário da conversão.

Campos opcionais

• quantityMillis: o número de itens nessa conversão. Por exemplo, o número de pessoas que se inscreveram para uma newsletter por e-mail ou a quantidade total de itens vendidos. Se você não especificar esse campo para conversões de AÇÃO, o Search Ads 360 vai inserir automaticamente um valor de 1000.
• currencyCode: a moeda da receita de uma transação. Por padrão, a receita é considerada na moeda do anunciante. Se você especificar uma moeda diferente, o Search Ads 360 vai converter o valor da receita especificado para a moeda do anunciante. Saiba mais
  Use o formato alfabético (três caracteres) ISO 4217 para especificar a moeda.
  Aplicável apenas para conversões de TRANSAÇÃO.
• customMetric e customDimension: fazem upload de dados adicionais sobre uma conversão, como o país para onde um item comprado é enviado, IDs de produtos ou até mesmo a duração de uma ligação telefônica. Saiba mais sobre como fazer upload de dados para variáveis personalizadas do Floodlight.
• deviceType: especifica o tipo de dispositivo em que a conversão ocorreu. Consulte a lista de valores aceitos para esse campo.

POST  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 a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue
    "currencyCode": "USD"
  }]
}
          

  /**
   * Instantiate the Doubleclicksearch service, create conversions, and upload them.
   */
  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>();

    // Add a conversion to the List.
    addTransactionConversionForVisit(conversions, "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
        "test_" + System.currentTimeMillis(), 10000000L, 1378710000000L);

    // Upload the List and handle the response.
    uploadConversions(conversions, service);
  }


  /**
   * Create a TRANSACTION conversion and add it to a List<Conversion>. This sample hard-codes
   * the segmentation name and currency. You probably wouldn't want your production code to be so brittle.
   */
  private static List<Conversion> addTransactionConversionForVisit(List<Conversion> conversions,
      String clickId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion().setClickId(clickId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }


  /**
   * Convert the List of conversions to a DS ConversionList, send an insert request to DS,
   * and output the response to a file.
   */
  private static void uploadConversions(List<Conversion> conversions, Doubleclicksearch service)
      throws IOException {

    FileOutputStream outputStream =
        new FileOutputStream(new File("./", "InsertConversionsResponse.txt"));
    final PrintStream printStream = new PrintStream(outputStream);

    try {
      // Convert the List to a ConversionList.
      ConversionList conversionList = new ConversionList().setConversion(conversions);

      // Insert an upload request and download the response to a file.
      service.conversion().insert(conversionList).executeAndDownloadTo(printStream);
      printStream.close();
    } catch (GoogleJsonResponseException e) {
      System.err.println("Get request was rejected.");
      for (ErrorInfo error : e.getDetails().getErrors()) {
        System.err.println(error.getMessage());
      }
      System.exit(e.getStatusCode());
    }
  }
            

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a visit.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with a click ID from your site
              'conversionId': 'test_20140206_00',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '10000000', // 10 million revenueMicros is equivalent to $10 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

Atribuir uma conversão apenas a uma palavra-chave

Se sua principal preocupação é atribuir conversões a palavras-chave, e você não se preocupa em atribuir a anúncios, pode omitir a maioria dos identificadores do Search Ads 360 e especificar apenas o identificador da palavra-chave com alguns outros campos:

Campos obrigatórios

• criterionId: é o identificador da palavra-chave. Para receber o criterionId, adicione a macro TrackerId aos URLs da página de destino. Para saber como conseguir IDs de palavras-chave, consulte IDs e conversões do Search Ads 360.
• conversionId: para conversões off-line, os anunciantes fornecem esse ID. Os anunciantes podem especificar qualquer ID que seja relevante para eles. Cada conversão em uma solicitação precisa especificar um ID exclusivo, e a combinação de ID e carimbo de data/hora precisa ser única entre todas as conversões do anunciante. Para conversões on-line, o Search Ads 360 copia o dsConversionId ou o floodlightOrderId para essa propriedade, dependendo das instruções do Floodlight do anunciante.
• conversionTimestamp: indica a data e a hora em que a conversão ocorreu. Por exemplo, se a conversão ocorrer em 05 de agosto de 2016, às 11h53min22s (horário de verão do leste dos EUA, GMT -4:00), especifique o carimbo de data/hora em milissegundos do Epoch: 1470412402000.
• segmentationType: especifica o tipo de sistema de conversão para o qual você está fazendo o upload da conversão. No momento, apenas as conversões do Floodlight são compatíveis. Portanto, esse campo é sempre necessário para especificar FLOODLIGHT.
• segmentationName: o nome da atividade do Floodlight que o anunciante está usando para informar a conversão.

  Se o anunciante tiver atividades com o mesmo nome (isso pode acontecer se as atividades pertencerem a grupos diferentes do Floodlight), a ação recomendada é renomear uma das atividades.

  Como alternativa, se você souber o ID atribuído pelo Search Ads 360 a uma atividade do Floodlight, especifique o ID em segmentationId em vez de especificar o nome no campo segmentationName. O Campaign Manager também atribui um ID à atividade do Floodlight, mas o ID do Campaign Manager é diferente do ID do Search Ads 360 e não pode ser usado para atribuir conversões. Para conferir o ID do Search Ads 360 de uma atividade do Floodlight, faça o download de um relatório de conversões na interface do Search Ads 360 ou na API de relatórios. Se pelo menos uma conversão tiver sido atribuída à atividade do Floodlight durante o período do relatório, o ID do Search Ads 360 vai aparecer no relatório.

• type: o tipo de conversão, ou seja, ACTION ou TRANSACTION. Uma conversão de AÇÃO não tem valor monetário, enquanto uma conversão de TRANSAÇÃO tem. Exemplos são inscrições em listas de e-mail (AÇÃO) em comparação com compras de e-commerce (TRANSAÇÃO).

  Se você especificar TRANSACTION, também precisará especificar o seguinte campo:

  • revenueMicros: o valor monetário da conversão.

Campos opcionais

• quantityMillis: o número de itens nessa conversão. Por exemplo, o número de pessoas que se inscreveram para uma newsletter por e-mail ou a quantidade total de itens vendidos. Se você não especificar esse campo para conversões de AÇÃO, o Search Ads 360 vai inserir automaticamente um valor de 1000.
• currencyCode: a moeda da receita de uma transação. Por padrão, a receita é considerada na moeda do anunciante. Se você especificar uma moeda diferente, o Search Ads 360 vai converter o valor da receita especificado para a moeda do anunciante. Saiba mais
  Use o formato alfabético (três caracteres) ISO 4217 para especificar a moeda.
  Aplicável apenas para conversões de TRANSAÇÃO.
• customMetric e customDimension: fazem upload de dados adicionais sobre uma conversão, como o país para onde um item comprado é enviado, IDs de produtos ou até mesmo a duração de uma ligação telefônica. Saiba mais sobre como fazer upload de dados para variáveis personalizadas do Floodlight.
• deviceType: especifica o tipo de dispositivo em que a conversão ocorreu. Consulte a lista de valores aceitos para esse campo.

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "criterionId": "43700003491981017", // Replace with your ID
    "conversionId": "customerTransaction73126",
    "conversionTimestamp": "1351196386000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "Offline Purchase",
    "type": "TRANSACTION",
    "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue
    "currencyCode": "USD"
  }]
}

  /**
   * Creates a TRANSACTION conversion, attributes it to a keyword only, and adds it to a List<Conversion>.
   * The example in the preceding section contains the uploadConversions method,
   * which can submit the list as an insert() request.
   */
  private static List<Conversion> addTransactionConversionForKeyword(List<Conversion> conversions,
      Long criterionId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion()
        .setCriterionId(criterionId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }        

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a keyword only.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'criterionId': '43700004289911004', // Replace with your ID
              'conversionId': 'test_1378710000000',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '20000000', // 20 million revenueMicros is equivalent to $20 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

Exemplo

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "PP5K8iI6ul7Vw09JZZDEp", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "attributionModel": "External Attribution Model",
    "countMillis": "330",
    "revenueMicros": "33000000", // 33 million revenueMicros is equivalent to $33 of revenue
    "currencyCode": "USD"
  }]
}
          

erros de requestValidation

Os erros requestValidation indicam problemas de dados na solicitação de upload de conversão, por exemplo, a conversão já foi enviada ou o clickId não foi encontrado. Nesse tipo de erro, os detalhes da mensagem contêm dois itens:

• Um código hexadecimal que identifica o tipo de erro. Você pode usar o código nos seus próprios scripts para identificar os erros.
• Uma descrição do erro de validação.

Para mais informações, consulte a lista de códigos e descrições que o Search Ads 360 pode retornar para erros de upload de conversões.

Outros tipos de erros

Todos os outros tipos de erros (internalError, transactionFailed ou lateStageRequestError) indicam que há um problema interno no Search Ads 360.

Como responder a um erro

Se a solicitação falhar, tente reenviar toda a chamada de solicitação mais tarde. O Search Ads 360 vai informar erros de requestValidation para todas as conversões que já foram enviadas, mas vai tentar fazer o upload das conversões restantes.

Se ainda houver erros após o reenvio, consulte a seção Solução de problemas para saber como proceder.