تتبع التجارة الإلكترونية

تتضمن Joryio SDKs تتبعاً مدمجاً للتجارة الإلكترونية لتفاعل المنتجات ونشاط السلة ومعاملات الشراء. يعمل المتتبع بالطريقة نفسها على كل منصة: الدوال نفسها وأسماء الأحداث القياسية نفسها ودلالات الخصائص نفسها؛ ويختلف فقط بناء اللغة.

اختر منصتك في أي مثال؛ يتزامن الاختيار في الصفحة كلها. للتثبيت والإعداد، راجع Web SDK وiOS SDK وAndroid SDK وReact Native SDK. لا يملك React Native متتبعاً مستقلاً؛ استخدم استدعاءات Joryio.track() المكافئة.

اصطلاح تسمية المعرّفات

معرّفك	الوصف	المثال
`productId`	معرّف منتجك، SKU أو معرّف من منصة التجارة	`"SKU-12345"`
`orderId`	معرّف طلبك أو رقمه في المنصة	`"ORD-2024-001"`
`userId`	معرّف المستخدم، يمرر إلى `identify()`	`"user-123"`

استخدم معرّفاتك الطبيعية؛ لا تحتاج إلى بادئات خاصة.

تهيئة متتبع التجارة الإلكترونية

Web (JS)
iOS (Swift)
Android (Kotlin)
React Native

// Get the e-commerce tracker from your SDK instance
const ecommerce = joryio.ecommerce({
  currency: 'USD' // Default currency for all events
});

let ecommerce = Joryio.shared.ecommerce(config: EcommerceConfig(currency: "USD"))

import io.joryio.sdk.ecommerce.*
val ecommerce = Joryio.getInstance().ecommerce(EcommerceConfig(currency = "USD"))

// React Native has no dedicated tracker. Send the standard events with Joryio.track()
// and include currency on each monetary event.
import Joryio from '@joryio/react-native-sdk';

تتبع مشاهدات المنتجات والبحث

استخدم viewProduct عند عرض صفحة منتج، وviewCategory عند عرض فئة، وsearch عند البحث. تحمل رؤية المنتج productId وname وprice ويمكنها حمل category وbrand وimageUrl وurl.

ecommerce.viewProduct({
  productId: 'SKU-12345',
  name: 'Classic Blue T-Shirt',
  price: 29.99,
  category: 'Clothing/T-Shirts',
  brand: 'Acme Apparel',
  imageUrl: 'https://example.com/images/blue-tshirt.jpg',
  url: 'https://example.com/products/blue-tshirt'
});
ecommerce.viewCategory('tshirts', 'T-Shirts');
ecommerce.search('blue shirts', 42);

في React Native أرسل الأحداث المكافئة:

Joryio.track('Product Viewed', {
  product_id: 'SKU-12345', name: 'Classic Blue T-Shirt', price: 29.99,
  category: 'Clothing/T-Shirts', brand: 'Acme Apparel',
  image_url: 'https://example.com/images/blue-tshirt.jpg',
  url: 'https://example.com/products/blue-tshirt', currency: 'USD',
});
Joryio.track('Product List Viewed', { category_id: 'tshirts', category_name: 'T-Shirts' });
Joryio.track('Products Searched', { query: 'blue shirts', result_count: 42 });

تتبع نشاط السلة

استخدم addToCart لإضافة عنصر وremoveFromCart لإزالته وupdateCart لاستبدال السلة كلها. يمرر كل عنصر productId وname وprice وquantity، ويمكن تمرير قيمة السلة الحالية.

ecommerce.addToCart({
  productId: 'SKU-12345', name: 'Classic Blue T-Shirt', price: 29.99,
  quantity: 1, variantId: 'var-medium', sku: 'BTS-001-M'
}, 59.98);
ecommerce.removeFromCart({ productId: 'SKU-12345', name: 'Classic Blue T-Shirt', price: 29.99 }, 1);
ecommerce.updateCart([
  { productId: 'SKU-12345', name: 'Blue T-Shirt', price: 29.99, quantity: 2 },
  { productId: 'SKU-67890', name: 'Black Jeans', price: 49.99, quantity: 1 }
], 109.97);

في React Native استخدم Product Added وProduct Removed وCart Updated، مع خصائص wire بصيغة snake_case مثل product_id وitem_total وcart_value وcurrency.

تتبع مسار الدفع

استخدم startCheckout(items, cartValue) عندما يبدأ المستخدم الدفع، وaddPaymentInfo(paymentMethod) عندما يضيف وسيلة الدفع.

ecommerce.startCheckout([
  { productId: 'SKU-12345', name: 'Blue T-Shirt', price: 29.99, quantity: 2 },
  { productId: 'SKU-67890', name: 'Black Jeans', price: 49.99, quantity: 1 }
], 109.97);
ecommerce.addPaymentInfo('credit_card');

تكون أحداث React Native المكافئة Checkout Started وPayment Info Entered، مع items وitem_count وvalue وcurrency وpayment_method.

تتبع المشتريات

استخدم purchase() عند إتمام الطلب. مرّر رقم الطلب وبنود الطلب والقيمة والعملة، ويمكن إضافة الشحن والضريبة والخصم والقسيمة.

ecommerce.purchase({
  orderId: 'ORD-2024-001',
  items: [
    { productId: 'SKU-12345', name: 'Classic Blue T-Shirt', price: 29.99, quantity: 2, category: 'Clothing', brand: 'Acme' },
    { productId: 'SKU-67890', name: 'Black Jeans', price: 49.99, quantity: 1 }
  ],
  value: 109.97, currency: 'USD', shipping: 5.99, tax: 8.80,
  discount: 10.00, coupon: 'SAVE10'
});

يجب تقديم البنود

تتطلب purchase() تمرير بنود الطلب صراحة. لا تخزن SDK حالة السلة في العميل ولا تجلب العناصر تلقائياً من السلة المتتبعة أو الخادم. يضمن ذلك الدقة لأن صفحة أو شاشة تأكيد الطلب تعرف العناصر التي اشتريت بالضبط.

في React Native استخدم Joryio.ecommerce.purchase()، الذي يرسل Order Completed بالمفتاحين اللذين تقرؤهما تقارير الإيرادات: orderId وtotal (مع currency والعناصر).

تتبع تغييرات حالة الطلب

استخدم الدوال التالية لإرسال تغيير الحالة:

ecommerce.orderFulfilled('ORD-2024-001', '1Z999AA10123456784', 'UPS');
ecommerce.orderDelivered('ORD-2024-001');
ecommerce.orderCancelled('ORD-2024-001', 'Customer requested');
ecommerce.orderRefunded('ORD-2024-001', 29.99, 'Product defective');

تطابقها في React Native الأحداث Order Fulfilled وOrder Delivered وOrder Cancelled وOrder Refunded، مع order_id وtracking_number وcarrier وreason أو refund_amount حسب الحالة.

تتبع قائمة الرغبات والمشاركة

ecommerce.addToWishlist({ productId: 'SKU-12345', name: 'Classic Blue T-Shirt', price: 29.99 });
ecommerce.shareProduct({ productId: 'SKU-12345', name: 'Classic Blue T-Shirt' }, 'facebook');

تتوفر في iOS وAndroid أيضاً removeFromWishlist وshareProduct. في React Native استخدم Product Added to Wishlist وProduct Removed from Wishlist وProduct Shared بالخصائص product_id وname وprice وcurrency وshare_method.

تتبع القسائم

ecommerce.applyCoupon('SAVE10', 10.00, 'percentage');
ecommerce.removeCoupon('SAVE10');

في React Native استخدم Coupon Applied مع coupon_code وdiscount_amount وdiscount_type، وCoupon Removed مع coupon_code.

تتبع التقييمات

ecommerce.submitReview('SKU-12345', 5, 'Great quality shirt!');

في React Native أرسل Product Reviewed بالخصائص product_id وrating وreview_text.

أحداث التجارة الإلكترونية القياسية

اسم الحدث	الوصف
`Product Viewed`	عرض المستخدم صفحة منتج
`Product List Viewed`	عرض المستخدم صفحة فئة
`Products Searched`	بحث المستخدم عن منتجات
`Product Added`	إضافة عنصر إلى السلة
`Product Removed`	إزالة عنصر من السلة
`Cart Updated`	تغير محتويات السلة
`Checkout Started`	بدأ المستخدم الدفع
`Payment Info Entered`	أضاف المستخدم وسيلة دفع
`Order Completed`	اكتمل الطلب
`Order Fulfilled`	شُحن الطلب
`Order Delivered`	سُلّم الطلب
`Order Cancelled`	أُلغي الطلب
`Order Refunded`	استُرد الطلب
`Product Added to Wishlist`	إضافة المنتج إلى قائمة الرغبات
`Product Removed from Wishlist`	إزالة المنتج من قائمة الرغبات
`Product Shared`	مشاركة المنتج
`Coupon Applied`	تطبيق رمز قسيمة
`Coupon Removed`	إزالة رمز قسيمة
`Product Reviewed`	إرسال تقييم منتج

React Native

لا تتضمن React Native SDK متتبع تجارة إلكترونية مستقلاً. ترسل تطبيقات React Native الأحداث القياسية نفسها تماماً باستدعاء Joryio.track() وبأسماء الأحداث وخصائص wire نفسها التي تطلقها متتبعات SDK الأخرى. تحوّل المتتبعات مدخلات camelCase إلى خصائص أحداث snake_case على السلك؛ وتعرض الأمثلة أعلاه استدعاءات Joryio.track() المكافئة.

عندما يرسل متجر (Shopify وWooCommerce وMagento) أو واجهة Orders API طلباتك، يُطلق Joryio بنفسه Order Refunded وOrder Cancelled - فلا تستدعِ أيضًا orderRefunded / orderCancelled لتلك الطلبات، وإلا سُجل كل استرداد مرتين. تستخدم أحداث الخادم المفاتيح نفسها order_id وrefund_amount وreason التي تستخدمها أدوات التتبع، فيطابق شرط رحلة واحد كليهما. راجع أحداث الاسترداد والإلغاء.

الوسائط المطلوبة

يرفض كل متتبِّع الاستدعاء الناقص بالطريقة نفسها في كل SDK: يسجّل تحذيرًا ولا يرسل شيئًا - لا يرسل أبدًا حدثًا بمعرّف فارغ أو بمبلغ صفري قد يحسبه تقرير الإيرادات حقيقيًا. لا يرمي أي استدعاء استثناءً.

الاستدعاء	المطلوب
`viewProduct`, `removeFromCart`, `addToWishlist`, `removeFromWishlist`	منتج له `productId` و`price` محدود
`addToCart`	عنصر له `productId` و`price` محدود
`shareProduct`	منتج كما سبق، و`shareMethod`
`viewCategory`	`categoryId` و`categoryName`
`search`	`query`
`cartViewed`, `updateCart`, `startCheckout`	مصفوفة `items`، لكل عنصر `productId` و`price` محدود، و`cartValue` محدود
`addPaymentInfo`	`paymentMethod`
`purchase`	`orderId`، ومصفوفة `items` (يجوز أن تكون فارغة؛ كل عنصر كما سبق) و`value` محدود
`orderFulfilled`, `orderDelivered`, `orderCancelled`, `orderRefunded`	`orderId`
`applyCoupon`, `removeCoupon`	`couponCode`
`submitReview`	`productId`

يُعدّ المعرّف أو التسمية الفارغة أو التي تحتوي على مسافات فقط مفقودة. يمكن حذف المبلغ الاختياري - cartValue في addToCart، وshipping وtax وdiscount في الطلب، وrefundAmount، وdiscountAmount - لكن أي مبلغ تمرّره يجب أن يكون رقمًا محدودًا: القيمة NaN أو اللانهاية ترفض الاستدعاء كله بدلًا من إرساله دون ذلك المبلغ.

أما الخصائص المخصصة التي تمررها معها فتتبع القاعدة العامة: تُسقط القيمة NaN أو اللانهائية فيها مع تحذير ويُرسل الاستدعاء بدون ذلك المفتاح - راجع الخصائص وأنواع البيانات.

يستخدم Unity أسماء بصيغة PascalCase (ViewProduct، ProductId)؛ والقواعد نفسها.

الخطوات التالية

Web SDK - التثبيت والإعداد ومرجع API الكامل.
iOS SDK - دمج iOS SDK.
Android SDK - دمج Android SDK.
React Native SDK - دمج React Native SDK.
الأحداث المخصصة - تتبع أحداث مخصصة.
E-Commerce API - تكامل التجارة الإلكترونية من الخادم.

اصطلاح تسمية المعرّفات​

تهيئة متتبع التجارة الإلكترونية​

تتبع مشاهدات المنتجات والبحث​

تتبع نشاط السلة​

تتبع مسار الدفع​

تتبع المشتريات​

تتبع تغييرات حالة الطلب​

تتبع قائمة الرغبات والمشاركة​

تتبع القسائم​

تتبع التقييمات​

أحداث التجارة الإلكترونية القياسية​

React Native​

الوسائط المطلوبة​

الخطوات التالية​