وثائق المطورين

حزمة رسمية للـ TypeScript وأخرى لـ PHP. نفس العقد، نفس المسارات، نفس الصلاحيات التي يفحصها تطبيق قُرب نفسه.

TypeScript1.9.0PHP1.9

الدخول عبر الشريك

للجهة التي يملك أعضاؤها حسابات على موقعها: يفتحون مجتمعك على قُرب وهم مسجّلون الدخول، وعضويتك أنت هي التي تحدد من يبقى.

ما هو

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

  • لا ينشئ العضو كلمة مرور على قُرب، ولا يملأ نموذج انضمام.
  • لا يدخل إلا أعضاؤك: المجتمع يقبل الأعضاء من خلال موقعك فقط.
  • عند إيقاف العضوية أو انتهائها أو إلغائها يخرج العضو من المجتمع فوراً.
  • لا ينتقل إلا ما تختاره: معرّف مستعار للعضو، واسم العرض، واختيارياً البريد والصورة.

كيف يتم الدخول

  1. العضو مسجّل الدخول في موقعك، ويضغط «المجتمع».
  2. يتحقق خادمك من قواعدك (عضوية فعّالة، بريد موثّق…) ثم يطلب من قُرب رمز دخول لمرة واحدة بمفتاح مجتمعك.
  3. يحوّل خادمك المتصفح إلى صفحة ⁦/embed⁩ في مجتمعك، والرمز في جزء العنوان بعد العلامة #.
  4. يستبدل قُرب الرمز، وينشئ العضو في أول زيارة، ويفتح الصفحة التي حددتها وهو مسجّل الدخول.

قواعدك تقرر قبل أن يُسأل قُرب

قُرب لا يسأل موقعك من يحق له الدخول. أنت تقرر حين تطلب الرمز، وتبلّغ عن كل تغيير لاحق بأحداث الشريك. إن كنت سترفض شخصاً فلا تطلب له رمزاً.

ما تستلمه من قُرب، وما تسلّمه

يجهّز مسؤول في قُرب المجتمع للدخول عبر الشريك، ويسلّمك خمس قيم:

القيمةالاستخدام
معرّف المجتمع (⁦UUID⁩)يحدد مجتمعك في عنوان الأحداث ومحتواها.
مفتاح ⁦API⁩ للمجتمع (⁦gurb_⁩…، صلاحية كتابة)طلب رموز الدخول. على الخادم فقط.
سر الأحداث (⁦whsec_⁩…)توقيع أحداث الشريك. مختلف عن مفتاح ⁦API⁩.
عنوان الأحداث⁦https://COMMUNITY_DOMAIN/api/webhooks/inbound/COMMUNITY_ID/host⁩
نطاق المجتمعحيث يصل الأعضاء، مثل ⁦community.example.com⁩ أو ⁦mygurb.com/:slug⁩.

وتسلّم قُرب النطاقات المسموح لها بعرض المجتمع داخل صفحاتها (إن كنت ستعرضه في صفحاتك)، وعنوان صفحة تسجيل الدخول لديك، وهو ما يصبح زر «الدخول عبر …» في صفحة المجتمع العامة.

تُتبادل عبر مدير كلمات المرور فقط

يتبادل مالكا النظامين مفتاح ⁦API⁩ وسر الأحداث عبر رابط مشاركة من مدير كلمات مرور له مدة صلاحية، ولا يُرسلان أبداً بالبريد أو المحادثة أو في تذكرة أو مستودع. ولا يصل أي منهما إلى متصفح أو سجل.

1 — اطلب رمز الدخول من خادمك

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

ts
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
})
php
$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اختياري. يملأ ملف العضو في قُرب — انظر «حقول الملف الشخصي» أدناه.

لا ترسل معرّف قاعدة البيانات ولا البريد كمعرّف للعضو

أرسل معرّفاً مستعاراً: بصمة ⁦HMAC⁩ لمعرّفك الداخلي بسرّ مخصص لهذا الغرض. يبقى ثابتاً، ولا يكشف شيئاً، ولا يمكن تخمينه من الخارج. لا تغيّر ذلك السر بعد وجود أعضاء، فالسر الجديد يعني هويات جديدة.
ts
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
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⁩، والإضافة التلقائية لاحقاً.
  • الأعضاء الذين أدخلتهم قبل التفعيل يظهرون أيضاً: يمسح قُرب «الإخفاء» الذي سجّله عند انضمامهم. أما العضو الذي أخفى نفسه بنفسه فيبقى اختياره.
  • هو يغيّر الافتراضي فقط. يستطيع العضو إخفاء نفسه، أو إخفاء بيانات بعينها، في أي وقت من إعداداته، ولا يكتب فوق اختياره أي شيء ترسله — الجلسات أو الإضافة الجماعية أو أحداث الشريك.
  • بيانات التواصل (البريد، الجوال، واتساب، تاريخ الميلاد…) تبقى مخفية عن بقية الأعضاء حتى يظهرها العضو. فريق المجتمع يرى السجل كاملاً دائماً.

كيف تتحقق

ادخل بعضو لم يغيّر خصوصيته أبداً: ⁦GET /api/communities/:communityId/members/me/privacy⁩ يرجع ⁦directoryVisible: true⁩ و⁦hiddenByDefault: false⁩، ويظهر العضو في قائمة الأعضاء الآخرين.

الاستيراد الجماعي للأعضاء تفعّله قُرب

يحتاج POST /api/sdk/members/bulk صلاحية users:manage على مفتاحك. تفعّلها قُرب لمفتاحك الحالي (host-sign-in grant-bulk) دون مفتاح جديد أو سر جديد، ويسري التفعيل خلال دقيقة. قبل التفعيل يرجع كل طلب 403 INSUFFICIENT_PERMISSION برسالة “This key's owner is missing a required permission: users:manage”. اطلبها كتابياً عبر support@mygurb.com.

حقول الملف الشخصي

أرسل ما يعرفه موقعك عن العضو — النبذة والمسمى الوظيفي والشركة والقطاع والمدينة والجوال وروابط التواصل — فيبدأ ملفه في قُرب مكتملاً. الكائن الاختياري profile بالشكل نفسه في embed.createSession (POST /api/embed/sessions) وفي كل صف من members.bulkUpsert (POST /api/sdk/members/bulk).

الحقل في الواجهة البرمجيةأقصى طولظاهر للأعضاء الآخرين افتراضياً
bio200نعم
jobTitle200نعم
company200نعم
industry200نعم
city100نعم
phone— (يُوحَّد كما في نموذج العضو)لا — العضو يختار إظهاره
whatsapp50لا — العضو يختار إظهاره
social.linkedin · x · instagram · facebook · youtube · tiktok · snapchat · telegram500نعم

كيف يُطبَّق كل حقل

  • المفتاح الذي لا ترسله لا يتغيّر.
  • النص يضبط الحقل (بعد حذف المسافات الطرفية). والنص الفارغ يمسحه.
  • القيمة null تمسح الحقل.
  • الحقل الذي عدّله العضو بنفسه في قُرب يبقى كما هو: قيمتك تُتجاهَل بصمت من ذلك الحين.
  • في members.bulkUpsert: النوع الخاطئ أو القيمة الأطول من حدّها تُفشل ذلك الصف بـ VALIDATION_ERROR، ولا يُكتب منه شيء. وبقية الصفوف تُحفظ — راجع failed.
  • في embed.createSession: الحقل غير الصالح يُحذف ويمضي الدخول كالمعتاد، تماماً مثل avatarUrl غير الصالح. حقل ملف خاطئ لا يمنع العضو من الدخول أبداً.
ts
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
  },
}])
php
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 يُترك (لا يتغيّر) والنص الفارغ يمسح.

ما لا يكتبه الشريك أبداً

خصوصية الدليل اختيار العضو وحده ولا تكتبها أي واجهة برمجية: الجوال وواتساب يبقيان مخفيين عن الأعضاء الآخرين حتى يُظهرهما العضو. ولا تُقبل كذلك تواريخ الميلاد والجنس والحالة الاجتماعية والجنسية والرقم الوظيفي. والحقل x يُنسخ أيضاً إلى حقل twitter القديم.

ما لا يمكنك فعله، عن قصد

  • تحديد دور. كل من تُدخله عضو؛ والمشرفون والمديرون يُعيَّنون من داخل قُرب.
  • تحديد مجتمع. المفتاح هو المجتمع، فلا يمكن أن يقود الرمز إلى مكان آخر.
  • إدخال عضو أبلغت قُرب أنه محظور. يجيب طلب الرمز بـ ⁦HOST_MEMBER_BLOCKED⁩ حتى ترسل «مسموح».
  • قراءة نشاط الأعضاء الخاص في المجتمع عبر الدخول. الهوية تنتقل في اتجاه واحد فقط.
  • إعادة استخدام رمز، أو إبقاء العضو داخل المجتمع أكثر من 60 دقيقة دون موقعك.

الأخطاء

كل رفض يحمل رمزاً ثابتاً. اعرض للأعضاء رسالة بكلماتك أنت؛ الرموز لسجلاتك.

الحالةالرمزماذا تفعل
400VALIDATION_ERRORمحتوى الطلب غير صالح، كاسم ناقص أو معرّف أطول من المسموح. أصلح الطلب.
401EMBED_TOKEN_INVALIDعند الاستبدال فقط: الرمز استُخدم من قبل أو انتهى. اطلب رمزاً جديداً.
403HOST_MEMBER_BLOCKEDأبلغت قُرب أن هذا العضو محظور. اعرض «العضوية غير فعّالة» وليس رسالة خطأ.
403ACCOUNT_NOT_USABLEحساب قُرب الخاص بهذا العضو موقوف. تواصل مع دعم قُرب.
403JOIN_THROUGH_HOST_ONLYحاول شخص الانضمام دون موقعك، أو بمفتاح ليس لك. لا شيء تصلحه من جهتك.
409MEMBER_NOT_ACTIVEأزال أحد مشرفي المجتمع هذا العضو أو حظره. طلب الرمز لا يعيده أبداً.
503EMBED_STORE_UNAVAILABLEمؤقت: لا يستطيع قُرب الآن ضمان أن الرمز لمرة واحدة. أعد المحاولة بعد ثوانٍ.

التالي: إبقاء الوصول متطابقاً

الدخول نصف العمل. النصف الآخر أن تبلّغ قُرب خلال ثوانٍ حين يتغير وصول العضو أو اسمه أو صورته، بأحداث شريك موقّعة. أحداث الشريك ←

قائمة التحقق قبل الإطلاق

  • القيم الخمس محفوظة على الخادم فقط، ولا تصل إلى متصفح أو سجل أو مستودع.
  • خادمك يطبّق كل قواعدك قبل طلب الرمز، ويحدّ عدد الطلبات لكل عضو، ويجعل إجاباته ⁦no-store⁩.
  • معرّف العضو مستعار، وسرّه محفوظ بنسخة احتياطية ولن يتغير.
  • الرمز لا ينتقل إلا بعد العلامة #، ولا شيء يسجّله.
  • أحداث الشريك تُكتب في نفس عملية قاعدة البيانات مع كل تغيير، ويرسلها عامل خلفي مع إعادة المحاولة.
  • اللقطة الليلية تشمل كل حسابات الأعضاء وتصل كاملة.
  • توجد صفحة «العضوية غير فعّالة» للأعضاء الذين ترفضهم.
  • اختُبر على مجتمع تجريبي بحسابات تجريبية، وليس بأعضاء حقيقيين: الدخول، والإيقاف (خروج فوري)، والإعادة، والانتهاء، والتجديد، وتغيير البريد، والحذف.
  • إن كنت تستورد الأعضاء دفعة واحدة: أكّدت قُرب تفعيل الاستيراد الجماعي لمفتاحك (الرد 403 INSUFFICIENT_PERMISSION يعني أنه لم يُفعَّل بعد).