مصادقة SDK
توفّر وحدة dypai.auth طريقة كاملة لمعالجة تسجيل المستخدمين وتسجيل الدخول وإدارة الجلسات. تتولى تلقائياً ثبات الرمز في localStorage وتجديد الرمز في الخلفية والمزامنة عبر التبويبات وردود نداء التحقق من البريد.
تحتاج مساعدة في اختيار تدفق المنتج أولاً؟
إذا كنت تقرر ما إذا كان يجب أن يدعم تطبيقك التسجيل أو الإعداد بدعوة فقط أو تكاملات الخلفية فقط، اقرأ تدفقات المصادقة أولاً.
البريد وكلمة المرور
التسجيل (إنشاء حساب)
const { data, error } = await dypai.auth.signUp({
email: 'user@example.com',
password: 'secure-password',
full_name: 'John Doe' // extra fields auto-forwarded to user_metadata
});
if (error) {
console.error(error.message);
return;
}
if (data.confirmationRequired) {
// Email confirmation is enabled — user must verify their email
showMessage('Check your inbox to confirm your email');
} else {
// Email confirmation disabled — user is logged in immediately
console.log('Logged in:', data.user);
}
تأكيد البريد مفعّل افتراضياً. عند التفعيل، ينشئ signUp() المستخدم لكنه لا يبدأ جلسة. يجب أن ينقر المستخدم رابط التأكيد المُرسل إلى بريده قبل أن يتمكن من تسجيل الدخول.
تُدمَج الحقول الإضافية مثل full_name و username أو أي بيانات مخصصة تلقائياً في user_metadata. يمكنك أيضاً تمريرها صراحة عبر user_data:
await dypai.auth.signUp({
email, password,
user_data: { full_name: 'John Doe', company: 'Acme' }
});
تسجيل الدخول
const { data, error } = await dypai.auth.signInWithPassword({
email: 'user@example.com',
password: 'secure-password'
});
if (error) {
// If user hasn't confirmed email, error.status will be 400
console.error(error.message);
return;
}
console.log('Logged in:', data.user);
سيفشل signInWithPassword() بخطأ 400 إذا لم يؤكّد المستخدم بريده بعد. اعرض رسالة مثل «يرجى تأكيد بريدك أولاً» وعرض إعادة إرسال بريد التأكيد.
إعادة إرسال بريد التأكيد
إذا لم يستلم المستخدم بريد التأكيد أو انتهت صلاحية الرابط:
const { data, error } = await dypai.auth.resendConfirmationEmail('user@example.com');
if (!error) {
showMessage('Confirmation email resent — check your inbox');
}
التحقق من البريد وردود النداء
عندما ينقر المستخدم رابط تأكيد أو رابطاً سحرياً أو رابط إعادة تعيين كلمة المرور من بريده، يعيد خادم المصادقة التوجيه إلى تطبيقك مع الرموز في تجزئة عنوان URL:
https://your-app.com/#access_token=eyJ...&refresh_token=xxx&type=signup
لدعوات التطبيقات الخاصة، استخدم نمط رد النداء نفسه مع type=invite:
https://your-app.com/#access_token=eyJ...&refresh_token=xxx&type=invite
يتولى SDK هذا تلقائياً. عند التهيئة، يقوم بـ:
- فحص
window.location.hashبحثاً عن رموز رد نداء المصادقة. - إن وُجدت: جلب بيانات المستخدم وإنشاء الجلسة وتنظيف عنوان URL.
- إصدار الحدث المناسب:
SIGNED_INأوPASSWORD_RECOVERY.
لا حاجة لكود إضافي — استمع فقط لأحداث المصادقة:
dypai.auth.onAuthStateChange((event, session) => {
if (event === 'SIGNED_IN') {
router.push('/dashboard');
}
if (event === 'PASSWORD_RECOVERY') {
router.push('/reset-password');
}
});
الدعوات (تطبيقات خاصة)
لتطبيقات B2B/الخاصة، يجب أن يعيش تجربة الدعوة في تطبيق العميل (وليس لوحة تحكم DYPAI):
- تولّد خلفيتك رابط دعوة عبر نظام المصادقة (
type=invite). - يجب أن يشير
redirect_toإلى مسار في تطبيق العميل (مثلاً/auth/callback). - يجب أن يكون ذلك المسار مسموحاً في قائمة السماح لإعادة توجيه المصادقة.
- يكتشف SDK رد نداء الدعوة ويُصدر
PASSWORD_RECOVERY. - اعرض نموذج «تعيين كلمة المرور» واستدعِ
dypai.auth.setPassword(...).
dypai.auth.onAuthStateChange(async (event) => {
if (event === 'PASSWORD_RECOVERY') {
await dypai.auth.setPassword('new-secure-password');
}
});
بدون كلمة مرور (OTP)
OTP عبر البريد
// 1. Send a 6-digit code to the user's email
await dypai.auth.signInWithOtp({
email: 'user@example.com',
create_user: true // auto-register if user doesn't exist
});
// 2. User enters the code
const { data, error } = await dypai.auth.verifyOtp({
email: 'user@example.com',
token: '123456',
type: 'magiclink' // always 'magiclink' for email OTP
});
OTP عبر الهاتف (SMS)
اضبط SMS أولاً
يعمل OTP عبر الهاتف/الرسائل القصيرة فقط بعد ضبط مزوّد SMS تحت Auth → SMS في لوحة التحكم. دونه سيفشل signInWithOtp({ phone }).
// 1. Send a 6-digit code via SMS
await dypai.auth.signInWithOtp({
phone: '+34600000000',
create_user: true
});
// 2. User enters the code
const { data, error } = await dypai.auth.verifyOtp({
phone: '+34600000000',
token: '123456',
type: 'sms' // always 'sms' for phone OTP
});
يجب أن يطابق type في OTP التدفق. استخدم 'magiclink' لـ OTP عبر البريد، و'sms' لـ OTP عبر الهاتف، و'signup' لرموز تأكيد التسجيل. استخدام النوع الخطأ سيؤدي إلى فشل التحقق.
OAuth
أعد توجيه المستخدمين لتسجيل الدخول بحسابات Google أو GitHub أو حسابات OAuth أخرى:
await dypai.auth.signInWithOAuth('google', {
redirectTo: 'https://your-app.com/auth/callback',
scopes: ['email', 'profile'] // optional
});
يعيد هذا توجيه المتصفح إلى مزوّد OAuth. عندما يعود المستخدم إلى تطبيقك، يلتقط SDK الجلسة تلقائياً من رد نداء عنوان URL.
فعّل المزوّد أولاً
يجب تفعيل كل مزوّد OAuth وضبطه تحت Auth → Providers في لوحة التحكم قبل أن يعمل signInWithOAuth له.
استعادة كلمة المرور
// 1. Send a password reset email
await dypai.auth.resetPasswordForEmail('user@example.com');
// 2. User clicks the link in the email → SDK auto-detects the recovery token
dypai.auth.onAuthStateChange(async (event, session) => {
if (event === 'PASSWORD_RECOVERY') {
// Show "set new password" form, then:
const { data, error } = await dypai.auth.updateUser({
password: 'new-secure-password'
});
}
});
الجلسة والمستخدم
الحصول على الجلسة
const { data: session, error } = await dypai.auth.getSession();
if (session) {
console.log('Token:', session.access_token);
console.log('User:', session.user);
}
ينتظر getSession() اكتمال تهيئة SDK قبل الرد، لذا من الآمن استدعاؤه عند تحميل الصفحة دون حالات سباق.
الحصول على المستخدم الحالي
const { data: user, error } = await dypai.auth.getUser();
// or the shorthand alias:
const { data: user, error } = await dypai.me();
فحص متزامن سريع
if (dypai.auth.isLoggedIn()) {
// User has an active session
}
isLoggedIn() متزامن وقد يُرجع false أثناء تهيئة SDK. لفحص موثوق عند البدء، استخدم await dypai.auth.getSession() أو onAuthStateChange بدلاً منه.
كائن المستخدم والدور
يطبع SDK كائن المستخدم بحيث يكون دور تطبيقك دائماً متاحاً كـ user.role:
const { data: user } = await dypai.auth.getUser();
user.id // User UUID
user.email // email
user.role // "admin", "editor", "viewer", etc. — your app role
user.confirmed_at // null if email not confirmed
user.role هو دائماً دور تطبيقك، وليس الدور الداخلي لمحرك المصادقة. داخلياً، يخزّن خادم المصادقة الدور في app_metadata.role. يستخرجه SDK تلقائياً إلى user.role حتى لا تحتاج إلى الوصول إلى user.app_metadata.role يدوياً. ينطبق هذا على كل من dypai.auth.getUser() و dypai.users.list().
ملف المستخدم
// Read current user
const user = dypai.auth.user;
console.log(user.email, user.confirmed_at);
// Update user metadata
await dypai.auth.updateUser({
data: {
full_name: 'John Doe',
avatar_url: 'https://example.com/avatar.jpg'
}
});
مستمع حالة المصادقة
تفاعل مع تغييرات المصادقة في الوقت الفعلي:
const { data: { subscription } } = dypai.auth.onAuthStateChange((event, session) => {
switch (event) {
case 'INITIAL_SESSION':
// Fired on SDK init — session recovered from storage (or null)
break;
case 'SIGNED_IN':
// User logged in (password, OTP, OAuth, or email link callback)
break;
case 'SIGNED_OUT':
// User logged out or session expired
break;
case 'TOKEN_REFRESHED':
// Access token silently refreshed in background
break;
case 'USER_UPDATED':
// Profile or password changed via updateUser()
break;
case 'PASSWORD_RECOVERY':
// User arrived via password reset link — show new password form
break;
}
});
// To unsubscribe later:
subscription.unsubscribe();
تسجيل الخروج
await dypai.auth.signOut();
مرجع الطرق
| Parameter | Type | Description |
|---|---|---|
signUp(data) | async | تسجيل مستخدم جديد. يُرجع علم confirmationRequired |
signInWithPassword(credentials) | async | تسجيل الدخول بالبريد وكلمة المرور |
signInWithOtp(options) | async | إرسال رمز OTP عبر البريد أو الهاتف |
verifyOtp(params) | async | التحقق من رمز OTP وبدء جلسة |
signInWithOAuth(provider, options) | async | إعادة التوجيه إلى مزوّد OAuth (Google و GitHub وغيرها) |
getSession() | async | الحصول على الجلسة الحالية (ينتظر التهيئة) |
getUser() | async | جلب بيانات المستخدم الحالي من الخادم |
isLoggedIn() | boolean | فحص متزامن إن كانت جلسة موجودة |
updateUser(attributes) | async | تحديث البريد أو كلمة المرور أو بيانات المستخدم الوصفية |
setPassword(password) | async | تعيين كلمة مرور جديدة (تدفقات الدعوة/الاستعادة) |
resetPasswordForEmail(email) | async | إرسال بريد إعادة تعيين كلمة المرور |
resendConfirmationEmail(email) | async | إعادة إرسال بريد تأكيد التسجيل |
onAuthStateChange(callback) | function | الاستماع لتغييرات حالة المصادقة (SIGNED_IN و SIGNED_OUT و PASSWORD_RECOVERY) |
signOut() | async | مسح الجلسة وتسجيل الخروج |
الأسماء البديلة: login() = signInWithPassword()، register() = signUp()، logout() = signOut()، me() = getUser().