Zmień istniejące konwersje

Wywołaj metodę Conversion.update(), aby wprowadzić te typy zmian w co najmniej 1 istniejącej konwersji:

Search Ads 360 nie umożliwia zmiany tych danych:

  • Data konwersji.
  • typ konwersji;
  • słowo kluczowe lub wizyta, do których konwersja jest przypisana;
  • aktywność Floodlight lub nazwa aktywności;

Zawsze możesz jednak oznaczyć dotychczasową konwersję jako REMOVED (USUNIĘTA) i przesłać nową konwersję ze zaktualizowaną datą, typem, identyfikatorami atrybucji lub aktywnością Floodlight (pamiętaj, aby podać też nowy parametr conversionId).

Możesz edytować zarówno konwersje przesłane za pomocą interfejsu Search Ads 360 API (konwersje offline), jak i konwersje zarejestrowane przez Search Ads 360 za pomocą tagów Floodlight (konwersje online) z uwzględnieniem tych limitów czasowych:

  • Jeśli identyfikujesz konwersję za pomocą parametru clickId, identyfikator kliknięcia musi być wygenerowany w ciągu ostatnich 60 dni (w przeciwnym razie pojawi się kod błędu 0x0000012F).
  • Konwersje zarejestrowane za pomocą tagów Floodlight można edytować tylko w ciągu 28 dni od conversionTimestamp (w przeciwnym razie wystąpi kod błędu 0x00000125).

Podobnie jak w przypadku metody Conversion.insert(), jeśli żądanie aktualizacji określa wiele konwersji, Search Ads 360 próbuje zaktualizować każdą z nich, zamiast aktualizować całą partię jako transakcję typu „wszystko albo nic”. Jeśli niektóre aktualizacje w partii się nie powiodą, inne mogą się udać. Zalecamy zapoznanie się z odpowiedzią dotyczącą każdej zaktualizowanej konwersji, aby upewnić się, że aktualizacja się powiodła.

Wycofanie: dsConversionId

Pole dsConversionId zostało wycofane i nie można go już używać do identyfikowania konwersji. Aby edytować konwersje w interfejsie Search Ads 360 Conversion API, musisz używać parametru conversionId (identyfikator konwersji reklamodawcy). Conversion.update() odrzuca konwersję z kodem błędu 0x0000013C (Conversion editing using integer DS conversion ID is deprecated), jeśli konwersja:

  • określa pole dsConversionId lub
  • przekazuje w polu conversionId identyfikator konwersji Search Ads 360 (17-cyfrowy identyfikator liczbowy, który Search Ads 360 generuje dla każdej konwersji).

Najważniejsze zmiany:

  • Wycofanie dsConversionId: parametr dsConversionID nie jest już obsługiwany w interfejsie Search Ads 360 Conversion API, interfejsie Search Ads 360 Reporting API (określanym jako conversion.id) ani w interfejsie raportowania (określanym jako „Identyfikator konwersji”).
  • conversionId Wymaganie: conversionId to pole obowiązkowe, jeśli chcesz edytować konwersje za pomocą interfejsu Search Ads 360 Conversion API.

Jak uzyskać conversionId:

  • Konwersje przesłane za pomocą interfejsu Search Ads 360 API: użyj wartości conversionId podanej podczas wstawiania konwersji.
  • Konwersje zarejestrowane przez tagi Floodlight: użyj identyfikatora zamówienia Floodlight (wartość ord) zgłoszonego przez tag Floodlight dla konwersji, np. identyfikatora zamówienia lub identyfikatora transakcji aktywności Floodlight typu sprzedaż.
  • Search Ads 360 Reporting API: możesz pobierać advertiser_conversion_id za pomocą interfejsu Search Ads 360 Reporting API. Ta wartość odpowiada parametrowi conversionId, który jest wymagany do edycji.
  • Interfejs Search Ads 360: „Identyfikator konwersji u reklamodawcy” znajdziesz na stronie raportowania konwersji w interfejsie Search Ads 360. Identyfikator konwersji w raportach SA360

Wysyłanie prośby o aktualizację

Większość pól, które określasz w Conversion.update(), służy do identyfikowania konwersji, które chcesz zaktualizować. Aby zidentyfikować istniejącą konwersję, możesz użyć jednej z tych metod:

  • Określ clickId konwersji.
    • Wszystkie edytowane konwersje muszą mieć datę nie późniejszą niż 60 dni od momentu wygenerowania identyfikatora kliknięcia.
  • Określ słowo kluczowe konwersji (customerId, campaignId, adGroupId i criterionId).

Obie techniki wymagają podania conversionId, conversionTimestamp i type transakcji. Wartość conversionTimestamp musi być sygnaturą czasową istniejącej konwersji w milisekundach od początku epoki w strefie czasowej UTC. Jeśli sygnatura czasowa nie pasuje do istniejącej konwersji (np. dlatego, że została przekonwertowana z lokalnej strefy czasowej), Search Ads 360 nie może znaleźć konwersji i zwraca kod błędu 0x0000011B.

W przypadku konwersji zarejestrowanych przez Search Ads 360 za pomocą tagów Floodlight musisz też podać aktywność Floodlight konwersji (segmentationType oraz segmentationName lub segmentationId). W przeciwnym razie żądanie nie powiedzie się i zostanie zwrócony kod błędu 0x0000010C. Zalecamy podawanie aktywności Floodlight w każdym żądaniu aktualizacji.

Jeśli pierwotna konwersja zawierała parametry revenueMicros i currencyCode lub quantityMillis, żądanie aktualizacji musi zawierać te dane, nawet jeśli ich nie zmieniasz.

Identyfikowanie konwersji według identyfikatora kliknięcia

Jeśli konwersja pierwotnie określała identyfikator kliknięcia, możesz wysłać żądanie Conversion.update(), które określa te pola:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • segmentationType i segmentationName (lub segmentationId) (wymagane w przypadku konwersji rejestrowanych za pomocą tagów Floodlight, zalecane w przypadku wszystkich konwersji)
  • state (wymagane tylko wtedy, gdy chcesz zmienić stan na REMOVED lub ACTIVE)
  • quantityMillis (tylko wtedy, gdy określono w pierwotnej konwersji)
  • revenueMicros (tylko wtedy, gdy określono w pierwotnej konwersji)
  • currencyCode (tylko wtedy, gdy określono w pierwotnej konwersji)

Przykład

Oto przykład 2 istniejących konwersji:

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

To żądanie aktualizuje jedną z konwersji z poprzedniego przykładu i usuwa drugą:

JSON

Pamiętaj, że żądanie Conversion.update() używa metody 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())

Identyfikowanie konwersji według identyfikatora słowa kluczowego

Jeśli nie masz dostępu do identyfikatora kliknięcia lub konwersja została pierwotnie przypisana do słowa kluczowego lub słowa kluczowego i reklamy, możesz wysłać żądanie Conversion.update(), które zawiera te pola:

  • customerId, campaignId, adGroupId i criterionId (identyfikatory nowej wersji Search Ads 360, które identyfikują słowo kluczowe)
  • conversionId
  • conversionTimestamp
  • type
  • state (wymagane tylko wtedy, gdy chcesz zmienić stan na REMOVED lub ACTIVE)
  • quantityMillis (tylko wtedy, gdy określono w pierwotnej konwersji)
  • revenueMicros (tylko wtedy, gdy określono w pierwotnej konwersji)
  • currencyCode (tylko wtedy, gdy określono w pierwotnej konwersji)

Identyfikatory słów kluczowych są unikalne tylko w obrębie grupy reklam, więc musisz podać wszystkie 4 identyfikatory. Jeśli konwersja określa criterionId bez customerId, campaignId lub adGroupId, aktualizacja nie powiedzie się i zostanie wyświetlony kod błędu 0x0000012E. Nie musisz podawać innych identyfikatorów, np. identyfikatora reklamy, która doprowadziła do konwersji.

Przykład

Oto przykład utworzonej wcześniej konwersji:

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

To żądanie aktualizuje liczbę konwersji:

JSON

Pamiętaj, że żądanie Conversion.update() używa metody 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())

Obsługa odpowiedzi Search Ads 360

Odpowiedź na żądanie aktualizacji jest taka sama jak odpowiedź na żądanie wstawienia: Search Ads 360 wskazuje powodzenie tylko wtedy, gdy wszystkie konwersje w żądaniu zostały pomyślnie zaktualizowane.

Jeśli żądanie się powiedzie, odpowiedź będzie zawierać pełną wewnętrzną reprezentację nowej wersji Search Ads 360 dla każdej zaktualizowanej konwersji, np. nowy identyfikator klienta Search Ads 360, identyfikator kampanii, identyfikator grupy reklam i identyfikator słowa kluczowego (kryterium).

Jeśli nie uda się zweryfikować lub przesłać co najmniej 1 aktualizacji, odpowiedź będzie zawierać komunikaty o błędach dotyczące każdej nieudanej aktualizacji. Odpowiedź nie zawiera komunikatów o konwersjach, które zostały pomyślnie zaktualizowane. Więcej informacji o tych komunikatach o błędach znajdziesz w artykule Obsługa odpowiedzi Search Ads 360 dotyczących żądań wstawienia.