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

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

لیست تعاریف سفارشی و ایجاد گزارش

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

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

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

مرحله 1: روش 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: روش 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: روش 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: روش 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: روش 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" }]
}

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

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

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

تجسم کاربران گروه در طول زمان

گروه های متعدد و کسر حفظ کاربر

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

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

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

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

نمودار حفظ گروهی چندگانه

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

برای حذف واریانس روزانه در رفتار کاربر، از گروه‌های هفتگی استفاده کنید. در گزارش های همگروهی هفتگی، همه کاربران دارای 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 در تعریف گزارش، مقایسه را تعریف کنید. ویژگی مقایسه‌های API داده‌ها مشابه مقایسه‌ها در بخش جلویی Google Analytics است.

برای مستندات دقیق هر فیلد API، مرجع 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"
        }
      ]
    },

    ...

  ],

...

}