توصيات المنتجات على الموقع

يمكن لـ Web SDK عرض توصيات المنتجات على موقعك الإلكتروني: في صفحة المنتج، أو في سلة التسوق، أو في صفحة الكتالوج، أو في صفحة 404. تأتي المنتجات من كتالوج المنتجات الخاص بالتطبيق. هناك طريقتان لعرضها:

• Widget: أضف عنصرًا يحمل السمة data-pw-recommendations، وسيملؤه SDK بشبكة من المنتجات.
• Headless API: استدعِ Pushwoosh.recommendations.fetch واعرض المنتجات باستخدام الترميز الخاص بك.

مثال حي على ذلك هو متجر Pushwoosh التجريبي على pushon.pushwoosh.com. يحتوي على كتلة widget في صفحة 404 وكتل headless في صفحة المنتج وفي سلة التسوق.

المتطلبات الأساسية

• Web SDK 3.96.0 أو أحدث، يتم تحميله من CDN الخاص بـ Pushwoosh كما هو موضح في دليل Web push SDK 3.0. لا تتضمن حزمة npm web-push-notifications التوصيات بعد.
• منتجات في كتالوج المنتجات الخاص بالتطبيق.
• تفعيل التوصيات على الموقع للتطبيق. راجع تفعيل التوصيات على الموقع.

تفعيل التوصيات على الموقع

يتم تفعيل كل تطبيق على حدة، لأن الموجز الذي يقدم الكتل عام ولا يتطلب API token. وإلى أن يتم التفعيل، يرد الموجز بخطأ وتبقى الكتل فارغة.

لتفعيل التوصيات على الموقع في لوحة التحكم:

1. انتقل إلى Content → Product Catalog للتطبيق.
2. انقر على On-site recommendations.
3. فعّل Show recommendations on my website.
4. في Website domains، أدخل نطاقات المواقع الإلكترونية التي ستعرض الكتل، نطاقًا واحدًا في كل سطر. على سبيل المثال، shop.example.com.
5. انقر على Save.

بعد الحفظ:

• يعرض Website domains النطاقات كما خزّنها Pushwoosh: مع إضافة https://، وبأحرف صغيرة، ودون تكرار. تحقق من القائمة بحثًا عن أخطاء إملائية.
• لا يتم تحميل الكتل إلا على المواقع الإلكترونية المدرجة. إذا تركت Website domains فارغًا، فسيتم تحميل الكتل على أي موقع إلكتروني.
• يسري التغيير خلال دقيقة واحدة.

إذا لم تتمكن من الوصول إلى لوحة التحكم، فاطلب من دعم Pushwoosh أو من Customer Success Manager الخاص بك تفعيل التوصيات على الموقع للتطبيق. أرفق رمز التطبيق ونطاقات مواقعك الإلكترونية.

استراتيجيات التوصية

الاستراتيجية	ما تعرضه	المتطلبات
viewed	المنتجات التي شاهدها هذا الزائر مؤخرًا. بالنسبة للزائر الذي سجّل الدخول، تظهر أولًا المنتجات التي شاهدها تحت user ID الخاص به.	مشاهدات المنتجات المرسلة باستخدام trackProductView.
bestsellers_30d	المنتجات الأكثر مبيعًا في التطبيق خلال آخر 30 يومًا. يتم تخطي المنتجات النافدة.	أحداث الطلبات مع عناصر الطلب.
also_bought	المنتجات التي يتم شراؤها أو مشاهدتها غالبًا مع منتج معين. يتم تخطي المنتجات النافدة.	مشاهدات المنتجات المرسلة باستخدام trackProductView، أو أحداث الطلبات، أو أي أحداث أخرى تحمل معرّف منتج. راجع تتبع نشاط المنتج. يحتاج الطلب إلى معرّف منتج.

عندما لا يكون لدى استراتيجية ما شيء لعرضه، يقدم الموجز الاستراتيجية الاحتياطية بدلًا منها. الاستراتيجية الاحتياطية هي bestsellers_30d افتراضيًا. اضبطها على none للحصول على استجابة فارغة بدلًا من ذلك. تخبرك الاستجابة دائمًا بالاستراتيجية التي تم تقديمها فعليًا، حتى تتمكن من تغيير عنوان الكتلة.

تتبع مشاهدات المنتجات

تستخدم الاستراتيجيتان viewed وalso_bought مشاهدات المنتجات. في كل صفحة منتج، استدعِ trackProductView بعد أن يصبح SDK جاهزًا:

Pushwoosh.push(() => {
  Pushwoosh.trackProductView({
    id: 'SKU-123',
    name: 'Linen shirt',
    price: 49.9,
    currency: 'USD',
    category: 'Shirts',
    url: 'https://shop.example.com/linen-shirt',
    imageUrl: 'https://shop.example.com/img/linen-shirt.jpg',
  });
});

الحقل id فقط هو المطلوب. استخدم معرّف المنتج نفسه الموجود في كتالوج المنتجات الخاص بك. يرسل SDK حدث PW_ProductView ويتخطى المشاهدات المتكررة للمنتج نفسه خلال 30 ثانية، لذلك لا تُحتسب إعادة تحميل الصفحة مشاهدةً ثانية.

إرسال أحداث الطلبات

لا تحتسب الاستراتيجية bestsellers_30d إلا المبيعات الواردة من أحداث الطلبات، وهي الاستراتيجية الاحتياطية الافتراضية لكل كتلة. عندما يقدم الزائر طلبًا، أرسل PW_OrderCreated:

Pushwoosh.push((api) => {
  api.postEvent('PW_OrderCreated', {
    orderId: 'ORDER-10293',
    items: [
      { productId: 'SKU-123', quantity: 1 },
      { productId: 'SKU-456', quantity: 2 },
    ],
  });
});

الحقل orderId مطلوب، لأن الطلب الذي لا يحتوي عليه لا يُحتسب. في items، استخدم معرّفات المنتجات نفسها الموجودة في كتالوج المنتجات الخاص بك. عندما يتغير الطلب، أرسل PW_OrderUpdated مع orderId وitems نفسيهما. لإرسال أحداث الطلبات من الخادم الخاص بك بدلًا من ذلك، راجع الأكثر مبيعًا: أضف العناصر إلى أحداث طلبك.

إضافة كتلة widget

أضف عنصرًا يحمل السمة data-pw-recommendations في المكان الذي يجب أن تظهر فيه الكتلة. يحمّل SDK الـ widget فقط في الصفحات التي تحتوي على مثل هذا العنصر.

<div
  data-pw-recommendations
  data-pw-strategy="also_bought"
  data-pw-product-id="SKU-123"
  data-pw-fallback="bestsellers_30d"
  data-pw-limit="4"
  data-pw-title="Bought together"
  data-pw-fallback-title="Popular right now"
  data-pw-block="pdp-also-bought"
  data-pw-min-height="260"
></div>

السمة	الوصف
data-pw-recommendations	تحدد العنصر ككتلة توصيات. مطلوبة.
data-pw-strategy	viewed، أو bestsellers_30d، أو also_bought. القيمة الافتراضية هي bestsellers_30d.
data-pw-fallback	الاستراتيجية التي يتم تقديمها عندما لا يكون لدى الاستراتيجية الرئيسية شيء: viewed، أو bestsellers_30d، أو also_bought، أو none. القيمة الافتراضية هي bestsellers_30d.
data-pw-limit	عدد المنتجات، من 1 إلى 12. القيمة الافتراضية هي 6.
data-pw-product-id	المنتج المعروض على الشاشة. مطلوبة لـ also_bought.
data-pw-exclude	معرّفات المنتجات المفصولة بفواصل التي يجب عدم عرضها، على سبيل المثال المنتجات الموجودة بالفعل في سلة التسوق. حتى 50.
data-pw-block	اسم الكتلة. تتم إضافته إلى روابط المنتجات وإلى أحداث النقر، حتى تتمكن من التمييز بين الكتل في التحليلات.
data-pw-title	عنوان الكتلة.
data-pw-fallback-title	العنوان الذي يُعرض عند تقديم الاستراتيجية الاحتياطية، على سبيل المثال “Popular right now” بدلًا من “You viewed”.
data-pw-min-height	المساحة التي يتم حجزها أثناء تحميل الكتلة، لتجنب إزاحة التخطيط. يُقرأ الرقم بالبكسل. تعمل أيضًا أي قيمة طول في CSS.

تعرض الـ widget صورة كل منتج واسمه وسعره، وترتبط بصفحة المنتج. تحمل روابط المنتجات utm_medium=onsite. يؤدي النقر على منتج إلى إرسال حدث PW_RecommendationClick مع اسم الكتلة والاستراتيجية وموضع المنتج.

عندما تغيّر أي سمة data-pw-*، يتم تحميل الكتلة مرة أخرى. على سبيل المثال، حدّث data-pw-product-id عندما يتغير المنتج المعروض على الشاشة دون إعادة تحميل الصفحة.

كتل للصفحات النموذجية

الصفحة	الاستراتيجية	السمات المطلوب ضبطها
صفحة المنتج	also_bought	data-pw-product-id بالمنتج المعروض على الشاشة، وdata-pw-exclude بالمعرّف نفسه
سلة التسوق	also_bought	data-pw-product-id بمنتج من سلة التسوق، وdata-pw-exclude بجميع المنتجات في سلة التسوق
صفحة الكتالوج أو الصفحة الرئيسية	bestsellers_30d	—
صفحة 404	viewed	data-pw-fallback="bestsellers_30d" وdata-pw-fallback-title، حتى يرى الزوار لأول مرة المنتجات الرائجة

حالات الكتلة

تضبط الـ widget السمة data-pw-state على عنصر الكتلة:

• loading: يتم تحميل المنتجات.
• ready: يتم عرض المنتجات.
• empty: لا توجد منتجات لدى الاستراتيجية ولا لدى الاستراتيجية الاحتياطية. تبقى الكتلة فارغة.
• error: لم يتم تحميل المنتجات. تبقى الكتلة فارغة.

استخدم الحالة لإخفاء الإطار أو العنوان الخاص بك حول كتلة فارغة:

.recommendations-frame:has([data-pw-state="empty"], [data-pw-state="error"]) {
  display: none;
}

تنسيق الـ widget

يتم عرض الـ widget داخل shadow DOM، لذلك لا يصل CSS الخاص بموقعك إلى محتواها. بدلًا من ذلك، اضبط هذه الخصائص المخصصة على عنصر الكتلة:

الخاصية	الوصف	القيمة الافتراضية
--pw-reco-font	عائلة الخط	موروثة من الصفحة
--pw-reco-accent	لون السعر	لون النص الحالي
--pw-reco-radius	نصف قطر زوايا صور المنتجات	8px
--pw-reco-columns	عدد أعمدة الشبكة. على الشاشات التي يصل عرضها إلى 600px، تحتوي الشبكة دائمًا على عمودين.	أكبر عدد ممكن يتسع

[data-pw-recommendations] {
  --pw-reco-columns: 4;
  --pw-reco-radius: 0;
  --pw-reco-accent: #337ab7;
}

لتنسيق أدق، يتم كشف العنوان والشبكة وكل بطاقة منتج على أنها CSS parts title وgrid وcard، على سبيل المثال [data-pw-recommendations]::part(card).

تطبيقات الصفحة الواحدة

افتراضيًا، يبحث SDK عن الكتل مرة واحدة، عندما يصبح جاهزًا. إذا كان موقعك يعرض الكتل لاحقًا، على سبيل المثال عند التنقل في تطبيق صفحة واحدة، فاضبط recommendations.spa على true في استدعاء init:

Pushwoosh.push(['init', {
  applicationCode: 'XXXXX-XXXXX',
  // other initialization parameters...
  recommendations: {
    spa: true,
  },
}]);

استبدل XXXXX-XXXXX بـ رمز التطبيق الخاص بك.

بعد ذلك يواصل SDK مراقبة الصفحة ويحمّل الـ widget بمجرد ظهور كتلة.

لإبقاء الـ widget معطّلة حتى عندما تحتوي الصفحة على عناصر data-pw-recommendations، اضبط recommendations.widget على false. يستمر Headless API في العمل.

عرض الكتل باستخدام الترميز الخاص بك

استخدم headless API عندما لا يناسب تخطيط الـ widget تصميمك. اطلب المنتجات باستخدام Pushwoosh.recommendations.fetch وأبلغ عن النقرات باستخدام Pushwoosh.recommendations.trackClick:

Pushwoosh.push(async () => {
  const request = {
    strategy: 'also_bought',
    productId: 'SKU-123',
    exclude: ['SKU-123'],
    fallback: 'bestsellers_30d',
    limit: 4,
    block: 'pdp-also-bought',
  };
  const { items, strategy } = await Pushwoosh.recommendations.fetch(request);

  const title = strategy === request.strategy ? 'Bought together' : 'Popular right now';
  renderBlock(title, items, (item, index) => {
    Pushwoosh.recommendations.trackClick({
      block: request.block,
      strategy,
      productId: item.id,
      position: index + 1,
    });
  });
});

تقبل fetch المعلمات نفسها التي تقبلها سمات الـ widget: strategy، وfallback، وlimit، وproductId، وexclude، وblock. وتُرجع:

• items: المنتجات. يحتوي كل منها على id، وtitle، وdescription، وimage_url، وurl، وprice، وprice_formatted، وold_price_formatted (فقط للمنتج المعروض بتخفيض)، وcurrency، وcategory، وsku.
• strategy: الاستراتيجية التي تم تقديمها فعليًا. تختلف عن الاستراتيجية المطلوبة عند تقديم الاستراتيجية الاحتياطية، وتكون none عندما تكون الاستجابة فارغة.

إذا فشل الطلب، تطرح fetch خطأ. التقطه وأخفِ الكتلة.

ترسل trackClick حدث PW_RecommendationClick. يتم تسليمه حتى عندما يفتح النقر صفحة أخرى. position هو موضع المنتج في الكتلة، بدءًا من 1.

السلوك دون الموافقة على التواصل

إذا كان التواصل مع Pushwoosh معطّلًا للزائر، على سبيل المثال باستخدام communicationEnabled: false في استدعاء init (راجع إدارة موافقة المستخدم لإشعارات الويب الفورية (Web Push Notifications)):

• لا ترسل trackProductView وtrackClick أي شيء.
• تظل الكتل تعرض المنتجات، لكن الطلب لا يحدد هوية الزائر. لا يوجد لدى الاستراتيجية viewed سجل لاستخدامه، لذلك يتم تقديم الاستراتيجية الاحتياطية.

بمجرد أن يفعّل الزائر التواصل، يتم تتبع مشاهدات المنتجات والنقرات مرة أخرى.