تعديل الإحالات الناجحة الحالية

استخدِم طريقة Conversion.update() للتغييرات التالية على إحالة ناجحة حالية واحدة أو أكثر:

لا تتيح "إعلانات شبكة البحث 360" تغيير ما يلي:

  • تاريخ الإحالة الناجحة
  • نوع الإحالة الناجحة
  • الكلمة الرئيسية أو الزيارة المنسوبة إلى الإحالة الناجحة
  • نشاط Floodlight أو اسم النشاط

مع ذلك، يمكنك دائمًا وضع علامة "تمّت إزالتها" على إحالة ناجحة حالية وتحميل إحالة ناجحة جديدة بالتاريخ أو النوع أو أرقام تعريف تحديد المصدر أو نشاط Floodlight المعدّل (احرص على تحديد conversionId جديد أيضًا).

كما هو الحال مع Conversion.insert()، إذا كان طلب التعديل يحدّد عدّة إحالات ناجحة، تحاول "إعلانات شبكة البحث 360" تعديل كل إحالة ناجحة على أساس أقصى جهد ممكن بدلاً من تعديل المجموعة بأكملها كعملية "كلّي أو لا شيء". إذا تعذّر إجراء بعض التعديلات في مجموعة، قد تنجح التعديلات الأخرى. ننصحك بقراءة الردّ لكل إحالة ناجحة تم تعديلها للتأكّد من نجاح التعديل.

(تم التعديل في 2025) إيقاف dsConversionId نهائيًا

يمكنك حاليًا استخدام dsConversionId أو conversionId لتحديد الإحالات الناجحة وتعديلها. سيتم إيقاف حقل dsConversionId نهائيًا في الربع الثالث من العام 2025. من الآن فصاعدًا، عليك استخدام conversionId لتعديل الإحالات الناجحة في Search Ads 360 Conversion API.

أهم التغييرات:

  • dsConversionId الإيقاف النهائي: لن يعود dsConversionID متاحًا في Search Ads 360 Reporting API (المعروفة باسم conversion.id) أو واجهة مستخدِم إعداد التقارير (المعروفة باسم "رقم تعريف الإحالة الناجحة").
  • conversionId المتطلّبات: conversionId سيصبح الحقل conversionId إلزاميًا لتعديل الإحالات الناجحة من خلال Search Ads Conversion API.

كيفية الحصول على conversionId:

  • Search Ads 360 Reporting API: يمكنك استرداد advertiser_conversion_id باستخدام Search Ads 360 Reporting API. تتوافق هذه القيمة مع conversionId المطلوبة للتعديل.
  • واجهة مستخدِم "إعلانات شبكة البحث 360": يمكنك العثور على "رقم تعريف الإحالة الناجحة للمعلِن" في صفحة إعداد تقارير الإحالات الناجحة ضمن واجهة مستخدِم "إعلانات شبكة البحث 360". رقم تعريف الإحالة الناجحة في تقارير "إعلانات شبكة البحث 360"

إرسال طلب تعديل

تُستخدَم معظم الحقول التي تحدّدها في Conversion.update() لتحديد الإحالات الناجحة التي تريد تعديلها. يمكنك استخدام أيٍّ من يلي من الأساليب لتحديد إحالة ناجحة حالية:

  • حدِّد clickId للإحالة الناجحة.
    • يجب أن تكون جميع الإحالات الناجحة التي تم تعديلها خلال 60 يومًا من وقت إنشاء معرّف النقرة.
  • حدِّد criterionId للإحالة الناجحة (رقم تعريف الكلمة الرئيسية).

تتطلّب كلتا الطريقتَين تحديد conversionId وconversionTimestamp وtype للمعاملة.

بالإضافة إلى ذلك، إذا حدّدت الإحالة الناجحة الأصلية revenueMicros وcurrencyCode أو quantityMillis، يجب أن يحدّد طلب التعديل هذه البيانات حتى إذا لم تكن بصدد تغييرها.

تحديد الإحالة الناجحة حسب معرّف النقرة

إذا حدّدت إحالة ناجحة في الأصل معرّف نقرة، يمكنك إرسال طلب Conversion.update() يحدّد الحقول التالية:

  • clickId
  • conversionId
  • conversionTimestamp
  • type
  • 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() يستخدم طريقة PUT لبروتوكول HTTP. 

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

تحديد الإحالة الناجحة حسب رقم تعريف الكلمة الرئيسية

إذا لم يكن لديك إذن الوصول إلى رقم تعريف النقرة، أو إذا كانت الإحالة الناجحة منسوبة في الأصل إلى كلمة رئيسية أو كلمة رئيسية/إعلان، يمكنك إرسال طلب Conversion.update() يحدد الحقول التالية:

  • criterionId (معرّف الكلمة الرئيسية)
  • conversionId
  • conversionTimestamp
  • type
  • state (يجب إدخال هذا الحقل فقط إذا أردت تغيير الحالة إلى "مُزالة" أو "نشط")
  • quantityMillis (فقط إذا تم تحديده في الإحالة الناجحة الأصلية)
  • revenueMicros (فقط إذا تم تحديده في الإحالة الناجحة الأصلية)
  • currencyCode (فقط إذا تم تحديده في الإحالة الناجحة الأصلية)

يمكنك اختياريًا تحديد أرقام تعريف أخرى، مثل رقم تعريف الإعلان للإحالة الناجحة ورقم تعريف الحملة، وما إلى ذلك، ولكن ليس عليك ذلك. لا تحتاج "إعلانات شبكة البحث 360" إلا إلى الأرقام التعريفية الواردة في القائمة أعلاه لتحديد إحالة ناجحة حالية.

مثال

في ما يلي مثال على إحالة ناجحة حالية: 

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

يعدّل الطلب التالي الطابع الزمني للإحالة الناجحة:

JSON

يُرجى العلم أنّ طلب Conversion.update() يستخدم طريقة PUT في HTTP. 

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

معالجة ردود "إعلانات شبكة البحث 360"

يكون الردّ على طلب التعديل مطابقًا للردّ على طلب الإدراج . لا تشير "إعلانات شبكة البحث 360" إلى النجاح إلا إذا تم تعديل جميع الإحالات الناجحة في الطلب بنجاح.

في حال نجاح الطلب، يتضمّن الردّ التمثيل الداخلي الكامل في "إعلانات شبكة البحث 360" لكل إحالة ناجحة معدّلة، مثل رقم تعريف الحملة ورقم تعريف المجموعة الإعلانية ورقم تعريف الكلمة الرئيسية (المعيار).

إذا تعذّر التحقّق من تعديل واحد أو أكثر أو تحميله، يتضمّن الردّ رسائل تتعلّق بالخطأ لكل تعديل تعذّر تحميله. لا يحتوي الردّ على رسائل عن الإحالات الناجحة التي تم تعديلها بنجاح. لمزيد من المعلومات عن رسائل الخطأ هذه، اطّلِع على مقالة معالجة ردود "إعلانات شبكة البحث 360" لطلبات الإدراج.