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

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

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

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

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

إذا حدّدت 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. (يُخصّص "مدير الحملة" أيضًا رقم تعريف لنشاط 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 أحرف)لتحديد العملة.
    ينطبق هذا المقياس على الإحالات الناجحة التي تخصّ المعاملات فقط.
  • 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())

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

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

حقول مطلوبة

  • ‫criterionId: هذا هو معرّف الكلمة الرئيسية. يمكنك الحصول على criterionId من خلال إضافة وحدة الماكرو TrackerId إلى عناوين URL الخاصة بالصفحات المقصودة. للحصول على معلومات حول الحصول على أرقام تعريف الكلمات الرئيسية، اطّلِع على أرقام التعريف في &quot;إعلانات شبكة البحث 360&quot; والإحالات الناجحة.
  • ‫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. (يُخصّص "مدير الحملة" أيضًا رقم تعريف لنشاط Floodlight، ولكن يختلف رقم تعريف "مدير الحملة" عن رقم تعريف "إعلانات شبكة البحث 360" ولا يمكن استخدامه لتحديد مصدر الإحالات الناجحة). للاطّلاع على رقم تعريف "إعلانات شبكة البحث 360" الخاص بنشاط Floodlight، نزِّل تقرير إحالات ناجحة (إمّا من واجهة مستخدم "إعلانات شبكة البحث 360" أو Reporting API). إذا تمّ إسناد إحالة ناجحة واحدة على الأقل إلى نشاط Floodlight خلال الإطار الزمني للتقرير، سيظهر لك معرّف "إعلانات شبكة البحث 360" في التقرير.

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

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

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

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

  • quantityMillis: عدد السلع في هذه الإحالة الناجحة على سبيل المثال، عدد المستخدمين الذين اشتركوا في نشرة إخبارية عبر البريد الإلكتروني أو إجمالي كمية السلع المباعة. إذا لم تحدّد هذا الحقل للإحالات الناجحة من النوع ACTION، ستُدرج "إعلانات شبكة البحث 360" تلقائيًا القيمة 1000.
  • currencyCode: عملة إيرادات المعاملة. بشكلٍ تلقائي، يُفترض أنّ الأرباح تكون بعملة المعلِن. في حال تحديد عملة مختلفة، تحوّل &quot;إعلانات شبكة البحث 360&quot; مبلغ الأرباح المحدّد إلى عملة المعلِن. مزيد من المعلومات
    استخدِم تنسيق ISO 4217 الأبجدي (3 أحرف)لتحديد العملة.
    ينطبق هذا المقياس على الإحالات الناجحة التي تخصّ المعاملات فقط.
  • 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: معرّف النقرة الحساس لحالة الأحرف الخاص بالزيارة. ابحث في سجلّات الويب الخاصة بالمعلِن عن معرّف النقرة أو قائمة الإحالات الناجحة، واستخدِم معرّف نقرة من إحالة ناجحة أخرى. ستحدّد &quot;إعلانات شبكة البحث 360&quot; مصدر الإحالة الناجحة على أنّه الكلمة الرئيسية والإعلان وعناصر &quot;إعلانات شبكة البحث 360&quot; الأخرى التي أدّت إلى إنشاء الزيارة.
    انتظِر 30 دقيقة على الأقل بعد أن تنشئ "إعلانات شبكة البحث 360" معرّف نقرة قبل تحميل إحالة ناجحة باستخدام المعرّف. بخلاف ذلك، قد لا يتعرّف Search Ads 360 API على الزيارة.
  • attributionModel: اضبط على نموذج تحديد المصدر الخارجي. مزيد من المعلومات
  • countMillis: مقدار نسبة المساهمة في الإحالة الناجحة التي سيتم توزيعها على هذه النقرة. ينطبق ذلك فقط إذا كان الطلب يتضمّن الحقل attributionModel أيضًا.

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

  • ‫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. (يُخصّص "مدير الحملة" أيضًا رقم تعريف لنشاط 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: عملة إيرادات المعاملة. بشكلٍ تلقائي، يُفترض أنّ الأرباح تكون بعملة المعلِن. في حال تحديد عملة مختلفة، تحوّل &quot;إعلانات شبكة البحث 360&quot; مبلغ الأرباح المحدّد إلى عملة المعلِن. مزيد من المعلومات
    استخدِم تنسيق ISO 4217 الأبجدي (3 أحرف)لتحديد العملة.
    ينطبق هذا المقياس على الإحالات الناجحة التي تخصّ المعاملات فقط.
  • 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" إلى النجاح إلا إذا تم التحقّق من صحة جميع الإحالات الناجحة في الطلب وتحميلها بنجاح.

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

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

{
 "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 أو transactionFailed أو lateStageRequestError.

أخطاء requestValidation

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

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

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

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

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

الردّ على رسالة خطأ

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

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