يوضّح هذا المستند كيفية إرسال البيانات إلى "إحصاءات Google" باستخدام Measurement Protocol.
نظرة عامة
هناك جزءان لإرسال البيانات إلى "إحصاءات Google" باستخدام Measurement Protocol:
- النقل - إلى أين يتم إرسال البيانات وكيفية إرسالها
- الحمولة - البيانات التي ترسلها
ويصف هذا المستند كيفية تنسيقهما معًا.
خدمة نقل
نقطة نهاية عنوان URL
يمكنك إرسال البيانات باستخدام Measurement Protocol عن طريق إرسال طلبات HTTP إلى نقطة النهاية التالية:
https://www.google-analytics.com/collect
يجب إرسال جميع البيانات بشكل آمن باستخدام بروتوكول HTTPS.
يمكنك إرسال البيانات باستخدام طلبات POST أو GET.
استخدام POST
ننصحك بإرسال البيانات من خلال POST لأنّها تتيح حمولة أكبر. عند استخدام POST، أصدر طلب HTTP التالي:
User-Agent: user_agent_string POST https://www.google-analytics.com/collect payload_data
المكان:
- user_agent_string – هي
سلسلة وكيل مستخدم منسّقة تُستخدَم لحساب
السمات التالية: المتصفّح والنظام الأساسي وإمكانات الأجهزة الجوّالة.
في حال عدم ضبط هذه القيمة، لن يتم احتساب البيانات الواردة أعلاه.
- payload_data:
BODYالخاص بطلب البريد يجب أن يشتمل النص على حمولة بيانات مرمّزة من معرّف الموارد المنتظم (URI) واحد فقط، ويجب ألا يزيد طولها عن 8192 بايت. - عنوان IP: يتم إرساله ضمنيًا في طلب HTTP، ويُستخدم لحساب جميع أبعاد الموقع الجغرافي / الشبكة في "إحصاءات Google".
GET
بالنسبة إلى البيئات التي لا يمكنك فيها إرسال بيانات POST، يمكنك أيضًا إرسال طلبات HTTP GET إلى نقطة النهاية نفسها:
GET /collect?payload_data HTTP/1.1 Host: https://www.google-analytics.com User-Agent: user_agent_string
حيث يتم إرسال بيانات حمولة البيانات كمَعلمات طلب بحث تم تجاوزها لمعرّف الموارد المنتظم (URI). يجب ألا يزيد طول عنوان URL المشفّر بالكامل عن 8,000 بايت.
تنظيم ذاكرة التخزين المؤقت
في بعض البيئات، مثل المتصفحات، قد يتم تخزين طلبات HTTP GET مؤقتًا.
عندما يتم تخزين طلب في ذاكرة التخزين المؤقت، قد يتم استرداد الطلبات اللاحقة من ذاكرة التخزين المؤقت ولا يتم إرسالها إلى "إحصاءات Google". للتدقيق في ذاكرة التخزين المؤقت، يوفر Measurement Protocol مَعلمة خاصة (z) يمكن ضبطها باستخدام رقم عشوائي. ويضمن ذلك أن جميع طلبات Measurement Protocol فريدة وأنّه لا يتم استرداد الطلبات اللاحقة من ذاكرة التخزين المؤقت.
عند استخدام أداة تنظيم ذاكرة التخزين المؤقت، ننصحك بشدة بإضافة هذه المَعلمة باعتبارها المعلَمة الأخيرة في الحمولة.
https://www.google-analytics.com/collect?payload_data&z=123456
رموز الاستجابة
سيعرض Measurement Protocol رمز الحالة 2xx في حال استلام طلب HTTP. لا يعرض Measurement Protocol رمز خطأ إذا كانت بيانات الحمولة مكتوبة بشكلٍ غير صحيح، أو إذا كانت البيانات في الحمولة غير صحيحة أو لم تتم معالجتها بواسطة "إحصاءات Google".
إذا لم يظهر لك رمز الحالة 2xx، عليك
عدم إعادة محاولة الطلب. بدلاً من ذلك، عليك إيقاف أي أخطاء في طلب HTTP وتصحيحها.
بيانات الحمولة
يتم إرسال جميع البيانات التي تجمعها "إحصاءات Google" باستخدام Measurement Protocol كحمولة. تشبه الحمولة سلسلة طلب البحث لعنوان URL حيث تحتوي كل مَعلمة على مفتاح وقيمة، تفصل بينها حرف =، ويتم الفصل بين كل زوج باستخدام حرف &.
مثال:
key1=val1&key2=val2
لكل حمولة قواعد تحكم: القيم المطلوبة وترميز معرّف الموارد المنتظم (URI) والمَعلمات التي يمكن إرسالها معًا وطول المَعلمة. بالإضافة إلى ذلك، تحتوي كل معلَمة على نوع محدد يتطلب تنسيقًا محددًا. وتخضع الأقسام التالية لهذه القواعد.
اطّلِع على مرجع المَعلمات للحصول على قائمة كاملة بجميع المَعلمات التي يمكنك إرسالها باستخدام Measurement Protocol.
القيم المطلوبة لجميع النتائج
يجب تضمين المَعلمات التالية في كل حمولة:
| الاسم | المَعلمة | مثال | الوصف |
|---|---|---|---|
| إصدار البروتوكول | v |
v=1 |
إصدار البروتوكول. يجب أن تكون القيمة 1. |
| الرقم التعريفي للتتبع | tid |
tid=UA-123456-1 |
رقم التعريف الذي يميّز موقع "إحصاءات Google" الذي يجب إرسال البيانات إليه. |
| معرِّف العميل | cid |
cid=xxxxx |
رقم تعريف فريد لمستخدم معيّن. |
| نوع النتيجة | t |
t=pageview |
تمثّل هذه السمة نوع التفاعل الذي يتم جمعه لمستخدِم معيّن. |
يتم ربط بيانات Client ID وHit Type مباشرةً بنموذج بيانات "إحصاءات Google".
إذا أردت تتبُّع المستخدم "5555" الذي ذهب إلى
/pageA و/pageB و/pageC،
يمكنك إرسال الحمولات الثلاث التالية:
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC
لاحظ أنّه تم ترميز / إلى %2F.
قيم ترميز عناوين URL
يجب أن تكون جميع القيم المرسَلة إلى "إحصاءات Google" إما UTF-8 وترميز عنوان URL معًا.
لإرسال المفتاح dp مع القيمة /my page €، عليك أولاً التأكّد من أنّ ترميز UTF-8 ثم ترميز عنوان URL يؤدي إلى ظهور السلسلة النهائية:
dp=%2Fmy%20page%20%E2%82%AC
إذا تم ترميز أي من الأحرف بشكل غير صحيح، سيتم استبداله بحرف يونيكود البديل xFFFD.
القيم المطلوبة لأنواع نتائج معيّنة
قد يتم إرسال بعض المَعلمات مع أنواع نتائج معيّنة فقط.
على سبيل المثال، يتطلب نوع النتيجة pageview ضبط
معلَمة مسار الصفحة (dp) أيضًا. يوضّح
مرجع المَعلمات
المَعلمات المطلوبة لأنواع النتائج.
الحدّ الأقصى للطول
بعض القيم النصية في Measurement Protocol لها حدّ أقصى معيّن لأطوال
بالبايت. على سبيل المثال، يبلغ الحد الأقصى لطول حقل مُحيل المستند dr 2,048 بايت. إذا كانت أي من القيم أكبر من
الحد الأقصى للأطوال، سيتم اقتطاعها تلقائيًا. إذا تجاوز حرف متعدد البايت الحدّ الأقصى للطول، سيتم اقتطاع الحرف بأكمله.
أنواع البيانات المتوافقة
ينتمي كل حقل بيانات في Measurement Protocol إلى نوع محدّد، لكل حقل قواعد خاصة به للتحقق من الصحة. إذا كانت أيٌّ من قيم المَعلمات لا تتوافق مع قواعد التحقّق، ستتجاهل "إحصاءات Google" هذه المَعلمة المحدّدة ولن تعالجها. أما جميع المَعلمات الأخرى، فستتم معالجتها كالمعتاد.
يتيح Measurement Protocol أنواع البيانات التالية:
تجدر الإشارة إلى أنّ حقول البيانات الفردية قد تكون لها قيود خاصة بها. راجِع مرجع الحقول للحصول على قائمة كاملة بجميع حقول البيانات والأنواع المقبولة.
النص
تُستخدَم لتمثيل السلاسل. تتم المعالجة الإضافية للحقول النصية. تتم إزالة جميع أحرف المسافات البيضاء البادئة واللاحقة. يتم تقليل عمليات التنفيذ الداخلية لحرفَي مسافة بيضاء أو أكثر (بما في ذلك المسافة وعلامة التبويب والسطور الجديدة وما إلى ذلك) إلى حرف مسافة واحد. يتم تطبيق عملية التحويل على النص الأولي قبل حدوث أي اقتطاع. مثال:
Hello World
سيصبح:
Hello World
Currency
تُستخدَم لتمثيل القيمة الإجمالية للعملة. ويتم استخدام علامة عشرية كمحدد بين الجزء الصحيح والجزء الكسري من العملة. تصل الدقة إلى 6 مواضع عشرية. يصلح ما يلي لحقل العملة:
1000.000001
وبعد إرسال القيمة إلى "إحصاءات Google"، تتم إزالة كل النصوص حتى
الرقم الأول أو الحرف - أو الحرف .
(عشري). وبالتالي:
$-55.00
سيصبح:
-55.00
منطقي
يتم استخدامه لتحديد ما إذا كانت القيمة صواب أم خطأ. القيم الصالحة هي:
1– صحيح0– خطأ
عدد صحيح
تُستخدَم لتمثيل عدد صحيح. يتم تخزين القيمة على شكل int64 مُوقَّعة
العدد
تُستخدَم لتمثيل عدد صحيح أو رقم نقطة عائمة.