توثيق Connect

حساب واحد للمتاجر

تتيح المكتبة للعملاء تسجيل الدخول إلى المتجر بالحساب المستخدم في التطبيق. يشرح هذا التوثيق الدوال المتاحة للمتاجر المدعومة.

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

إضافة تسجيل الدخول

في متجر مدعوم، يكون window.rankappConnect محمّلًا ومهيّأً مسبقًا. استخدم ثلاث دوال: login() وgetSession() وlogout(). لا تحتاج إلى تثبيت إضافي. يضيف المثال الكامل الأزرار ورسائل الحالة المتاحة لقارئات الشاشة فقط.

استدعِ login() مباشرة من نقرة المستخدم. يعيد الوعد {status: "success", session} أو {status: "cancelled"} أو {status: "redirecting"}. ترفض الأخطاء الوعد برمز ثابت. على الهاتف أو عند حظر النافذة المنبثقة، يستمر المسار بإعادة التوجيه. يجب أن يبقى returnTo داخل متجرك.

const connect = window.rankappConnect;

function onSignInClick() {
  return connect.login({ returnTo: '/account' });
}

function readSession() {
  return connect.getSession();
}

function onSignOutClick() {
  return connect.logout();
}

<button type="button" id="connect-login">تسجيل الدخول عبر RankAPP</button>
<button type="button" id="connect-logout" hidden>تسجيل الخروج</button>
<p id="connect-status" role="status" aria-live="polite"></p>

<script>
const connect = window.rankappConnect;
const login = document.querySelector('#connect-login');
const logout = document.querySelector('#connect-logout');
const status = document.querySelector('#connect-status');
const copy = {
  "cancelled": "تم إلغاء تسجيل الدخول. يمكنك المحاولة مجددًا.",
  "redirecting": "جارٍ الانتقال إلى تسجيل الدخول…",
  "login": "تسجيل الدخول عبر RankAPP",
  "logout": "تسجيل الخروج",
  "signedOut": "أنت غير مسجل الدخول.",
  "signedIn": "تم تسجيل الدخول: ",
  "error": "تسجيل الدخول غير متاح. حاول مجددًا.",
  "pending": "جارٍ تسجيل الدخول…"
};
function render(session) {
  status.textContent = session.authenticated
    ? copy.signedIn + session.user.username : copy.signedOut;
  logout.hidden = !session.authenticated;
}
function failure() {
  status.textContent = copy.error;
}
function busy(value) {
  login.disabled = logout.disabled = value;
}
login.addEventListener('click', async () => {
  busy(true);
  status.textContent = copy.pending;
  let redirecting = false;
  try {
    const result = await connect.login({ returnTo: '/account' });
    if (result.status === 'success') render(result.session);
    else if (result.status === 'cancelled') status.textContent = copy.cancelled;
    else {
      redirecting = true;
      status.textContent = copy.redirecting;
    }
  } catch (error) { failure(); }
  finally { if (!redirecting) busy(false); }
});
logout.addEventListener('click', async () => {
  busy(true);
  try { render(await connect.logout()); }
  catch (error) { failure(); }
  finally { busy(false); }
});
busy(true);
connect.getSession().then(render).catch(failure)
  .finally(() => busy(false));
</script>

عرض الجلسة

تقرأ getSession() الحالة من الخادم: تعني {authenticated: false} عدم وجود جلسة. تحتوي الجلسة المصادق عليها على user (userId, username, avatarUrl, language)، وفي المتاجر المُدارة على orders أيضًا. استدعها عند تحميل الصفحة وبعد إعادة التوجيه، ولا تستنتج الهوية من معاملات الرابط.

تبقى أعطال الخدمة أخطاء: لا يتحول STOREFRONT_SESSION_ERROR إلى حالة تسجيل خروج. اعرض رسالة تسمح بإعادة المحاولة. تميّز login() بين الإلغاء والفشل، وتنهي logout() جلسة المتجر فقط.

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

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

يُدخل العميل كلمة المرور على auth.rankapp.io، وليس في موقع التاجر. يربط رمز يستخدم مرة واحدة مع PKCE S256 النافذة بالطلب الأصلي. يجري تبادل الرمز والتعامل مع الرموز المميزة على الخادم، ولا تحتوي رسالة اكتمال النافذة على أي رمز مميز.

تستخدم ملفات الجلسة HttpOnly وSecure وSameSite=Lax. كل ملف مرتبط بمضيفه فقط، دون سمة Domain مشتركة. الجلسة المركزية مستقلة عن جلسات المتاجر. يؤدي logout() إلى إنهاء جلسة المتجر، ولا ينهي تلقائيًا تسجيل الدخول المركزي.

دور خادم المتجر

يغطي هذا التوثيق SDK 1.1.0. في متجر متوافق، استخدم فقط العميل المهيّأ مسبقًا window.rankappConnect. يدير الخادم تسجيل الدخول والجلسة وتسجيل الخروج، ويطبّق العميل النقل الموقّع المطلوب. لا تحتاج إلى إعداد نقاط نهاية أو مهايئات في صفحتك.

التجربة في المعاينة

تدعم المعاينة حسابات حقيقية لتجربة الدخول والخروج من منظور العميل. يحتاج الوصول الخاص إلى المسودة إلى إذن مستقل؛ فتح المعاينة لا يسجل دخول المشتري تلقائيًا. المدفوعات معطلة في هذا الوضع.

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

الاستعداد للتكامل الخارجي

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

لا تفترض وجود client_id متوافق أو نقطة إصدار رموز أو إعداد OIDC. العقد الحالي يخص المتاجر المدعومة والمحوّل المرفق بها. أبقِ كلمات المرور والرموز خارج JavaScript الخاص بالتاجر، واعتمد دائمًا على جلسة تحقق منها الخادم، مع رسائل واضحة للإلغاء والأعطال المؤقتة.