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

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

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

يمكن لواجهة Data API إنشاء تقارير عن السمات المخصّصة والمقاييس المخصّصة المسجّلة. يمكن استخدام طريقة Metadata API لعرض أسماء واجهات برمجة التطبيقات الخاصة بالتعريفات المخصّصة المسجّلة في موقعك. يمكن استخدام أسماء واجهات برمجة التطبيقات هذه في طلبات التقارير، مثلاً في الطريقة 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 باستخدام معرّف موقعك.

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 الخاص بـ Comparison.

إنشاء مقارنة

يمكنك إنشاء مقارنة منفصلة لكلّ مجموعة بيانات تريد مقارنتها. على سبيل المثال، للمقارنة بين بيانات التطبيقات والمواقع الإلكترونية، يمكنك إنشاء مقارنة لبيانات 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"
        }
      ]
    },

    ...

  ],

...

}