Chame o método Conversion.update()
para fazer os seguintes tipos de alterações em uma ou mais conversões atuais:
- Modifique a receita, o código da moeda ou a quantidade.
- Modifique o ID do pedido fornecido pelo anunciante e qualquer variável personalizada do Floodlight.
- Remova a conversão mudando o
conversion.state
deACTIVE
paraREMOVED
.
O Search Ads 360 não é compatível com mudanças nos seguintes itens:
- A data da conversão.
- O tipo de conversão.
- A palavra-chave, o anúncio ou a visita atribuídos à conversão.
- Atividade ou nome da atividade do Floodlight.
No entanto, você sempre pode marcar uma conversão existente como REMOVIDA 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 também um novo conversionId
.
Assim como em Conversion.insert()
, se sua solicitação de atualização especificar várias conversões, o Search Ads 360 tentará atualizar cada conversão da melhor maneira possível, em vez de atualizar todo o lote como uma transação "tudo ou nada". Se algumas atualizações de um lote falharem, outras ainda poderão ser bem-sucedidas. Recomendamos que você leia a resposta para cada conversão atualizada para garantir que a ação seja bem-sucedida.
Enviar uma solicitação de atualização
A maioria dos campos especificados em um Conversion.update()
é usada para identificar as conversões que você quer atualizar. É possível usar uma das técnicas a seguir para identificar uma conversão existente:
- Especifique o
clickId
da conversão- Todas as conversões editadas precisam ser feitas até 60 dias após a geração do ID de clique.
- Especifique o
criterionId
(ID da palavra-chave) da conversão
Ambas as técnicas exigem que você especifique o conversionId
, o conversionTimestamp
e o type
da transaçã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 por 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
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
Veja um exemplo de duas conversões 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" }] }
A solicitação a seguir atualiza uma das conversões do exemplo anterior e remove a outra:
JSON
Observe que 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", "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" } ] }
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())
Identificar a conversão por ID de palavra-chave
Se você não tiver acesso a um ID de clique ou se uma conversão tiver sido atribuída originalmente a uma palavra-chave ou palavra-chave/anúncio, envie uma solicitação Conversion.update()
especificando os campos a seguir:
criterionId
(ID da 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)
Opcionalmente, você pode especificar outros IDs, como o ID do anúncio, da campanha e assim por diante, mas não é necessário. O Search Ads 360 só precisa dos IDs na lista acima para identificar uma conversão existente.
Exemplo
Veja um exemplo de uma conversão 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" }] }
A solicitação a seguir atualiza o carimbo de data/hora da conversão:
JSON
Observe que 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": [ { "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())
Processar respostas do Search Ads 360
A resposta de uma solicitação de atualização é igual à resposta de uma solicitação de inserção: o Search Ads 360 indica o sucesso somente se todas as conversões na solicitação tiverem sido atualizadas.
Se a solicitação for bem-sucedida, a resposta vai incluir a representação interna completa do Search Ads 360 para cada conversão atualizada, como ID da campanha, ID do grupo de anúncios e ID de palavra-chave (critério).
Se uma ou mais atualizações não forem validadas ou enviadas, a resposta 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 Gerenciar respostas do Search Ads 360 para solicitações de inserção.