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

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

يمكن العثور على معلومات عن القيود المفروضة على تحميل الإحالات الناجحة السابقة في مركز مساعدة "إعلانات شبكة البحث 360".

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

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

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

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

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

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

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

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

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

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

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

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

  3. في حال الانتظار أكثر من 24 ساعة قبل تحميل الإحالات الناجحة لنشاط Floodlight، يمكنك إرسال طابع زمني لمدى التوفّر.

    يجب أن يكون الطابع الزمني لمدى التوفّر واحدًا مما يلي:

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

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

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

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

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

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

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

حقول مطلوبة

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

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

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

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

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

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

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

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

JSON

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

Java

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

Python

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 صباحًا بالتوقيت الصيفي الشرقي (GMT -4:00)، حدِّد الطابع الزمني بالملي ثانية من الحقبة: 1470412402000.
  • segmentationType: تحدّد نوع نظام الإحالات الناجحة الذي تريد تحميل الإحالة الناجحة إليه. في الوقت الحالي، يمكن فقط استخدام الإحالات الناجحة في Floodlight، لذا يكون هذا الحقل مطلوبًا دائمًا لتحديد FLOODLIGHT.
  • segmentationName: اسم نشاط Floodlight الذي يستخدمه المعلِن لتسجيل الإحالة الناجحة.

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

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

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

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

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

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

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

JSON

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

Java

  /**
   * 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;
  }

Python


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

تحميل البيانات من نموذج تحديد مصدر تابع لجهة خارجية

يوزِّع نموذج تحديد المصدر نسبة المساهمة في الإحالة الناجحة على مستوى كل النشاط في مسار الإحالة الناجحة. على سبيل المثال، إذا نقر مستهلك على إعلان يظهر على نتائج البحث المدفوعة وإعلان صوري وإعلان آخر من نتائج البحث المدفوعة قبل إجراء الإحالة الناجحة، سيمنح نموذج تحديد المصدر الخطي لكل نقرة نسبة 33% من نسبة المساهمة في الإحالة الناجحة.

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

قبل البدء

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

حقول مطلوبة

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

  • clickId: رقم تعريف النقرة الحسّاس لحالة الأحرف المتعلّق بالزيارة. ابحث في سجلّات الويب الخاصة بالمعلِن عن معرّف النقرة أو إدراج الإحالات الناجحة واستخدِم معرّف نقرة من إحالة ناجحة أخرى. ستنسِب "إعلانات شبكة البحث 360" الإحالة الناجحة إلى الكلمة الرئيسية والإعلان وغيرهما من عناصر "إعلانات شبكة البحث 360" التي كانت مسؤولة عن إنشاء الزيارة.
    انتظِر لمدة 30 دقيقة على الأقل بعد أن تنشئ "إعلانات شبكة البحث 360" معرّف نقرة قبل تحميل إحالة ناجحة تحتوي على رقم التعريف. وإلا، قد لا تتمكّن واجهة Search Ads 360 API من التعرّف على الزيارة.
  • attributionModel: تم الضبط على نموذج تحديد المصدر الخارجي. مزيد من المعلومات
  • countMillis: مبلغ نسبة المساهمة في الإحالة الناجحة المطلوب توزيعه على هذه النقرة لا ينطبق هذا الإجراء إلا إذا كان الطلب يتضمّن أيضًا الحقل attributionModel.

    لا تخلط بين هذا الحقل والحقل quantityMillis، وهو حقل اختياري يحدّد عدد السلع في الإحالة الناجحة (مثل عدد السلع في عملية شراء داخل سلة التسوّق).

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

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

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

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

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

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

إذا كنت تتتبّع أرباح الإحالة الناجحة، احرص على أن يوزّع النموذج الأرباح على كل نقطة اتصال في مسار الإحالة الناجحة.على سبيل المثال، إذا كان نموذجك يستخدم منهجًا خطيًا (توزيع الأرباح بالتساوي على كل نقطة اتصال)، في مسار إحالة ناجحة يتضمّن 3 نقرات على الإعلان، ستُنسب كل نقرة إلى 33% من الإحالة الناجحة. إذا حقّقت الإحالة الناجحة أرباحًا بقيمة 100 دولار أمريكي (أو ما يعادلها بالعملة المحلّية)، احرص على أن يوزّع النموذج أرباحًا بقيمة 33 دولارًا أمريكيًا (أو ما يعادلها بالعملة المحلّية) على كلّ نقرة، بالإضافة إلى التأكّد من أنّ revenueMicros يحدِّد سوى 33 دولارًا أمريكيًا (أو ما يعادلها بالعملة المحلّية) من الأرباح لكلّ نقرة.

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

  • quantityMillis: عدد العناصر في هذه الإحالة الناجحة على سبيل المثال، عدد المستخدمين الذين اشتركوا في نشرة إخبارية عبر البريد الإلكتروني أو العدد الإجمالي للسلع المباعة. في حال عدم تحديد هذا الحقل لإحالات ناجحة ACTION، تُدرج "إعلانات شبكة البحث 360" تلقائيًا القيمة 1000.
  • currencyCode: عملة أرباح المعاملة ووفقًا للإعدادات التلقائية، تكون الأرباح بعملة المعلِن. في حال تحديد عملة مختلفة، ستحوِّل "إعلانات شبكة البحث 360" مبلغ الأرباح المحدّد إلى عملة المعلِن. مزيد من المعلومات
    يُرجى استخدام تنسيق ISO 4217 الأبجدي (3 أحرف) لتحديد العملة.
    لا يسري إلا على الإحالات الناجحة التي تحقّق TRANSACTION.
  • 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" : "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"
  }]
}

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

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

في حال نجح الطلب

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

{
 "kind": "doubleclicksearch#conversionList",
 "conversion": [
  {
   "agencyId": "12300000000000456",
   "advertiserId": "45600000000010291",
   "engineAccountId": "700000000042441",
   "campaignId": "71700000002044839",
   "adGroupId": "58700000032026064",
   "criterionId": "43700004289911004",
   "adId": "0",
   "dsConversionId": "48719131694768384",
   "conversionId": "test_1383157331951",
   "state": "ACTIVE",
   "type": "TRANSACTION",
   "revenueMicros": "20000000",
   "currencyCode": "USD",
   "segmentationType": "FLOODLIGHT",
   "segmentationId": "25700000001464141",
   "segmentationName": "Test",
   "conversionTimestamp": "1378710000000",
   "conversionModifiedTimestamp": "1383157332368"
  },
  ...
 ]
}

إذا لم ينجح الطلب

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

في ما يلي مثال على ردّ على طلب تعذّر إكماله بنجاح:

{
 "error": {
    "errors": [
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details: [0x0000011F: Advertiser conversion ID ..."
       },
       {
          "reason": "requestValidation",
          "message": "The request was not valid. Details:  [0x00000101: Click ID ..."
       }
    ]
  }
}

تحتوي كل رسالة خطأ على حقلين مهمين: السبب ورسالة خطأ تفصيلية. يمكن أن يحتوي حقل السبب على requestValidation أو internalError أو transactionتعذُّر أو lateStageRequestError.

أخطاء requestالتحقق من الصحة

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

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

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

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

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

الاستجابة لخطأ

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

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