Chame o método Conversion.update() para fazer os seguintes tipos de mudanças em uma ou mais conversões:
- Modifique a receita, o código da moeda ou a quantidade.
- Modifique o código do pedido fornecido pelo anunciante e as variáveis personalizadas do Floodlight.
- Remova a conversão mudando o
conversion.statedeACTIVEparaREMOVED.
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 erro0x00000125será 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
dsConversionIdou - 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:
-
dsConversionIdDescontinuação: odsConversionIDnão é mais compatível com a API Search Ads 360 Conversion, a API Search Ads 360 Reporting (chamada deconversion.id) ou a interface de relatórios (chamada de "ID de conversão"). -
conversionIdRequisito: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
conversionIdque 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_idusando a API Search Ads 360 Reporting. Esse valor corresponde aoconversionIdnecessá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.
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
clickIdda 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,adGroupIdecriterionId)
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:
clickIdconversionIdconversionTimestamptypesegmentationTypeesegmentationName(ousegmentationId) (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,adGroupIdecriterionId(os IDs do novo Search Ads 360 que identificam a palavra-chave)conversionIdconversionTimestamptypestate(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.