amazon chime sdk js
Release amazon-chime-sdk-3.25.0
مجلس مشروع Amazon Chime SDK
مكونات تفاعل Amazon Chime SDK
Amazon Chime SDK عبارة عن مجموعة من مكونات الاتصالات في الوقت الفعلي التي يمكن للمطورين استخدامها لإضافة إمكانات مشاركة الرسائل والصوت والفيديو والشاشة بسرعة إلى تطبيقات الويب أو الهاتف المحمول الخاصة بهم.
يمكن للمطورين الاعتماد على البنية التحتية للاتصالات العالمية لشركة AWS لتقديم تجارب جذابة في تطبيقاتهم. على سبيل المثال، يمكنهم إضافة فيديو إلى تطبيق صحي حتى يتمكن المرضى من استشارة الأطباء عن بُعد بشأن المشكلات الصحية، أو إنشاء مطالبات صوتية مخصصة للتكامل مع شبكة الهاتف العامة.
تعمل Amazon Chime SDK for JavaScript عن طريق الاتصال بموارد جلسة الاجتماع التي تقوم بإنشائها في حساب AWS الخاص بك. تحتوي مجموعة SDK على كل ما تحتاجه لإنشاء تجارب اتصال وتعاون مخصصة في تطبيق الويب الخاص بك، بما في ذلك طرق تكوين جلسات الاجتماع، وقائمة أجهزة الصوت والفيديو وتحديدها، وبدء وإيقاف مشاركة الشاشة وعرض مشاركة الشاشة، وتلقي عمليات رد الاتصال عند أحداث الوسائط مثل تحدث تغييرات في مستوى الصوت، والتحكم في ميزات الاجتماع مثل كتم الصوت وربط مقاطع الفيديو.
إذا كنت تقوم بإنشاء تطبيق React، ففكر في استخدام Amazon Chime SDK React Component Library التي توفر إدارة الحالة من جانب العميل ومكونات واجهة المستخدم القابلة لإعادة الاستخدام لواجهات الويب الشائعة المستخدمة في تطبيقات مؤتمرات الصوت والفيديو. تقدم Amazon Chime أيضًا Amazon Chime SDK لنظام iOS وAmazon Chime SDK لنظام Android لتطوير تطبيقات الهاتف المحمول الأصلية.
تلتقط لوحة مشروع Amazon Chime SDK حالة طلبات ميزات المجتمع عبر جميع مستودعاتنا. تم توضيح أوصاف الأعمدة الموجودة على اللوحة في هذا الدليل.
بالإضافة إلى ما يلي، إليك قائمة بجميع منشورات المدونة حول Amazon Chime SDK.
تغطي أدلة المطورين التالية موضوعات محددة للجمهور التقني.
تغطي أدلة المطورين التالية Amazon Chime SDK على نطاق أوسع.
.js واحدقم بمراجعة الموارد الواردة في ملف README واستخدم وثائق عملائنا للحصول على إرشادات حول كيفية تطوير Chime SDK لـ JavaScript. بالإضافة إلى ذلك، ابحث في قاعدة بيانات المشكلات والأسئلة الشائعة لمعرفة ما إذا كانت مشكلتك قد تمت معالجتها بالفعل. إذا لم يكن الأمر كذلك، فيرجى طرح مشكلة لنا باستخدام النماذج المتوفرة.
تتناول مشاركة المدونة المراقبة واستكشاف الأخطاء وإصلاحها باستخدام Amazon Chime SDK Meeting Events بالتفصيل حول كيفية استخدام أحداث الاجتماع لاستكشاف أخطاء تطبيقك وإصلاحها عن طريق تسجيل الدخول إلى Amazon CloudWatch.
إذا كان لديك المزيد من الأسئلة، أو كنت بحاجة إلى دعم لشركتك، يمكنك التواصل مع دعم عملاء AWS. يمكنك مراجعة خطط الدعم لدينا هنا.
تستخدم Amazon Chime SDK لـ JavaScript WebRTC، وهي واجهة برمجة التطبيقات للاتصالات في الوقت الفعلي المدعومة في معظم المتصفحات الحديثة. فيما يلي بعض الموارد العامة حول WebRTC.
تأكد من أن لديك الإصدار 18 من Node.js أو أعلى. يوصى بالعقدة 20 ويدعمها.
لإضافة Amazon Chime SDK لـ JavaScript إلى تطبيق موجود، قم بتثبيت الحزمة مباشرة من npm:
npm install amazon-chime-sdk-js --save
لاحظ أن Amazon Chime SDK لـ JavaScript يستهدف ES2015، وهو متوافق تمامًا مع جميع المتصفحات المدعومة.
قم بإنشاء جلسة اجتماع في تطبيق العميل الخاص بك.
import {
ConsoleLogger ,
DefaultDeviceController ,
DefaultMeetingSession ,
LogLevel ,
MeetingSessionConfiguration
} from 'amazon-chime-sdk-js' ;
const logger = new ConsoleLogger ( 'MyLogger' , LogLevel . INFO ) ;
const deviceController = new DefaultDeviceController ( logger ) ;
// You need responses from server-side Chime API. See below for details.
const meetingResponse = /* The response from the CreateMeeting API action */ ;
const attendeeResponse = /* The response from the CreateAttendee or BatchCreateAttendee API action */ ;
const configuration = new MeetingSessionConfiguration ( meetingResponse , attendeeResponse ) ;
// In the usage examples below, you will use this meetingSession object.
const meetingSession = new DefaultMeetingSession (
configuration ,
logger ,
deviceController
) ; يمكنك استخدام AWS SDK، أو واجهة سطر أوامر AWS (AWS CLI)، أو REST API لإجراء استدعاءات API. في هذا القسم، ستستخدم AWS SDK لـ JavaScript في تطبيق الخادم الخاص بك، على سبيل المثال Node.js. راجع مرجع واجهة برمجة تطبيقات Amazon Chime SDK لمزيد من المعلومات.
️ لا يتطلب تطبيق الخادم Amazon Chime SDK لـ JavaScript.
const AWS = require ( 'aws-sdk' ) ;
const { v4 : uuid } = require ( 'uuid' ) ;
// You must use "us-east-1" as the region for Chime API and set the endpoint.
const chime = new AWS . ChimeSDKMeetings ( { region : 'us-east-1' } ) ;
const meetingResponse = await chime
. createMeeting ( {
ClientRequestToken : uuid ( ) ,
MediaRegion : 'us-west-2' , // Specify the region in which to create the meeting.
} )
. promise ( ) ;
const attendeeResponse = await chime
. createAttendee ( {
MeetingId : meetingResponse . Meeting . MeetingId ,
ExternalUserId : uuid ( ) , // Link the attendee to an identity managed by your application.
} )
. promise ( ) ; الآن قم بنقل كائنات meetingResponse و attendeeResponse بشكل آمن إلى تطبيق العميل الخاص بك. تحتوي هذه الكائنات على كافة المعلومات المطلوبة لتطبيق العميل الذي يستخدم Amazon Chime SDK لـ JavaScript للانضمام إلى الاجتماع.
يجب تعيين قيمة معلمة MediaRegion في createMeeting() بشكل مثالي على إحدى مناطق الوسائط الأقرب إلى المستخدم الذي يقوم بإنشاء اجتماع. يمكن العثور على التنفيذ ضمن موضوع "اختيار أقرب منطقة وسائط" في وثائق مناطق وسائط Amazon Chime SDK.
قم بإنشاء جلسة مراسلة في تطبيق العميل الخاص بك لتلقي الرسائل من Amazon Chime SDK للمراسلة.
import { ChimeSDKMessagingClient } from '@aws-sdk/client-chime-sdk-messaging' ;
import {
ConsoleLogger ,
DefaultMessagingSession ,
LogLevel ,
MessagingSessionConfiguration ,
} from 'amazon-chime-sdk-js' ;
const logger = new ConsoleLogger ( 'SDK' , LogLevel . INFO ) ;
// You will need AWS credentials configured before calling AWS or Amazon Chime APIs.
const chime = new ChimeSDKMessagingClient ( { region : 'us-east-1' } ) ;
const userArn = /* The userArn */ ;
const sessionId = /* The sessionId */ ;
const configuration = new MessagingSessionConfiguration ( userArn , sessionId , undefined , chime ) ;
const messagingSession = new DefaultMessagingSession ( configuration , logger ) ; إذا كنت ترغب في تمكين ميزة الجلب المسبق عند الاتصال بجلسة مراسلة، فيمكنك اتباع الكود أدناه. سترسل ميزة الجلب المسبق حدث CHANNEL_DETAILS عند اتصال websocket، والذي يتضمن معلومات حول القناة ورسائل القناة وعضويات القناة وما إلى ذلك. ويمكن تعديل ترتيب فرز الجلب المسبق باستخدام prefetchSortBy ، وتعيينه إما على unread (القيمة الافتراضية إذا لم يتم تعيينها) أو lastMessageTimestamp
configuration . prefetchOn = Prefetch . Connect ;
configuration . prefetchSortBy = PrefetchSortBy . Unread ; git fetch --tags https://github.com/aws/amazon-chime-sdk-js
npm run build
npm run test
بعد تشغيل npm run test للمرة الأولى، يمكنك استخدام npm run test:fast لتسريع مجموعة الاختبار.
يتم جلب العلامات لإنشاء بيانات تعريف الإصدار بشكل صحيح.
لعرض نتائج تغطية التعليمات البرمجية، افتح coverage/index.html في متصفحك بعد تشغيل npm run test .
إذا قمت بتشغيل npm run test وكانت الاختبارات قيد التشغيل ولكن لم يتم إنشاء تقرير التغطية، فقد تكون لديك مشكلة في تنظيف المورد. في Mocha v4.0.0 أو الأحدث، تم تغيير التنفيذ بحيث لا تفرض عمليات Mocha الخروج عند اكتمال التشغيل الاختباري.
على سبيل المثال، إذا كان لديك DefaultVideoTransformDevice في اختبار الوحدة الخاصة بك، فيجب عليك استدعاء await device.stop(); لتنظيف الموارد وعدم الوقوع في هذه المشكلة. يمكنك أيضًا النظر في استخدام done(); في وثائق موكا.
لإنشاء وثائق مرجعية لـ JavaScript API، قم بتشغيل:
npm run build
npm run doc
ثم افتح docs/index.html في متصفحك.
إذا اكتشفت مشكلة أمنية محتملة في هذا المشروع، فنطلب منك إخطار AWS/Amazon Security عبر صفحة الإبلاغ عن الثغرات الأمنية. الرجاء عدم إنشاء مشكلة GitHub عامة.
ملاحظة: قبل بدء الجلسة، يتعين عليك اختيار الميكروفون ومكبر الصوت والكاميرا.
حالة الاستخدام 1. قم بإدراج أجهزة إدخال الصوت وإخراج الصوت وأجهزة إدخال الفيديو. سيطلب المتصفح أذونات الميكروفون والكاميرا.
مع تعيين المعلمة forceUpdate على "صحيح"، يتم تجاهل معلومات الجهاز المخزنة مؤقتًا وتحديثها بعد استدعاء مشغل تسمية الجهاز. في بعض الحالات، يحتاج المنشئون إلى تأخير تشغيل مربعات حوار الأذونات، على سبيل المثال، عند الانضمام إلى اجتماع في وضع العرض فقط، ومن ثم يمكنهم لاحقًا تشغيل مطالبة الإذن لإظهار تسميات الجهاز؛ تحديد forceUpdate يسمح بحدوث ذلك.
const audioInputDevices = await meetingSession . audioVideo . listAudioInputDevices ( ) ;
const audioOutputDevices = await meetingSession . audioVideo . listAudioOutputDevices ( ) ;
const videoInputDevices = await meetingSession . audioVideo . listVideoInputDevices ( ) ;
// An array of MediaDeviceInfo objects
audioInputDevices . forEach ( mediaDeviceInfo => {
console . log ( `Device ID: ${ mediaDeviceInfo . deviceId } Microphone: ${ mediaDeviceInfo . label } ` ) ;
} ) ; حالة الاستخدام 2. اختر أجهزة إدخال الصوت وإخراج الصوت عن طريق تمرير deviceId لكائن MediaDeviceInfo . لاحظ أنك تحتاج إلى استدعاء listAudioInputDevices و listAudioOutputDevices أولاً.
const audioInputDeviceInfo = /* An array item from meetingSession.audioVideo.listAudioInputDevices */ ;
await meetingSession . audioVideo . startAudioInput ( audioInputDeviceInfo . deviceId ) ;
const audioOutputDeviceInfo = /* An array item from meetingSession.audioVideo.listAudioOutputDevices */ ;
await meetingSession . audioVideo . chooseAudioOutput ( audioOutputDeviceInfo . deviceId ) ; حالة الاستخدام 3. اختر جهاز إدخال فيديو عن طريق تمرير deviceId لكائن MediaDeviceInfo . لاحظ أنك تحتاج إلى استدعاء listVideoInputDevices أولاً.
إذا كان هناك ضوء LED بجوار كاميرا الحاضر، فسيتم تشغيله للإشارة إلى أنه يتم الآن الالتقاط من الكاميرا. ربما تريد اختيار جهاز إدخال الفيديو عند بدء مشاركة الفيديو الخاص بك.
const videoInputDeviceInfo = /* An array item from meetingSession.audioVideo.listVideoInputDevices */ ;
await meetingSession . audioVideo . startVideoInput ( videoInputDeviceInfo . deviceId ) ;
// Stop video input. If the previously chosen camera has an LED light on,
// it will turn off indicating the camera is no longer capturing.
await meetingSession . audioVideo . stopVideoInput ( ) ; حالة الاستخدام 4. قم بإضافة مراقب تغيير الجهاز لتلقي قائمة الأجهزة المحدثة. على سبيل المثال، عندما تقوم بإقران سماعات رأس Bluetooth مع جهاز الكمبيوتر الخاص بك، يتم استدعاء audioInputsChanged و audioOutputsChanged مع قائمة الأجهزة بما في ذلك سماعات الرأس.
يمكنك استخدام رد الاتصال audioInputMuteStateChanged لتتبع حالة كتم صوت الأجهزة الأساسية على المتصفحات وأنظمة التشغيل التي تدعم ذلك.
const observer = {
audioInputsChanged : freshAudioInputDeviceList => {
// An array of MediaDeviceInfo objects
freshAudioInputDeviceList . forEach ( mediaDeviceInfo => {
console . log ( `Device ID: ${ mediaDeviceInfo . deviceId } Microphone: ${ mediaDeviceInfo . label } ` ) ;
} ) ;
} ,
audioOutputsChanged : freshAudioOutputDeviceList => {
console . log ( 'Audio outputs updated: ' , freshAudioOutputDeviceList ) ;
} ,
videoInputsChanged : freshVideoInputDeviceList => {
console . log ( 'Video inputs updated: ' , freshVideoInputDeviceList ) ;
} ,
audioInputMuteStateChanged : ( device , muted ) => {
console . log ( 'Device' , device , muted ? 'is muted in hardware' : 'is not muted' ) ;
} ,
} ;
meetingSession . audioVideo . addDeviceChangeObserver ( observer ) ; حالة الاستخدام 5. ابدأ الجلسة. لسماع الصوت، تحتاج إلى ربط جهاز والبث بعنصر <audio> . بمجرد بدء الجلسة، يمكنك التحدث والاستماع إلى الحضور. تأكد من اختيار الميكروفون ومكبر الصوت (راجع قسم "الجهاز")، ومن انضمام ضيف آخر على الأقل إلى الجلسة.
const audioElement = /* HTMLAudioElement object e.g. document.getElementById('audio-element-id') */ ;
meetingSession . audioVideo . bindAudioElement ( audioElement ) ;
const observer = {
audioVideoDidStart : ( ) => {
console . log ( 'Started' ) ;
}
} ;
meetingSession . audioVideo . addObserver ( observer ) ;
meetingSession . audioVideo . start ( ) ;استخدم الحالة 6. قم بإضافة مراقب لتلقي أحداث دورة حياة الجلسة: الاتصال والبدء والتوقف.
ملاحظة: يمكنك إزالة مراقب عن طريق استدعاء
meetingSession.audioVideo.removeObserver(observer). في البنية القائمة على المكونات (مثل React وVue وAngular)، قد تحتاج إلى إضافة مراقب عند تثبيت مكون، وإزالته عند إلغاء تثبيته.
const observer = {
audioVideoDidStart : ( ) => {
console . log ( 'Started' ) ;
} ,
audioVideoDidStop : sessionStatus => {
// See the "Stopping a session" section for details.
console . log ( 'Stopped with a session status code: ' , sessionStatus . statusCode ( ) ) ;
} ,
audioVideoDidStartConnecting : reconnecting => {
if ( reconnecting ) {
// e.g. the WiFi connection is dropped.
console . log ( 'Attempting to reconnect' ) ;
}
} ,
} ;
meetingSession . audioVideo . addObserver ( observer ) ;ملاحظة: لقد قمت حتى الآن بإضافة مراقبين لتلقي أحداث دورة حياة الجهاز والجلسة. في حالات الاستخدام التالية، ستستخدم أساليب واجهة برمجة التطبيقات (API) في الوقت الفعلي لإرسال واستقبال مؤشرات مستوى الصوت والتحكم في حالة كتم الصوت.
حالة الاستخدام 7. كتم صوت الإدخال الصوتي وإلغاء كتمه.
// Mute
meetingSession . audioVideo . realtimeMuteLocalAudio ( ) ;
// Unmute
const unmuted = meetingSession . audioVideo . realtimeUnmuteLocalAudio ( ) ;
if ( unmuted ) {
console . log ( 'Other attendees can hear your audio' ) ;
} else {
// See the realtimeSetCanUnmuteLocalAudio use case below.
console . log ( 'You cannot unmute yourself' ) ;
}استخدم الحالة 8. للتحقق مما إذا كان الميكروفون المحلي مكتومًا أم لا، استخدم هذه الطريقة بدلاً من تتبع حالة كتم الصوت الخاصة بك.
const muted = meetingSession . audioVideo . realtimeIsLocalAudioMuted ( ) ;
if ( muted ) {
console . log ( 'You are muted' ) ;
} else {
console . log ( 'Other attendees can hear your audio' ) ;
}حالة الاستخدام 9. قم بتعطيل إلغاء كتم الصوت. إذا كنت تريد منع المستخدمين من إلغاء كتم الصوت بأنفسهم (على سبيل المثال أثناء العرض التقديمي)، فاستخدم هذه الطرق بدلاً من تتبع حالة إمكانية إلغاء كتم الصوت الخاصة بك.
meetingSession . audioVideo . realtimeSetCanUnmuteLocalAudio ( false ) ;
// Optional: Force mute.
meetingSession . audioVideo . realtimeMuteLocalAudio ( ) ;
const unmuted = meetingSession . audioVideo . realtimeUnmuteLocalAudio ( ) ;
console . log ( ` ${ unmuted } is false. You cannot unmute yourself` ) ;حالة الاستخدام 10. اشترك في تغييرات الحجم لحاضر محدد. يمكنك استخدام هذا لإنشاء واجهة مستخدم لمؤشر الحجم في الوقت الفعلي.
import { DefaultModality } from 'amazon-chime-sdk-js' ;
// This is your attendee ID. You can also subscribe to another attendee's ID.
// See the "Attendees" section for an example on how to retrieve other attendee IDs
// in a session.
const presentAttendeeId = meetingSession . configuration . credentials . attendeeId ;
meetingSession . audioVideo . realtimeSubscribeToVolumeIndicator (
presentAttendeeId ,
( attendeeId , volume , muted , signalStrength ) => {
const baseAttendeeId = new DefaultModality ( attendeeId ) . base ( ) ;
if ( baseAttendeeId !== attendeeId ) {
// See the "Screen and content share" section for details.
console . log ( `The volume of ${ baseAttendeeId } 's content changes` ) ;
}
// A null value for any field means that it has not changed.
console . log ( ` ${ attendeeId } 's volume data: ` , {
volume , // a fraction between 0 and 1
muted , // a boolean
signalStrength , // 0 (no signal), 0.5 (weak), 1 (strong)
} ) ;
}
) ;حالة الاستخدام 11. اشترك في كتم الصوت أو تغيير قوة الإشارة لحضور معين. يمكنك استخدام هذا لإنشاء واجهة مستخدم لكتم الصوت فقط أو لتغييرات قوة الإشارة فقط.
// This is your attendee ID. You can also subscribe to another attendee's ID.
// See the "Attendees" section for an example on how to retrieve other attendee IDs
// in a session.
const presentAttendeeId = meetingSession . configuration . credentials . attendeeId ;
// To track mute changes
meetingSession . audioVideo . realtimeSubscribeToVolumeIndicator (
presentAttendeeId ,
( attendeeId , volume , muted , signalStrength ) => {
// A null value for volume, muted and signalStrength field means that it has not changed.
if ( muted === null ) {
// muted state has not changed, ignore volume and signalStrength changes
return ;
}
// mute state changed
console . log ( ` ${ attendeeId } 's mute state changed: ` , {
muted , // a boolean
} ) ;
}
) ;
// To track signal strength changes
meetingSession . audioVideo . realtimeSubscribeToVolumeIndicator (
presentAttendeeId ,
( attendeeId , volume , muted , signalStrength ) => {
// A null value for volume, muted and signalStrength field means that it has not changed.
if ( signalStrength === null ) {
// signalStrength has not changed, ignore volume and muted changes
return ;
}
// signal strength changed
console . log ( ` ${ attendeeId } 's signal strength changed: ` , {
signalStrength , // 0 (no signal), 0.5 (weak), 1 (strong)
} ) ;
}
) ;حالة الاستخدام 12. اكتشف المتحدث الأكثر نشاطًا. على سبيل المثال، يمكنك تكبير عنصر الفيديو الخاص بالمتحدث النشط إذا كان ذلك متاحًا.
import { DefaultActiveSpeakerPolicy } from 'amazon-chime-sdk-js' ;
const activeSpeakerCallback = attendeeIds => {
if ( attendeeIds . length ) {
console . log ( ` ${ attendeeIds [ 0 ] } is the most active speaker` ) ;
}
} ;
meetingSession . audioVideo . subscribeToActiveSpeakerDetector (
new DefaultActiveSpeakerPolicy ( ) ,
activeSpeakerCallback
) ;ملاحظة: في مصطلحات Chime SDK، يعتبر مربع الفيديو عبارة عن o
