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

يصف هذا المستند العديد من الميزات المتقدمة للإصدار الأول من واجهة برمجة تطبيقات البيانات في 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": "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/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionKeyEventRate: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
}

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

المقارنات

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

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

إنشاء مقارنة

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

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

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

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
        }
      ]
    },

    ...

  ],

...

}