يصف هذا المستند كيفية إرسال البيانات إلى "إحصاءات 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".
الاطّلاع على
بالنسبة إلى البيئات التي لا يمكنك إرسال بيانات POST لها، يمكنك أيضًا إرسال طلبات HTTP GET إلى نقطة النهاية نفسها:
GET /collect?payload_data HTTP/1.1 Host: https://www.google-analytics.com User-Agent: user_agent_string
حيث يتم إرسال بيانات الحمولة على أنها معلمات طلب بحث معرف موارد منتظم (URI) تم تجاوزها. يجب ألا يتجاوز طول عنوان URL المشفر بالكامل 8000 بايت.
تنظيم ذاكرة التخزين المؤقت
في بعض البيئات، مثل المتصفِّحات، قد يتم تخزين طلبات HTTP GET مؤقتًا.
وعند تخزين الطلب مؤقتًا، قد يتم استرداد الطلبات اللاحقة من
ذاكرة التخزين المؤقت، ولا يتم إرسالها إلى "إحصاءات Google". للبحث في ذاكرة التخزين المؤقت، يوفر Measurement Protocol معلّمة خاصة (z) يمكن ضبطها باستخدام رقم عشوائي. يضمن هذا الإجراء أن تكون جميع طلبات Measurement Protocol فريدة، وأنّه لا يتم استرداد
الطلبات اللاحقة من ذاكرة التخزين المؤقت.
عند استخدام النص البرمجي لذاكرة التخزين المؤقت، ننصح بشدة بإضافة هذه المعلّمة باعتبارها المعلَمة last في الحمولة.
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
العملة
يُستخدَم لتمثيل القيمة الإجمالية للعملة. يتم استخدام علامة عشرية كمحدِّد بين الجزء الكامل والكسر من العملة. تصل الدقة إلى 6 مواضع عشرية. في ما يلي قيمة صالحة لحقل عملة:
1000.000001
بعد إرسال القيمة إلى "إحصاءات Google"، تتم إزالة النص بالكامل حتى
الرقم الأول، أو الحرف - أو الحرف .
(خاتمي). وبالتالي:
$-55.00
ستصبح:
-55.00
منطقي
يتم استخدامه لتحديد ما إذا كانت القيمة صحيحة أو خاطئة. القيم الصالحة هي:
1- صحيح0– خطأ
عدد صحيح
يُستخدم لتمثيل عدد صحيح. يتم تخزين القيمة بصفتها int64 موقّعة
الرقم
يُستخدَم لتمثيل عدد صحيح أو رقم عائم.