معمل إشعارات المالك: ابنِ طلب خدمة واضحًا وآمن العرض

افهم المستلم والتكلفة قبل بناء الزر

يوثق عقد إشعارات Gammal Tech الدالة GammalTech.notify(subject, html). المستلم دائمًا البريد الموثق لمالك المشروع. لا توجد وسيطة لبريد الزائر أو حقول عامة مثل to وcc وfrom. الزائر لا يحتاج تسجيل الدخول لهذه الوظيفة، وفق نموذج الدومين المسجل. تحتفظ الخدمة بنسخة خاضعة للمراقبة؛ وضح هذا المسار للعميل عند مراجعة وجهات البيانات.

بحسب السعر المنشور في 12 أكتوبر 2026، كل رسالة بريد يتم تسليمها تكلف 0.40 جنيه دون رصيد رسائل مجاني. تمويل المحفظة يختلف عن تحويل رصيد للمشروع. أكمل المعاينة دون دفع؛ الإرسال الحقيقي اختياري ويحتاج موافقة المالك ورصيدًا متاحًا. في عمل العميل، يحتفظ العميل بالتحكم في حسابه دون مشاركة بيانات الدخول.

أنشئ نموذجًا صغيرًا بمحتوى وهمي

استخدم نوعين معروفين من الطلبات ورسالة قصيرة. لا تجمع مستند هوية أو توكن جلسة أو بيانات دفع أو سجل عميل حساسًا.

<label for="service">Fictional enquiry type</label>
<select id="service">
  <option value="website-review">Website review</option>
  <option value="training">Training</option>
</select>
<label for="message">Fictional message (10-500 characters)</label>
<textarea id="message" maxlength="500"></textarea>
<button id="preview" type="button">Preview without sending</button>
<pre id="notification-preview"></pre>
<label><input id="cost-consent" type="checkbox">
  I approve one paid owner notification.
</label>
<button id="send" type="button">Optional paid send</button>
<p id="notification-status" role="status"></p>

ضع JavaScript بعد العناصر في ملف التمرين، واكتب السعر بوضوح بجوار خيار الإرسال في الصفحة الفعلية. مربع الموافقة يبين فعلًا محليًا مقصودًا، لكنه لا يمثل نظام صلاحيات موثوقًا. إذا ستسلم نسخة معاينة فقط، فلا تضف معالج الإرسال الاختياري ولا تحمل SDK.

افحص الاختيار وعالج نص الزائر

استخدم عنوان رسالة ثابتًا وقائمة محدودة لأنواع الطلبات. الدالة التالية ترمز نص الزائر قبل وضعه داخل فقرة HTML ثابتة. توضح إرشادات OWASP للمخرجات أهمية اختيار المعالجة المناسبة لموضع العرض.

const service = document.getElementById("service");
const message = document.getElementById("message");
const status = document.getElementById("notification-status");
const preview = document.getElementById("notification-preview");
const escapeHtml = value => value.replace(/[&<>"']/g, c => ({
  "&": "&amp;", "<": "&lt;", ">": "&gt;",
  '"': "&quot;", "'": "&#39;"
}[c]));
function buildNotification() {
  const choices = { "website-review": "Website review", training: "Training" };
  if (!Object.hasOwn(choices, service.value)) throw new Error();
  const text = message.value.trim();
  if (text.length < 10 || text.length > 500) throw new Error();
  return {
    subject: "Learning lab: fictional service enquiry",
    html: "<p>Type: " + choices[service.value] + "</p><p>"
      + escapeHtml(text) + "</p>"
  };
}
document.getElementById("preview").addEventListener("click", () => {
  try {
    const draft = buildNotification();
    preview.textContent = draft.subject + "\n" + draft.html;
    status.textContent = "Local preview only. No email sent.";
  } catch {
    preview.textContent = "";
    status.textContent = "Check the enquiry type and message length.";
  }
});

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

أنهِ اختبار المعاينة المجاني أولًا

استخدم جملة وهمية مثل «أرغب في مناقشة موقع تدريبي». المعاينة تثبت طريقة تجهيز الرسالة ولا تثبت تسليمها. إذا توقفت هنا، اكتب أمام تجربة الإرسال الفعلي «لم تنفذ» .

أضف إرسالًا مدفوعًا واحدًا إذا حصلت على الموافقة

للتجربة الاختيارية، انشر على دومين HTTPS المسجل، وحمل SDK الموثق قبل المعالج التالي، مع إبقاء دالة تجهيز الرسالة السابقة في نفس النطاق:

<script src="https://api.gammal.tech/sdk-web.js"></script>

const send = document.getElementById("send");
const consent = document.getElementById("cost-consent");
send.addEventListener("click", async () => {
  if (send.disabled) return;
  if (!consent.checked) {
    status.textContent = "Owner approval and cost consent required.";
    return;
  }
  let draft;
  try { draft = buildNotification(); }
  catch {
    status.textContent = "Check the enquiry type and message length.";
    return;
  }
  send.disabled = true;
  status.textContent = "Submitting one request.";
  try {
    const accepted = await GammalTech.notify(draft.subject, draft.html);
    status.textContent = accepted === true
      ? "Accepted for delivery. Check the owner’s inbox."
      : "Delivery request not confirmed. Check before trying again.";
  } catch {
    status.textContent = "Request not confirmed. Check before trying again.";
  }
  // Remain disabled until the owner checks the result.
});

القيمة true تعني قبول الطلب للتسليم، ولا تعني أن المالك قرأ الرسالة. يبقى الزر معطلًا بعد الطلب، حتى إذا لم تتأكد النتيجة، إلى أن تراجع المالك. لا توجد حلقة إعادة إرسال من التطبيق. ولا تحول مسار الخطأ إلى إشعار آخر يبلغ عن فشل الإشعار نفسه.

اشرح ما لا يفرضه شكل النموذج

الحدود الموثقة هي 10 إشعارات في الساعة لكل زائر و120 في الساعة لكل مشروع. هذه حدود الخدمة، أما قصر الحقول وتعطيل الزر فسلوك محلي. يمكن للمستخدم تعديل المتصفح أو إعادة تحميل الصفحة، ولذلك الزر ليس نظامًا كاملًا لمنع إساءة الاستخدام.

حدد مسؤولًا عن مراجعة حجم الاستخدام والإنفاق المتوقع. تحسب الورقة التكلفة بضرب عدد الرسائل المسلمة في 0.40 جنيه؛ 25 رسالة مسلمة تعني 10 جنيهات وفق السعر المذكور. المثال يستبعد الخدمات الأخرى. قيّم احتياج مراسلات العملاء أو الردود الآلية منفصلًا؛ هذه الوظيفة ليست نظام بريد شاملًا.

حدد معنى التنبيه وكيف تعالج النتيجة غير المؤكدة

الإشعار يساعد في توجيه الطلب، وليس إثباتًا لقرار حساس. كتابة «تم الدفع» في الرسالة لا تثبت الدفع؛ يمكن للزائر كتابة هذه العبارة. لا تمنح صلاحية ولا ترسل سلعة ولا تغير دور مدير اعتمادًا على محتوى الرسالة.

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

سلّم ورقة إشعارات يستطيع شخص آخر فهمها

سلّم النموذج ودالة التجهيز ونتائج المعاينة وحساب التكلفة ووصف الحالات: مسودة، غير صالحة، جاهزة، قيد الإرسال، مقبولة، أو غير مؤكدة. سجل حالة الإرسال الفعلية واشرح المستلم الثابت وغياب حقل المستلم في الكود.

القبول يتطلب نص زائر معالجًا ومدخلات محدودة وإدراكًا للتكلفة وعدم إعادة الإرسال تلقائيًا ورسائل تفرق بين قبول الطلب وتأكيد الوصول. حدد مسؤولية المالك والدعم بالأدوار بدلًا من بيانات الحساب الخاصة.

أسئلة شائعة

هل يمكن للدالة إرسال بريد لأي عميل؟

لا. الدالة الموثقة ترسل إلى البريد الموثق لمالك المشروع فقط. ليست واجهة بريد جماعي أو رد تلقائي عام إلى عنوان الزائر.

هل يجب الدفع لإتمام الدرس؟

لا. تجهيز الرسالة ومعاينتها محليًا يكملان التمرين الأساسي دون إرسال. التجربة الحية اختيارية وبموافقة وتكلف 0.40 جنيه لكل رسالة مسلمة وفق التاريخ المذكور.