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

يتناول هذا المستند عدة ميزات متقدّمة في خدمة "إحصاءات Google". الإصدار 1 من 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 بشأن المقارنة:

إنشاء مقارنة

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

    ...

  ],

...

}