این سند چندین ویژگی پیشرفته 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"
}
]
},
...
],
...
}