تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

حالات الاستخدام المتقدّمة

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

سرد التعريفات المخصصة وإنشاء التقارير

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

تعرض الأقسام التالية أمثلة لكل نوع من أنواع التعريفات المخصّصة. في هذه الأمثلة، استبدِل GA4_PROPERTY_ID بـ رقم تعريف الموقع.

السمات المخصّصة على مستوى الحدث

الخطوة 1: إجراء طلب بحث في طريقة واجهة برمجة تطبيقات البيانات الوصفية باستخدام رقم تعريف موقعك

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

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

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

الخطوة 3: تضمين السمة المخصّصة في طلب تقرير. في ما يلي نموذج طلب لطريقة runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

السمات المخصّصة على مستوى المستخدم

الخطوة 1: إجراء طلب بحث في طريقة واجهة برمجة تطبيقات البيانات الوصفية باستخدام رقم تعريف موقعك

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

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

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

الخطوة 3: تضمين السمة المخصّصة في طلب تقرير. في ما يلي نموذج طلب لطريقة runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA4_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

المقاييس المخصَّصة على مستوى الحدث

الخطوة 1: إجراء طلب بحث في طريقة واجهة برمجة تطبيقات البيانات الوصفية باستخدام رقم تعريف موقعك

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

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

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

الخطوة 3: أدرِج المقياس المخصّص في طلب تقرير. في ما يلي نموذج طلب لطريقة runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

مقاييس معدل الإحالات الناجحة لإحالة ناجحة واحدة

الخطوة 1: إجراء طلب بحث في طريقة واجهة برمجة تطبيقات البيانات الوصفية باستخدام رقم تعريف موقعك

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

الخطوة 2: ابحث عن مقياس معدل الإحالات الناجحة "لإحالة ناجحة واحدة" الذي تريد إنشاء تقارير عنه من خلال الرد. وإذا لم يكن حدث الإحالة الناجحة متوفّرًا، عليك إعداد حدث الإحالة الناجحة.

"metrics": [
...
    {
      "apiName": "sessionConversionRate:add_to_cart",
      "uiName": "Session conversion rate for add_to_cart",
      "description": "The percentage of sessions in which a specific conversion event was triggered",
    },
...
],

الخطوة 3: أدرِج مقياس معدّل الإحالات الناجحة في طلب تقرير. في ما يلي نموذج طلب لطريقة runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionConversionRate:add_to_cart" }]
}

متوسطات المقاييس المخصّصة على مستوى الحدث

الخطوة 1: إجراء طلب بحث في طريقة واجهة برمجة تطبيقات البيانات الوصفية باستخدام رقم تعريف موقعك

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

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

"metrics": [
...
    {
      "apiName": "averageCustomEvent:credits_spent",
      "uiName": "Average Credits Spent",
      "description": "The average of an event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

الخطوة الثالثة: أدرِج متوسط المقياس المخصّص في طلب تقرير. في ما يلي نموذج طلب لطريقة runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

أمثلة على تقارير المجموعات النموذجية

تنشئ تقارير المجموعات النموذجية سلسلة زمنية للحفاظ على المستخدمين في المجموعة النموذجية. للحصول على الوثائق التفصيلية حول كل حقل من حقول واجهة برمجة التطبيقات، اطلع على مرجع RST المتعلق بـ CohortSpec.

إنشاء تقرير مجموعة نموذجية

في ما يلي نموذج لتقرير المجموعة النموذجية حيث:

المجموعة النموذجية هي المستخدمين الذين لديهم firstSessionDate من 2020-12-01، ويتم ضبطه من خلال العنصر cohorts. ستعتمد السمات والمقاييس الواردة في استجابة التقرير فقط على مستخدمي المجموعة النموذجية.
سيعرِض تقرير المجموعة النموذجية ثلاثة أعمدة، يتمّ ضبط هذه الأعمدة باستخدام عناصر المقاييس والسمات.
- السمة cohort هي اسم المجموعة النموذجية.
- السمة cohortNthDay هي عدد الأيام منذ 2020-12-01.
- المقياس cohortActiveUsers هو عدد المستخدمين الذين لا يزالون نشطين.
يحدد العنصر cohortsRange أن التقرير يجب أن يحتوي على بيانات الأحداث التي تبدأ من 2020-12-01 وتنتهي في 2020-12-06 لهذه المجموعة النموذجية.
- عند استخدام درجة دقة DAILY، يُنصح باستخدام السمة cohortNthDay لتحقيق الاتساق.

طلب التقرير للمجموعة النموذجية هو:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "DAILY"
    }
  },
}

في ما يلي مثال على ردّ على التقرير لهذا الطلب:

{
  "dimensionHeaders": [
    { "name": "cohort" }, { "name": "cohortNthDay" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "293" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "143" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "123" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "92" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
      "metricValues": [{ "value": "86" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "83" }]
    }
  ],
  "metadata": {},
  "rowCount": 6
}

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

عرض مستخدمي المجموعة النموذجية بمرور الوقت

مجموعات نموذجية متعددة وجزء الحفاظ على المستخدمين

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

لإنشاء هذا التقرير، نحدّد ثلاث مجموعات نموذجية: الأولى تحتوي على firstSessionDate من 2020-11-02، والثانية بقيمة firstSessionDate من 2020-11-09، والثالثة تتضمّن firstSessionDate من 2020-11-16. بما أنّ عدد المستخدمين على موقعك سيكون مختلفًا خلال هذه الأيام الثلاثة، سنقارن مقياس نسبة الحفاظ على المستخدمين وهو cohortActiveUsers/cohortTotalUsers في المجموعة النموذجية بدلاً من استخدام مقياس cohortActiveUsers المباشر.

طلب التقرير لهذه المجموعات النموذجية هو:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metrics": [
    {
      "name": "cohortRetentionFraction",
      "expression": "cohortActiveUsers/cohortTotalUsers"
    }
  ],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
      }
    ],
    "cohortsRange": {
      "endOffset": 4,
      "granularity": "DAILY"
    }
  },
}

في ما يلي مثال على ردّ على التقرير لهذا الطلب:

{
  "dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metricHeaders": [{
      "name": "cohortRetentionFraction",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.308" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.272" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.257" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.248" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.235" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.211" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.198" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.172" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.167" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.155" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.141" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.118" }]
    }
  ],
  "metadata": {},
  "rowCount": 15
}

من استجابة التقرير هذا، يتبع الرسم البياني لتقرير المجموعة النموذجية هذا. يتضح من هذا التقرير أن معدل الاحتفاظ بالمستخدمين لمدة 4 أيام قد زاد بنسبة 10٪ على مدار أسبوعين. إنّ المجموعة النموذجية الأخيرة التي تتضمن firstSessionDate من 2020-11-16 فاقت معدل الاحتفاظ بالمجموعة النموذجية السابقة بنسبة firstSessionDate من 2020-11-02.

رسم بياني لعدة مجموعات نموذجية للاحتفاظ بالبيانات

المجموعات النموذجية الأسبوعية واستخدام المجموعات النموذجية مع ميزات واجهة برمجة التطبيقات الأخرى

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

طلب التقرير لهذه المجموعات النموذجية هو:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "inListFilter": {
        "values": [ "Russia", "Mexico" ]
      }
    }
  },
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": {
          "startDate": "2020-10-04",
          "endDate": "2020-10-10"
        }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "WEEKLY"
    }
  },
}

في ما يلي مثال على ردّ على التقرير لهذا الطلب:

{
  "dimensionHeaders": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "105" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "98" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "35" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "24" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "23" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "17" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "3" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    }
  ],
  "metadata": {},
  "rowCount": 11
}

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

رسم بياني للمجموعات النموذجية للمقارنة بين البلدان