MailInApp
Documentation menu

عنصر المنتج

بطاقة منتج مع زر اشترِ الآن. يحدّد حقل الدفع فيها إلى أين تقود النقرة فعلًا. يحمل خيار الدفع عبر MailInApp (Stripe) عملية دفع حقيقية ضمن المسار نفسه: لا واجهة متجر، ولا صفحة دفع منفصلة تحتاج إلى بنائها، ولا تمرّ بيانات البطاقات أبدًا بخوادم MailInApp نفسها. أما خيار رابط إلى صفحة الدفع في متجر خارجي فيرسل المشتري بدلًا من ذلك مباشرة إلى صفحة منتج في متجرك على Shopify/WooCommerce، حين تفضّل إبقاء عملية البيع (ومعها المخزون والضرائب والخصومات) في المتجر الذي تديره أصلًا.

الدفع عبر MailInApp (Stripe)

هذا هو الوضع الافتراضي للعنصر، وكل ما في هذا القسم يخصّه تحديدًا — راجع الربط بصفحة الدفع في متجرك أدناه للوضع الآخر. اربط أولًا حساب Stripe الخاص بك من الإعدادات ← المدفوعات (Stripe Connect، بنمط Standard/OAuth)؛ وتُسوّى كل عملية دفع مباشرة في ذلك الحساب.

على عكس التصويت أو التقييم، لا يمكن إتمام عملية شراء بأمان إلا على صفحة الدفع المستضافة لدى Stripe نفسها، ولذلك لا يملك هذا العنصر أي مستوى حركي داخل الرسالة على الإطلاق. فزر اشترِ الآن يعتمد على الرابط أولًا في كل مكان، بما في ذلك الرسالة المُرسَلة. والنقر عليه يفتح دائمًا العرض المباشر المستضاف أولًا على صفحة تأكيد (/v/[token]/act?blockId=...&blockType=product&action=buy)، تعيد عرض اسم المنتج وسعره وتطلب نقرة إضافية («المتابعة إلى الدفع») قبل أن تُنشئ أي شيء فعليًا.

وشكل «التأكيد ثم POST» هذا مقصود: فالماسح الأمني أو الخادم الوكيل المؤسسي الذي يجلب مسبقًا كل رابط في الرسالة يجب ألّا يطلق أبدًا جلسة Stripe Checkout حقيقية عبر طلب GET مجرّد. وحده طلب POST الصريح من صفحة التأكيد يصل إلى POST /api/checkout. ويحدّد هذا المسار السعر والاسم والمخزون من إعدادات العنصر المخزّنة نفسها على الخادم، لا من أي شيء يرسله العميل أبدًا. ثم ينشئ جلسة Checkout على حساب Stripe المرتبط لدى المالك، ويكتب طلبًا بحالة pending، ويعيد التوجيه إلى Stripe برمز 303.

لا شيء في الطلب ذي الحالة pending يُحتسب عملية بيع بعد. وحده POST /api/webhooks/stripe ينقل الطلب إلى paid. ويُصادَق عليه بتوقيع Stripe نفسه، وهو نموذج الثقة نفسه المتّبع في روابط HMAC لنقطتي نهاية العدّاد التنازلي وتتبّع الفتح، لأن إعادة التوجيه إلى رابط النجاح الذي يصل إليه متصفح المشتري مسألة تجربة استخدام فحسب، ولا يمكن الوثوق بها دليلًا على الدفع.

عند وصول ذلك الـ Webhook، يعيد MailInApp التحقق من المخزون ضمن معاملة واحدة قبل التأكيد. فإذا تسابق مشتريان على الوحدة الأخيرة وتجاوز كلاهما Stripe، يُردّ المبلغ إلى الخاسر تلقائيًا ويُراسَل بإشعار، بدلًا من بيع كمية تفوق المتاح دون علم أحد. ويكتب الشراء المؤكَّد أيضًا حدث تفاعل من نوع purchase، فتتدفق الإيرادات عبر المجاميع نفسها ومسار Webhook المشروع نفسه اللذين تستخدمهما ردود كل العناصر الأخرى. راجع التفاعلات والتحليلات.

يعتمد تنفيذ الطلب على قيمة حقل تنفيذ الطلب:

  • رقمي — تُدخل محتوى التسليم (رابط تنزيل أو رمزًا) في العنصر مباشرة؛ ولحظة يؤكّد الـ Webhook الدفع، يُرسَل ذلك المحتوى إلى المشتري بالبريد تلقائيًا.
  • مادي — يجمع Stripe Checkout عنوان الشحن ضمن مسار الدفع؛ ويبقى الطلب في جدول الطلبات الخاص بالمشروع حتى تنقر تحديد كمنفَّذ، فيُرسَل إلى المشتري إشعار بالشحن.

المخزون حدّ أقصى اختياري (0 = غير محدود). رسالة HTML المُرسَلة ثابتة لحظة الإرسال، وهو الاصطلاح نفسه الذي يتّبعه الموعد النهائي في عنصر العدّاد التنازلي ونافذة الانضمام في عنصر رابط الاجتماع، لذا لا يُثبَّت مخزون المنتج المحدود نصًا في الرسالة. بل تضمّن الرسالة صورة صغيرة لشارة المخزون تُعرض على الخادم («تبقّى 3» / «نفدت الكمية») وتُحدَّث وفق أعداد الطلبات المدفوعة الفعلية، وتُخزَّن مؤقتًا لمدة دقيقة واحدة على الأكثر لاحتواء تكلفة إعادة استخدام الروابط الموقّعة. أما في العرض المباشر المستضاف، فيُتحقَّق من المخزون مباشرة وبشكل ديناميكي: بمجرد أن تبلغ الطلبات المدفوعة الحدّ، يُستبدَل زر اشترِ الآن كليًا بعنصر «نفدت الكمية» معطّل، لا بمجرد شارة بجانب زر ما زال قابلًا للنقر. وفي الحالتين، تبقى إعادة التحقق التي يجريها الـ Webhook ضمن معاملة لحظة الدفع هي المرجع الفعلي؛ فالشارة والزر المعطّل وسيلتان لتسهيل التجربة، لا آلية الإنفاذ.

إذا ربطت متجر Shopify أو WooCommerce، يظهر مربع بحث استيراد من المتجر فوق هذه الحقول، يعرض منتجات من كتالوج ذلك المتجر نفسه. ويبقى متزامنًا تلقائيًا في الخلفية، دون زر منفصل تضغط عليه. واختيار منتج يملأ لك الاسم والوصف والصورة والسعر.

حين يكون للمنتج المتزامن صفحة معروفة في واجهة المتجر (معرّف المنتج (handle) في Shopify، أو رابط الصفحة في WooCommerce)، فإن استيراده يحوّل أيضًا الدفع إلى رابط إلى صفحة الدفع في متجر خارجي ويملأ تلك الصفحة في حقل رابط صفحة المنتج الخارجية. فيصبح المنتج المستورد جاهزًا للبيع في متجرك دون أي إعداد متبقٍّ. أما المنتج الذي تزامن قبل أن يبدأ اتصال متجرك بجلب روابط الصفحات، فيبقى على الدفع عبر MailInApp بدلًا من ذلك، دون أن يتغيّر شيء من تحتك.

إنها نسخة لمرة واحدة، لا ربط حيّ. يبقى كل حقل قابلًا للتعديل بعد ذلك، والسعر الذي يُحصَّل فعليًا عند الدفع هو دائمًا ما يحمله العنصر حاليًا، ولا يُجلب من المتجر من جديد أبدًا. تعمل الحقول أدناه بالطريقة نفسها مع متجر مرتبط أو دونه — فالاستيراد اختصار، لا شرط.

الربط بصفحة الدفع في متجرك بدلًا من ذلك

حوّل الدفع إلى رابط إلى صفحة الدفع في متجر خارجي واضبط رابط صفحة المنتج الخارجية — صفحة منتجك على Shopify، أو رابط سلة دائم، أو صفحة منتج على WooCommerce، أو أي رابط https:// — لتتجاوز مسار الدفع الخاص بـ MailInApp كليًا. يتصرّف زر اشترِ الآن حينها تمامًا كزر أو صورة مرتبطة برابط عادي: لا صفحة تأكيد، ولا /api/checkout، ولا Stripe. وتبقى النقرة متتبَّعة (فتُحتسب ضمن الخريطة الحرارية للنقرات)، ويصل المشتري مباشرة إلى متجرك لإتمام الشراء هناك.

ولأن MailInApp ليس طرفًا في عملية الدفع تلك أبدًا، فلا ينطبق أيٌّ من آليات الدفع عبر MailInApp المذكورة أعلاه على المنتج الخارجي. فلا طلب بحالة pending/paid، ولا إدخال في جدول الطلبات، ولا إجراءات تنفيذ أو استرداد، ولا إنفاذ للمخزون ولا شارة لحالته، ولا خطوة رحلة يطلقها الشراء. تتبّع تلك الإيرادات كما تتتبّع أي عملية بيع أخرى في متجرك. ويشرح تتبّع طلبات Shopify وعمليات الدفع والإيرادات كيفية نسب المشتريات التي تتم في المتجر إلى الرسالة التي قادت إليها.

إذا تُرك رابط صفحة المنتج الخارجية فارغًا، أو لم يكن رابط https:// صالحًا، بينما الدفع مضبوط على الوضع الخارجي، فإن العنصر يعود بهدوء إلى التصرّف تمامًا كما في وضع الدفع عبر MailInApp، بدلًا من عرض زر معطّل.

خصم خاص بكل منتج

بمجرد أن يُملأ العنصر عبر استيراد من المتجر (فيحمل storeProductId حقيقيًا، لا رابطًا مكتوبًا يدويًا) ويُضبط الدفع على الوضع الخارجي، يظهر مفتاح خصم خاص بكل منتج. فعّله واضبط نوع الخصم (نسبة مئوية أو مبلغ ثابت)، وقيمة الخصم، وينتهي (بالأيام بعد الإرسال). تُعيد مساحة التصميم في الاستوديو الرسم فورًا بشارة الخصم نفسها والسعر المشطوب اللذين سيراهما المستلمون — دون الحاجة إلى فتح العرض المباشر للتحقق. وقبيل عرض رسالة كل مستلم مباشرة، يولّد MailInApp رمز خصم للاستخدام مرة واحدة في متجرك المرتبط على Shopify أو WooCommerce — مقصورًا على ذلك المستلم وعلى هذا المنتج وحده، لا على متجرك بأكمله — ويعيد كتابة زر اشترِ الآن ليصبح رابطًا لاستخدام الرمز يعيد المتسوّق إلى صفحة هذا المنتج نفسه والرمز مطبَّق مسبقًا. وهذا مستقل عن عرض الخصم على مستوى المشروع في صفحة الإرسال (راجع عرض الخصم): يمكن للمشروع استخدام أحدهما، أو كليهما، أو لا شيء منهما، ويحتفظ كلٌّ منهما بفترة التهدئة الخاصة به فلا يحجب أحدهما الآخر أبدًا. أما العنصر الذي لم يُستورَد منتجه من متجر مرتبط فيعرض بدلًا من ذلك ملاحظة تشرح سبب إخفاء المفتاح. وتجد شرحًا كاملًا من البداية إلى النهاية في رموز خصم Shopify للمنتجات وقسائم WooCommerce للمنتجات.

بالنسبة إلى متاجر Shopify، يمكن أيضًا لعنصر تطبيق اختياري أن يعرض الشارة نفسها مباشرة على صفحة المنتج الحيّة، قبل الوصول إلى الدفع — راجع خصومات المتجر — عرض الخصم في صفحة منتجك (Shopify) لخطوات الإعداد.

إذا فشل توليد الرمز لمستلم ما — لعدم وجود عميل مطابق في المتجر، أو لرمز وصول يحتاج إلى إعادة ربط، أو لخلل عابر في API — تُرسَل رسالته رغم ذلك؛ ويعود زر اشترِ الآن ببساطة إلى رابط المنتج العادي في العنصر دون خصم.

الحقول القابلة للضبط:

  • الاسم، والوصف، والصورة — تُختار الصورة من مكتبة الوسائط بدلًا من كتابتها رابطًا، أو تُملأ الحقول عبر استيراد من المتجر أعلاه.
  • السعر والعملة (USD أو EUR أو GBP) — يُعرضان على البطاقة في الحالتين، حتى في الوضع الخارجي حيث يكونان للعلم فقط.
  • الدفع — الدفع عبر MailInApp (Stripe) أو رابط إلى صفحة الدفع في متجر خارجي.
  • رابط صفحة المنتج الخارجية — في الوضع الخارجي فقط؛ وهو المكان الذي يرسل إليه زر اشترِ الآن المشتري.
  • خصم خاص بكل منتج، ونوع الخصم، وقيمة الخصم، وينتهي (بالأيام بعد الإرسال) — في الوضع الخارجي فقط، وفقط بعد أن يأتي منتج العنصر من استيراد من المتجر.
  • تنفيذ الطلب — رقمي أو مادي؛ في وضع الدفع عبر MailInApp فقط.
  • المخزون — 0 لعدد غير محدود؛ في وضع الدفع عبر MailInApp فقط.
  • محتوى التسليم — للمنتجات الرقمية فقط؛ رابط التنزيل أو الرمز المُرسَل بعد الدفع؛ في وضع الدفع عبر MailInApp فقط.
  • لون الخلفية، والحشو، والحدّ، واستدارة الزوايا، وتجاوزات نمط النص للاسم والوصف.

أمثلة

Subject

Back in stock: the Weekender Tote

إطلاق البضائع أو الطبعة المحدودة هو الاستخدام الأنسب مباشرة: اضبط المخزون على حجم الطبعة ودع شارة المخزون تُعبّر عن الندرة مع نفاد الكمية. راجع التجارة الإلكترونية وإطلاق المنتجات للنمط الأوسع المتمثّل في البيع مباشرة من رسالة ترويجية بدلًا من توجيه النقرات عبر متجر منفصل. ويستخدم إطلاق دورة رقمية أو كتاب إلكتروني تنفيذ الطلب الرقمي ليحصل المشتري على رابط التنزيل لحظة اكتمال الدفع، دون أي خطوة تنفيذ يدوية على الإطلاق. أما النشاط التجاري المحلي الذي يبيع إضافة مادية (منتجًا يحمل علامته، أو صندوقًا موسميًا) فيستخدم تنفيذ الطلب المادي ويتعامل مع جدول الطلبات كقائمة طلبات خفيفة، فيحدّد كل طلب كمنفَّذ عند شحنه. استخدم التواصل مع المشتري لفتح تذكرة دعم إذا احتاج عنوان ما إلى تأكيد.

كيف يبدو البديل الثابت

<div style="margin:12px 0;padding:16px;border:1px solid #e5e7eb;
            border-radius:8px;background-color:#ffffff">
  <p style="margin:0 0 4px;font-weight:600;font-size:16px;color:#111827">
    Limited edition tote bag
  </p>
  <p style="margin:0 0 10px;font-weight:700;font-size:18px">$29.00</p>
  <img src="https://mailinapp.com/api/product-status?p=proj123&b=prod-1&s=..."
       width="180" height="30" alt="" style="display:block;margin-bottom:8px" />
  <a href="https://mailinapp.com/v/eyJhbGci.../act?blockId=prod-1&blockType=product&action=buy"
     style="display:inline-block;padding:10px 20px;background-color:#4f46e5;
            color:#ffffff;border-radius:6px;text-decoration:none;
            font-size:14px;font-weight:600">
    Buy now
  </a>
</div>

لا تُعرض صورة حالة المخزون إلا عند ضبط حدّ للمخزون؛ ويفتح زر اشترِ الآن دائمًا صفحة التأكيد بدلًا من إرسال عملية دفع مباشرة من داخل الرسالة.

في وضع الدفع الخارجي، لا توجد صفحة تأكيد ولا شارة مخزون على الإطلاق — فزر اشترِ الآن رابط عادي متتبَّع النقرات يقود مباشرة إلى رابط صفحة المنتج الخارجية:

<div style="margin:12px 0;padding:16px;border:1px solid #e5e7eb;
            border-radius:8px;background-color:#ffffff">
  <p style="margin:0 0 4px;font-weight:600;font-size:16px;color:#111827">
    Limited edition tote bag
  </p>
  <p style="margin:0 0 10px;font-weight:700;font-size:18px">$29.00</p>
  <a href="https://mailinapp.com/v/eyJhbGci.../click?blockId=prod-1&blockType=product&dest=https%3A%2F%2Fshop.example.com%2Fproducts%2Ftote-bag"
     style="display:inline-block;border:none;border-radius:6px;
            background-color:#4f46e5;color:#ffffff;padding:10px 20px;
            font-size:14px;font-weight:600;text-decoration:none">
    Buy now
  </a>
</div>

انظر أيضًا