التتبّع

ست دوال تغطي كل شيء. track وidentify هما ما ستستخدمه فعلًا.

track

flowfyanalytics.track(eventName, properties)

flowfyanalytics.track("Product Viewed", {
  product_id: "P-4471",
  name: "Wireless Headphones",
  price: 199.99,
  currency: "SAR",
  category: "Electronics"
});

اسم الحدث يُطابَق مع قائمة ثابتة. Order Completed يصبح عملية شراء في ميتا وتيك توك وسناب شات؛ والاسم الذي لا يعرفه فلوفاي يُخزَّن مع ذلك، لكن لن تفعل به أي منصة إعلانية شيئًا. استخدم مرجع الأحداث.

المطابقة لا تفرّق بين الحروف الكبيرة والصغيرة، فـ order completed تُحتسب شراءً أيضًا — لكن الأسماء تُخزَّن تمامًا كما أرسلتها، وميتا تطابق أحداثها القياسية بحساسية لحالة الأحرف. أرسلها كما هي مكتوبة في المرجع.

أسماء الخصائص بصيغة snake_case. إرسال productId بدل product_id لن ينتج عنه خطأ؛ الخاصية ببساطة لا تُقرأ أبدًا.

identify

flowfyanalytics.identify(userId, traits)

flowfyanalytics.identify("customer_9931", {
  email: "sara@example.com",
  phone: "+966500000000",
  first_name: "Sara",
  last_name: "Al-Otaibi"
});

استدعِها عند تسجيل الدخول أو التسجيل أو تحديث البيانات — وفي كل تحميل صفحة تعرف فيه من المشتري، لأن المكتبة لا تحمل الهوية عبر الجلسات من تلقاء نفسها.

إلى أن تستدعيها، يُتتبَّع المشتري تحت معرّف مجهول مولَّد. identify يربط الأحداث السابقة له بالشخص، وبهذا يُحتسب من تصفّح على الجوال واشترى من الكمبيوتر مرة واحدة لا مرتين.

email وphone أهم من غيرهما: ميتا وتيك توك وسناب شات تستخدمهما لمطابقة التحويل بمشاهدة الإعلان، وتُشفَّر قبل أن تغادر فلوفاي.

الخصائص الشائعة هي email وphone وfirst_name وlast_name وname وusername وage وbirthday وgender وavatar وtitle وcreated_at، وaddress ككائن متداخل يضم street_address وcity وstate وpostal_code وcountry. وأي شيء تضيفه غير ذلك يُحفظ كما هو.

page

flowfyanalytics.page();
flowfyanalytics.page("Catalogue", "Headphones");
flowfyanalytics.page({ path: "/products/headphones", title: "Headphones" });

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

router.afterEach((to) => {
  flowfyanalytics.page({ path: to.fullPath, title: document.title });
});

الرابط والمسار والعنوان والمُحيل وأي معطيات UTM تُملأ نيابة عنك.

group و alias و reset

flowfyanalytics.group("company_88", { name: "Alpha Trading", plan: "wholesale" });
flowfyanalytics.alias("customer_9931", "temp_44f0");
flowfyanalytics.reset();

group يربط المشتري بشركة، وهو مفيد للبيع بالجملة. alias يدمج معرّفين لشخص واحد. reset يمسح الهوية المحفوظة ويصدر معرّفًا مجهولًا جديدًا — استدعِها عند تسجيل الخروج، وإلا ورث المشتري التالي على جهاز مشترك هوية من سبقه.

ما تجمعه المكتبة نيابة عنك

لا شيء من هذا يحتاج إلى إرسال. يُرفق بكل حدث تلقائيًا:

• الصفحة — الرابط والمسار والعنوان والمُحيل ونطاق المُحيل ونص البحث وأول مُحيل في الجلسة
• الحملة — utm_source وutm_medium وutm_campaign وutm_term وutm_content
• الشاشة — العرض والارتفاع وكثافة البكسل والعرض والارتفاع الداخليان
• اللغة والمنطقة الزمنية
• وكيل المستخدم، وعنوان IP الذي يحوّله فلوفاي إلى دولة

معرّفات النقر من منصات الإعلانات — fbclid وttclid وsc_click_id والكوكيز التابعة لها — تُقرأ من الرابط أيضًا. هي ما يربط الطلب بالإعلان الذي أنتجه، فلا تحذف هذه المعطيات حين ينظّف موجّهك الروابط.

انتظار المكتبة

الاستدعاءات المنتظرة تُعاد بالترتيب بمجرد تحميل المكتبة، فنادرًا ما تحتاج هذا. حين تريد قراءة قيمة:

flowfyanalytics.ready(function () {
  console.log(flowfyanalytics.getAnonymousId());
});

وgetUserId() وgetUserTraits() وgetSessionId() وgetGroupId() متاحة على الكائن نفسه.

الموافقة

إن كنت تحجب التتبّع خلف إشعار كوكيز، حمّل المكتبة مع تفعيل الموافقة المسبقة، واستدعِ consent() بمجرد قبول المشتري:

flowfyanalytics.consent();

حتى ذلك الحين تُحتجَز الأحداث بدل إرسالها. وإن لم تُهيّئ إعداد موافقة، تتبّع المكتبة فورًا.