الدخول عبر الشريك
للجهة التي يملك أعضاؤها حسابات على موقعها: يفتحون مجتمعك على قُرب وهم مسجّلون الدخول، وعضويتك أنت هي التي تحدد من يبقى.
ما هو
يبقى موقعك المرجع الوحيد للهوية والعضوية، ويستضيف قُرب المجتمع: دليل الأعضاء والرسائل والمجموعات والفعاليات والمنشورات. لا يُبنى شيء خاص لكل شريك؛ تتبع الخطوات في هذه الصفحة والصفحة التي تليها، والقواعد نفسها تسري على كل شريك.
- لا ينشئ العضو كلمة مرور على قُرب، ولا يملأ نموذج انضمام.
- لا يدخل إلا أعضاؤك: المجتمع يقبل الأعضاء من خلال موقعك فقط.
- عند إيقاف العضوية أو انتهائها أو إلغائها يخرج العضو من المجتمع فوراً.
- لا ينتقل إلا ما تختاره: معرّف مستعار للعضو، واسم العرض، واختيارياً البريد والصورة.
كيف يتم الدخول
- العضو مسجّل الدخول في موقعك، ويضغط «المجتمع».
- يتحقق خادمك من قواعدك (عضوية فعّالة، بريد موثّق…) ثم يطلب من قُرب رمز دخول لمرة واحدة بمفتاح مجتمعك.
- يحوّل خادمك المتصفح إلى صفحة /embed في مجتمعك، والرمز في جزء العنوان بعد العلامة #.
- يستبدل قُرب الرمز، وينشئ العضو في أول زيارة، ويفتح الصفحة التي حددتها وهو مسجّل الدخول.
قواعدك تقرر قبل أن يُسأل قُرب
ما تستلمه من قُرب، وما تسلّمه
يجهّز مسؤول في قُرب المجتمع للدخول عبر الشريك، ويسلّمك خمس قيم:
| القيمة | الاستخدام |
|---|---|
| معرّف المجتمع (UUID) | يحدد مجتمعك في عنوان الأحداث ومحتواها. |
| مفتاح API للمجتمع (gurb_…، صلاحية كتابة) | طلب رموز الدخول. على الخادم فقط. |
| سر الأحداث (whsec_…) | توقيع أحداث الشريك. مختلف عن مفتاح API. |
| عنوان الأحداث | https://COMMUNITY_DOMAIN/api/webhooks/inbound/COMMUNITY_ID/host |
| نطاق المجتمع | حيث يصل الأعضاء، مثل community.example.com أو mygurb.com/:slug. |
وتسلّم قُرب النطاقات المسموح لها بعرض المجتمع داخل صفحاتها (إن كنت ستعرضه في صفحاتك)، وعنوان صفحة تسجيل الدخول لديك، وهو ما يصبح زر «الدخول عبر …» في صفحة المجتمع العامة.
تُتبادل عبر مدير كلمات المرور فقط
1 — اطلب رمز الدخول من خادمك
طلب واحد لكل دخول، يرسله خادمك لعضو تسمح قواعدك بدخوله. الرمز صالح لمرة واحدة وينتهي بعد 120 ثانية، فاطلبه لحظة الضغط وليس قبلها.
import { createGurbClient } from '@gurb/server'
const gurb = createGurbClient({
apiKey: process.env.GURB_API_KEY!, // the community key, server-only
baseUrl: 'https://community.example.com', // your community's domain
})
// Only for a member YOUR rules allow in (active membership, verified email…)
const session = await gurb.embed.createSession({
externalUserId: pseudonymousId(user.id), // stable, opaque, ≤ 255 chars
displayName: user.fullName,
email: user.email, // optional
avatarUrl: user.photoUrl, // optional, https only
})$session = $gurb->createEmbedSession(
externalUserId: pseudonymousId($user->id),
displayName: $user->fullName,
email: $user->email, // optional
avatarUrl: $user->photoUrl, // optional, https only
);| الحقل | القاعدة |
|---|---|
externalUserId | مطلوب. معرّفك الثابت المستعار لهذا الشخص، بحد أقصى 255 حرفاً. لا يتغير طوال العضوية؛ المعرّف نفسه يقود دائماً إلى العضو نفسه في قُرب. |
displayName | مطلوب. الاسم الذي يراه بقية الأعضاء. |
email | اختياري. إن كان العنوان مستخدماً في حساب آخر على قُرب، يحصل العضو مع ذلك على حساب مستقل بعنوان بديل؛ لا يُدمج حساب ولا يُستولى عليه أبداً. |
avatarUrl | اختياري. رابط https كامل؛ وأي شيء غير ذلك يُتجاهل. |
profile | اختياري. يملأ ملف العضو في قُرب — انظر «حقول الملف الشخصي» أدناه. |
لا ترسل معرّف قاعدة البيانات ولا البريد كمعرّف للعضو
import { createHmac } from 'node:crypto'
// A dedicated secret (≥ 32 chars), never rotated once members exist.
export function pseudonymousId(userId: string): string {
const digest = createHmac('sha256', process.env.GURB_IDENTITY_SECRET!)
.update('yourorg:gurb:member:v1:')
.update(userId)
.digest('hex')
return `yourorg_${digest}`
}2 — أرسل المتصفح إلى المجتمع
أجب ضغطة العضو بتحويل إلى صفحة /embed في مجتمعك. يوضع الرمز بعد العلامة # مع الصفحة المطلوب فتحها:
HTTP/1.1 303 See Other
Location: https://community.example.com/embed#token=gurbe_…&next=/events
Cache-Control: private, no-store
Referrer-Policy: no-referrer- ما بعد العلامة # لا يُرسل إلى أي خادم، فيبقى الرمز خارج سجلات الوصول وترويسات Referer. لا تضعه في معاملات الرابط بعد ?، ولا تسجّله أبداً.
- next مسار داخل المجتمع (مثل /events). أي شيء آخر — موقع آخر، أو //، أو شرطة مائلة عكسية — يُتجاهل ويصل العضو إلى الصفحة الرئيسية للمجتمع.
- اجعل التحويل no-store وno-referrer كما في المثال. الرمز المستخدم أو المنتهي يُرفض برسالة عامة واحدة؛ اطلب رمزاً جديداً.
تفضّل عرض المجتمع داخل صفحاتك؟ الرمز نفسه يفتح الإطار: التضمين ←
3 — اعرف مدة الجلسة
لجلسة عضو الشريك في قُرب نهاية ثابتة، وهذا ما يجعل رفضك نهائياً حتى لو ضاع حدث يوماً ما.
| القاعدة | الاستخدام |
|---|---|
| ستون دقيقة كحد أقصى لكل دخول، دون تجديد صامت. | بعدها يعود العضو عبر موقعك، فتُطبّق قواعدك من جديد. |
| الإطار يجدّد نفسه (@gurb/embed الإصدار 1.8 أو أحدث). | يطلب من خادمك رمزاً جديداً عند انتهاء الساعة، فيجب أن يجيبه خادمك. |
| حدث «محظور» ينهي كل الجلسات فوراً. | تُغلق التبويبات المفتوحة وتطبيق الجوال والتحديثات الحية، وتتوقف الإشعارات إلى الهاتف. |
ما يفرضه قُرب في مجتمع الشريك
هذه مفعّلة في كل مجتمع يعمل بالدخول عبر الشريك، ولا يستطيع مشرفوه إيقافها:
- لا طريق آخر للدخول: الانضمام والدعوات وطلبات الانضمام تُرفض بالرمز JOIN_THROUGH_HOST_ONLY. ويضيف قُرب مشرفي المجتمع من داخل قُرب.
- لا كلمات مرور: لا يستطيع عضو الشريك تعيين كلمة مرور على قُرب أو استعادتها، ولا تغيير بريد الدخول فيه.
- الخصوصية افتراضياً: العضو مخفي من دليل الأعضاء، وبيانات تواصله مخفية عن غيره، حتى يختار غير ذلك في قُرب. ويمكنك أن تطلب أن يظهر أعضاؤك افتراضياً بدلاً من ذلك — انظر «الظهور في الدليل افتراضياً».
- لا نص للرسائل في الإشعارات: يخبر الإشعار بوصول رسالة، لا بمحتواها.
- العرض داخل الإطار من النطاقات التي سلّمتها فقط: المتصفح يرفض أي موقع آخر.
الظهور في الدليل افتراضياً
يبدأ أعضاؤك مخفيين من دليل الأعضاء. إذا قررت جهتك أن يظهروا من البداية، فاطلب ذلك من قُرب كتابياً (support@mygurb.com) — هو إعداد للمجتمع يفعّله مشرف عام في قُرب لمجتمعك وحده. لا يوجد له حقل في الواجهة البرمجية: الخصوصية الافتراضية قرار يخص مجتمعك، لا خياراً في كل طلب.
- الإعداد: directoryVisibleByDefault على مجتمعك، يضبطه قُرب (host-sign-in directory-default :communityId visible). لا يتغير شيء في طلباتك.
- يسري على كل عضو تُدخله — جلسات التضمين (أول دخول)، وmembers/bulk، والإضافة التلقائية لاحقاً.
- الأعضاء الذين أدخلتهم قبل التفعيل يظهرون أيضاً: يمسح قُرب «الإخفاء» الذي سجّله عند انضمامهم. أما العضو الذي أخفى نفسه بنفسه فيبقى اختياره.
- هو يغيّر الافتراضي فقط. يستطيع العضو إخفاء نفسه، أو إخفاء بيانات بعينها، في أي وقت من إعداداته، ولا يكتب فوق اختياره أي شيء ترسله — الجلسات أو الإضافة الجماعية أو أحداث الشريك.
- بيانات التواصل (البريد، الجوال، واتساب، تاريخ الميلاد…) تبقى مخفية عن بقية الأعضاء حتى يظهرها العضو. فريق المجتمع يرى السجل كاملاً دائماً.
كيف تتحقق
الاستيراد الجماعي للأعضاء تفعّله قُرب
حقول الملف الشخصي
أرسل ما يعرفه موقعك عن العضو — النبذة والمسمى الوظيفي والشركة والقطاع والمدينة والجوال وروابط التواصل — فيبدأ ملفه في قُرب مكتملاً. الكائن الاختياري profile بالشكل نفسه في embed.createSession (POST /api/embed/sessions) وفي كل صف من members.bulkUpsert (POST /api/sdk/members/bulk).
| الحقل في الواجهة البرمجية | أقصى طول | ظاهر للأعضاء الآخرين افتراضياً |
|---|---|---|
bio | 200 | نعم |
jobTitle | 200 | نعم |
company | 200 | نعم |
industry | 200 | نعم |
city | 100 | نعم |
phone | — (يُوحَّد كما في نموذج العضو) | لا — العضو يختار إظهاره |
whatsapp | 50 | لا — العضو يختار إظهاره |
social.linkedin · x · instagram · facebook · youtube · tiktok · snapchat · telegram | 500 | نعم |
كيف يُطبَّق كل حقل
- المفتاح الذي لا ترسله لا يتغيّر.
- النص يضبط الحقل (بعد حذف المسافات الطرفية). والنص الفارغ يمسحه.
- القيمة null تمسح الحقل.
- الحقل الذي عدّله العضو بنفسه في قُرب يبقى كما هو: قيمتك تُتجاهَل بصمت من ذلك الحين.
- في members.bulkUpsert: النوع الخاطئ أو القيمة الأطول من حدّها تُفشل ذلك الصف بـ VALIDATION_ERROR، ولا يُكتب منه شيء. وبقية الصفوف تُحفظ — راجع failed.
- في embed.createSession: الحقل غير الصالح يُحذف ويمضي الدخول كالمعتاد، تماماً مثل avatarUrl غير الصالح. حقل ملف خاطئ لا يمنع العضو من الدخول أبداً.
await gurb.members.bulkUpsert([{
externalUserId: pseudonymousId(user.id),
displayName: user.fullName,
profile: {
bio: user.bio, // ≤ 200
jobTitle: user.jobTitle, // ≤ 200
company: user.company, // ≤ 200
industry: user.industry, // ≤ 200
city: user.city, // ≤ 100
phone: user.phone, // hidden until the member shows it
whatsapp: null, // null clears
social: { linkedin: user.linkedinUrl }, // ≤ 500 each
},
}])use Gurb\Input\MemberProfileInput;
use Gurb\Input\MemberSocialLinks;
$session = $gurb->createEmbedSession(
externalUserId: pseudonymousId($user->id),
displayName: $user->fullName,
profile: new MemberProfileInput(
jobTitle: $user->jobTitle,
company: $user->company,
industry: $user->industry,
whatsapp: '', // '' clears; null leaves it untouched
social: new MemberSocialLinks(linkedin: $user->linkedinUrl),
),
);الصلاحيات: members.bulkUpsert مع profile يحتاج users:manage على مفتاحك (انظر الاستيراد الجماعي أعلاه). وembed.createSession لا يحتاج شيئاً جديداً.
مُعرَّف بالأنواع في @gurb/server 1.11.0 (PartnerMemberProfile) وفي gurb/sdk 1.11 (MemberProfileInput). في PHP المُعامل null يُترك (لا يتغيّر) والنص الفارغ يمسح.
ما لا يكتبه الشريك أبداً
ما لا يمكنك فعله، عن قصد
- تحديد دور. كل من تُدخله عضو؛ والمشرفون والمديرون يُعيَّنون من داخل قُرب.
- تحديد مجتمع. المفتاح هو المجتمع، فلا يمكن أن يقود الرمز إلى مكان آخر.
- إدخال عضو أبلغت قُرب أنه محظور. يجيب طلب الرمز بـ HOST_MEMBER_BLOCKED حتى ترسل «مسموح».
- قراءة نشاط الأعضاء الخاص في المجتمع عبر الدخول. الهوية تنتقل في اتجاه واحد فقط.
- إعادة استخدام رمز، أو إبقاء العضو داخل المجتمع أكثر من 60 دقيقة دون موقعك.
الأخطاء
كل رفض يحمل رمزاً ثابتاً. اعرض للأعضاء رسالة بكلماتك أنت؛ الرموز لسجلاتك.
| الحالة | الرمز | ماذا تفعل |
|---|---|---|
| 400 | VALIDATION_ERROR | محتوى الطلب غير صالح، كاسم ناقص أو معرّف أطول من المسموح. أصلح الطلب. |
| 401 | EMBED_TOKEN_INVALID | عند الاستبدال فقط: الرمز استُخدم من قبل أو انتهى. اطلب رمزاً جديداً. |
| 403 | HOST_MEMBER_BLOCKED | أبلغت قُرب أن هذا العضو محظور. اعرض «العضوية غير فعّالة» وليس رسالة خطأ. |
| 403 | ACCOUNT_NOT_USABLE | حساب قُرب الخاص بهذا العضو موقوف. تواصل مع دعم قُرب. |
| 403 | JOIN_THROUGH_HOST_ONLY | حاول شخص الانضمام دون موقعك، أو بمفتاح ليس لك. لا شيء تصلحه من جهتك. |
| 409 | MEMBER_NOT_ACTIVE | أزال أحد مشرفي المجتمع هذا العضو أو حظره. طلب الرمز لا يعيده أبداً. |
| 503 | EMBED_STORE_UNAVAILABLE | مؤقت: لا يستطيع قُرب الآن ضمان أن الرمز لمرة واحدة. أعد المحاولة بعد ثوانٍ. |
التالي: إبقاء الوصول متطابقاً
الدخول نصف العمل. النصف الآخر أن تبلّغ قُرب خلال ثوانٍ حين يتغير وصول العضو أو اسمه أو صورته، بأحداث شريك موقّعة. أحداث الشريك ←
قائمة التحقق قبل الإطلاق
- القيم الخمس محفوظة على الخادم فقط، ولا تصل إلى متصفح أو سجل أو مستودع.
- خادمك يطبّق كل قواعدك قبل طلب الرمز، ويحدّ عدد الطلبات لكل عضو، ويجعل إجاباته no-store.
- معرّف العضو مستعار، وسرّه محفوظ بنسخة احتياطية ولن يتغير.
- الرمز لا ينتقل إلا بعد العلامة #، ولا شيء يسجّله.
- أحداث الشريك تُكتب في نفس عملية قاعدة البيانات مع كل تغيير، ويرسلها عامل خلفي مع إعادة المحاولة.
- اللقطة الليلية تشمل كل حسابات الأعضاء وتصل كاملة.
- توجد صفحة «العضوية غير فعّالة» للأعضاء الذين ترفضهم.
- اختُبر على مجتمع تجريبي بحسابات تجريبية، وليس بأعضاء حقيقيين: الدخول، والإيقاف (خروج فوري)، والإعادة، والانتهاء، والتجديد، وتغيير البريد، والحذف.
- إن كنت تستورد الأعضاء دفعة واحدة: أكّدت قُرب تفعيل الاستيراد الجماعي لمفتاحك (الرد 403 INSUFFICIENT_PERMISSION يعني أنه لم يُفعَّل بعد).
