الاتّصال عبر الويب (WebRTC)

تتيح لك Calling SDK إجراء مكالمات صوتيّة حقيقيّة من المتصفّح عبر WebRTC — دون إضافات. تُضمّن سكربتًا واحدًا، وتمنحه مفتاح API، ثمّ تستدعي connect() ثمّ initCall(). يتولّى Wave تسجيل SIP والوسائط وبيانات الجلسة قصيرة العمر نيابةً عنك.

يستخدم الاتّصال عبر الويب نطاق webrtc:write. في sandbox تكون المكالمات مقيّدة بالأصل (origin) وبوجهة رقم تسجيلك؛ ويزيل مفتاح production (sk_live_) قيد الوجهة.

التثبيت

npm install @wave-sa/calling-sdk

<script src="https://unpkg.com/@wave-sa/calling-sdk"></script>
<!-- يوفّر المتغيّر العامّ `Wave.SDK` -->

قبل البدء

اسمح بأصلك. في لوحة تحكّم Wave، أضِف الأصل الذي يعمل عليه تطبيقك (مثل https://app.example.com) إلى الأصول المسموح بها لمشروعك. تجلب الـ SDK جلستها من /v1/webrtc/config التي ترفض أيّ أصل ليس على القائمة.
استخدم مفتاح webrtc:write. يُرسَل المفتاح من المتصفّح، لذا فهو مقيّد بالأصل بحكم التصميم.

المفتاح المُضمَّن في المتصفّح مرئيّ لأيّ شخص يحمّل صفحتك. يقيّده Wave بالأصل (وبالوجهة في sandbox) لاحتواء الأثر — لكن في production عامِل المفتاح المُضمَّن كأنّه عامّ واقصره على webrtc:write فقط.

بداية سريعة

import { WaveSDK } from "@wave-sa/calling-sdk";

const sdk = new WaveSDK(
  { apiKey: "sk_live_xxxxxxxxxxxx", apiUrl: "https://api.wave.sa/v1" },
  {
    onConnected: () => console.log("مُسجَّل — جاهز للاتّصال"),
    onCallProgress: () => console.log("يرنّ…"),
    onCallConnected: () => console.log("في مكالمة"),
    onCallEnded: () => console.log("انتهت المكالمة"),
    onFailed: (err) => console.error(err.code, err.message),
  },
);

await sdk.connect();              // جلب الجلسة، فتح WebSocket، تسجيل SIP
await sdk.initCall("+966500000000"); // اتّصال
// … لاحقًا
await sdk.endCall();
sdk.disconnect();

الإعدادات

new WaveSDK(config, events)

الخيار	النوع	ملاحظات
`apiKey`	نصّ	مطلوب. مفتاحك `sk_sandbox_` / `sk_live_`.
`destination`	نصّ	رقم افتراضيّ اختياريّ لـ `initCall()`.
`locale`	`"en"` \| `"ar"`	لغة الواجهة. الافتراضيّ `"en"`.
`apiUrl`	نصّ	أساس الـ API. الافتراضيّ `https://api.wave.sa/v1`.

الدوالّ

الدالّة	ما تفعله
`connect()`	تجلب الجلسة، تفتح قناة الإشارة، وتسجّل. تُطلق `onConnected` عند الجاهزيّة.
`initCall(destination?)`	تحصل على الميكروفون وتتّصل. تُعيد `{ callSid, status: "initiated" }`.
`endCall()`	تنهي المكالمة النشطة.
`muteCall()` / `unmuteCall()`	كتم الميكروفون أو استعادته.
`holdCall()` / `resumeCall()`	تعليق المكالمة أو استئنافها.
`sendDTMF(tones, transportType?)`	إرسال نغمات لوحة المفاتيح (`0–9 * # A–D`). الافتراضيّ RFC 2833؛ مرّر `"INFO"` لـ SIP INFO.
`disconnect()`	تفكيك كلّ شيء وتحرير الميكروفون.
`isMuted`	حالة الكتم الحاليّة.

الأحداث

مرّر المُعالِجات في الوسيط الثاني للـ constructor.

الحدث	يُطلَق عند
`onConnecting()`	فتح قناة الإشارة.
`onConnected()`	التسجيل — جاهز للاتّصال.
`onCallProgress()`	رنين الطرف الآخر.
`onCallConnected()`	الردّ على المكالمة وتدفّق الوسائط.
`onCallEnded()`	إنهاؤك المكالمة عبر `endCall()`.
`onCallDisconnected(reason)`	انقطاع المكالمة — `reason` هو `NETWORK_ERROR` أو `TIMEOUT` أو `SERVER_ERROR` أو `REMOTE_HANGUP`.
`onMuteStateChange(isMuted)`	بعد `muteCall()` / `unmuteCall()`.
`onHold()` / `onResumed()`	تعليق المكالمة / استئنافها.
`onFailed(error)`	فشل الإعداد أو التسجيل — راجِع رموز الأخطاء أدناه.
`onTokenWillExpire()`	قبل ~60 ثانية من انتهاء بيانات الجلسة (للعلم).
`onSessionRefreshed()`	تدوير بيانات الجلسة بنجاح.
`onSessionEnded(reason)`	انتهاء الجلسة عند Wave (`auth_failure` أو `revoked`).

لا تتعامل أنت مع كلمة مرور SIP أو رمز الجلسة. تجلبها الـ SDK، وتُبقي المكالمة حيّة، وتدوّرها تلقائيًّا قبل انتهائها بنحو دقيقة.

رموز الأخطاء

يمنحك onFailed(error) قيمة error.code:

الرمز	المعنى
`INVALID_API_KEY_FORMAT`	`apiKey` ليس مفتاح Wave معروفًا.
`UNSUPPORTED_BROWSER`	لا دعم لـ WebRTC.
`MICROPHONE_UNAVAILABLE`	رُفض إذن الميكروفون أو لا جهاز إدخال.
`CONFIG_FAILED`	تعذّر جلب الجلسة — غالبًا الأصل غير مسموح به.
`AUTH_FAILURE`	رُفض المفتاح.
`REGISTRATION_FAILED`	فشل تسجيل SIP.
`TURN_UNAVAILABLE`	لا مُرحِّل وسائط على شبكة مقيّدة.
`CALL_ALREADY_ACTIVE` / `NO_ACTIVE_CALL`	سوء استخدام لحالة المكالمة.
`NOT_CONNECTED`	استدعاء `initCall()` قبل اكتمال `connect()`.
`CALL_FAILED`	تعذّر إعداد المكالمة.

الخطوات التالية

كيف يعمل الصوت

أين تقع مكالمة المتصفّح في دورة حياة المكالمة.

المكالمات والتسجيلات

اقرأ السجلّ واجلب تسجيلًا.

البدء

الصوت

Web Callback

المرجع

الاتّصال عبر الويب (WebRTC)

التثبيت

قبل البدء

بداية سريعة

الإعدادات

الدوالّ

الأحداث

رموز الأخطاء

الخطوات التالية

كيف يعمل الصوت

المكالمات والتسجيلات

​التثبيت

​قبل البدء

​بداية سريعة

​الإعدادات

​الدوالّ

​الأحداث

​رموز الأخطاء

​الخطوات التالية

كيف يعمل الصوت

المكالمات والتسجيلات

التثبيت

قبل البدء

بداية سريعة

الإعدادات

الدوالّ

الأحداث

رموز الأخطاء

الخطوات التالية