مرجع الأحداث

أرسل الأسماء كما هي مكتوبة تمامًا. وأسماء الخصائص بصيغة 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 هو الحدث الذي يستحق ضبطه بدقة تامة — فهو ما تُحسّن عليه كل منصة إعلانية.

flowfyanalytics.track("Order Completed", {
  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_id هو ما يجعل الطلب طلبًا واحدًا. بدونه لا يستطيع فلوفاي التفريق بين حدث تكرّر وعملية شراء ثانية، فتُحتسب النسخة المكررة مرة أخرى. وtransaction_id مقبول بديلًا عنه. وorder_id بقيمة 0 يُعامَل كأنه غير موجود.

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

الكوبونات

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، فلن تُجمع تلك المصفوفة يومًا ضمن إيراداتك — وهذا ما يبقي تكلفة العميل المحتمل صادقة.