إضافة إحالات ناجحة جديدة

متى يمكنني استخدام البيانات المحمَّلة؟

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

حوِّل جميع الطوابع الزمنية للإحالات الناجحة إلى وقت الحقبة (المعروف أيضًا باسم وقت Unix).

هل يمكنني إنشاء أنشطة Floodlight من واجهة برمجة التطبيقات؟

إذا لم ينشئ المعلِن نشاطًا على Floodlight لتتبُّع الإحالات الناجحة بلا إنترنت، يمكنك استخدام واجهة برمجة التطبيقات Campaign Manager API لإنشاء نشاط. لا يمكنك استخدام واجهة برمجة التطبيقات لتحديد أنّ نشاط Floodlight يُستخدَم بشكل أساسي للإحالات الناجحة بلا إنترنت، وهو من أفضل الممارسات عندما تستخدِم استراتيجيات عروض الأسعار بيانات من الإحالة الناجحة.

ننصحك بعد استخدام واجهة برمجة التطبيقات لإنشاء نشاط Floodlight، بأن يسجّل مستخدم "إعلانات شبكة البحث 360" الدخول إلى "إعلانات شبكة البحث 360" ويغيّر إعدادات النشاط للإشارة إلى أنّ المصدر الأساسي للإحالات الناجحة هو النشاط بلا إنترنت.

أفضل الممارسات لإضافة الإحالات الناجحة

ننصحك باتّباع أفضل الممارسات التالية لإضافة الإحالات الناجحة:

1. اطلب من أحد مستخدمي "إعلانات شبكة البحث 360" تسجيل الدخول إلى "إعلانات شبكة البحث 360" وتغيير الإعدادات لكلّ نشاط من أنشطة Floodlight التي تستخدمها للإبلاغ عن الإحالات الناجحة بلا إنترنت. يجب أن تشير الإعدادات إلى أنّ المصدر الأساسي للإحالات الناجحة هو النشاط بلا إنترنت. اطّلِع على مركز مساعدة "إعلانات شبكة البحث 360" للحصول على التعليمات.

2. حمِّل الإحالات الناجحة فور توفّرها. إذا كنت تُنسِب الإحالات الناجحة إلى زيارات معيّنة، انتظِر 6 ساعات على الأقل بعد الزيارة قبل تحميل الإحالة الناجحة. قد لا تتعرّف "إعلانات شبكة البحث 360" على معرّف النقرة للزيارة في حال تحميله قبل مرور 6 ساعات على الزيارة. في حالات نادرة، قد تحتاج إلى الانتظار لمدة تصل إلى 24 ساعة قبل أن تتمكّن "إعلانات شبكة البحث 360" من التعرّف على clickId.

   تأكَّد من أنّ كل عملية تحميل تحتوي على أحدث الإحالات الناجحة. ضمن طلب تحميل واحد، لا بأس إذا كانت الإدخالات خارج الترتيب الزمني. ولكن قد لا تتمكّن استراتيجية عروض الأسعار من أخذ الإحالات الناجحة القديمة التي تحمّلها لاحقًا في طلب مختلف في الاعتبار.

إرسال طلب إدراج

يمكنك إرسال طلب Conversion.insert() لتنفيذ أيٍّ ممّا يلي:

• إسناد إحالة ناجحة إلى زيارة معيّنة
• إسناد إحالة ناجحة إلى كلمة رئيسية فقط

تعتمد الحقول المطلوبة في طلب Conversion.insert() على الحدث أو السلعة التي تُنسِب إليها الإحالة الناجحة. تسرد الأقسام التالية الحقول المطلوبة والاختيارية لكلّ حدث أو عنصر يمكنك إسناد إحالة ناجحة إليه.

إسناد إحالة ناجحة إلى زيارة معيّنة

عندما ينقر عميل على إعلان واحد أو أكثر وينتقل إلى موقع المعلِن الإلكتروني، تُعتبر جلسة المستخدِم على موقع المعلِن الإلكتروني زيارة في "إعلانات شبكة البحث 360". لتحديد مصدر إحالة ناجحة لزيارة، حدِّد ما يلي في طلب Conversion.insert():

حقول مطلوبة

• clickId: معرّف النقرة الحسّاس لحالة الأحرف للزيارة. ابحث في سجلّات الويب للمعلِن عن معرّف النقرة أو قائمة الإحالات الناجحة واستخدِم معرّف نقرة من إحالة ناجحة أخرى. ستحدد "إعلانات شبكة البحث 360" مصدر الإحالة الناجحة على أنّه الكلمة الرئيسية والإعلان والعناصر الأخرى في "إعلانات شبكة البحث 360" التي كانت مسؤولة عن إنشاء الزيارة.
  انتظِر لمدة 6 ساعات على الأقل بعد أن تنشئ "إعلانات شبكة البحث 360" معرّف نقرة لتحميل الإحالات الناجحة. إذا ظهرت لك رسالة الخطأ "لم يتم العثور على معرّف النقرة"، انتظِر لمدة 24 ساعة، ثم حمِّل الإحالات الناجحة مرة أخرى. يجب تحميل جميع الإحالات الناجحة خلال 90 يومًا من إنشاء معرّف النقرة. بخلاف ذلك، قد لا تتعرّف Search Ads 360 API على الزيارة.
• conversionId: بالنسبة إلى الإحالات الناجحة بلا إنترنت، يقدّم المعلِنون هذا المعرّف. يمكن للمعلِنين تحديد أي معرّف يهمّهم. يجب أن تحدِّد كل إحالة ناجحة في الطلب رقم تعريف فريدًا، ويجب أن يكون الجمع بين رقم التعريف والطابع الزمني فريدًا بين جميع الإحالات الناجحة للمعلِن. بالنسبة إلى الإحالات الناجحة على الإنترنت، تنسخ "إعلانات شبكة البحث 360" dsConversionId أو floodlightOrderId إلى هذا الموقع استنادًا إلى تعليمات Floodlight للمعلِن.
• conversionTimestamp: يشير إلى تاريخ ووقت حدوث الإحالة الناجحة. على سبيل المثال، إذا حدثت الإحالة الناجحة يوم الجمعة 5 آب (أغسطس) 2016 الساعة 11:53:22 صباحًا بالتوقيت الصيفي الشرقي (غرينتش -4:00)، حدِّد الطابع الزمني بالمللي ثانية من Epoch: 1470412402000.
• segmentationType: لتحديد نوع نظام الإحالات الناجحة الذي يتم تحميل الإحالة الناجحة إليه. لا تتوفّر حاليًا سوى الإحالات الناجحة في Floodlight، لذا يكون هذا الحقل مطلوبًا دائمًا لتحديد FLOODLIGHT.
• segmentationName: اسم نشاط Floodlight الذي يستخدمه المعلِن للإبلاغ عن الإحالة الناجحة.

  إذا كان المعلِن يتضمّن أنشطة تحمل الاسم نفسه (يمكن أن يحدث ذلك إذا كانت الأنشطة تنتمي إلى مجموعات Floodlight مختلفة)، فإنّ الإجراء المقترَح هو إعادة تسمية أحد الأنشطة.

  بدلاً من ذلك، إذا كنت تعرف رقم التعريف الذي حدّدته "إعلانات شبكة البحث 360" لنشاط Floodlight، يمكنك تحديد رقم التعريف في الحقل segmentationId بدلاً من تحديد الاسم في الحقل segmentationName. (يحدّد "مدير الحملة 360" أيضًا رقم تعريف لنشاط Floodlight، ولكن يختلف رقم تعريف "مدير الحملة 360" عن رقم تعريف "إعلانات شبكة البحث 360" ولا يمكن استخدامه لتحديد مصدر الإحالات الناجحة). للاطّلاع على رقم تعريف "إعلانات شبكة البحث 360" لنشاط Floodlight، نزِّل تقرير الإحالات الناجحة (إما من واجهة مستخدم إعلانات شبكة البحث 360 أو reporting API). إذا تمّ تحديد مصدر إحالة ناجحة واحدة على الأقلّ لنشاط Floodlight خلال الإطار الزمني للتقرير، سيظهر لك رقم تعريف "إعلانات شبكة البحث 360" في التقرير.

• type: نوع الإحالة الناجحة، أي ACTION أو TRANSACTION. لا تتضمّن الإحالة الناجحة من النوع "إجراء" أي قيمة مالية، في حين تتضمّن الإحالة الناجحة من النوع "معاملة" قيمة مالية. وتشمل الأمثلة عمليات الاشتراك في قوائم البريد الإلكتروني (الإجراء) مقارنةً بعمليات شراء التجارة الإلكترونية (المعاملة).

  في حال تحديد TRANSACTION، عليك أيضًا تحديد الحقل التالي:

  • revenueMicros: القيمة النقدية للإحالة الناجحة.

الحقول الاختيارية

• quantityMillis: عدد السلع في هذه الإحالة الناجحة على سبيل المثال، عدد الأشخاص الذين اشتركوا في نشرة إخبارية عبر البريد الإلكتروني أو إجمالي كمية السلع المُباعة. إذا لم تحدّد هذا الحقل للإحالات الناجحة من النوع "إجراء"، ستُدرج "إعلانات شبكة البحث 360" تلقائيًا قيمة 1000 لملفه الشخصي.
• ‫currencyCode: عملة أرباح المعاملة. وافتراضيًا، يُفترض أن تكون الأرباح بالعملة التي يستخدمها المعلِن. في حال تحديد عملة مختلفة، تحوِّل "إعلانات شبكة البحث 360" مبلغ الأرباح المحدّد إلى عملة المعلِن. مزيد من المعلومات
  استخدِم التنسيق الأبجدي (3 أحرف) وفقًا لمعيار ISO 4217 لتحديد العملة.
  لا ينطبق ذلك إلّا على الإحالات الناجحة للمعاملات.
• ‫customMetric وcustomDimension: لتحميل بيانات إضافية عن الإحالة الناجحة، مثل البلد الذي يتم شحن سلعة تم شراؤها إليه أو أرقام تعريف المنتجات أو حتى مدة مكالمة هاتفية اطّلِع على مزيد من المعلومات عن تحميل بيانات المتغيّرات المخصّصة في Floodlight.
• ‫deviceType: لتحديد نوع الجهاز الذي حدثت عليه الإحالة الناجحة اطّلِع على قائمة القيم المقبولة لهذا الحقل.

POST  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 a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue
    "currencyCode": "USD"
  }]
}
          

  /**
   * Instantiate the Doubleclicksearch service, create conversions, and upload them.
   */
  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>();

    // Add a conversion to the List.
    addTransactionConversionForVisit(conversions, "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
        "test_" + System.currentTimeMillis(), 10000000L, 1378710000000L);

    // Upload the List and handle the response.
    uploadConversions(conversions, service);
  }


  /**
   * Create a TRANSACTION conversion and add it to a List<Conversion>. This sample hard-codes
   * the segmentation name and currency. You probably wouldn't want your production code to be so brittle.
   */
  private static List<Conversion> addTransactionConversionForVisit(List<Conversion> conversions,
      String clickId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion().setClickId(clickId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }


  /**
   * Convert the List of conversions to a DS ConversionList, send an insert request to DS,
   * and output the response to a file.
   */
  private static void uploadConversions(List<Conversion> conversions, Doubleclicksearch service)
      throws IOException {

    FileOutputStream outputStream =
        new FileOutputStream(new File("./", "InsertConversionsResponse.txt"));
    final PrintStream printStream = new PrintStream(outputStream);

    try {
      // Convert the List to a ConversionList.
      ConversionList conversionList = new ConversionList().setConversion(conversions);

      // Insert an upload request and download the response to a file.
      service.conversion().insert(conversionList).executeAndDownloadTo(printStream);
      printStream.close();
    } catch (GoogleJsonResponseException e) {
      System.err.println("Get request was rejected.");
      for (ErrorInfo error : e.getDetails().getErrors()) {
        System.err.println(error.getMessage());
      }
      System.exit(e.getStatusCode());
    }
  }
            

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a visit.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with a click ID from your site
              'conversionId': 'test_20140206_00',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '10000000', // 10 million revenueMicros is equivalent to $10 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

إسناد إحالة ناجحة إلى كلمة رئيسية فقط

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

حقول مطلوبة

• ‫criterionId: هذا هو معرّف الكلمة الرئيسية. يمكنك الحصول على criterionId عن طريق إضافة وحدة الماكرو TrackerId إلى عناوين URL للصفحات المقصودة. للحصول على معلومات عن الحصول على أرقام تعريف الكلمات الرئيسية، اطّلِع على مقالة أرقام التعريف في "إعلانات شبكة البحث 360" و الإحالات الناجحة.
• conversionId: بالنسبة إلى الإحالات الناجحة بلا إنترنت، يقدّم المعلِنون هذا المعرّف. يمكن للمعلِنين تحديد أيّ معرّف يهمّهم. يجب أن تحدِّد كل إحالة ناجحة في الطلب رقم تعريف فريدًا، ويجب أن يكون الجمع بين رقم التعريف والطابع الزمني فريدًا بين جميع الإحالات الناجحة للمعلِن. بالنسبة إلى الإحالات الناجحة على الإنترنت، تنسخ "إعلانات شبكة البحث 360" dsConversionId أو floodlightOrderId إلى هذا الموقع استنادًا إلى تعليمات Floodlight للمعلِن.
• conversionTimestamp: يشير إلى تاريخ ووقت حدوث الإحالة الناجحة. على سبيل المثال، إذا حدثت الإحالة الناجحة يوم الجمعة 5 آب (أغسطس) 2016 الساعة 11:53:22 صباحًا بالتوقيت الصيفي الشرقي (غرينتش -4:00)، حدِّد الطابع الزمني بالمللي ثانية من Epoch: 1470412402000.
• segmentationType: لتحديد نوع نظام الإحالات الناجحة الذي يتم تحميل الإحالة الناجحة إليه. لا تتوفّر حاليًا سوى الإحالات الناجحة في Floodlight، لذا يكون هذا الحقل مطلوبًا دائمًا لتحديد FLOODLIGHT.
• segmentationName: اسم نشاط Floodlight الذي يستخدمه المعلِن للإبلاغ عن الإحالة الناجحة.

  إذا كان المعلِن يتضمّن أنشطة تحمل الاسم نفسه (يمكن أن يحدث ذلك إذا كانت الأنشطة تنتمي إلى مجموعات Floodlight مختلفة)، فإنّ الإجراء المقترَح هو إعادة تسمية أحد الأنشطة.

  بدلاً من ذلك، إذا كنت تعرف رقم التعريف الذي حدّدته "إعلانات شبكة البحث 360" لنشاط Floodlight، يمكنك تحديد رقم التعريف في الحقل segmentationId بدلاً من تحديد الاسم في الحقل segmentationName. (يحدّد "مدير الحملة 360" أيضًا رقم تعريف لنشاط Floodlight، ولكن يختلف رقم تعريف "مدير الحملة 360" عن رقم تعريف "إعلانات شبكة البحث 360" ولا يمكن استخدامه لتحديد مصدر الإحالات الناجحة). للاطّلاع على رقم تعريف "إعلانات شبكة البحث 360" لنشاط Floodlight، نزِّل تقرير الإحالات الناجحة (إما من واجهة مستخدم "إعلانات شبكة البحث 360" أو reporting API). إذا تمّ تحديد مصدر إحالة ناجحة واحدة على الأقلّ لنشاط Floodlight خلال الإطار الزمني للتقرير، سيظهر لك رقم تعريف "إعلانات شبكة البحث 360" في التقرير.

• type: نوع الإحالة الناجحة، أي ACTION أو TRANSACTION. لا تتضمّن الإحالة الناجحة من النوع "إجراء" أي قيمة مالية، في حين تتضمّن الإحالة الناجحة من النوع "معاملة" قيمة مالية. وتشمل الأمثلة عمليات الاشتراك في قوائم البريد الإلكتروني (الإجراء) مقارنةً بعمليات شراء التجارة الإلكترونية (المعاملة).

  في حال تحديد TRANSACTION، عليك أيضًا تحديد الحقل التالي:

  • revenueMicros: القيمة النقدية للإحالة الناجحة.

الحقول الاختيارية

• quantityMillis: عدد السلع في هذه الإحالة الناجحة على سبيل المثال، عدد الأشخاص الذين اشتركوا في نشرة إخبارية عبر البريد الإلكتروني أو إجمالي كمية السلع المُباعة. إذا لم تحدّد هذا الحقل للإحالات الناجحة من النوع "إجراء"، ستُدرج "إعلانات شبكة البحث 360" تلقائيًا قيمة 1000 لملفه الشخصي.
• ‫currencyCode: عملة أرباح المعاملة. وافتراضيًا، يُفترض أن تكون الأرباح بالعملة التي يستخدمها المعلِن. في حال تحديد عملة مختلفة، تحوِّل "إعلانات شبكة البحث 360" مبلغ الأرباح المحدّد إلى عملة المعلِن. مزيد من المعلومات
  استخدِم التنسيق الأبجدي (3 أحرف) وفقًا لمعيار ISO 4217 لتحديد العملة.
  لا ينطبق هذا المقياس إلّا على الإحالات الناجحة للمعاملات.
• ‫customMetric وcustomDimension: لتحميل بيانات إضافية عن الإحالة الناجحة، مثل البلد الذي يتم شحن سلعة تم شراؤها إليه أو أرقام تعريف المنتجات أو حتى مدة مكالمة هاتفية اطّلِع على مزيد من المعلومات عن تحميل بيانات المتغيّرات المخصّصة في Floodlight.
• ‫deviceType: لتحديد نوع الجهاز الذي حدثت عليه الإحالة الناجحة اطّلِع على قائمة القيم المقبولة لهذا الحقل.

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "criterionId": "43700003491981017", // Replace with your ID
    "conversionId": "customerTransaction73126",
    "conversionTimestamp": "1351196386000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "Offline Purchase",
    "type": "TRANSACTION",
    "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue
    "currencyCode": "USD"
  }]
}

  /**
   * Creates a TRANSACTION conversion, attributes it to a keyword only, and adds it to a List<Conversion>.
   * The example in the preceding section contains the uploadConversions method,
   * which can submit the list as an insert() request.
   */
  private static List<Conversion> addTransactionConversionForKeyword(List<Conversion> conversions,
      Long criterionId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion()
        .setCriterionId(criterionId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }        

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a keyword only.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'criterionId': '43700004289911004', // Replace with your ID
              'conversionId': 'test_1378710000000',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '20000000', // 20 million revenueMicros is equivalent to $20 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

مثال

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "PP5K8iI6ul7Vw09JZZDEp", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "attributionModel": "External Attribution Model",
    "countMillis": "330",
    "revenueMicros": "33000000", // 33 million revenueMicros is equivalent to $33 of revenue
    "currencyCode": "USD"
  }]
}
          

أخطاء requestValidation

تشير أخطاء requestValidation إلى مشاكل في البيانات في طلب تحميل الإحالة الناجحة (على سبيل المثال، سبق أن تم تحميل الإحالة الناجحة أو لم يتم العثور على clickId). في هذا النوع من الأخطاء، تحتوي تفاصيل الرسالة على عنصرَين:

• رمز سداسي عشري يحدِّد نوع الخطأ يمكنك استخدام الرمز في ملفاتك النصية لتحديد الأخطاء.
• وصف لخطأ التحقّق

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

أنواع أخرى من الأخطاء

تشير جميع الأنواع الأخرى من الأخطاء (internalError أو transactionFailed أو lateStageRequestError) إلى حدوث مشكلة داخلية في "إعلانات شبكة البحث 360".

الردّ على خطأ

إذا تعذّر إرسال الطلب، حاوِل إعادة إرسال طلب المكالمة بالكامل لاحقًا. ستُبلغ "إعلانات شبكة البحث 360" عن أخطاء requestValidation لأيّ إحالات ناجحة سبق أن تمّ تحميلها، ولكنّها ستحاول تحميل الإحالات الناجحة المتبقية.

إذا استمر ظهور أخطاء بعد إعادة الإرسال، اطّلِع على قسم تحديد المشاكل وحلّها للحصول على معلومات حول كيفية المتابعة.