موارد استفاده پیشرفته

این سند چندین ویژگی پیشرفته Google Analytics Data API v1 را شرح می دهد. برای مرجع دقیق API، به مرجع API مراجعه کنید.

فهرست کردن تعاریف سفارشی و ایجاد گزارش

Data API می‌تواند گزارش‌هایی درباره ابعاد سفارشی و معیارهای سفارشی ثبت‌شده ایجاد کند. روش API فراداده می‌تواند برای فهرست کردن نام‌های API تعاریف سفارشی ثبت‌شده ملک شما استفاده شود. برای مثال می‌توان از این نام‌های API در گزارش درخواست‌ها به روش runReport استفاده کرد.

بخش‌های زیر نمونه‌هایی را برای هر نوع تعریف سفارشی نشان می‌دهند. در این مثال‌ها، GA4_PROPERTY_ID با شناسه دارایی خود جایگزین کنید.

ابعاد سفارشی با محدوده رویداد

مرحله 1: روش API فراداده را با شناسه ویژگی خود پرس و جو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_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/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

ابعاد سفارشی با محدوده کاربر

مرحله 1: روش API فراداده را با شناسه ویژگی خود پرس و جو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_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/GA4_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA4_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

معیارهای سفارشی با محدوده رویداد

مرحله 1: روش API فراداده را با شناسه ویژگی خود پرس و جو کنید.

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: روش API فراداده را با شناسه ویژگی خود پرس و جو کنید.

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: روش API فراداده را با شناسه ویژگی خود پرس و جو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_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/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

نمونه های گزارش همگروهی

گزارش های کوهورت یک سری زمانی از حفظ کاربر برای گروه ایجاد می کند. برای مستندات دقیق هر فیلد API، به مرجع 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/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
}

از پاسخ این گزارش، نموداری برای این گزارش کوهورت به دست می آید. بینشی از این گزارش این است که بیشترین کاهش در کاربران فعال برای این گروه بین روز اول و دوم است.

گروه‌های چندگانه و کسر حفظ کاربر

جذب و حفظ کاربر راه هایی برای رشد وب سایت یا برنامه شما هستند. گزارش های همگروهی بر حفظ کاربر تمرکز دارند. در این مثال، گزارش نشان می‌دهد که این ویژگی در طول دو هفته، حفظ کاربر ۴ روزه خود را ۱۰ درصد بهبود داده است.

برای ایجاد این گزارش، ما سه گروه را مشخص می‌کنیم: اولی با firstSessionDate 2020-11-02 ، دومی با firstSessionDate 2020-11-09 ، و سومی با firstSessionDate 2020-11-16 . از آنجایی که تعداد کاربران در دارایی شما در این سه روز متفاوت خواهد بود، ما به جای استفاده از متریک مستقیم cohortActiveUsers ، معیار کسری حفظ کاربر گروه cohortActiveUsers/cohortTotalUsers را مقایسه می کنیم.

درخواست گزارش برای این گروه ها به شرح زیر است:

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 بیشتر است.

گروه‌های هفتگی و استفاده از گروه‌ها با سایر ویژگی‌های API

برای حذف واریانس روزانه در رفتار کاربر، از گروه‌های هفتگی استفاده کنید. در گزارش های همگروهی هفتگی، همه کاربران دارای 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
}

از پاسخ این گزارش، نمودار این گزارش همگروهی به شرح زیر است. بر اساس این گزارش، این ویژگی در حفظ کاربران با فعالیت در مکزیک بهتر از کاربران با فعالیت در روسیه عمل می کند.