أول مشروع باستخدام Gammal Tech API من الإعداد إلى التحقق

اعرف ما الذي ستثبته التجربة

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

تحتاج إلى أساسيات تعديل HTML، وتصريح بالنشر على موقع HTTPS، والتحكم في الحساب الخاص بمشروع التعلم. اعرف مكان رفع ملف HTML لدى شركة الاستضافة. اجعل التجربة منفصلة عن صفحة دفع عميل أو بوابة يستخدمها عملاء حقيقيون. نجاح فحص الجاهزية خطوة مفيدة، لكنه ليس تقييما أمنيا للموقع كله.

جهز حسابك ومشروعك

إذا كان حسابك معتمدًا بالفعل، ابدأ من الخطوة الثانية. اتبع الخطوات التالية داخل حسابك:

1. افتح صفحة التسجيل وأنشئ حسابك مرة واحدة، ثم استكمل التحقق من الهوية وفق المتطلبات المعروضة. الأصل هو بطاقة الهوية القومية لبلد تحمل جنسيته؛ راجع متطلبات المستندات والاستثناءات المحدودة للمصريين. انتظر اعتماد الحساب قبل خطوات الربط؛ قد تستغرق الموافقة حتى 10 أيام.
2. سجّل الدخول إلى حسابك، ثم افتح Developer Mode «وضع المطور». ستجد قائمة مشروعاتك.
3. اختر مشروعًا موجودًا، أو اضغط Create Project لإنشاء مشروع جديد. افتح صفحة المشروع واحتفظ بمعرّفه pid؛ هذا معرّف عام وليس مفتاحًا سريًا.
4. من إعدادات المشروع، أضف نطاق الموقع الذي ستستخدمه مع HTTPS. إذا كان الموقع يعمل بعنوان يبدأ بـ www وبدونه، سجّل كليهما.
5. اتبع مثال الربط أو التمرين الموجود في هذا الدليل على الموقع المسجل. جرّب مهمة واحدة من البداية إلى النهاية، وسجّل النتيجة الفعلية قبل إضافة وظائف أخرى.

سجل غرض المشروع ومعرفه. معرف المشروع معلن وليس مفتاح API سريا للمطور. لا تضف مفتاحا سريا أو قيمة في .env أو دالة تهيئة من مثال يخص منصة مختلفة. التزم بطريقة استخدام SDK الموثقة وإعدادات مشروعك الفعلية.

عند العمل لعميل، يجب أن يتحكم العميل في حسابه ومشروعه. مشروعك الشخصي للتعلم ليس سببا لطلب بيانات دخوله أو تشغيل ترتيبات مدفوعاته باستخدام هويتك أنت.

سجل الدومين الذي يعرض الصفحة فعليا

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

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

تتصل صفحتك بخدمة Gammal Tech API المستضافة؛ أنت لا تثبت المنصة على سيرفرك. وتظل الاستضافة مسؤولة عن تقديم كود الصفحة للزوار، لذلك احم حساب النشر وراجع من يستطيع تعديله.

انشر صفحة بسيطة لفحص الجاهزية

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

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>SDK readiness practice</title>
<h1>SDK readiness practice</h1>
<p id="status" role="status" aria-live="polite">Checking SDK…</p>
<script src="https://api.gammal.tech/sdk-web.js"></script>
<script>
"use strict";
const status = document.getElementById("status");
const sdk = window.GammalTech;
const required = ["login", "logout", "isLoggedIn", "verify"];
const ready = sdk && required.every(
  name => typeof sdk[name] === "function"
);
status.textContent = ready
  ? "SDK ready. No login attempted."
  : "Unable to prepare this page. Please try again later.";
</script>
</html>

يتحقق الكود من وجود أربع دوال موثقة. يستخدم textContent لعرض النتيجة، ولا يطبع الاستثناءات أو بيانات الدخول. تظهر رسالة محايدة عند الفشل. أما النجاح فيثبت وجود SDK والدوال المذكورة فقط؛ لا يعني أن الحساب سجل دخوله أو أن طلبا اجتاز ضوابط المشروع.

شخص المشكلة حسب ترتيب التحميل

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

سجل شروط القبول والنتائج

1. تفتح الصفحة من دومين HTTPS المقصود.
2. يظهر SDK الرسمي مرة واحدة قبل الكود الذي يعتمد عليه.
3. تعرض الصفحة الجاهزية دون فتح نافذة دخول تلقائية.
4. لا يوجد مفتاح سري ولا توكن جلسة مطبوع في الصفحة.
5. يميز سجل التجربة بين الجاهزية والدخول وصلاحيات العمليات.

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

اكتب النتيجة الفعلية بجوار المتوقعة. إذا كانت الصفحة جاهزة ولم تختبر الدخول، فاكتب «لم يختبر تسجيل الدخول بعد» بدلا من «التكامل آمن بالكامل». دقة وصف النتيجة جزء من التعلم نفسه.

جهز ملف التجربة للخطوة التالية

احتفظ بالمصدر وغرض المشروع والدومين المسجل والعنوان النهائي وصورة آمنة لرسالة الجاهزية. أضف رسما يربط المتصفح والموقع وAPI المستضاف، واكتب من يتحكم في حساب النشر.

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

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

أسئلة شائعة

لماذا لا يحتوي المثال على مفتاح API سري؟

التكامل الموثق لا يستخدم مفتاحا سريا للمطور. يختلف دور معرف المشروع العام عن توكن جلسة المستخدم الحساس؛ لا تتعامل مع الاثنين باعتبارهما شيئا واحدا.

هل رسالة SDK ready تثبت أن المشروع سجل دخوله؟

لا. هي تتحقق فقط من وجود SDK والدوال المطلوبة. تسجيل الدخول وصلاحية الجلسة وقواعد السماح داخل التطبيق تحتاج إلى تجارب منفصلة.