أساسيات إعداد تقارير الإحالات الناجحة

ملاحظة: لا تتوفّر هذه الوظيفة إلا في الإصدار v1alpha من Data API.

تنبيه: قد لا تتوفّر هذه الميزة لموقعك على "إحصاءات Google". يعمل فريق "إحصاءات Google" بجدية على توفير هذه الميزة للمزيد من المواقع. يُرجى التواصل مع فريق الدعم إذا كانت لديك أسئلة حول أهلية موقعك.

يشرح هذا الدليل كيفية استخدام وظيفة إعداد تقارير الإحالات الناجحة في الإصدار 1 من Google Analytics Data API. تتيح لك هذه الميزة إنشاء تقارير تركّز على أحداث الإحالات الناجحة مع إمكانية استخدام نماذج تحديد المصدر المختلفة. تتشابه تقارير الإحالات الناجحة التي يتم إنشاؤها باستخدام Data API مع تقارير تحديد المصدر التي يمكنك العثور عليها في قسم الإعلانات > الإحالات الناجحة ضمن واجهة مستخدم "إحصاءات Google". لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تقرير "أداء الإحالات الناجحة" في مركز المساعدة.

الغرض من إعداد تقارير الإحالات الناجحة

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

الإحالات الناجحة في مقابل التقارير المستندة إلى الأحداث

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

تفعيل تقارير الإحالات الناجحة

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

يحتوي العنصر conversionSpec على الحقول التالية:

• conversionActions: قائمة بأسماء موارد إجراءات الإحالات الناجحة التي سيتم تضمينها في التقرير (مثل ["conversionActions/12345"]). إذا كانت فارغة، سيتم تضمين جميع الإحالات الناجحة. يمكن استرداد أرقام تعريف إجراءات الإحالات الناجحة الصالحة من الحقل conversion_action ضمن قائمة conversions في الردّ على طريقة GetMetadata.
• ‫attributionModel: نموذج تحديد المصدر الذي سيتم استخدامه. القيمتان المسموح بإدراجهما هما DATA_DRIVEN (القيمة التلقائية) وLAST_CLICK.

إنشاء تقرير إحالات ناجحة

في ما يلي نموذج طلب باستخدام طريقة runReport لإنشاء تقرير إحالات ناجحة يعرض الإحالات الناجحة حسب اسم الحملة باستخدام نموذج تحديد المصدر بالاستناد إلى البيانات.

HTTP

فتح في "مستكشف واجهات برمجة التطبيقات"

{
    "dateRanges": [
        {
            "startDate": "2026-04-01",
            "endDate": "2026-04-30"
        }
    ],
    "dimensions": [
        {
            "name": "campaignName"
        }
    ],
    "metrics": [
        {
            "name": "allConversionsByConversionDate"
        }
    ],
    "conversionSpec": {
        "conversionActions": [],
        "attributionModel": "DATA_DRIVEN"
    }
}

مثال: إعادة إنشاء تقرير أداء الإحالات الناجحة

يوضّح هذا المثال كيفية استرداد إجراءات الإحالات الناجحة المتاحة لموقع معيّن أولاً، ثم استخدامها لإنشاء تقرير مشابه لتقرير "أداء الإحالات الناجحة" المعروض في واجهة مستخدم "إحصاءات Google" ضمن الإعلانات > الإحالات الناجحة > أداء الإحالات الناجحة.

الخطوة 1: استرداد إجراءات الإحالات الناجحة

استخدِم طريقة getMetadata للعثور على أرقام تعريف إجراءات الإحالات الناجحة الصالحة لموقعك. تأكَّد من تحديد رقم تعريف الموقع على "إحصاءات Google" (بدلاً من استخدام 0 للحصول على الحقول الشائعة لجميع المواقع) من أجل الاطّلاع على إجراءات الإحالات الناجحة التي تم إنشاؤها لموقعك.

يتضمّن الردّ قائمة conversions تتضمّن إجراءات الإحالات الناجحة المتاحة:

{
  ...

  "conversions": [
    {
      "conversionAction": "conversionActions/12345",
      "displayName": "purchase"
    },
    {
      "conversionAction": "conversionActions/67890",
      "displayName": "sign_up"
    }
  ]
}

الخطوة 2: تنفيذ التقرير

استدعِ الطريقة runReport. استخدِم أرقام تعريف إجراءات الإحالات الناجحة التي تم العثور عليها في الخطوة 1 لفلترة تقريرك، أو اترك الحقل conversionActions فارغًا لإعداد تقرير عن جميع الإحالات الناجحة. يعيد هذا الطلب إنشاء تقرير واجهة مستخدم "أداء الإحالات الناجحة" من خلال عرض النقرات على الإعلانات وتكلفة الإعلان وتكلفة الإعلان لكل نقرة وتكلفة الإعلان لكل الإحالات الناجحة ومرات ظهور الإعلان وعائد الإنفاق الإعلاني وإجمالي الإيرادات وجميع الإحالات الناجحة حسب المجموعة التلقائية للقنوات.

HTTP

فتح في "مستكشف واجهات برمجة التطبيقات"

{
    "dateRanges": [
        {
            "startDate": "2026-04-01",
            "endDate": "2026-04-30"
        }
    ],
    "dimensions": [
        {
            "name": "defaultChannelGroup"
        }
    ],
    "metrics": [
        {
            "name": "allConversionsByInteractionDate"
        },
        {
            "name": "advertiserAdCost"
        },
        {
            "name": "advertiserAdCostPerAllConversionsByInteractionDate"
        },
        {
            "name": "advertiserAdImpressions"
        },
        {
            "name": "advertiserAdClicks"
        },
        {
            "name": "advertiserAdCostPerClick"
        },
        {
            "name": "totalRevenueByInteractionDate"
        },
        {
            "name": "returnOnAdSpendByInteractionDate"
        }
    ],
    "conversionSpec": {
        "conversionActions": [
            "conversionActions/12345"
        ],
        "attributionModel": "DATA_DRIVEN"
    }
}

في ما يلي نموذج ردّ على هذا الطلب:

{
  "dimensionHeaders": [
    {
      "name": "defaultChannelGroup"
    }
  ],
  "metricHeaders": [
    {
      "name": "allConversionsByInteractionDate",
      "type": "TYPE_FLOAT"
    },
    {
      "name": "advertiserAdCost",
      "type": "TYPE_CURRENCY"
    },
    {
      "name": "advertiserAdCostPerAllConversionsByInteractionDate",
      "type": "TYPE_CURRENCY"
    },
    {
      "name": "advertiserAdImpressions",
      "type": "TYPE_INTEGER"
    },
    {
      "name": "advertiserAdClicks",
      "type": "TYPE_INTEGER"
    },
    {
      "name": "advertiserAdCostPerClick",
      "type": "TYPE_CURRENCY"
    },
    {
      "name": "totalRevenueByInteractionDate",
      "type": "TYPE_CURRENCY"
    },
    {
      "name": "returnOnAdSpendByInteractionDate",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Paid Search"
        }
      ],
      "metricValues": [
        {
          "value": "75.2"
        },
        {
          "value": "500"
        },
        {
          "value": "6.65"
        },
        {
          "value": "10000"
        },
        {
          "value": "500"
        },
        {
          "value": "1"
        },
        {
          "value": "1500"
        },
        {
          "value": "3"
        }
      ]
    }
  ],
  "rowCount": 1,
  "metadata": {
    "schemaRestrictionResponse": {},
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles",
    "section": "SECTION_ADVERTISING"
  },
  "kind": "analyticsData#runReport"
}

يمكنك التأكّد من أنّ الردّ تم التعامل معه كتقرير إحالة ناجحة من خلال التأكّد من أنّ قيمة الحقل metadata.section في الردّ تم ضبطها على SECTION_ADVERTISING.

للاطّلاع على القائمة الكاملة بالمكوّنات والمقاييس المتاحة لتقارير الإحالات الناجحة، يُرجى الرجوع إلى مخطّط تقارير الإحالات الناجحة.