Modifier les conversions existantes

Appelez la méthode Conversion.update() pour apporter les types de modifications suivants à une ou plusieurs conversions existantes:

Vous ne pouvez pas modifier les éléments suivants dans Search Ads 360:

  • Date de la conversion.
  • Type de conversion
  • Mot clé ou visite attribués à la conversion
  • Activité Floodlight ou nom de cette dernière

Toutefois, vous pouvez toujours marquer une conversion existante comme "SUPPRIMÉE" et en importer une nouvelle en indiquant la date, le type, les ID d'attribution ou l'activité Floodlight mis à jour (n'oubliez pas de spécifier un nouveau conversionId).

Comme avec Conversion.insert(), si votre requête de mise à jour spécifie plusieurs conversions, Search Ads 360 tente de mettre à jour chaque conversion dans la mesure du possible au lieu de mettre à jour l'ensemble du lot en tant que transaction tout ou rien. Si certaines mises à jour d'un lot échouent, d'autres peuvent toujours réussir. Nous vous recommandons de lire la réponse pour chaque conversion mise à jour afin de vous assurer que la mise à jour a bien été effectuée.

(Mise à jour 2025) Abandon de dsConversionId

Actuellement, vous pouvez utiliser dsConversionId ou conversionId pour identifier et modifier les conversions. Le champ dsConversionId sera abandonné au troisième trimestre 2025. À l'avenir, vous devrez utiliser conversionId pour modifier les conversions dans l'API Search Ads 360 Conversion.

Principaux changements :

  • Annulation de dsConversionId: dsConversionID ne sera plus pris en charge dans l'API Search Ads 360 Reporting (appelée conversion.id) ni dans l'UI de reporting (appelée "ID de conversion").
  • Exigence concernant conversionId: conversionId deviendra un champ obligatoire pour modifier les conversions via l'API Search Ads 360 Conversion.

Pour obtenir conversionId:

  • API Search Ads 360 Reporting: vous pouvez récupérer advertiser_conversion_id à l'aide de l'API Search Ads 360 Reporting. Cette valeur correspond à l'conversionId requise pour la modification.
  • Interface utilisateur de Search Ads 360: vous trouverez l'ID de conversion de l'annonceur sur la page des rapports sur les conversions de l'interface utilisateur de Search Ads 360. ID de conversion dans les rapports SA360

Envoyer une demande de mise à jour

La plupart des champs que vous spécifiez dans un Conversion.update() servent à identifier les conversions que vous souhaitez mettre à jour. Vous pouvez utiliser l'une des techniques suivantes pour identifier une conversion existante:

  • Spécifiez le clickId de la conversion.
    • Toutes les conversions modifiées doivent avoir lieu dans les 60 jours suivant la génération de l'ID de clic.
  • Spécifier l'criterionId (ID de mot clé) de la conversion

Les deux techniques nécessitent de spécifier les valeurs conversionId, conversionTimestamp et type de la conversion.

De plus, si la conversion d'origine spécifiait revenueMicros et currencyCode ou quantityMillis, la requête de mise à jour doit spécifier ces données, même si vous ne les modifiez pas.

Identifier la conversion par ID de clic

Si une conversion spécifiait initialement un ID de clic, vous pouvez envoyer une requête Conversion.update() qui spécifie les champs suivants:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • state (obligatoire uniquement si vous souhaitez définir l'état sur "SUPPRIMÉ" ou "ACTIF")
  • quantityMillis (uniquement si spécifié dans la conversion d'origine)
  • revenueMicros (uniquement si spécifié dans la conversion d'origine)
  • currencyCode (uniquement si spécifié dans la conversion d'origine)

Exemple

Voici un exemple de deux conversions existantes: 

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

La requête suivante met à jour l'une des conversions de l'exemple précédent et supprime l'autre:

JSON

Notez qu'une requête Conversion.update() utilise la méthode 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())

Identifier les conversions par ID de mot clé

Si vous n'avez pas accès à un ID de clic ou si une conversion a été attribuée à l'origine à un mot clé ou à un mot clé/une annonce, vous pouvez envoyer une requête Conversion.update() qui spécifie les champs suivants:

  • criterionId (ID du mot clé)
  • conversionId
  • conversionTimestamp
  • type
  • state (obligatoire uniquement si vous souhaitez définir l'état sur "SUPPRIMÉ" ou "ACTIF")
  • quantityMillis (uniquement si spécifié dans la conversion d'origine)
  • revenueMicros (uniquement si spécifié dans la conversion d'origine)
  • currencyCode (uniquement si spécifié dans la conversion d'origine)

Vous pouvez également spécifier d'autres ID, tels que l'ID de l'annonce ou de la campagne de la conversion, mais ce n'est pas obligatoire. Search Ads 360 n'a besoin que des ID de la liste ci-dessus pour identifier une conversion existante.

Exemple

Voici un exemple de conversion existante: 

{
 "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 requête suivante met à jour le code temporel de la conversion:

JSON

Notez qu'une requête Conversion.update() utilise la méthode 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())

Gérer les réponses Search Ads 360

La réponse à une requête de mise à jour est la même que celle d'une requête d'insertion: Search Ads 360 n'indique la réussite que si toutes les conversions de la requête ont bien été mises à jour.

Si la requête aboutit, la réponse inclut la représentation interne complète de Search Ads 360 pour chaque conversion mise à jour, comme l'ID de la campagne, l'ID du groupe d'annonces et l'ID du mot clé (critère).

Si la validation ou l'importation d'une ou de plusieurs mises à jour échoue, la réponse inclut des messages d'échec pour chaque mise à jour échouée. La réponse ne contient pas de messages sur les conversions mises à jour. Pour en savoir plus sur ces messages d'échec, consultez la section Gérer les réponses Search Ads 360 pour les requêtes d'insertion.