تسمح واجهة برمجة تطبيقات نشاط المستخدم لمالك موقع على "إحصاءات Google" باسترداد جميع بيانات قياس الإحصاءات المرتبطة بمستخدم واحد. وعلى وجه التحديد، تسترد واجهة برمجة التطبيقات جميع بيانات القياس المرتبطة برقم تعريف مستخدم أو رقم تعريف عميل محدّدَين.
تقديم طلب نشاط مستخدم
لتقديم طلب نشاط مستخدم، أنشئ كائن طلب باستخدام الحقول التالية:
Client ID أو User ID المرتبط بالمستخدم
- راجِع ملفات تعريف الارتباط وتعريف المستخدم للحصول على تفاصيل حول كيفية البحث عن هذه الحقول.
رقم تعريف ملف شخصي في "إحصاءات Google" يحتوي على البيانات المرتبطة بالمستخدم.
- يمكنك استخدام مستكشف الحساب للبحث عن رقم تعريف ملفك الشخصي.
قد تحتاج إلى نطاق زمني للبيانات التي تهمّك، على الرغم من أنّ هذا الإجراء ليس مطلوبًا. تعرض واجهة برمجة التطبيقات تلقائيًا نشاط المستخدم على مدار الأسبوع الماضي.
نموذج طلب
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(...).
تقسيم النتائج على عدّة صفحات
تستخدم واجهة برمجة تطبيقات نشاط المستخدم ميزة التقسيم على صفحات لتقسيم مجموعات البيانات الكبيرة إلى طلبات وردود متعددة. ومع ذلك، بما أنّه يتم تنظيم البيانات التي تعرضها واجهة برمجة التطبيقات بشكل هرمي، يجب أن يأخذ المطوّر بعض الاعتبارات الخاصة من أجل تجميع البيانات بشكل صحيح.
إنّ "النشاط" هو نوع "الصف" الأساسي الذي يهدف إلى تقسيم النتائج على عدّة صفحات. نظرًا لأنه يتم تجميع بيانات المستخدمين حسب الجلسة، فإن هذا يعني أن حدود الصفحة يمكن أن تحدث داخل الجلسة، وأن هذه الجلسة يمكن أن تتضمن أنشطة تمتد على صفحات متعددة.
عيّنات البيانات
سنستخدم البيانات النموذجية التالية لأغراض العرض التوضيحي. في هذا المثال، تفاعل المستخدم مع الموقع في 6 جلسات على مدار 3 أيام.
| التاريخ | معرّف الجلسة | علامة الحدث | الوقت |
|---|---|---|---|
| 2018-11-23 | 1 | جيم | 10:26 |
| 2018-11-23 | 1 | B | 10:32 |
| 2018-11-23 | 1 | C | 10:39 |
| 2018-11-23 | 2 | جيم | 18:04 |
| 2018-11-23 | 2 | B | 18:11 |
| 2018-11-23 | 2 | C | 18:26 |
| 2018-11-24 | 3 | جيم | 11:26 |
| 2018-11-24 | 3 | B | 11:29 |
| 2018-11-24 | 3 | C | 11:39 |
| 2018-11-24 | 3 | D | 11:42 |
| 2018-11-24 | 4 | جيم | 23:50 |
| 2018-11-24 | 4 | B | 23:54 |
| 2018-11-25 | 5 | C | 00:02 |
| 2018-11-25 | 5 | D | 00:13 |
| 2018-11-25 | 6 | جيم | 13:01 |
| 2018-11-25 | 6 | B | 13:09 |
| 2018-11-25 | 6 | C | 13:12 |
| 2018-11-25 | 6 | D | 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 | B | 10:32 |
| 2018-11-23 | 1 | C | 10:39 |
| 2018-11-23 | 2 | جيم | 18:04 |
| 2018-11-23 | 2 | B | 18:11 |
| الصفحة 2: | |||
| 2018-11-23 | 2 | C | 18:26 |
| 2018-11-24 | 3 | جيم | 11:26 |
| 2018-11-24 | 3 | B | 11:29 |
| 2018-11-24 | 3 | C | 11:39 |
| 2018-11-24 | 3 | D | 11:42 |
| الصفحة 3: | |||
| 2018-11-24 | 4 | جيم | 23:50 |
| 2018-11-24 | 4 | B | 23:54 |
| 2018-11-25 | 5 | C | 00:02 |
| 2018-11-25 | 5 | D | 00:13 |
| 2018-11-25 | 6 | جيم | 13:01 |
| الصفحة 4: | |||
| 2018-11-25 | 6 | B | 13:09 |
| 2018-11-25 | 6 | C | 13:12 |
| 2018-11-25 | 6 | D | 13:23 |
لاحظ أن الجلسة 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"}
}]
}]
}
تحليل عينات البيانات
إذا جمع العميل كمية ضخمة من البيانات للنطاق الزمني المطلوب، قد تعرض واجهة برمجة التطبيقات مجموعة فرعية من الأنشطة فقط. عند حدوث ذلك، سيشير الحقل sampleRate إلى نسبة أنشطة المستخدم التي تم عرضها.
كيفية أخذ عينات البيانات
يتم أخذ عينات من بيانات المستخدِمين على مستوى النشاط. على سبيل المثال، إذا كان معدل أخذ العينات 50% (0.5)، سيتم عرض نصف أنشطة المستخدم في الاستجابة.
يتم اختيار عيّنات الأنشطة هذه بشكل عشوائي، ولا تقدّم واجهة برمجة التطبيقات أي ضمانات بشأن أخذ العيّنات العشوائية، كما أنّ بيانات العينات تكون متناسبة مع جميع الأنشطة في النطاق الزمني المحدّد.
منع تحليل عيّنات البيانات
ولأنّ واجهة برمجة التطبيقات هذه تتعامل مع إحدى الجلسات على أنّها مجموعة من الأنشطة، لن تظهر في الردّ أي جلسات لا تظهر فيها أي أنشطة ضمن المجموعة المستندة إلى العيّنات. إذا كنت تحتاج إلى قائمة شاملة بالجلسات أو الأنشطة، فقدِّم طلبات متابعة بنطاقات زمنية أصغر.
على سبيل المثال، إذا طلبت بيانات من 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