رموز الانضمام الخاصة بـ RTC
يحتاج المشارك إلى بيانات اعتماد قصيرة الأمد للانضمام إلى غرفة. يمكن لخادمك الخلفي الحصول عليها بطريقتين:
| الطريقة | كيف | استخدم هذه الطريقة عندما |
|---|---|---|
| المعتمدة من الخادم | تقوم الخلفية الخاصة بك بالاتصال POST /v1/rooms/{roomId}/tokens باستخدام APIمفتاح | الافتراضي. APIاستدعاء واحد لكل عملية انضمام. |
| الإنشاء دون اتصال بالإنترنت | تقوم الخلفية الخاصة بك بتوقيع رمز الانضمام باستخدام مفتاح توقيع المشروع، دون استدعاء RTC؛ ويتم تبادل الرمز عند POST /v1/join | عند ارتفاع أحجام عمليات الانضمام، أو عندما لا ينبغي للخلفية الخاصة بك استدعاء RTC عند كل عملية انضمام |
كلاهما يمنحان نفس بيانات الاعتماد ويطبقان نفس فحوصات حالة الغرفة وسعتها وخطة الخدمة. في كلتا الحالتين تقرر الخلفية الخاصة بك من يمكنه الانضمام إلى أي غرفة؛ لا تسمح أبدًا للعميل باختيار غرفته أو دوره أو أذوناته بنفسه.
بيانات الاعتماد الصادرة عن الخادم
Section titled “بيانات الاعتماد الصادرة عن الخادم”curl --fail-with-body \ --request POST "https://api.rtc.champrep.com/v1/rooms/$RTC_ROOM_ID/tokens" \ --header "Authorization: Bearer $RTC_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"canPublish":true}'يحتاج المفتاح إلى tokens:write نطاق المطالبات. تحتوي الاستجابة على token,
participantId, url, iceServers و expiresIn؛ انظر
API مرجع و
تدفق الانضمام.
مفاتيح التوقيع الخاصة بالمشروع
Section titled “مفاتيح التوقيع الخاصة بالمشروع”ينتمي مفتاح التوقيع إلى مشروع واحد. ويكون id هو JWT kid.
| الخوارزمية | ما يحتفظ به RTC | ما تحتفظ به |
|---|---|---|
HS256 (افتراضي) | السر المشترك، المشفر | السر rtcsk_…، تُعرض مرة واحدة عند الإنشاء |
ES256 | المفتاح العام P-256 | المفتاح الخاص: يتم إنشاؤه بواسطة RTC ويتم عرضه مرة واحدة كـ JWK، أو مفتاحك الخاص (تقوم بإرسال JWK العام فقط) |
قم بإنشاء المفاتيح في وحدة التحكم RTC، أو باستخدام جلسة عمل وحدة التحكم الخاصة بك من خلالAPI:
| الطريقة والمسار | النتيجة |
|---|---|
GET /v1/projects/{projectId}/signing-keys | المفاتيح: id, name, algorithm, prefix (HS256) أو publicKeyJwk (ES256)، createdAt, expiresAt, revokedAt, lastUsedAt |
POST /v1/projects/{projectId}/signing-keys | 201، المفتاح، ومرة واحدة، secret (HS256) أو privateKeyJwk (ES256، مُولَّد) |
DELETE /v1/projects/{projectId}/signing-keys/{keyId} | { "revoked": true }؛ تتوقف الرموز الموقعة به عن العمل فورًا |
نص إنشاء هو { "name", "algorithm"?, "publicKeyJwk"?, "expiresInDays"? }.
expiresInDays تقبل القيم من 1 إلى 730؛ وبدونها لا تنتهي صلاحية المفتاح. يمكن أن يحتوي المشروع على ما يصل إلى خمسة مفاتيح نشطة (SIGNING_KEY_LIMIT). احتفظ بالمفتاح السري أو المفتاح الخاص في مدير الأسرار الخاص بخادمك فقط: لا تضعه أبدًا في متصفح أو تطبيق جوال أو مستودع أو دردشة. يمكن للمساعدCHAMPREP AI إدراج قائمة بمفاتيح التوقيع الخاصة بك، لكنه لا ينشئ مفتاحًا أبدًا ولا يعرض أي سر.
للتناوب، قم بإنشاء مفتاح جديد، ونشره، ثم قم بإلغاء المفتاح القديم.
تنسيق رمز الانضمام
Section titled “تنسيق رمز الانضمام”رمز الانضمام هو JWT موقّع بمفتاح توقيع المشروع.
| الجزء | الحقل | القواعد |
|---|---|---|
| رأس الرسالة | alg | HS256 أو ES256، خوارزمية المفتاح |
| رأس الرسالة | kid | مفتاح التوقيع id |
| المطالبات | aud | دائمًا rtc-join |
| المطالبات | roomId | الغرفة في مشروع المفتاح |
| المطالبات | iat, exp | أوقات الإصدار وانتهاء الصلاحية بالثواني؛ بفارق ساعة واحدة كحد أقصى |
| المطالبات | jti | معرف فريد، من 8 إلى 128 حرفًا (A-Z a-z 0-9 . _ : -)؛ يمكن استخدام كل رمز مرة واحدة |
| المطالبات (اختياري) | sub أو identity | معرف المستخدم الثابت الخاص بك (A-Z a-z 0-9 : _ -، بحد أقصى 128)؛ إذا تم تعيين كليهما، فيجب أن يتطابقا |
| المطالبات (اختياري) | name | الاسم المعروض للمشاركين الآخرين، بحد أقصى 80 حرفًا |
| المطالبات (اختياري) | role | host, cohost, participant, panelist أو attendee |
| المطالبات (اختياري) | permissions, canPublish | ما يمكن للمشارك نشره، كما هو الحال في طلب رمز REST |
| المطالبات (اختياري) | metadata | سلسلة نصية خاصة بك، بحد أقصى 1 كيلوبايت، مرئية للمشاركين الآخرين |
| المطالبات (اختياري) | ttlSeconds | مدة صلاحية بيانات اعتماد الوسائط التي يعيدها التبادل، من 30 إلى 300 |
| المطالبات (اختياري) | transcribe | false: هذا المشارك لا يتم نسخ؛ يتم تسجيل مساراتها ولكن يتم تخطيها في النص المكتوب |
اجعل مدة صلاحية الرمز قصيرة (بضع دقائق كافية لعملية الانضمام). أي رمز منتهي الصلاحية، أو معاد استخدامه، أو موقّع بشكل خاطئ، سيؤدي إلى 401
JOIN_GRANT_INVALID أو 409
JOIN_GRANT_USED.
Node.js (jose)
Section titled “Node.js (jose)”import { randomUUID } from 'node:crypto';import { SignJWT, importJWK } from 'jose';
// HS256: the key is the UTF-8 bytes of the whole rtcsk_ secret.const alg = 'HS256';const key = new TextEncoder().encode(process.env.RTC_SIGNING_SECRET);// ES256 instead:// const alg = 'ES256';// const key = await importJWK(JSON.parse(process.env.RTC_SIGNING_PRIVATE_JWK), 'ES256');
export async function mintJoinToken({ roomId, userId, displayName }) { return new SignJWT({ roomId, name: displayName, role: 'participant', canPublish: true }) .setProtectedHeader({ alg, kid: process.env.RTC_SIGNING_KEY_ID }) .setAudience('rtc-join') .setSubject(userId) .setIssuedAt() .setExpirationTime('5m') .setJti(randomUUID()) .sign(key);}Python (PyJWT)
Section titled “Python (PyJWT)”import jsonimport osimport timeimport uuid
import jwt # pip install "pyjwt[crypto]"
# HS256: the key is the whole rtcsk_ secret.KEY = os.environ["RTC_SIGNING_SECRET"]ALGORITHM = "HS256"# ES256 instead:# KEY = jwt.PyJWK(json.loads(os.environ["RTC_SIGNING_PRIVATE_JWK"])).key# ALGORITHM = "ES256"
def mint_join_token(room_id: str, user_id: str, display_name: str) -> str: now = int(time.time()) claims = { "aud": "rtc-join", "roomId": room_id, "sub": user_id, "name": display_name, "role": "participant", "canPublish": True, "iat": now, "exp": now + 300, "jti": str(uuid.uuid4()), } return jwt.encode(claims, KEY, algorithm=ALGORITHM, headers={"kid": os.environ["RTC_SIGNING_KEY_ID"]})
استبدال رمز الانضمام
Section titled “استبدال رمز الانضمام”POST /v1/join مع { "token": "<join token>" } تُرجع نفس النص الأساسي مثل
POST /v1/rooms/{roomId}/tokens. ولا تحتاج إلى مفتاحAPI: رمز الانضمام هو التفويض.
curl --fail-with-body \ --request POST https://api.rtc.champrep.com/v1/join \ --header 'Content-Type: application/json' \ --data "{\"token\":\"$RTC_JOIN_TOKEN\"}"قم بتبادل رمز الانضمام من الخادم الخاص بك، أو قم بترحيل التبادل من خلاله: تقبلAPI RTC طلبات المتصفح فقط من وحدات التحكم الخاصة CHAMPREPبـ، لذا فإن
POST /v1/join يتم رفض أي طلبات تُرسَل بواسطة متصفح من نطاقك. أرسل بيانات الاعتماد المتبادلة فقط إلى المستخدم الذي تم إنشاء الرمز الخاص به، عبر اتصالك المصادق عليه، وتعامل مع الرمز وبيانات الاعتماد على أنها معلومات سرية. قم بإنشاء رمز انضمام جديد لكل عملية انضمام وإعادة اتصال.