نظرة عامة على استدعاء SDK.
تسمح Azure Communication Services لمتصفحات المستخدمين النهائيين والتطبيقات والخدمات لدفع الاتصال الصوتي والفيديو. تركز هذه الصفحة على الاتصال ب SDK للعميل، والتي يمكن تضمينها في مواقع الويب والتطبيقات الأصلية. توفر هذه الصفحة أوصافا تفصيلية لميزات الاتصال بالعميل مثل معلومات دعم النظام الأساسي والمستعرض. تدير الخدمات المكالمات والوصول إليها برمجيا باستخدام واجهات برمجة تطبيقات أتمتة المكالمات. واجهة برمجة تطبيقات الغرف هي واجهة برمجة تطبيقات خدمات اتصالات Azure اختيارية تضيف ميزات إضافية إلى مكالمة صوتية أو مكالمة فيديو، مثل الأدوار والأذونات.
إشعار
يرجى مشاركة أفكارك وملاحظاتك حول Azure Communication Services معنا من خلال إجراء هذا الاستطلاع القصير.
لبناء تجربة المستخدم الخاصة بك باستخدام Calling SDK، راجع استدعاء التشغيل السريع أو استدعاء نموذج hero.
إذا كنت ترغب في المساعدة في تجربة المستخدم النهائي، توفر مكتبة واجهة مستخدم Azure Communication Services مجموعة من مكونات واجهة المستخدم الجاهزة للإنتاج مفتوحة المصدر للإفلات في التطبيق الخاص بك. باستخدام هذه المجموعة من عناصر التحكم التي تم إنشاؤها مسبقا، يمكنك إنشاء تجارب اتصال رائعة باستخدام لغة تصميم Fluent من Microsoft. إذا كنت تريد معرفة المزيد حول مكتبة واجهة المستخدم، فزر موقع النظرة العامة أو كتاب القصة.
بمجرد بدء التطوير، تحقق من صفحة المشكلات المعروفة للعثور على الأخطاء التي نعمل عليها.
ارتباطات SDK
| النظام الأساسي | الويب (JavaScript) | Windows (.NET) | iOS | Android | أخرى |
|---|---|---|---|---|---|
| الاتصال | npm | NuGet | GitHub | Maven | |
| مكتبة واجهة المستخدم | npm | - | GitHub | GitHub | GitHub, Storybook |
الميزات الرئيسية
- إدارة الأجهزة والوسائط- يوفر اتصال SDK تسهيلات للربط بأجهزة الصوت والفيديو، ويشفر المحتوى للإرسال الفعال عبر لوحة بيانات الاتصالات، ويعرض المحتوى إلى أجهزة الإخراج وطرق العرض التي تحددها. كما يتم توفير واجهات برمجة التطبيقات لمشاركة الشاشة والتطبيق.
- PSTN - يمكن ل SDK الاتصال ببدء المكالمات الصوتية مع شبكة الهاتف التقليدية التي تم تبديلها بشكل عام، باستخدام أرقام الهواتف التي تحصل عليها في مدخل Microsoft Azure أو برمجيا. يمكنك أيضا إحضار أرقامك الخاصة باستخدام وحدات التحكم في حدود جلسة العمل.
- اجتماعات Teams والمكالمات - يمكن ل SDK الاتصال بالانضمام إلى اجتماعات Teams والتفاعل مع مخطط بيانات الصوت والفيديو في Teams.
- التشفير - يقوم اتصال SDK بتشفير حركة المرور ويمنع التلاعب بالأسلاك.
- العنونة- توفر خدمات استدعاء Azure هوياتعامة تُستخدم لمعالجة نقاط نهاية الاتصال. يستخدم العملاء هذه الهويات للمصادقة على الخدمة والتواصل مع بعضهم البعض. يتم استخدام هذه الهويات في استدعاء واجهات برمجة التطبيقات التي توفر للعملاء رؤية لمن يتصل بمكالمة (القائمة).
- أمان وصول المستخدم
- يتم فرض التحكم في كشف القوائم والتحكم في الجدول وأدوار/أذونات المستخدم من خلال الغرف الظاهرية.
- يمكن إدارة قدرة المستخدم على بدء مكالمة جديدة أو الانضمام إلى مكالمة موجودة من خلال هويات المستخدم والرموز المميزة
- إعلامات - يوفر SDK الاتصال بواجهات برمجة التطبيقات والسماح بإعلام بالمكالمة الواردة. في الحالات التي لا يعمل فيها تطبيقك في المقدمة، تتوفر أنماط لإطلاق الإعلامات المنبثقة ("الإعلامات المنبثقة") لإعلام المستخدمين النهائيين بمكالمة واردة.
- إحصائيات الوسائط - يوفر Calling SDK رؤى شاملة حول مقاييس VoIP ومكالمات الفيديو. باستخدام هذه المعلومات، يتمتع المطورون بفهم أوضح لجودة المكالمات ويمكنهم اتخاذ قرارات مستنيرة لزيادة تعزيز تجربة الاتصال الخاصة بهم.
- قيود الفيديو - يوفر Calling SDK واجهات برمجة التطبيقات التي تكتسب القدرة على تنظيم جودة الفيديو بين معلمات أخرى أثناء مكالمات الفيديو عن طريق ضبط المعلمات مثل الدقة ومعدل الإطارات التي تدعم مواقف المكالمات المختلفة لمستويات مختلفة من جودة الفيديو
- تشخيصات مواجهة المستخدم (UFD) - يوفر Calling SDK أحداثا مصممة لتوفير رؤى حول المشكلات الأساسية التي يمكن أن تؤثر على جودة المكالمة. يمكن للمطورين الاشتراك في مشغلات مثل إشارات الشبكة الضعيفة أو الميكروفونات المكتمة، ما يضمن أنهم على علم دائما بأي عوامل تؤثر على المكالمات.
الإمكانات المفصلة
تعرض القائمة التالية مجموعة الميزات المتوفرة حاليا في Azure Communication Services Calling SDKs.
| مجموعة من الميزات | الإمكانية | JS | Windows | Java (Android) | الهدف -C (iOS) |
|---|---|---|---|---|---|
| الإمكانيات الأساسية | إجراء مكالمة فردية بين مستخدمين | ✔️ | ✔️ | ✔️ | ✔️ |
| إجراء مكالمة جماعية مع أكثر من اثنين من المستخدمين (حتى 100 مستخدم) | ✔️ | ✔️ | ✔️ | ✔️ | |
| ترقية المكالمة الفردية بين مستخدمين إلى مكالمة مجموعة بين أكثر من اثنين. | ✔️ | ✔️ | ✔️ | ✔️ | |
| الانضمام إلى مكالمة جماعية بعد بدء تشغيلها | ✔️ | ✔️ | ✔️ | ✔️ | |
| دعوة مشارك آخر في الاتصالات عبر بروتوكول الإنترنت للانضمام إلى مكالمة جماعية مستمرة | ✔️ | ✔️ | ✔️ | ✔️ | |
| التحكم في منتصف المكالمة | تشغيل/إيقاف تشغيل الفيديو | ✔️ | ✔️ | ✔️ | ✔️ |
| كتم صوت الميكروفون/إلغاء كتمه | ✔️ | ✔️ | ✔️ | ✔️ | |
| كتم صوت المشاركين الآخرين | ✔️1 | ✔️1 | ✔️1 | ✔️1 | |
| التبديل بين الكاميرات | ✔️ | ✔️ | ✔️ | ✔️ | |
| احتجاز محلي/إلغاء تعليق | ✔️ | ✔️ | ✔️ | ✔️ | |
| مكبر صوت النشط | ✔️ | ✔️ | ✔️ | ✔️ | |
| اختيار مكبر الصوت للمكالمات | ✔️ | ✔️ | ✔️ | ✔️ | |
| اختيار الميكروفون للمكالمات | ✔️ | ✔️ | ✔️ | ✔️ | |
| إظهار حالة المشارك التعطل، الإعلام المبكر، الاتصال، متصل، في الاحتجاز، في الانتظار، قطع الاتصال |
✔️ | ✔️ | ✔️ | ✔️ | |
| إظهار حالة المكالمة الوسائط المبكرة، الواردة، التوصيل، الرنين، الاتصال، الاحتفاظ، يجري قطع الاتصال، قطع الاتصال |
✔️ | ✔️ | ✔️ | ✔️ | |
| إظهار ما إذا كان أحد المشاركين صامتًا | ✔️ | ✔️ | ✔️ | ✔️ | |
| إظهار سبب ترك أحد المشاركين لمكالمة | ✔️ | ✔️ | ✔️ | ✔️ | |
| مشاركة الشاشة | مشاركة الشاشة بالكامل من داخل التطبيق | ✔️ | ✔️2 | ✔️2 | ✔️2 |
| مشاركة تطبيق معين (من قائمة التطبيقات قيد التشغيل) | ✔️ | ✔️2 | ❌ | ❌ | |
| مشاركة علامة تبويب مستعرض ويب من قائمة علامات التبويب المفتوحة | ✔️ | ||||
| مشاركة صوت النظام أثناء مشاركة الشاشة | ✔️ | ❌ | ❌ | ❌ | |
| يمكن للمشارك عرض مشاركة الشاشة البعيدة | ✔️ | ✔️ | ✔️ | ✔️ | |
| قائمة المكالمات | قائمة المشاركين | ✔️ | ✔️ | ✔️ | ✔️ |
| إزالة مشارك | ✔️ | ✔️ | ✔️ | ✔️ | |
| PSTN | إجراء مكالمة واحدة مع مشارك شبكة الهاتف العامة | ✔️ | ✔️ | ✔️ | ✔️ |
| إجراء مكالمة جماعية مع المشاركين في شبكة الهاتف العامة | ✔️ | ✔️ | ✔️ | ✔️ | |
| الترويج لمكالمة واحدة مع مشارك شبكة هاتف عامة في مكالمة جماعية | ✔️ | ✔️ | ✔️ | ✔️ | |
| الطلب الهاتفي من مكالمة جماعية كمشارك في شبكة هاتف عامة | ✔️ | ✔️ | ✔️ | ✔️ | |
| دعم الوسائط المبكرة | ✔️ | ✔️ | ✔️ | ✔️ | |
| عام | اختبر الميكروفون والمكبر والكاميرا باستخدام خدمة اختبار الصوت (متوفرة عن طريق الاتصال بالرقم 8:echo123) | ✔️ | ✔️ | ✔️ | ✔️ |
| إدارة الأجهزة | اطلب الإذن باستخدام الصوت و/أو الفيديو | ✔️ | ✔️ | ✔️ | ✔️ |
| الحصول على قائمة الكاميرا | ✔️ | ✔️ | ✔️ | ✔️ | |
| تعيين الكاميرا | ✔️ | ✔️ | ✔️ | ✔️ | |
| الحصول على كاميرا محددة | ✔️ | ✔️ | ✔️ | ✔️ | |
| الحصول على قائمة الميكروفون | ✔️ | ✔️ | ❌3 | ❌3 | |
| تعيين الميكروفون | ✔️ | ✔️ | ❌3 | ❌3 | |
| الحصول على ميكروفون محدد | ✔️ | ✔️ | ❌3 | ❌3 | |
| الحصول على قائمة مكبرات الصوت | ✔️ | ✔️ | ❌3 | ❌3 | |
| تعيين مكبر الصوت | ✔️ | ✔️ | ❌3 | ❌3 | |
| الحصول على مكبر صوت محدد | ✔️ | ✔️ | ❌3 | ❌3 | |
| عرض الفيديو | عرض فيديو واحد في العديد من الأماكن (الكاميرا المحلية أو البث البعيد) | ✔️ | ✔️ | ✔️ | ✔️ |
| تعيين / تحديث وضع التحجيم | ✔️ | ✔️ | ✔️ | ✔️ | |
| عرض دفق الفيديو عن بُعد | ✔️ | ✔️ | ✔️ | ✔️ | |
| تأثيرات الفيديو | تمويه الخلفية | ✔️ | ✔️ | ✔️ | ✔️ |
| صورة خلفية مخصصة | ✔️ | ✔️ | ✔️ | ✔️ | |
| التأثيرات الصوتية | وضع الموسيقى | ❌ | ✔️ | ✔️ | ✔️ |
| إلغاء صدى الصوت | ❌ | ✔️ | ✔️ | ✔️ | |
| ضغط الضوضاء | ✔️ | ✔️ | ✔️ | ✔️ | |
| التحكم التلقائي في الاكتساب (AGC) | ❌ | ✔️ | ✔️ | ✔️ | |
| الإعلامات 4 | الإعلامات | ✔️ | ✔️ | ✔️ | ✔️ |
1 القدرة على كتم صوت الآخرين حاليا في المعاينة العامة.
2 يمكن تحقيق إمكانية مشاركة الشاشة باستخدام واجهات برمجة تطبيقات الوسائط الأولية. لمعرفة المزيد، تفضل بزيارة دليل التشغيل السريع للوصول إلى الوسائط الأولية.
3 لا يحتوي Calling SDK على واجهة برمجة تطبيقات صريحة لهذه الوظائف، يجب عليك استخدام واجهات برمجة تطبيقات نظام التشغيل Android وiOS لتحقيقها بدلا من ذلك.
4 الحد الأقصى لقيمة TTL في الأنظمة الأساسية الأصلية، هو 180 يوما (15552000 ثانية)، وقيمة الحد الأدنى هي 5 دقائق (300 ثانية). بالنسبة إلى CTE (نقطة نهاية Teams المخصصة)/M365 Identity، تبلغ قيمة TTL القصوى 24 ساعة (86400 ثانية).
دعم JavaScript استدعاء SDK بواسطة نظام التشغيل والمتصفح
يمثل الجدول التالي مجموعة المستعرضات المدعومة المتوفرة حاليا. نحن ندعم أحدث ثلاثة إصدارات رئيسية من المتصفح (أحدث ثلاثة إصدارات ثانوية ل Safari) ما لم يشار إلى خلاف ذلك.
| النظام الأساسي | Chrome | Safari | Edge | Firefox | عرض ويب | إلكترون |
|---|---|---|---|---|---|---|
| Android | ✔️ | ❌ | ✔️ | ❌ | ✔️ | ❌ |
| iOS | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ |
| macOS | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ |
| Windows | ✔️ | ❌ | ✔️ | ✔️ | ❌ | ✔️ |
| Ubuntu/Linux | ✔️ | ❌ | ❌ | ❌ | ❌ | ❌ |
- مشاركة الشاشة الصادرة غير مدعومة على مستعرضات الأجهزة المحمولة التي تعمل بنظام التشغيل iOS أو Android.
- دعم Firefox في المعاينة العامة.
- حاليا، يدعم استدعاء SDK فقط نظام Android WebView على Android وiOS WebView (WKWebView) في المعاينة العامة. لا يتم دعم أنواع أخرى من المستعرضات المضمنة أو WebView على الأنظمة الأساسية الأخرى لنظام التشغيل رسميا، على سبيل المثال، GeckoView وChromium Embedded Framework (CEF) وMicrosoft Edge WebView2. لا يتم اختبار تشغيل JavaScript Calling SDK على هذه الأنظمة الأساسية بشكل نشط، فقد يعمل أو لا يعمل.
- يتعذر على تطبيق iOS على Safari تعداد/تحديد أجهزة الميكروفون والسماعات (على سبيل المثال، Bluetooth). هذه المشكلة هي قيود على iOS، ويتحكم نظام التشغيل في تحديد الجهاز الافتراضي.
استدعاء العميل - طراز أمان المستعرض
استخدام WebRTC عبر HTTPS
تتطلب واجهات برمجة تطبيقات WebRTC مثل getUserMedia التطبيق الذي يستدعي واجهات برمجة التطبيقات هذه عبر HTTPS. للتنمية المحلية، يمكنك استخدام http://localhost .
تضمين خدمات الاتصال التي تستدعي SDK في iframe
يتوفر نهج أذونات جديد (يسمى أيضا نهج ميزة) في مستعرضات مختلفة. تؤثر هذه السياسة على سيناريوهات الاتصال من خلال التحكم في كيفية وصول التطبيقات إلى الكاميرا والميكروفون للجهاز من خلال عنصر iframe عبر الأصل.
إذا كنت ترغب في استخدام iframe لاستضافة جزء من التطبيق من مجال مختلف، يجب إضافة allow السمة ذات القيمة الصحيحة إلى iframe الخاص بك.
على سبيل المثال، يسمح هذا الإطار iframe لكل من الكاميرا والميكروفون بالوصول:
<iframe allow="camera *; microphone *">
دعم SDK الاتصال بنظام التشغيل Android
- دعم واجهة برمجة التطبيقات لـAndroid للمستوى 21 أو أعلى
- دعم Java 7 أو أعلى
- الدعم لـ Android Studio 2.0
- أجهزة Android Auto وIoT التي تعمل بنظام التشغيل Android غير مدعومة حاليا
دعم iOS Calling SDK
- دعم iOS 10.0+ في وقت الإنشاء، و iOS 12.0+ في وقت التشغيل
- Xcode 12.0+
- دعم iPadOS 13.0+
الحد الأقصى لمدة المكالمة
الحد الأقصى لمدة المكالمة هو 30 ساعة، وسيتم قطع اتصال المشاركين الذين يصلون إلى الحد الأقصى لمدة المكالمة البالغة 30 ساعة من المكالمة.
العدد المعتمد لتدفقات الفيديو الواردة
تدعم Azure Communication Services Calling SDK تكوينات الدفق التالية:
| الحد | الويب | Windows/Android/iOS |
|---|---|---|
| الحد الأقصى لعدد التدفقات المحلية الصادرة التي يمكن إرسالها في وقتٍ واحدٍ | فيديو ومشاركة شاشة 1 | فيديو واحد+مشاركة شاشة واحدة |
| العدد الأقصى من التدفقات البعيدة الواردة التي يمكن تقديمها في وقتٍ واحدٍ | 9 مقاطع فيديو + مشاركة شاشة 1 على مستعرضات سطح المكتب*، 4 مقاطع فيديو + 1 مشاركة شاشة على مستعرضات الويب للأجهزة المحمولة | 9 مقاطع فيديو + مشاركة شاشة 1 |
* بدءا من Azure Communication Services Web Calling SDK الإصدار 1.16.3 بينما لا يفرض Calling SDK هذه الحدود، قد يواجه المستخدمون تدهورا في الأداء إذا تم تجاوزها. استخدم واجهة برمجة التطبيقات الخاصة بعدد الفيديو الأمثل لتحديد عدد تدفقات الفيديو الواردة الحالية التي يمكن أن تدعمها بيئة الويب الخاصة بك.
دقة الفيديو المدعومة
تقوم Azure Communication Services Calling SDK تلقائيا بضبط دقة تدفقات مشاركة الفيديو والشاشة أثناء المكالمة.
إشعار
يمكن أن يختلف الحل اعتمادا على عدد المشاركين في مكالمة، ومقدار النطاق الترددي المتاح للعميل، وقدرات الأجهزة للمشارك المحلي الذي يعرض سلاسل الفيديو عن بعد ومعلمات المكالمات الإجمالية الأخرى.
يدعم Azure Communication Services Calling SDK إرسال دقة الفيديو التالية
| الحد الأقصى لدقة الفيديو | WebJS | iOS | Android | النوافذ |
|---|---|---|---|---|
| إرسال فيديو | 720P | 720P | 720P | 1080P |
| إرسال مشاركة الشاشة | 1080P | 1080P | 1080P | 1080P |
| تلقي دفق فيديو عن بعد أو مشاركة شاشة | 1080P | 1080P | 1080P | 1080P |
عدد المشاركين في دعم المكالمة
- يمكن ما يصل إلى 350 مستخدما الانضمام إلى مكالمة جماعية أو غرفة أو Teams + مكالمة ACS.
- بمجرد أن يصل حجم المكالمة إلى أكثر من 100 مشارك في مكالمة، لا يمكن رؤية سوى أفضل 4 متحدثين مهيمنين تم تشغيل كاميرا الفيديو الخاصة بهم.
- عندما يكون عدد الأشخاص في المكالمة أكثر من 100، ينخفض عدد عرض الفيديو الوارد تلقائيا من 3x3 (9 مقاطع فيديو واردة) إلى 2x2 (4 مقاطع فيديو واردة).
- عندما يقل عدد المستخدمين عن 100، يعود عدد مقاطع الفيديو الواردة المدعومة إلى 3x3 (9 مقاطع فيديو واردة).
استدعاء مهلات SDK
تنطبق المهلات التالية على اتصالات خدمات استدعاء SDKs:
| الإجراء | المهلة بالثواني |
|---|---|
| مشارك إعادة الاتصال/الإزالة | 60 |
| إضافة طريقة جديدة أو إزالتها من مكالمة (بدء/إيقاف الفيديو أو مشاركة الشاشة) | 40 |
| مهلة عملية تحويل المكالمات | 60 |
| 1:1 استدعاء مهلة المؤسسة | 85 |
| مهلة إنشاء استدعاء المجموعة | 85 |
| استدعاء مهلة إنشاء شبكة الهاتف العامة | 115 |
| الترويج لمكالمة 1:1 إلى مهلة استدعاء جماعية | 115 |
الخطوات التالية
لمزيد من المعلومات، راجع المقالات التالية:
- اطلع على تدفقات المكالمات العامة
- تعرف على المزيد حول أنواع المكالمات
- تعرف على واجهة برمجة تطبيقات أتمتة المكالمات التي تمكنك من إنشاء مهام سير عمل الاتصال المستندة إلى الخادم التي يمكنها توجيه المكالمات والتحكم فيها باستخدام تطبيقات العميل.
- خطة حل شبكة الهاتف العامة الخاص بك