این سند چندین ویژگی پیشرفته از Google Analytics Data API v1 را شرح میدهد. برای مرجع دقیق میانای برنامهسازی کاربردی، مرجع میانای برنامهسازی کاربردی را ببینید.
فهرست کردن تعریفهای سفارشی و ایجاد گزارش
«میانای برنامهسازی کاربردی داده» میتواند گزارشهایی درباره ابعاد سفارشی و سنجههای سفارشی ثبتشده ایجاد کند. از روش Metadata API میتوان برای فهرست کردن نامهای API «تعریفهای سفارشی» ثبتشده «دارایی» استفاده کرد. از این نامهای API میتوان در «درخواستهای گزارش» برای روش runReport استفاده کرد.
بخشهای زیر نمونههایی برای هر نوع «تعریف سفارشی» نشان میدهد. در این مثالها، GA_PROPERTY_ID را با شناسه دارایی خودتان جایگزین کنید.
ابعاد سفارشی رویدادمحور
مرحله ۱: روش Metadata API را با «شناسه دارایی» خود پُرسمان کنید.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
مرحله ۲: «ابعاد سفارشی رویدادمحور» موردنظرتان را برای ایجاد گزارش از پاسخ پیدا کنید. اگر بُعد وجود ندارد، باید بُعد را ثبت کنید.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
مرحله ۳: بُعد سفارشی را در درخواست گزارش اضافه کنید. در زیر درخواست نمونهای برای روش 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" }]
}
ابعاد سفارشی کاربرمحور
مرحله ۱: روش Metadata API را با «شناسه دارایی» خود پُرسمان کنید.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
مرحله ۲: «ابعاد سفارشی با حوزه کاربر» موردنظرتان را برای ایجاد گزارش از پاسخ پیدا کنید. اگر بُعد وجود ندارد، باید بُعد را ثبت کنید.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
مرحله ۳: بُعد سفارشی را در درخواست گزارش اضافه کنید. در زیر درخواست نمونهای برای روش 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" }]
}
سنجههای سفارشی رویدادمحور
مرحله ۱: روش Metadata API را با «شناسه دارایی» خود پُرسمان کنید.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
مرحله ۲: «سنجه سفارشی رویدادمحور» موردنظرتان را برای ایجاد گزارش از پاسخ پیدا کنید. اگر سنجه وجود ندارد، باید سنجه را ثبت کنید.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
مرحله ۳: سنجه سفارشی را در درخواست گزارش بگنجانید. در زیر درخواست نمونهای برای روش 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" }]
}
سنجههای نرخ رویداد کلیدی برای یک رویداد کلیدی
مرحله ۱: Metadata API Method را با «شناسه دارایی» خود پُرسمان کنید.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
مرحله ۲: «سنجه نرخ رویداد کلیدی» را برای یک «رویداد کلیدی» که به ایجاد گزارش درباره آن از پاسخ علاقهمندید پیدا کنید. اگر رویداد کلیدی وجود ندارد، باید رویداد کلیدی را راهاندازی کنید.
"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",
},
...
],
مرحله ۳: سنجه نرخ رویداد کلیدی را در درخواست گزارش بگنجانید. درخواست نمونه برای روش 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" }]
}
میانگینهای سنجه سفارشی رویدادمحور
مرحله ۱: روش Metadata API را با «شناسه دارایی» خود پُرسمان کنید.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_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/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/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
}
از این پاسخ گزارش، نموداری برای این گزارش «همگروه» دنبال میشود. اطلاعات آماری
این گزارش نشان میدهد که حفظ کاربر ۴ روزه درطول دو هفته ۱۰٪ افزایش یافته است. گروه بعدی با 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 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"
}
]
},
...
],
...
}