اصلاح تبدیل‌های موجود

روش Conversion.update() را فراخوانی کنید تا انواع تغییرات زیر را در یک یا چند تبدیل موجود اعمال کنید:

‫Search Ads 360 از تغییر موارد زیر پشتیبانی نمی‌کند:

  • تاریخ تبدیل.
  • نوع تبدیل.
  • کلیدواژه یا بازدیدی که به تبدیل نسبت داده می‌شود.
  • فعالیت Floodlight یا نام فعالیت.

بااین‌حال، همیشه می‌توانید تبدیل موجودی را به‌عنوان «برداشته‌شده» علامت‌گذاری کنید و تبدیل جدیدی را با تاریخ، نوع، شناسه‌های اسنادی، یا فعالیت Floodlight به‌روزشده بارگذاری کنید (حتماً conversionId جدیدی را نیز مشخص کنید).

می‌توانید هم تبدیل‌هایی را که ازطریق Search Ads 360 API بارگذاری شده‌اند (تبدیل‌های آفلاین) و هم تبدیل‌هایی را که Search Ads 360 ازطریق برچسب‌های Floodlight ضبط کرده است (تبدیل‌های آنلاین) ویرایش کنید، مشروط به محدودیت‌های زمانی زیر:

  • اگر تبدیل را با clickId شناسایی کنید، شناسه کلیک باید در ۶۰ روز گذشته تولید شده باشد (درغیراین‌صورت کد خطا 0x0000012F است).
  • تبدیل‌های ثبت‌شده ازطریق برچسب‌های Floodlight فقط درطول ۲۸ روز از conversionTimestamp قابل‌ویرایش هستند (درغیراین‌صورت کد خطای 0x00000125 نشان داده می‌شود).

همانند Conversion.insert()، اگر درخواست به‌روزرسانی شما چندین تبدیل را مشخص کند، Search Ads 360 تلاش می‌کند هر تبدیل را براساس بهترین تلاش به‌روزرسانی کند، به‌جای اینکه کل دسته را به‌عنوان یک تراکنش همه‌یاهیچ به‌روزرسانی کند. اگر برخی‌از به‌روزرسانی‌ها در یک دسته ناموفق باشد، ممکن است بقیه همچنان موفقیت‌آمیز باشد. توصیه می‌کنیم برای هر تبدیل به‌روزشده، پاسخ را بخوانید تا مطمئن شوید به‌روزرسانی موفقیت‌آمیز بوده است.

منسوخ شدن dsConversionId

فیلد dsConversionId منسوخ شده است و دیگر نمی‌توان از آن برای شناسایی تبدیل‌ها استفاده کرد. برای ویرایش تبدیل‌ها در Search Ads 360 Conversion API، باید از conversionId (شناسه تبدیل آگهی‌دهنده) استفاده کنید. Conversion.update() تبدیل با کد خطای 0x0000013C (Conversion editing using integer DS conversion ID is deprecated) را رد می‌کند اگر تبدیل:

  • فیلد dsConversionId را مشخص می‌کند، یا
  • شناسه تبدیل Search Ads 360 (شناسه عددی ۱۷ رقمی که Search Ads 360 برای هر تبدیل تولید می‌کند) را در فیلد conversionId ارسال می‌کند.

تغییرات کلیدی:

  • dsConversionId منسوخ شدن: dsConversionID دیگر در Search Ads 360 Conversion API،‏ Search Ads 360 Reporting API (که به‌عنوان conversion.id به آن اشاره می‌شود)، یا میانای کاربر گزارش‌دهی (که به‌عنوان «شناسه تبدیل» به آن اشاره می‌شود) پشتیبانی نمی‌شود.
  • conversionId الزام: conversionId فیلدی اجباری برای ویرایش تبدیل‌ها ازطریق Search Ads 360 Conversion API است.

نحوه دریافت conversionId:

  • تبدیل‌های بارگذاری‌شده ازطریق Search Ads 360 API: از conversionId که هنگام درج تبدیل مشخص کرده‌اید استفاده کنید.
  • تبدیل‌های ثبت‌شده ازطریق برچسب‌های Floodlight: از شناسه سفارش Floodlight (مقدار ord) که برچسب Floodlight برای تبدیل گزارش کرده است استفاده کنید، برای مثال شناسه سفارش یا تراکنش فعالیت فروش Floodlight.
  • Search Ads 360 Reporting API: می‌توانید advertiser_conversion_id را بااستفاده از Search Ads 360 Reporting API بازیابی کنید. این مقدار با conversionId موردنیاز برای ویرایش مطابقت دارد.
  • میانای کاربر Search Ads 360: می‌توانید «شناسه تبدیل آگهی‌دهنده» را در صفحه گزارش‌دهی تبدیل در میانای کاربر Search Ads 360 پیدا کنید. شناسه تبدیل در گزارش‌های SA360

ارسال درخواست به‌روزرسانی

بیشتر فیلدهایی که در Conversion.update() مشخص می‌کنید برای شناسایی تبدیل‌هایی که می‌خواهید به‌روز کنید استفاده می‌شوند. می‌توانید از هریک از روش‌های زیر برای شناسایی تبدیل موجود استفاده کنید:

  • clickId تبدیل را مشخص کنید
    • همه تبدیل‌های ویرایش‌شده باید ظرف ۶۰ روز از زمان تولید شناسه کلیک باشند.
  • کلیدواژه تبدیل را مشخص کنید (customerId، campaignId، adGroupId، و criterionId)

هر دو روش مستلزم این است که conversionId، conversionTimestamp، و type تراکنش تبدیل را مشخص کنید. conversionTimestamp باید مُهر زمان تبدیل موجود، در میلی‌ثانیه Epoch UTC باشد. اگر مُهر زمان با تبدیل موجود مطابقت نداشته باشد (برای مثال، چون از منطقه زمانی محلی تبدیل شده است)، Search Ads 360 نمی‌تواند تبدیل را پیدا کند و کد خطای 0x0000011B را برمی‌گرداند.

برای تبدیل‌هایی که Search Ads 360 ازطریق برچسب‌های Floodlight ثبت کرده است، باید فعالیت Floodlight تبدیل را نیز مشخص کنید (segmentationType و segmentationName یا segmentationId). درغیراین‌صورت، درخواست با کد خطای 0x0000010C ناموفق خواهد بود. توصیه می‌کنیم که فعالیت Floodlight را در هر درخواست به‌روزرسانی مشخص کنید.

علاوه‌براین، اگر تبدیل اصلی revenueMicros و currencyCode یا quantityMillis را مشخص کرده باشد، درخواست به‌روزرسانی باید این داده‌ها را مشخص کند، حتی اگر آن‌ها را تغییر ندهید.

شناسایی تبدیل با شناسه کلیک

اگر تبدیلی در ابتدا شناسه کلیک را مشخص کرده باشد، می‌توانید Conversion.update() درخواستی ارسال کنید که فیلدهای زیر را مشخص کند:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • segmentationType و segmentationName (یا segmentationId) (برای تبدیل‌های ثبت‌شده ازطریق برچسب‌های Floodlight الزامی است، برای همه تبدیل‌ها توصیه می‌شود)
  • state (فقط اگر می‌خواهید وضعیت را به «برداشته‌شده» یا «فعال» تغییر دهید الزامی است)
  • quantityMillis (فقط اگر در تبدیل اصلی مشخص شده باشد)
  • revenueMicros (فقط اگر در تبدیل اصلی مشخص شده باشد)
  • currencyCode (فقط اگر در تبدیل اصلی مشخص شده باشد)

مثال

در اینجا مثالی از دو تبدیل موجود آورده شده است:

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

درخواست زیر یکی از تبدیل‌های مثال قبلی را به‌روزرسانی می‌کند و دیگری را برمی‌دارد:

(قالب) JSON

توجه داشته باشید که درخواست Conversion.update() از روش 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"
  }
 ]
}        

جاوا

/**
 * 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())

شناسایی تبدیل براساس شناسه کلیدواژه

اگر به شناسه کلیک دسترسی ندارید، یا اگر تبدیلی در ابتدا به کلیدواژه یا کلیدواژه/آگهی نسبت داده شده است، می‌توانید درخواست Conversion.update() ارسال کنید که فیلدهای زیر را مشخص می‌کند:

  • customerId، campaignId، adGroupId، و criterionId (شناسه‌های Search Ads 360 جدید که کلیدواژه را شناسایی می‌کنند)
  • conversionId
  • conversionTimestamp
  • type
  • state (فقط اگر می‌خواهید وضعیت را به «برداشته‌شده» یا «فعال» تغییر دهید الزامی است)
  • quantityMillis (فقط اگر در تبدیل اصلی مشخص شده باشد)
  • revenueMicros (فقط اگر در تبدیل اصلی مشخص شده باشد)
  • currencyCode (فقط اگر در تبدیل اصلی مشخص شده باشد)

شناسه‌های کلیدواژه فقط در یک گروه آگهی یکتا هستند، بنابراین باید هر چهار شناسه را مشخص کنید. اگر تبدیلی criterionId را بدون customerId، campaignId، یا adGroupId مشخص کند، به‌روزرسانی با کد خطای 0x0000012E ناموفق می‌شود. لازم نیست شناسه‌های دیگر، مثل شناسه آگهی تبدیل را مشخص کنید.

مثال

در اینجا مثالی از تبدیل موجود آورده شده است:

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

درخواست زیر مقدار تبدیل را به‌روز می‌کند:

(قالب) JSON

توجه داشته باشید که درخواست Conversion.update() از روش 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"
  }
 ]
}        

جاوا

    // 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())

مدیریت پاسخ‌های Search Ads 360

پاسخ درخواست به‌روزرسانی همانند پاسخ درخواست درج است: Search Ads 360 تنها درصورتی موفقیت را نشان می‌دهد که همه تبدیل‌های موجود در درخواست باموفقیت به‌روز شده باشند.

اگر درخواست موفقیت‌آمیز باشد، پاسخ شامل نمایش داخلی کامل Search Ads 360 برای هر تبدیل به‌روزشده است، مانند شناسه مشتری جدید Search Ads 360، شناسه کمپین، شناسه گروه آگهی، و شناسه کلیدواژه (معیار).

اگر یک یا چند به‌روزرسانی اعتبارسنجی یا بارگذاری نشود، پاسخ شامل پیام‌های ناموفق برای هر به‌روزرسانی ناموفق است. پاسخ حاوی پیام‌هایی درباره تبدیل‌هایی که باموفقیت به‌روز شده‌اند نیست. برای اطلاعات بیشتر درباره این پیام‌های خطا، به رسیدگی به پاسخ‌های Search Ads 360 برای درخواست‌های درج مراجعه کنید.