مرجع الأحداث

أرسل الأسماء كما هي مكتوبة تمامًا. وأسماء الخصائص بصيغة snake_case في كل الصفحة. وكل ما لم يُوسم بأنه مطلوب فهو اختياري، ولا مانع من إضافة خصائص من عندك — تُحفظ مع البقية.

لا تحتاج الثلاثين كلها. أغلب المتاجر ترسل خمسة: Product Viewed وProduct Added وCheckout Started وOrder Completed وProducts Searched.

كائن المنتج

عدة أحداث تحمل مصفوفة products، وكل عنصر فيها له الشكل نفسه:

{
  product_id: "P-4471",   // required
  sku: "WH-BLK-01",
  name: "Wireless Headphones",
  price: 199.99,
  quantity: 1,
  currency: "SAR",
  category: "Electronics",
  brand: "AudioTech",
  variant: "Black",
  position: 3,
  coupon: "SUMMER20",
  url: "https://store.example.com/p/headphones",
  image_url: "https://store.example.com/i/headphones.jpg"
}

price وquantity يستحقان التعبئة حتى حين يكونان اختياريين: فحين يصل طلب بلا إجمالي، يعيد فلوفاي بناء الإيرادات بجمع price × quantity على عناصر المصفوفة.

المال

أرسل value مع كل ما يحمل مبلغًا؛ وrevenue مقبول مرادفًا له. وأرسل currency بجانبه دائمًا — مبلغ بلا عملة لا يمكن مقارنته بإنفاقك الإعلاني.

التصفّح

filters مصفوفة من { type, value }. وsorts مصفوفة من { field, direction }، والاتجاه فيها إما asc أو desc.

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

العروض الترويجية

السلة والدفع

step رقم صحيح يبدأ من 1. وsource في Product Added يقول من أين جاءت الإضافة: product_page أو wishlist أو search أو listing أو recommendation أو other.

flowfyanalytics.track("Checkout Started", {
  checkout_id: "CHK-8821",
  currency: "SAR",
  value: 523.17,
  subtotal: 489.98,
  shipping: 22.00,
  tax: 11.19,
  products: [
    { product_id: "P-4471", name: "Wireless Headphones", price: 199.99, quantity: 1 },
    { product_id: "P-2210", name: "Phone Case", price: 145.00, quantity: 2 }
  ]
});

الطلبات

أربعة أحداث تتبع الطلب من لحظة الدفع حتى مصيره الأخير. Order Completed يفتح الطلب، والثلاثة الأخرى تنقله من حالة إلى أخرى. ويحتفظ فلوفاي بآخر حالة لكل طلب، ويستخدمها ليُخرج من إيراداتك الطلبات الملغاة والمستردة والمرتجعة.

Order Completed هو الحدث الذي يستحق ضبطه بدقة تامة — فهو ما تُحسّن عليه كل منصة إعلانية. أما الثلاثة الأخرى فلا تُمرَّر إلى أي منصة إعلانية أبدًا؛ عملها الوحيد تصحيح أرقام فلوفاي نفسه.

order_id هو ما يجعل الطلب طلبًا واحدًا. بدونه لا يستطيع فلوفاي التفريق بين حدث تكرّر وعملية شراء ثانية، فتُحتسب النسخة المكررة مرة أخرى، ولا يجد أي تحديث لاحق طلبًا يرتبط به. أرسل order_id نفسه في الأحداث الأربعة. وtransaction_id مقبول بديلًا عنه. وorder_id بقيمة 0 يُعامَل كأنه غير موجود.

اكتب الاسم Order Cancelled بحرفَي L. ومع ذلك يُقبل Order Canceled بحرف واحد، ويؤدي العمل نفسه. ولا يهم في هذه الأسماء الأربعة حجم الأحرف ولا المسافات ولا الشرطة السفلية ولا الشرطة، فـ OrderCompleted وorder_cancelled وOrder-Refunded كلها تُعرف — لكن أرسل الأسماء كما هي مكتوبة هنا.

الحالات السبع

Order Completed

{
  "type": "track",
  "event": "Order Completed",
  "userId": "customer_9931",
  "messageId": "8f14e45f-ea0a-4c1f-9f2c-3b7d1a0e5c62",
  "timestamp": "2026-09-18T14:02:11.000Z",
  "properties": {
    "order_id": "ORD-12345",
    "currency": "SAR",
    "value": 523.17,
    "subtotal": 489.98,
    "shipping": 22.00,
    "tax": 11.19,
    "coupon": "SUMMER20",
    "payment_method": "mada",
    "products": [
      { "product_id": "P-4471", "name": "Wireless Headphones", "price": 199.99, "quantity": 1 },
      { "product_id": "P-2210", "name": "Phone Case", "price": 145.00, "quantity": 2 }
    ]
  }
}

Order Updated

أرسله كلما تقدّم الطلب خطوة — أُكّد، أو شُحن، أو وصل، أو أُرجع.

تقبل status القيم confirmed أو shipped أو delivered أو cancelled أو refunded أو returned. وتقبل كذلك رموز الحالات الخاصة بسلة وزد، ويحوّلها فلوفاي بنفسه — راجع الجدولين أدناه. ولا يهم حجم الأحرف ولا المسافات حولها. أما placed فلا تغيّر شيئًا هنا: وحده Order Completed يُنشئ الطلب. أي قيمة أخرى — processing أو اسم حالة بالعربية أو حالة من منصة أخرى — تُحفظ، لكن حالة الطلب لا تتغيّر.

الحالة الجديدة مكانها status. أما خاصية current_status فتُحفظ، لكنها لا تُقرأ.

{
  "type": "track",
  "event": "Order Updated",
  "userId": "customer_9931",
  "messageId": "0b7c2d9e-5a41-4f3e-9d6b-7e2a1c4f8b10",
  "timestamp": "2026-09-20T09:15:42.000Z",
  "properties": {
    "order_id": "ORD-12345",
    "status": "shipped",
    "order_placed_at": "2026-09-18T14:02:11.000Z",
    "previous_status": "confirmed",
    "currency": "SAR",
    "value": 523.17,
    "payment_method": "mada"
  }
}

Order Cancelled

{
  "type": "track",
  "event": "Order Cancelled",
  "userId": "customer_9931",
  "messageId": "c3e1f7a2-8d4b-4b6a-a1f0-2e9d5c7b3a41",
  "timestamp": "2026-09-19T11:40:03.000Z",
  "properties": {
    "order_id": "ORD-12345",
    "order_placed_at": "2026-09-18T14:02:11.000Z",
    "currency": "SAR",
    "value": 523.17,
    "cancellation_reason": "Customer changed their mind",
    "previous_status": "confirmed"
  }
}

Order Refunded

في الاسترجاع الجزئي، أرسل السطور المُرجَعة وحدها والمبلغ المسترجع فعلًا. وفي الاسترجاع الكامل يمكنك حذف مصفوفة products بالكامل. ولا يفترض فلوفاي أبدًا أن الاسترجاع كان للمبلغ كاملًا.

{
  "type": "track",
  "event": "Order Refunded",
  "userId": "customer_9931",
  "messageId": "5d2a8f61-3c9e-4e07-b8a4-91f6e0d2c7b5",
  "timestamp": "2026-09-27T16:22:48.000Z",
  "properties": {
    "order_id": "ORD-12345",
    "order_placed_at": "2026-09-18T14:02:11.000Z",
    "refund_id": "RF-2207",
    "refund_amount": 290.00,
    "currency": "SAR",
    "reason": "Damaged in transit",
    "products": [
      { "product_id": "P-2210", "name": "Phone Case", "price": 145.00, "quantity": 2 }
    ]
  }
}

متى أُنشئ الطلب

تُسجَّل كل نتيجة تحت يوم إنشاء الطلب، لا يوم تغيّره: فالإلغاء الذي يصل اليوم لطلب من الأسبوع الماضي يصحّح أرقام الأسبوع الماضي. لذلك تحتاج Order Updated وOrder Cancelled وOrder Refunded إلى وقت إنشاء الطلب الأصلي. ويبحث عنه فلوفاي بهذا الترتيب:

1. order_placed_at في الحدث.
2. created_at في الحدث.
3. createdAt في الحدث.
4. حدث Order Completed للـ order_id نفسه، أُرسل في الدفعة نفسها أو قبلها.

وقيمة order_placed_at التي يتعذّر على فلوفاي قراءتها تُعامَل كأنها غائبة، فينتقل إلى الخطوة التالية. وإن لم يجد أيًّا منها، يُحفظ الحدث لكنه لا يُحتسب في نتائج الطلبات. ولا يُؤرَّخ أبدًا بوقت إرساله. أرسل الوقت بصيغة ISO 8601 مع المنطقة الزمنية، مثل 2026-09-18T14:02:11Z؛ وتُقبل كذلك ثواني Unix أو أجزاء الألف منها، حتى لو أُرسلت نصًّا. والطلبات التي أُنشئت قبل وصول الحدث بأكثر من 400 يوم لا تُحتسب، وكذلك الطلبات المؤرَّخة بأكثر من يوم واحد بعد وصول الحدث إلى فلوفاي.

طرق الدفع

بـ payment_method يميّز فلوفاي طلب الدفع عند الاستلام من الطلب المدفوع مسبقًا. ولا يهم حجم الأحرف، ولا الفرق بين المسافة والشرطة والشرطة السفلية — فـ Credit Card وcash-on-delivery وcredit_card كلها تعمل. وهذه هي القيم المعتمدة:

أي قيمة أخرى تُحفظ كما أرسلتها وتُصنَّف ضمن «أخرى».

حالات سلة وزد

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

سلة — قيمة slug للحالة:

سلة تكتب canceled بحرف L واحد، وحالة فلوفاي بحرفين. وللحالة المخصّصة، أرسل الحالة الأساسية التي بُنيت عليها.

زد — قيمة order_status.code:

زد تستخدم cancelled وcanceled معًا؛ فعاملهما معاملة واحدة. وpayment_status في زد مهم أيضًا: refunded تعني refunded — إلا إن كانت status بالفعل cancelled، فالإلغاء له الأولوية — وvoided تعني cancelled. أما pending وpaid فلا تغيّران الحالة.

لكن فلوفاي لا يقرأ payment_status. فعند استرداد طلب في زد أو إبطاله، أرسل Order Refunded أو Order Cancelled، أو أرسل status بقيمة refunded أو cancelled.

حالة initial في زد لا تغيّر شيئًا — فالطلب لم يُنشأ بعد.

الكوبونات

coupon هو الرمز الذي كتبه المشتري. وcoupon_id وcoupon_name وdiscount اختيارية.

قائمة الأمنيات

انتبه إلى to وfrom بالحروف الصغيرة في هذين الاسمين.

وحين ينقل المشتري شيئًا من قائمة الأمنيات إلى السلة، أرسل Product Added مع source: "wishlist".

المشاركة

share_via واحد من email أو whats_app أو sms أو social أو link أو other. وفي Cart Shared يكفي أن يحمل كل عنصر في products قيمة product_id فقط.

التقييمات

rating رقم صحيح من 1 إلى 5.

العملاء المحتملون والنماذج

lead_source واحد من contact_form أو lead_form أو whats_app أو phone أو live_chat أو quote_request أو callback_request أو newsletter أو other.

لا تضع اسم المشتري ولا بريده ولا رقمه في خصائص Lead. أرسلها عبر identify بدلًا من ذلك، حيث تُشفَّر قبل تمريرها.

أي الأحداث تُحتسب تحويلات

تُعامَل هذه الأحداث تحويلات في التقارير: Order Completed وCheckout Completed وPurchase وLead وSign Up وForm Submitted وContact وCompleteRegistration.

ومنها ثلاثة فقط تحمل إيرادات: Order Completed وCheckout Completed وPurchase. أما حدث Lead الذي يصادف أن يحمل مصفوفة products، فلن تُجمع تلك المصفوفة يومًا ضمن إيراداتك — وهذا ما يبقي تكلفة العميل المحتمل صادقة.