أحداث واجهة المتجر في زد: تتبّع المشاهدات والسلة والمشتريات عبر Scripts تطبيقك

لماذا طبقة الأحداث؟

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

هناك نوعان من الـ Scripts:

• Scripts عامة (Global) تُحمَّل في كل صفحة.
• Scripts مرتبطة بحدث (Event-driven) تعمل استجابةً لتصرف المتسوق، مثل مشاهدة منتج أو إضافته إلى السلة أو إتمام الشراء.

الـ Objects العامة: من المتسوق؟

تتوفر ثلاثة Objects في Scope window داخل الصفحة:

• window.customer: العميل المسجّل دخوله، ويحتوي id وname وfirstname وlastname وmobile وemail. ويكون فارغًا إذا لم يسجّل أحد دخوله.
• window.customerAuthState: متاح فور تحميل الصفحة، ويحتوي isAuthenticated وisGuest.
• window.customerAsync: وعد (Promise) يُحلّ ببيانات العميل بعد جلبها، مفيد عندما لا يكون window.customer جاهزًا بعد.

(async function () {
  var auth = window.customerAuthState || {};
  if (!auth.isAuthenticated) return; // guest or logged out

  var customer = (window.customer && window.customer.id)
    ? window.customer
    : await window.customerAsync;

  // use customer.id to map the shopper to your own records
})();

الأحداث السبعة المدعومة

1. Purchase: بعد إتمام عملية شراء ناجحة.
2. Product View: عند مشاهدة المتسوق لمنتج (productViewd).
3. Add to Cart: عند إضافة منتج إلى السلة (productCart).
4. Remove from Cart: عند حذف منتج من السلة (productCart).
5. Start Checkout: عند بدء المتسوق إتمام الطلب.
6. View Item List (جديد): عند مشاهدة قائمة منتجات، مثل صفحة تصنيف أو نتائج بحث.
7. Select Item (جديد): عند نقر المتسوق على منتج في قائمة.

الكتابة غير المألوفة لـ productViewd وproductCart مقصودة، وهي مطابقة لشيفرة زد، فاستخدمها كما هي.

أحداث Product View وAdd to Cart وRemove from Cart تحمل Object منتج واحدًا فيه id وname وsku وcategory وprice وposition (ترتيب العرض)، ويضيف حدثا السلة quantity. ويحمل Select Item Object product (بنفس بنية productViewd) وlistName. أما View Item List فيحمل listName ومصفوفة products فيها item_id وitem_name وitem_sku وcurrency وprice وquantity وitem_category.

Payloads الشراء وبدء الدفع: الحالية والقديمة

يحمل حدث Purchase الحقول order (Object الطلب كاملًا) وtransaction_id (رقم الطلب) وvalue وcurrency ومصفوفة items. المثال التالي مبني من الحقول الموثّقة:

{
  "transaction_id": "order-123",
  "value": 199.98,
  "currency": "SAR",
  "items": [
    {
      "item_id": "product-1",
      "item_name": "Product Name",
      "item_sku": "SKU-123",
      "price": 99.99,
      "quantity": 2,
      "item_category": "Category Name"
    }
  ],
  "order": { }
}

ويستقبل حدث Start Checkout الآن Object cart كاملًا: id وsession_id وproducts (فيها product_id وname وsku وprice وquantity) وproducts_count وproducts_subtotal وtotals وcurrency (الرمز في cart_currency.code) وcoupon.

ولكلا الحدثين شكل قديم (Legacy) موثّق أيضًا. في الشراء القديم تصل مصفوفة مسطّحة transactionItems مع رقم الطلب في id، وفي بدء الدفع القديم تصل حقول مسطّحة مثل cart_id وcart_total وcurrency وitems بعناصر فيها item_id وitem_name وitem_price وitem_quantity. إذا كان الـ Script الخاص بك قد يواجه الشكلين، فوحّدهما أولًا:

function normalizePurchase(evt) {
  if (evt.items) {
    return { orderId: evt.transaction_id, value: evt.value,
             currency: evt.currency, items: evt.items };
  }
  var legacy = evt.transactionItems || [];
  return {
    orderId: evt.id,
    value: legacy.reduce(function (s, i) { return s + Number(i.total || 0); }, 0),
    currency: legacy.length ? legacy[0].currency : undefined,
    items: legacy.map(function (i) {
      return { item_id: i.id, item_name: i.name, item_sku: i.sku,
               price: i.price, quantity: i.quantity, item_category: i.category };
    })
  };
}

إيصال الـ Script الخاص بك عبر Custom Snippets

1. افتح تطبيقك في لوحة الشركاء وانتقل إلى General Settings.
2. اضغط Add Snippet وأدخل شيفرة JavaScript أو CSS.
3. حدّد موضع الـ Script (مثل الـ Header أو التذييل) واضبط أي Parameters مطلوبة.
4. أرسله للمراجعة والاعتماد. ويمكنك تعديله أو حذفه لاحقًا في أي وقت.

في بيئات الجوال والتطبيقات الهجينة، يوضح ملف Scripts الموثّق (GET /api/v1/scripts) طريقة تجميع الـ Scripts: external_scripts فيه روابط الـ Scripts البعيدة المعتمدة، وapp_scripts_bundle فيه الـ Scripts المضمّنة تحت مفاتيح محجوزة: head وglobal_head_script وpurchase_event وproduct_details_event وadd_to_cart_event وremove_from_cart_event وstart_checkout_event، إضافة إلى params لـ IDs مثل IDs البكسل.

قد يعمل الـ Script الخاص بك على ثيم Vitrin أو على ثيم قديم. تحقّق من window.vitrin، فقيمته true فقط في متاجر Vitrin. وإذا كان الـ Script الخاص بك البعيد يستخدم Parameters في الرابط، فسيصلك vitrin=true في متاجر Vitrin، فتقدّم نسخة أحدث دون فحص داخل الـ Script:

// Inside your script
var hasVitrin = window.vitrin == true;

// How Zid calls a remote script URL:
//   Vitrin: {script_url}?store={store_uuid}&vitrin=true
//   Legacy: {script_url}?store={store_uuid}

لمطوري الثيمات: zidTracking

يوثّق قسم JS Integration حدثَي تتبّع يستدعيهما مطور الثيم يدويًا، وكلاهما متاح عبر window.zidTracking:

• zidTracking.sendGaSelectItemEvent({ product, listName, listId, index }) عند نقر المتسوق على منتج في قائمة، مثل شريط المنتجات ذات الصلة. الحقل الوحيد المطلوب هو product، وقيمة listName الافتراضية "products"، وindex يبدأ من الصفر. ويُرسل باسم select_item إلى GA4 وGTM.
• zidTracking.sendGaCartDetailViewedEvent({ cart }) عند عرض محتوى السلة خارج صفحة السلة، مثل سلة مصغّرة أو درج جانبي. ويُرسل باسم view_cart إلى GA4 وGTM، وباسم ViewCart إلى Facebook.

// Product card click in a list
zidTracking.sendGaSelectItemEvent({
  product: product,
  listName: 'Related Products',
  listId: 'related_products_pdp',
  index: 2
});

// Cart drawer opened (not on /cart)
const cart = await zid.cart.get();
window.zidTracking?.sendGaCartDetailViewedEvent({ cart });