User Activity API

User Activity API به مالک دارایی Google Analytics اجازه می دهد تا تمام داده های اندازه گیری تحلیلی مرتبط با یک کاربر را بازیابی کند. به طور خاص، API تمام داده های اندازه گیری مرتبط با شناسه کاربری خاص یا شناسه مشتری را بازیابی می کند.

توجه: برای آشنایی مختصر با شناسه های مشتری، شناسه های کاربری و تفاوت های بین آنها به مرجع User-ID مراجعه کنید.

ایجاد درخواست فعالیت کاربر

برای ایجاد یک درخواست فعالیت کاربر، یک شی درخواست با فیلدهای زیر بسازید:

1. شناسه مشتری یا شناسه کاربری مرتبط با کاربر

   • برای جزئیات بیشتر در مورد نحوه جستجوی این فیلدها، کوکی ها و شناسایی کاربر را ببینید.

2. شناسه View Analytics حاوی داده‌های مرتبط با کاربر.

   • می توانید از Account Explorer برای جستجوی شناسه نمای خود استفاده کنید.

3. اگرچه لازم نیست، احتمالاً به یک محدوده تاریخ برای داده هایی که به آنها علاقه دارید نیاز خواهید داشت. به طور پیش فرض، API فعالیت کاربر را برای هفته گذشته فهرست می کند.

توجه: برای فهرست کامل فیلدهایی که این API می پذیرد، به مستندات مرجع مراجعه کنید، از جمله مقادیر پیش فرض برای فیلدهای اختیاری.

نمونه درخواست

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000"
    },
    "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31",
    }
}

نمونه پاسخ

{
    "sessions": [{
        "sessionId": "1539184430",
        "deviceCategory": "desktop",
        "platform": "Windows",
        "dataSource": "web",
        "sessionDate": "2018-10-10"
        "activities": [{
            "activityTime": "2018-10-10T08:13:50.555105Z",
            "source": "(direct)",
            "medium": "(none)",
            "channelGrouping": "Direct",
            "campaign": "(not set)",
            "keyword": "(not set)",
            "hostname": "shop.googlemerchandisestore.com",
            "landingPagePath": "/gpsmap",
            "activityType": "PAGEVIEW",
            "customDimension": [{
                "index": 1,
                "value": "(not set)"
            }, ...]
        }, ...]
    }, ...]
    "totalRows": 1000,
    "nextPageToken": "A6JGY3",
    "sampleRate": 1
}

نکته: در این مثال از ... برای نشان دادن آرایه های کوتاه شده استفاده می کنیم

جلسات و فعالیت ها

داده های فعالیت کاربر بر اساس جلسه گروه بندی می شود. هر جلسه حاوی اطلاعات کلی در مورد جلسه، مانند شناسه جلسه و تاریخ، و همچنین لیستی از فعالیت های کاربر برای آن جلسه است. فعالیت‌های کاربر در یک جلسه شامل هر ضربه‌ای است که کاربر مسئول آن بوده است. این شامل مواردی مانند بازدید از صفحه، رویدادهای تجارت الکترونیک، و رویدادهای سفارشی ارسال شده از طریق gtag(...) یا ga(...) می شود.

توجه: جلسات نمی توانند مرزهای تاریخ را باز کنند. اگر زمان کاربر در سایت شما شامل دو روز متفاوت باشد، این زمان به صورت دو جلسه متفاوت در تاریخ های مختلف ظاهر می شود. برای اطلاعات بیشتر در مورد نحوه تعریف یک جلسه در Google Analytics، به نحوه تعریف جلسه وب در Analytics مراجعه کنید

توجه: مرجع Activity شامل تعریف دقیق تری از یک Activity و روش های ظریفی است که آن را از یک Hit یا یک رویداد متمایز می کند.

صفحه بندی

User Activity API از صفحه بندی برای تقسیم مجموعه داده های بزرگ به چندین درخواست و پاسخ استفاده می کند. با این حال، از آنجایی که داده های بازگردانده شده توسط API به صورت سلسله مراتبی ساختار یافته اند، برخی ملاحظات ویژه باید توسط توسعه دهنده در نظر گرفته شود تا به درستی داده ها را جمع آوری کند.

نوع اصلی "ردیف" برای هدف صفحه بندی، Activity است. از آنجایی که داده‌های کاربر بر اساس جلسه گروه‌بندی می‌شوند، به این معنی است که یک مرز صفحه می‌تواند در داخل یک جلسه رخ دهد، و آن جلسه می‌تواند فعالیت‌هایی داشته باشد که چندین صفحه را در بر می‌گیرد.

نکته کلیدی: مرزهای صفحه ممکن است در داخل یک جلسه رخ دهد.

داده های نمونه

برای اهداف نمایشی، از داده های نمونه زیر استفاده خواهیم کرد. در این مثال، کاربر در 6 جلسه در طول 3 روز با سایت تعامل داشت.

تاریخ	شناسه جلسه	برچسب رویداد	زمان
2018-11-23	1	آ	10:26
2018-11-23	1	ب	10:32
2018-11-23	1	سی	10:39
2018-11-23	2	آ	18:04
2018-11-23	2	ب	18:11
2018-11-23	2	سی	18:26
2018-11-24	3	آ	11:26
2018-11-24	3	ب	11:29
2018-11-24	3	سی	11:39
2018-11-24	3	دی	11:42
2018-11-24	4	آ	23:50
2018-11-24	4	ب	23:54
2018-11-25	5	سی	00:02
2018-11-25	5	دی	00:13
2018-11-25	6	آ	13:01
2018-11-25	6	ب	13:09
2018-11-25	6	سی	13:12
2018-11-25	6	دی	13:23

صفحه تک

اگر یک درخواست فعالیت کاربر با pageSize حداقل 18 ارسال کنید، همه داده ها در یک صفحه تحویل داده می شوند و چیزی شبیه به این خواهند بود:

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000",
    },
    "dateRange": {
        "startDate": "2018-11-20",
        "endDate": "2018-11-30",
    },
    "pageSize": 100,
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

توجه: بسیاری از فیلدها برای اختصار حذف شده اند. این مثال فقط برای نشان دادن گروه بندی سلسله مراتبی فعالیت ها و جلسات است.

چندین صفحه

با این حال، اگر اندازه صفحه شما 5 باشد، این داده ها به 4 صفحه پاسخ تقسیم می شوند:

تاریخ	شناسه جلسه	برچسب رویداد	زمان
صفحه 1:
2018-11-23	1	آ	10:26
2018-11-23	1	ب	10:32
2018-11-23	1	سی	10:39
2018-11-23	2	آ	18:04
2018-11-23	2	ب	18:11
صفحه 2:
2018-11-23	2	سی	18:26
2018-11-24	3	آ	11:26
2018-11-24	3	ب	11:29
2018-11-24	3	سی	11:39
2018-11-24	3	دی	11:42
صفحه 3:
2018-11-24	4	آ	23:50
2018-11-24	4	ب	23:54
2018-11-25	5	سی	00:02
2018-11-25	5	دی	00:13
2018-11-25	6	آ	13:01
صفحه 4:
2018-11-25	6	ب	13:09
2018-11-25	6	سی	13:12
2018-11-25	6	دی	13:23

توجه: فعالیت های کاربر همیشه به ترتیب مرتب شده اند، به این معنی که مرز بین صفحات هرگز تصادفی نخواهد بود. همیشه بین جلسات و فعالیت های موقتی مجاور خواهد بود.

توجه داشته باشید که جلسه 2 در صفحات اول و دوم و 2 جلسه در 24 نوامبر در صفحات دوم و سوم تقسیم شده است. پاسخ ها چیزی شبیه به این خواهند بود:

{
    "totalRows": 18,
    "nextPageToken": "UGMGQS",
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "1FKOME",
    "sessions": [{
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "7S77H6",
    "sessions": [{
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }]
        }]
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

نمونه گیری داده ها

اگر مشتری مقدار زیادی داده برای محدوده تاریخ درخواستی جمع آوری کرده باشد، API ممکن است فقط یک زیر مجموعه نمونه از فعالیت ها را برگرداند. هنگامی که این اتفاق می افتد، فیلد sampleRate نشان می دهد که چه کسری از فعالیت های کاربر برگردانده شده است.

نحوه نمونه برداری از داده ها

داده های کاربر در سطح فعالیت نمونه برداری می شود. به عنوان مثال، با نرخ نمونه برداری 50٪ ( 0.5 )، نیمی از فعالیت های کاربر در پاسخ وجود خواهد داشت.

این فعالیت های نمونه به صورت دلخواه انتخاب می شوند. API هیچ تضمینی در مورد نمونه‌گیری تصادفی ارائه نمی‌کند، و نه اینکه نمونه‌گیری متناسب با فعالیت‌های محدوده تاریخ معین است.

جلوگیری از نمونه گیری داده ها

از آنجایی که این API یک جلسه را صرفاً مجموعه‌ای از فعالیت‌ها در نظر می‌گیرد، هر جلسه‌ای که هیچ فعالیتی برای آن در مجموعه نمونه‌برداری شده ظاهر نشود، در پاسخ ظاهر نمی‌شود. اگر به فهرست جامعی از جلسات یا فعالیت‌ها نیاز دارید، درخواست‌های بعدی را با محدوده‌های تاریخی کوچک‌تر ارائه دهید.

به عنوان مثال، اگر داده‌هایی را از 2018-01-01 تا 2018-12-31 درخواست می‌کنید، و پاسخ نرخ نمونه‌گیری 0.25 را نشان می‌دهد، محدوده تاریخ درخواستی را به 4 قسمت تقسیم کنید، به طوری که امیدواریم هر قسمت شامل حدود یک چهارم باشد. داده های اصلی:

• 2018-01-01 تا 2018-03-31
• 2018-04-01 تا 2018-06-30
• 2018-07-01 تا 2018-09-30
• 2018-10-01 تا 2018-12-31

توجه: به دلیل خوشه‌بندی تصادفی داده‌های احتمالی، این زیرمجموعه‌ها نیز ممکن است نمونه‌برداری شوند. به عنوان مثال، اگر بیشتر داده‌های کاربر در محدوده تاریخ 2018-01-01 تا 2018-03-31 رخ داده است، ممکن است مجبور شوید درخواست‌های دیگری را تا زمانی که همه داده‌های نمونه‌گیری نشده را در اختیار داشته باشید، انجام دهید.