مرجع Measurement Protocol

ويوضّح هذا المستند كيفية إرسال البيانات إلى "إحصاءات 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_dataBODY الخاص بطلب البريد. يجب أن يتضمّن النص حمولة بيانات بترميز 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 المشفّر بالكامل عن 8000 بايت.

منظم ذاكرة التخزين المؤقت

في بعض البيئات، مثل المتصفحات، قد يتم تخزين طلبات 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

العملة

يُستخدَم لتمثيل القيمة الإجمالية للعملة. ويتم استخدام العلامة العشرية كفاصل بين الجزء الصحيح والكسر من العملة. تصل الدقة إلى 6 مواضع عشرية. يصلح ما يلي لحقل العملة:

1000.000001

بعد إرسال القيمة إلى "إحصاءات Google"، تتم إزالة كل النص حتى الرقم الأول، وهو الحرف - أو الحرف . (عشري). وبالتالي:

$-55.00

سيصبح:

-55.00

منطقي

يُستخدم لتحديد ما إذا كانت القيمة صواب أم خطأ. القيم الصالحة هي:

  • 1 – صحيح
  • 0 – خطأ

عدد صحيح

يُستخدَم لتمثيل عدد صحيح. يتم تخزين القيمة كدالة int64 مُوقَّعة

العدد

يُستخدم لتمثيل عدد صحيح أو رقم نقطة عائمة.