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

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

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

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

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

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

الخطوة 1: ابحث عن طريقة Metadata API باستخدام معرّف موقعك.

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

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

"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/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

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

الخطوة 1: ابحث عن طريقة Metadata API باستخدام معرّف موقعك.

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

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

"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/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

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

الخطوة 1: ابحث عن طريقة Metadata API باستخدام معرّف موقعك.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

مقاييس معدّل الأحداث الرئيسية لحدث رئيسي واحد

الخطوة 1: ابحث في Metadata API Method باستخدام معرّف موقعك.

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

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

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

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

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

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

الخطوة 1: ابحث عن طريقة Metadata API باستخدام معرّف موقعك.

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

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

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

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

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

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

تنشئ تقارير المجموعة النموذجية سلسلة زمنية لاحتفاظ المستخدمين بالمجموعة النموذجية. للحصول على مستندات تفصيلية حول كل حقل من حقول واجهة برمجة التطبيقات، يُرجى الاطّلاع على مرجع REST لسمة 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/GA_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/GA_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/GA_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
}

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

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

المقارنات

تساعدك المقارنات على تقييم مجموعات فرعية من البيانات جنبًا إلى جنب. يمكنك تحديد المقارنات من خلال تحديد الحقل comparisons في تعريف التقرير. تشبه ميزة "المقارنات" في Data API المقارنات في واجهة مستخدم "إحصاءات Google".

للحصول على مستندات تفصيلية حول كل حقل من حقول واجهة برمجة التطبيقات، يُرجى الاطّلاع على مرجع REST لمقارنة.

إنشاء مقارنة

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

في ما يلي نموذج تقرير يحدّد مقارنتَين ويعرض المستخدِمين النشطين مقسّمين حسب البلد.

تستخدِم المقارنة الأولى التي تحمل الاسم "عدد زيارات التطبيق" مَعلمة inListFilter لمحاولة مطابقة سمة platform مع القيمتَين "iOS" و "Android". تستخدِم المقارنة الثانية التي تحمل الاسم "زيارات الويب" العنصر stringFilter لمطابقة سمة platform مع "الويب".

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
  {
    "comparisons": [
      {
        "name": "App traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "inListFilter": {
              "values": [
                "iOS",
                "Android"
              ]
            }
          }
        }
      },
      {
        "name": "Web traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "web"
            }
          }
        }
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }

بالنسبة إلى جميع الطلبات التي تستخدِم ميزة المقارنات، تتم إضافة الحقل comparison تلقائيًا إلى التقرير الذي تم إنشاؤه. يحتوي هذا الحقل على اسم مقارنة الأداء المقدَّمة في الطلب.

في ما يلي مثال على مقتطف من ردّ يتضمّن مقارنات:

{
  "dimensionHeaders": [
    {
      "name": "comparison"
    },
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "638572"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "376578"
        }
      ]
    },
  {
      "dimensionValues": [
        {
          "value": "App traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "79527"
        }
      ]
    },

    ...

  ],

...

}