واجهة برمجة تطبيقات نشاط المستخدم

تسمح واجهة برمجة تطبيقات نشاط المستخدم لمالك موقع "إحصاءات Google" باسترداد جميع بيانات قياس الإحصاءات المرتبطة بحساب مستخدم واحد. على وجه التحديد، تسترد واجهة برمجة التطبيقات جميع بيانات القياس المرتبطة برقم تعريف مستخدم معيّن أو معرّف عميل معيّن.

ملاحظة: اطّلِع على مرجع User-ID للحصول على مقدمة سريعة عن معرّفات العملاء وأرقام تعريف المستخدمين والاختلافات بينهما.

تقديم طلب نشاط المستخدم

لتقديم طلب نشاط مستخدم، أنشئ كائن طلب باستخدام الحقول التالية:

1. معرِّف العميل أو معرِّف المستخدم المرتبط بالمستخدم

   • راجِع ملفات تعريف الارتباط وتعريف المستخدم للحصول على تفاصيل عن كيفية البحث عن هذه الحقول.

2. رقم تعريف ملف شخصي في "إحصاءات Google" يحتوي على البيانات المرتبطة بالمستخدم.

   • يمكنك استخدام مستكشف الحساب للبحث عن رقم تعريف الملف الشخصي.

3. على الرغم من أنّ هذا الإجراء غير مطلوب، قد تحتاج إلى نطاق زمني للبيانات التي تهمّك. بشكل تلقائي، تسرد واجهة برمجة التطبيقات نشاط المستخدم للأسبوع الماضي.

ملاحظة: يمكنك الاطّلاع على المستندات المرجعية للحصول على قائمة كاملة بالحقول التي تقبلها واجهة برمجة التطبيقات هذه، بما في ذلك القيم التلقائية للحقول الاختيارية.

نموذج طلب

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
}

ملاحظة: في هذا المثال، نستخدم ... للإشارة إلى المصفوفات التي تم اقتطاعها

الجلسات والأنشطة

يتم تجميع بيانات نشاط المستخدم حسب الجلسة. وتتضمن كل جلسة معلومات عامة عن الجلسة، مثل معرِّفها وتاريخها، بالإضافة إلى قائمة بأنشطة المستخدم لتلك الجلسة. تتألف أنشطة المستخدم في جلسة من كل "&&hl=ar&hit" ويكون المستخدم مسؤولاً عنها، ويشمل ذلك أمورًا مثل مشاهدات الصفحة وأحداث التجارة الإلكترونية والأحداث المخصّصة التي يتم إرسالها عبر gtag(...) أو ga(...).

ملاحظة: لا يمكن أن تتجاوز الجلسات حدود التاريخ. إذا كان وقت المستخدم على موقعك الإلكتروني يشمل يومين مختلفين، سيظهر ذلك كجلستين مختلفتين في تواريخ مختلفة. لمزيد من المعلومات عن كيفية تحديد جلسة في "إحصاءات Google"، يُرجى الاطّلاع على كيفية تحديد جلسة ويب في "إحصاءات Google"

ملاحظة: يحتوي مرجع 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	D	11:42
2018-11-24	4	أمبير	23:50
2018-11-24	4	ب	23:54
2018-11-25	5	ج	00:02
2018-11-25	5	D	00:13
2018-11-25	6	أمبير	13:01
2018-11-25	6	ب	13:09
2018-11-25	6	ج	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	ب	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	D	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	D	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	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

ملاحظة: بسبب التجميع العشوائي المحتمل للبيانات، قد يتم أيضًا أخذ عينات من هذه النطاقات الفرعية. على سبيل المثال، إذا حدثت معظم بيانات المستخدمين في النطاق الزمني 2018-01-01 إلى 2018-03-31، قد تحتاج إلى إجراء طلبات إضافية إلى أن تتوفّر لديك جميع البيانات غير المستندة إلى عينات.