بشكل افتراضي، سيرسل المتعقّب (tracker) الخاص بنا الكثير من المعلومات المفيدة إلى منصتنا، لكن كل تلك المعلومات قياسية. وطالما أن نقطة بيانات ما جزء من Web API، فمن المرجّح أننا نتعقّبها.

ولكن ماذا يحدث إذا كنت ترغب أيضًا في إثراء تسجيلات جلساتك ببيانات خاصة بتطبيقك؟

مثل معرفة الخطة المدفوعة التي يندرج تحتها المستخدم عند مراجعتك لإعادة تشغيل جلسته؟ يمكن أن توفر هذه المعلومات سياقًا إضافيًا لمطوريك، لذا فإن كونها غير قياسية لا يعني أنه ينبغي علينا تجاهلها، أليس كذلك؟

هنا يأتي دور البيانات الوصفية.

لاحظ أن هناك نسخة فيديو من هذا الدرس التعليمي على قناتنا على YouTube. لذا لا تتردد في مشاهدتها إذا كنت تميل أكثر إلى التعلّم البصري.

في سياق إعادة تشغيل الجلسة، فإن البيانات الوصفية هي كل المعلومات التي لا يولّدها المستخدم، لكنها ترتبط بطريقة ما بذلك المستخدم.

بعبارة أخرى، إذا نقر المستخدم على رابط محدد، أو نفّذ إجراءً معينًا، فهذا ليس بيانات وصفية، بل هو حدث مخصص (راجع الوثائق حول الأحداث المخصصة إذا أردت معرفة المزيد عنها).

ولكن إذا كان هناك علامة تخبرك بأن المستخدم يندرج تحت الخطة المجانية، أو الخطة المدفوعة. أو ربما رمز تتبّع يوضح لك من أين أتى ذلك المستخدم؟ كل هذه بيانات وصفية ويمكنك بسهولة إضافتها إلى جلساتك.

أول ما يجب فعله هو إعداد حقول البيانات الوصفية مباشرة في المنصة.

إذا تخطّيت هذه الخطوة، فلن تتمكن من تسجيل أي معلومات، لذا لا تتخطّاها!

للقيام بذلك، ستنتقل إلى صفحة إعدادات مشروعك من خلال النقر على رمز الترس في أعلى يمين القائمة العلوية:

بمجرد دخولك هناك، انقر على عنصر القائمة Metadata في أقصى يسار شاشتك:

سينقلك ذلك إلى شاشة إعداد البيانات الوصفية. تأكد من تحديد المشروع الصحيح من القائمة المنسدلة وأنشئ العدد الذي تحتاجه من الحقول.

في هذا المثال، أنشأنا 3 حقول لمشروع “e-commerce test”:

• حقل “plan” الذي سيحتوي على الخطة الحالية للمستخدم.
• حقل “utm_source” الذي يحتوي على رمز يحدد من أين يأتي المستخدم.
• وأخيرًا، يحتوي حقل “items_in_cart” على إجمالي عدد العناصر في سلة المستخدم.

الحقل الأخير هو بيانات تعتمد على إجراء المستخدم، وهو ما يختلف عمّا نوصي به. ومع ذلك، في هذا المثال، سترى القيود المفروضة على حقول البيانات الوصفية، ولماذا كان ينبغي أن تكون هذه المعلومة بالذات حدثًا مخصصًا بدلًا من ذلك.

وبعد أن أصبح هذا الإعداد جاهزًا، تكون الخطوة التالية هي إضافة الشيفرة المطلوبة لإرسال البيانات فعليًا كجزء من جلستك.

لإضافة البيانات الوصفية إلى الجلسة، سنستخدم طريقة setMetadata من المتعقّب. يمكنك استخدام هذه الطريقة في أي وقت طوال جلسة المستخدم، فقط ضع في اعتبارك الاعتبارين التاليين:

1. إذا طبّقت عدة قيم على نفس حقل البيانات الوصفية، فلن يُحفظ سوى القيمة الأخيرة كجزء من الجلسة.
2. يجب أن تكون جميع القيم سلاسل نصية (strings). وإلا، فلن تُحفظ. لن يقوم المتعقّب بتحويل القيم إلى سلاسل نصية، لذا كن حذرًا في هذا الشأن.

توضّح الأسهم الحمراء أين أُجريت التحديثات ذات الصلة. يصدّر مزوّد السياق (context provider) هذا دالة تُسمى setMetadata والتي تستدعي بدورها طريقة setMetadata من المتعقّب.

إذا أردت مثالًا عمليًا، يمكنك الاطلاع على هذا المستودع.

والآن كل ما علينا فعله هو استخدام الدالة المُصدَّرة كلما أردنا إعداد حقول البيانات الوصفية.

لأغراض هذا المثال، سنقرر تعيين حقلي utm_source وplan مباشرة من الصفحة الرئيسية، ثم في كل مرة يضيف فيها المستخدم عنصرًا إلى السلة، سنحدّث الحقل الأخير المتبقّي.

في ملف pages/index.tsx، سنضيف الشيفرة التالية:

// inside the main component
const { startTracking, setMetadata } = useContext(TrackerContext)
//...
useEffect(() => {
    async function getProds() {
      await startTracking()
      setMetadata('plan', getPlan()) //addition 
      setMetadata('utm_source', getUTMSource()) //addition
      dispatch(getMakeUpProducts() as any)
    }

    getProds()
  }, [dispatch])

كان معظم ذلك الـ hook موجودًا بالفعل، لكننا أضفنا الإشارة إلى دالة setMetadata ثم الاستدعاءين لها. كلتا الدالتين، getPlan وgetUTMSource، تُعيدان بيانات عشوائية في هذا المثال. بالنسبة لحالة الاستخدام الخاصة بك، سيتعين عليك تنفيذهما وفقًا لذلك.

ستقوم هذه الشيفرة بتعيين قيم البيانات الوصفية هذه عند تحميل الصفحة الرئيسية.

الآن نحتاج إلى إضافة القيمة الأخيرة، وهي عدد العناصر في السلة. لهذا، سننتقل إلى المكوّن ProductSidebar، وهو المكوّن المسؤول عن التحكّم بما يحدث عند النقر على “Add to cart”، وسنضيف hook آخر للتفاعل مع تغيّر عدد عناصر السلة.

useEffect(() => {
    setMetadata('items_in_cart', productsInCart)
  }, [productsInCart])

بالطبع، عليك أيضًا الحصول على دالة setMetadata من مزوّد السياق كما فعلت سابقًا، ولكن بمجرد أن تفعل ذلك، تكون قد انتهيت.

الآن أصبحت البيانات تُحفظ. يمكننا أيضًا رؤية ذلك على المنصة من خلال قائمة الجلسات.

الآن وقد أصبحت البيانات الوصفية تُحفظ داخل جميع عمليات إعادة تشغيل الجلسات، فماذا يمكنك أن تفعل بها؟

حسنًا، بدايةً، يمكنك تصوّرها مباشرة من إعادة التشغيل:

ينبغي أن تبدأ في رؤية حقول البيانات الوصفية في الزاوية العلوية اليمنى من شاشة المُشغّل لديك. في هذا المثال، نرى أن المستخدم لديه خطة Enterprise Edition، وأنه قادم من Reddit، وأن لديه عنصرًا واحدًا فقط مُضافًا إلى السلة.

الأمر القوي الآخر الذي يمكنك فعله بالبيانات الوصفية هو استخدامها كمعيار بحث. باستخدام شريط omnisearch، يمكنك تحديد حقول البيانات الوصفية المخصصة التي أنشأتها كمعايير بحث:

لذا إذا أردت الاطلاع على عمليات إعادة تشغيل Enterprise Edition فقط، يمكنك ببساطة تحديد حقل Plan وتصفيته حسب “ee”، على النحو التالي:

يمكنك أيضًا استخدام شريط omnisearch نفسه عند إنشاء widget للوحة المعلومات (dashboard) الخاصة بك. لذا، لنتابع مع مثال EE، إذا أردت إنشاء لوحة معلومات خاصة بعملاء Enterprise فقط، يمكنك تصفية كل widget مخصص باستخدام السمة “Plan”.

على سبيل المثال، يوضّح الـ widget التالي عدد عملاء Enterprise الذين ينقرون على زر “Add to cart”:

مما ينتج عنه widget يبدو على هذا النحو:

باستخدام حقول البيانات الوصفية، يمكنك تخصيص وتوسيع الرؤى التي تحصل عليها من عمليات إعادة تشغيل جلساتك بالقدر الذي تريده.

يمكن للبيانات الوصفية أن تعزّز بشكل كبير الرؤى التي يمكنك الحصول عليها من عمليات إعادة تشغيل جلساتك، وإعدادها سهل نسبيًا.

تذكّر أن أي معلومة تريد حفظها يجب أن تكون دائمًا على هيئة سلاسل نصية، وإلا فسيتم تجاهلها.

يمكن الاطلاع على الشيفرة المصدرية الكاملة للمشروع النموذجي الذي يستخدم البيانات الوصفية هنا.

إذا واجهت أي مشكلات في أي من خطوات هذه العملية، يُرجى التواصل معنا عبر مجتمعنا على Slack وطرح أسئلتك مباشرة على مطورينا!