إجراءات الصفحة

تسجيل إجراء من الموقع المضيف#

تتيح إجراءات الصفحة لموقعك فتح واجهته الخاصة أو الانتقال إلى صفحة معتمدة. ثبّت أحدث إصدار من التضمين، ثم نفّذ التسجيل بعد تحميل السكربت. احتفظ بالمعالجات (handlers) داخل تطبيقك؛ فالـ agent يتلقى أسماءها وأوصافها وتعريفات معاملاتها فقط، ولا يتلقى شيفرة المعالج أبدًا.

MakeAgentFast.registerAction("show_details", {
  description: "Show the details section on this page",
  params: { section: { type: "string", description: "Use delivery or returns" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("Unknown section");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// Run when the page component unmounts:
// MakeAgentFast.unregisterAction("show_details");

تُرجع الدالتان قيمة منطقية تشير إلى ما إذا كان التسجيل أو الإزالة قد قُبل. تتكوّن الأسماء من أحرف إنجليزية صغيرة وأرقام وشرطات سفلية، وتبدأ بحرف، ويتراوح طولها بين 2 و40 حرفًا. هناك تسع خانات تسجيل مخصّصة، إضافة إلى الإجراء المدمج open_page. يسمح كل تعريف بخمسة معاملات نصية؛ وجميع المعاملات المعلنة مطلوبة، وتصل قيمها إلى 200 حرف. أما الأوصاف فحدّها الأقصى 200 حرف. يمكن للمعالج أن يُرجع نصًا أو قيمة قابلة للتحويل إلى JSON بحجم يصل إلى 2 كيلوبايت خلال 10 ثوانٍ.

اعتماد الإجراءات في لوحة التحكم#

افتح الموقع الذي ثبّتّ عليه التضمين ليُبلغ عن أسماء الإجراءات وأوصافها، ثم افتح Agent → الإجراءات → إجراءات الصفحة. فعّل الميزة واسمح بكل إجراء تريده. أوصاف الإجراءات المُبلَّغ عنها هي بيانات وصفية من الموقع وغير موثوقة؛ والاكتشاف لا يعتمد أي إجراء. تُحفظ الإعدادات تلقائيًا.

يمكن للـ agent اقتراح الإجراءات التي تكون مسجّلة حاليًا ومسموحًا بها فقط. يرى العميل بطاقة قبل التنفيذ. التأكيد مطلوب ما لم يحدّد المالك (Owner) الإجراء على أنه آمن؛ أما confirm: true في شيفرة الموقع المضيف فيتطلب دائمًا نقرة تأكيد. ولا يتجاوز confirm: false وحده سياسة المالك. خصّص الوضع الآمن لتغييرات الواجهة غير الضارة.

لا يحتاج الإجراء المدمج open_page إلى معالج. اسمح به من لوحة التحكم؛ فهو يقبل مسارًا نسبيًا أو عنوان URL بصيغة HTTP(S) ضمن أصول الموقع (origins) المسموح بها للـ agent. كما تتطلب المسارات النسبية أن يكون أصل الموقع الحالي مسموحًا به. ولا يمكنه الانتقال إلى وجهة خارجية عشوائية.

الإبلاغ عن حدث باستخدام track#

MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });

استدعِ هذه الدوال بعد تحميل التضمين وعند وقوع الحدث المقابل فعلًا. اضبط اسم حدث مطابقًا في المتابعات. تتبع الأسماء الصيغة نفسها (من 2 إلى 40 حرفًا)، ويجب أن تكون البيانات الاختيارية كائن JSON لا يزيد حجمه على 1 كيلوبايت. لا ترسل قيم الحقول أو بيانات الاعتماد أو تفاصيل الدفع. تطابق القواعد الحدث والمسار والمهلة؛ ولا تُخزَّن البيانات الوصفية ولا تُرسل إلى النموذج ولا تُستخدم كادعاء بحدوث تحويل. تعني القيمة المُرجعة true أن المُحمِّل (loader) قبل الحدث، وليس أن رسالة قد عُرضت.

الأمان والتحقق#

تعمل إجراءات الصفحة في أداة الموقع الحية فقط، ولا تعمل في قنوات المراسلة أو تجربة المالك أو الصوت المباشر. يتحقق المُحمِّل والإطار من الأصل والمصدر والـ slug ومعرّفات الطلبات المعلّقة. تعود النتائج إلى المحادثة بوصفها بيانات متصفح غير موثوقة، وليست دليلًا على تغيّر سجل في الخادم. أبقِ المصادقة والتفويض داخل معالجاتك أو خادمك الخلفي؛ واستخدم إجراءات التغيير لعمليات الكتابة المهمة على بيانات النشاط التجاري.

لا يلغي انتهاء المهلة تنفيذ المعالج، ولا يثبت أن شيئًا لم يحدث. لا تُعِد محاولة إجراء غير مؤكَّد النتيجة تلقائيًا. ألغِ تسجيل المعالجات عندما يغادر مكوّن الصفحة الشاشة. تحتاج نسخ التضمين المخزّنة مؤقتًا إلى إصدار المُحمِّل الحالي 20261014-page-actions لاستخدام هذه الواجهة البرمجية.

لا تتعامل هذه الواجهة البرمجية مع المدفوعات ولا توفّر موصل Shopify.