100ms flutter

؟ دليل الإعداد

اشترك على https://dashboard.100ms.live/register وزيارة علامة التبويب المطور للوصول إلى بيانات الاعتماد الخاصة بك.
تعرف على الرموز والأمن هنا
أكمل الخطوات في دليل البدء السريع لـ Auth Token
الحصول على HMSSDK عبر pub.dev. أضف hmssdk_flutter إلى pubspec.yaml الخاص بك.

قم بإحالة دليل التثبيت الكامل هنا.

؟ ♀ كيفية تشغيل تطبيق المثال

تطبيق المثال الكامل المتميز متاح هنا.

لقد أضفنا تفسيرات ودليل الاستخدام الموصى به لميزات مختلفة ، وتخطيطات واجهة المستخدم ، ومتجر البيانات ، وما إلى ذلك في مثال App readme.

لتشغيل تطبيق المثال على نظامك ، اتبع الخطوات هذه -

استنساخ 100ms رفرف جيثب ريبو
في جذر المشروع ، قم بتشغيل flutter pub get لبناء حزمة الرفرفة
تغيير الدليل إلى مجلد example
الآن ، لتشغيل التطبيق ، ما عليك سوى تنفيذ الأمر flutter run لتشغيل التطبيق على جهاز متصل أو محاكي iOS أو Android Emulator.
لتشغيله على جهاز iOS (iPhone أو iPad) ، تأكد من تعيين فريق التطوير الصحيح في قسم توقيع وقدرات Xcode.

يستخدم تطبيق المثال الافتراضي مكتبة إدارة حالة المزود. للتطبيقات الأخرى ، يرجى مراجعة -

Quickstart بسيط
كتلة
getx
MOBX
Riverpod
تطبيق غرفة الصوت
Callkit & VoIP
Flutterflow مع Brebuilt
البث المباشر مع HLS
التطبيق الكامل المميز

☝ الحد الأدنى للتكوين

دعم الرفرفة 3.3.0 أو أعلى
دعم Android API المستوى 21 أو أعلى
دعم Java 17 أو أعلى
دعم iOS 12 أو أعلى
Xcode 12 أو أعلى

؟ التكوين الموصى به

ترفرف 3.13.0 أو أعلى
Android API المستوى 34 أو أعلى
جافا 17 أو فوق
iOS 16 أو أعلى
Xcode 15 أو أعلى

الأجهزة المدعومة

يدعم نظام Android SDK مستوى API API Android 21 وما فوق. تم تصميمه لبنية Armeabi-V7a و Arm64-V8a و X86 و X86_64. ينصح الأجهزة التي تعمل بنظام التشغيل Android OS 12 أو أعلى.
يتم دعم iPhone & iPads مع الإصدار 12 أو أعلى. يوصى بأجهزة تشغيل iOS 16 أو أعلى.

؟ أذونات Android

دليل الأذونات الكامل متاح هنا.

أضف الأذونات التالية في ملف AndroidManifest.xml من Android's Android -

< uses-feature android : name = " android.hardware.camera " />

< uses-feature android : name = " android.hardware.camera.autofocus " />

< uses-permission android : name = " android.permission.CAMERA " />

< uses-permission android : name = " android.permission.CHANGE_NETWORK_STATE " />

< uses-permission android : name = " android.permission.MODIFY_AUDIO_SETTINGS " />

< uses-permission android : name = " android.permission.RECORD_AUDIO " />

< uses-permission android : name = " android.permission.INTERNET " />

< uses-permission android : name = " android.permission.ACCESS_NETWORK_STATE " />

< uses-permission android : name = " android.permission.FOREGROUND_SERVICE " />

< uses-permission android : name = " android.permission.BLUETOOTH " android : maxSdkVersion = " 30 " />

< uses-permission android : name = " android.permission.BLUETOOTH_CONNECT " />

؟ أذونات iOS

إضافة أذونات التالية في ملف IOS info.plist

< key >NSMicrophoneUsageDescription</ key >
< string >{YourAppName} wants to use your microphone</ string >

< key >NSCameraUsageDescription</ key >
< string >{YourAppName} wants to use your camera</ string >

< key >NSLocalNetworkUsageDescription</ key >
< string >{YourAppName} App wants to use your local network</ string >

؟ المفاهيم الرئيسية

Room هي الغرفة هي الكائن الأساسي الذي يعود 100 مللي ثانية SDKs على اتصال ناجح. يحتوي هذا على إشارات إلى أقرانها والمسارات وكل ما تحتاجه لتقديم تطبيق A/V أو البث المباشر.
Peer الأقران هو الكائن الذي تم إرجاعه بواسطة 100 مللي ثانية SDKs يحتوي على جميع المعلومات حول المستخدم - الاسم ، الدور ، مسار الفيديو ، إلخ.
Track A Track عبارة عن شريحة من الوسائط (الصوت/الفيديو) التي تم التقاطها من كاميرا الأقران والميكروفون. ينشر أقرانهم في جلسة المسارات المحلية والاشتراك في المسارات عن بُعد من أقرانهم الآخرين.
يحدد Role دور من يمكن أن يرى/سماع الأقران ، والجودة التي ينشر بها الفيديو ، سواء كان لديهم أذونات لنشر الفيديو/لقطة الشاشة ، كتم شخص ما ، دور شخص ما.

♻ إعداد مستمعي تحديث

يوفر 100 مللي ثانية SDK عمليات الاسترداد إلى تطبيق العميل حول أي تغيير أو تحديث يحدث في الغرفة بعد انضمام المستخدم عن طريق تطبيق HMSUpdateListener . يمكن استخدام هذه التحديثات لتقديم الفيديو على الشاشة أو لعرض معلومات أخرى بخصوص الغرفة. دعونا نلقي نظرة على المخطط الانسيابي.

 /// 100ms SDK provides callbacks to the client app about any change or update happening in the room after a user has joined by implementing HMSUpdateListener.
/// These updates can be used to render the video on the screen or to display other info regarding the room.
abstract class HMSUpdateListener {


  /// This will be called on a successful JOIN of the room by the user
  ///
  /// This is the point where applications can stop showing their loading state
  /// [room] : the room which was joined
  void onJoin ({ required HMSRoom room});


  /// This will be called whenever there is an update on an existing peer
  /// or a new peer got added/existing peer is removed.
  ///
  /// This callback can be used to keep a track of all the peers in the room
  /// [peer] : the peer who joined/left or was updated
  /// [update] : the triggered update type. Should be used to perform different UI Actions
  void onPeerUpdate ({ required HMSPeer peer, required HMSPeerUpdate update});


  /// This is called when there are updates on an existing track
  /// or a new track got added/existing track is removed
  ///
  /// This callback can be used to render the video on screen whenever a track gets added
  ///  [track] : the track which was added, removed or updated
  ///  [trackUpdate] : the triggered update type
  ///  [peer] : the peer for which track was added, removed or updated
  void onTrackUpdate ({ required HMSTrack track, required HMSTrackUpdate trackUpdate, required HMSPeer peer});


  /// This will be called when there is an error in the system
  /// and SDK has already retried to fix the error
  /// [error] : the error that occurred
  void onHMSError ({ required HMSException error});


  /// This is called when there is a new broadcast message from any other peer in the room
  ///
  /// This can be used to implement chat is the room
  /// [message] : the received broadcast message
  void onMessage ({ required HMSMessage message});


  /// This is called every 1 second with a list of active speakers
  ///
  /// ## A HMSSpeaker object contains -
  ///    - peerId: the peer identifier of HMSPeer who is speaking
  ///    - trackId: the track identifier of HMSTrack which is emitting audio
  ///    - audioLevel: a number within range 1-100 indicating the audio volume
  ///
  /// A peer who is not present in the list indicates that the peer is not speaking
  ///
  /// This can be used to highlight currently speaking peers in the room
  /// [speakers] the list of speakers
  void onUpdateSpeakers ({ required List < HMSSpeaker > updateSpeakers});


  /// This is called when there is a change in any property of the Room
  ///
  ///  [room] : the room which was joined
  ///  [update] : the triggered update type. Should be used to perform different UI Actions
  void onRoomUpdate ({ required HMSRoom room, required HMSRoomUpdate update});


  /// when network or some other error happens it will be called
  void onReconnecting ();


  /// when you are back in the room after reconnection
  void onReconnected ();


  /// This is called when someone asks for a change or role
  ///
  /// for eg. admin can ask a peer to become host from guest.
  /// this triggers this call on peer's app
  void onRoleChangeRequest ({ required HMSRoleChangeRequest roleChangeRequest});


  /// when someone requests for track change of yours be it video or audio this will be triggered
  /// [hmsTrackChangeRequest] request instance consisting of all the required info about track change
  void onChangeTrackStateRequest ({ required HMSTrackChangeRequest hmsTrackChangeRequest});


  /// when someone kicks you out or when someone ends the room at that time it is triggered
  /// [hmsPeerRemovedFromPeer] it consists of info about who removed you and why.
  void onRemovedFromRoom ({ required HMSPeerRemovedFromPeer hmsPeerRemovedFromPeer});


  /// whenever a new audio device is plugged in or audio output is changed we
  /// get the onAudioDeviceChanged update
  /// This callback is only fired on Android devices. On iOS, this callback will not be triggered.
  /// - Parameters:
  ///   - currentAudioDevice: Current audio output route
  ///   - availableAudioDevice: List of available audio output devices
  void onAudioDeviceChanged (
      { HMSAudioDevice ? currentAudioDevice,
      List < HMSAudioDevice > ? availableAudioDevice});


  /// Whenever a user joins a room [onSessionStoreAvailable] is fired to get an instance of [HMSSessionStore]
  /// which can be used to perform session metadata operations
  /// - Parameters:
  ///   - hmsSessionStore: An instance of HMSSessionStore which will be used to call session metadata methods
  void onSessionStoreAvailable (
      { HMSSessionStore ? hmsSessionStore});


  /// Upon joining a room with existing peers, onPeerListUpdated will be called with the list of peers present
  /// in the room instead of getting onPeerUpdate for each peer in the room.
  /// Subsequent peer joins/leaves would be notified via both onPeerUpdate and onPeerListUpdated
  void onPeerListUpdate (
      { required List < HMSPeer > addedPeers, required List < HMSPeer > removedPeers});
}

؟ كيف تستمع إلى تحديثات Peer & Track؟

يرسل 100 مللي ثانية SDK تحديثات إلى التطبيق حول أي تغيير في HMSPEER ، HMSTRACK ، HMSROOM ، إلخ عبر عروض الاسترجاعات في HMSUpdateListener .

يتم استدعاء طرق hmsupdatelistener لإخطار التحديثات التي تحدث في الغرفة مثل انضمام/إجازة نظير ، وتتبع كتم/unmut ، إلخ.

مزيد من المعلومات حول مستمعي التحديث متاح هنا.

فيما يلي أنواع التحديثات المختلفة التي تنبعث منها SDK -

HMSPeerUpdate
  .peerJoined: A new peer joins the Room
  .peerLeft: An existing peer leaves the Room
  .roleUpdated: When a peer's Role has changed
  .metadataChanged: When a peer's metadata has changed
  .nameChanged: When a peer's name has changed


HMSTrackUpdate
  .trackAdded: A new track (audio or video) is added to the Room
  .trackRemoved: An existing track is removed from the Room
  .trackMuted: A track of a peer is muted
  .trackUnMuted: A muted track of a peer was unmuted
  .trackDegraded: When track is degraded due to bad network conditions
  .trackRestored: When a degraded track is restored when optimal network conditions are available again


HMSRoomUpdate
  .roomMuted: When room is muted to due external interruption like a Phone Call
  .roomUnmuted: When a muted room is unmuted when external interruption has ended
  .serverRecordingStateUpdated: When Server recording state is updated
  .browserRecordingStateUpdated: When Browser recording state is changed
  .rtmpStreamingStateUpdated: When RTMP is started or stopped
  .hlsStreamingStateUpdated: When HLS is started or stopped
  .hlsRecordingStateUpdated: When HLS recording state is updated

انضم إلى غرفة

للانضمام والتفاعل مع الآخرين في مكالمة صوتية أو فيديو ، يحتاج المستخدم إلى join room .

للانضمام إلى غرفة ، يجب أن يكون لتطبيقك -

اسم المستخدم - الاسم الذي يجب عرضه على أقرانهم الآخرين في الغرفة.
رمز المصادقة - رمز المصادقة من جانب العميل الناتج عن خدمة الرمز المميز.

؟ احصل على رمز المصادقة

للانضمام إلى غرفة نحتاج إلى رمز مصادقة كما هو مذكور أعلاه. هناك طريقتان للحصول على الرمز المميز:

جلب الرمز المميز باستخدام طريقة رمز الغرفة (موصى بها)

يمكننا الحصول على رمز المصادقة باستخدام رمز الغرفة من اجتماع URL.

دعونا نفهم النطاق الفرعي والرمز من عينة عنوان URL في عنوان URL هذا: https://public.app.100ms.live/meeting/xvm-wxwo-gbl gbl

النطاق الفرعي public
رمز الغرفة هو xvm-wxwo-gbl

الآن للحصول على رمز الغرفة من مقابلة عنوان URL ، يمكننا كتابة منطقنا أو استخدام طريقة getCode من هنا

لتوليد الرمز المميز ، سوف نستخدم طريقة getAuthTokenByRoomCode من HMSSDK . تحتوي هذه الطريقة على roomCode كمعلمة مطلوبة ، userId ونقطة endPoint كمعلمة اختيارية.

يجب استدعاء هذه الطريقة بعد استدعاء طريقة build .

دعونا نغفد بالتنفيذ:

  //This returns an object of Future<dynamic> which can be either
  //of HMSException type or String? type based on whether
  //method execution is completed successfully or not

  dynamic authToken = await hmsSDK. getAuthTokenByRoomCode (roomCode : 'YOUR_ROOM_CODE' );

  if (authToken is String ){
    HMSConfig roomConfig = HMSConfig (
        authToken : authToken,
        userName : userName,
      );

    hmsSDK. join (config : roomConfig);
  }
  else if (authToken is HMSException ){
    // Handle the error
  }

احصل على رمز مؤقت من لوحة القيادة

لاختبار وظائف الصوت/الفيديو ، تحتاج إلى الاتصال بغرفة 100 مللي ثانية ؛ يرجى التحقق من الخطوات التالية لنفسه:

انتقل إلى لوحة معلومات 100 مللي ثانية أو إنشاء حساب إذا لم يكن لديك حساب.
استخدم Video Conferencing Starter Kit لإنشاء غرفة مع قالب افتراضي مخصص له لاختبار هذا التطبيق بسرعة.
انتقل إلى صفحة الغرف في لوحة القيادة الخاصة بك ، انقر فوق Room Id للغرفة التي قمت بإنشائها أعلاه ، وانقر على زر Join Room في الأعلى يمينًا.
في قسم الانضمام إلى SDK ، يمكنك العثور على Auth Token for role ؛ يمكنك النقر فوق أيقونة "النسخ" لنسخ رمز المصادقة.

الرمز المميز من لوحة معلومات 100 مللي ثانية هو لأغراض الاختبار فقط ، لتطبيقات الإنتاج ، يجب عليك إنشاء الرموز على الخادم الخاص بك. ارجع إلى قسم الرمز المميز للإدارة في دليل المصادقة والرموز لمزيد من المعلومات.

يمكنك أيضًا تمرير هذه الحقول اختياريًا في مُنشئ HMSSDK -

إعدادات المسار - مثل الانضمام إلى غرفة مع صوت أو مقطع فيديو صامت باستخدام كائن HMSTrackSetting . مزيد من المعلومات متوفرة هنا.
بيانات بيانات المستخدم - يمكن استخدام هذا لتمرير أي بيانات تعريف إضافية مرتبطة بالمستخدم باستخدام metadata كائن HMSConfig . على سبيل المثال: تعيين معرف المستخدم في جانب التطبيق. مزيد من المعلومات متوفرة هنا.

مزيد من المعلومات حول الانضمام إلى غرفة متاحة هنا.

 // create a class that implements `HMSUpdateListener` and acts as a data source for our UI
class Meeting implements HMSUpdateListener {

    late HMSSDK hmsSDK;

    Meeting () {
        initHMSSDK ();
    }

    void initHMSSDK () async {
        hmsSDK = HMSSDK (); // create an instance of `HMSSDK` by invoking it's constructor
        await hmsSDK. build (); // ensure to await while invoking the `build` method
        hmsSDK. addUpdateListener ( this ); // `this` value corresponds to the instance implementing HMSUpdateListener
        HMSConfig config = HMSConfig (authToken : 'eyJH5c' , // client-side token generated from your token service
                                userName : 'John Appleseed' );
        hmsSDK. join (config : config); // Now, we are primed to join the room. All you have to do is call `join` by passing the `config` object.
    }

    ... // implement methods of HMSUpdateListener
}

؟ عرض مسار

كل ذلك يأتي إلى هذا. لقد تم إجراء كل الإعدادات حتى الآن حتى نتمكن من عرض مقاطع الفيديو المباشرة في تطبيقنا الجميل.

توفر حزمة Flutter 100ms أداة HMSVideoView التي تجعل الفيديو على الشاشة.

علينا ببساطة تمرير كائن مسار الفيديو إلى HMSVideoView لبدء التقديم التلقائي لتيار الفيديو المباشر.

يمكننا أيضًا تمرير الدعائم اختياريًا مثل key ، scaleType ، mirror لتخصيص عنصر واجهة المستخدم HMSVideoView .

 HMSVideoView (
  track : videoTrack,
  key : Key (videoTrack.trackId),
),

يتوفر مزيد من المعلومات حول عرض الفيديو هنا.

اترك الغرفة

بمجرد الانتهاء من الاجتماع وترغب في الخروج ، اتصل بمثابة HMSSDK التي قمت بإنشائها للانضمام إلى الغرفة.

قبل استدعاء الإجازة ، قم بإزالة مثيل HMSUpdateListener على النحو التالي:

 // updateListener is the instance of class in which HMSUpdateListener is implemented
hmsSDK. removeUpdateListener (updateListener);

لمغادرة الاجتماع ، اتصل بطريقة leave لـ HMSSDK وتمرير معلمة hmsActionResultListener للحصول على رد اتصال من SDK في طريقة تجاوز onSuccess على النحو التالي.

ستحتاج إلى تنفيذ واجهة HMSActionResultListener في فصل للحصول على استدعاء onSuccess و onException . لمعرفة كيفية تنفيذ HMSActionResultListener تحقق من المستندات هنا

 class Meeting implements HMSActionResultListener {
//this is the instance of class implementing HMSActionResultListener
await hmsSDK. leave (hmsActionResultListener : this );

@override
  void onSuccess (
      { HMSActionResultListenerMethod methodType = HMSActionResultListenerMethod .unknown, Map < String , dynamic > ? arguments}) {
        switch (methodType) {
          case HMSActionResultListenerMethod .leave :
          // Room leaved successfully
          // Clear the local room state
          break ;
          ...
        }
      }
}

مزيد من المعلومات حول ترك غرفة متوفرة هنا.

؟ شرح HMSTRACKS

HMSTrack هي الفئة الفائقة لجميع المسارات التي يتم استخدامها داخل HMSSDK . يبدو التسلسل الهرمي هكذا -

 HMSTrack
    - AudioTrack
        - LocalAudioTrack
        - RemoteAudioTrack
    - VideoTrack
        - LocalVideoTrack
        - RemoteVideoTrack

؟ كيف تعرف نوع ومصدر المسار؟

يحتوي HMSTRACK على حقل يسمى المصدر يدل على مصدر المسار.

يمكن أن يكون Source القيم التالية -

regular للصوت العادي أو الفيديو الذي يتم نشره من قبل أقرانهم
screen لتتبع لقطة الشاشة عندما يبدأ النظراء في بث شاشته في غرفة
plugin لمكون من الصوت أو مكونات الفيديو المخصصة المستخدمة في الغرفة

لمعرفة نوع المسار ، تحقق من قيمة النوع الذي سيكون أحد قيم التعداد - AUDIO أو VIDEO

؟ رسائل الدردشة

يمكنك إرسال دردشة أو أي نوع آخر من الرسائل من نظير محلي إلى جميع أقرانهم عن بُعد في الغرفة.

لإرسال رسالة أولاً ، قم بإنشاء مثيل لكائن HMSMessage .

أضف المعلومات المراد إرسالها في خاصية message HMSMessage .

ثم استخدم وظيفة sendBroadcastMessage على مثيل HMSSDK لرسالة البث ، و sendGroupMessage لرسالة المجموعة و sendDirectMessage للرسالة المباشرة.

عندما تتلقى (النظير المحلي) رسالة من الآخرين (أي نظير عن بُعد) ، يتم استدعاء وظيفة void onMessage({required HMSMessage message}) لـ HMSUpdateListener .

مزيد من المعلومات حول رسائل الدردشة متاحة هنا.

 // onMessage is HMSUpdateListener method called when a new message is received
@override
void onMessage ({ required HMSMessage message}) {
  //Here we will receive messages sent by other peers
}


/// [message] : Message to be sent
/// [type] : Message type(More about this at the end)
/// [hmsActionResultListener] : instance of class implementing HMSActionResultListener
//Here this is an instance of class that implements HMSActionResultListener i.e. Meeting
hmsSDK. sendBroadcastMessage (
  message : message,
  type : type,
  hmsActionResultListener : this );


/// [message] : Message to be sent
/// [peerTo] : Peer to whom message needs to be sent
/// [type] : Message type(More about this at the end)
/// [hmsActionResultListener] : instance of class implementing HMSActionResultListener
//Here this is an instance of class that implements HMSActionResultListener i.e. Meeting
hmsSDK. sendDirectMessage (
  message : message,
  peerTo : peerTo,
  type : type,
  hmsActionResultListener : this );


/// [message] : Message to be sent
/// [hmsRolesTo] : Roles to which this message needs to be sent
/// [type] : Message type(More about this at the end)
/// [hmsActionResultListener] : instance of class implementing HMSActionResultListener
//Here this is an instance of class that implements HMSActionResultListener i.e. Meeting
hmsSDK. sendGroupMessage (
    message : message,
    hmsRolesTo : rolesToSendMessage,
    type : type,
    hmsActionResultListener : this );



@override
void onSuccess (
  { HMSActionResultListenerMethod methodType =
    HMSActionResultListenerMethod .unknown,
    Map < String , dynamic > ? arguments}) {

    switch (methodType) {

      case HMSActionResultListenerMethod .sendBroadcastMessage :
      //Broadcast Message sent successfully
      break ;

      case HMSActionResultListenerMethod .sendGroupMessage :
      //Group Message sent successfully
      break ;

      case HMSActionResultListenerMethod .sendDirectMessage :
      //Direct Message sent successfully
      break ;
      ...
    }
  }


@override
void onException (
  { HMSActionResultListenerMethod methodType =
    HMSActionResultListenerMethod .unknown,
    Map < String , dynamic > ? arguments,
    required HMSException hmsException}) {

    switch (methodType) {

      case HMSActionResultListenerMethod .sendBroadcastMessage :
      // Check the HMSException object for details about the error
      break ;

      case HMSActionResultListenerMethod .sendGroupMessage :
      // Check the HMSException object for details about the error
      break ;

      case HMSActionResultListenerMethod .sendDirectMessage :
      // Check the HMSException object for details about the error
      break ;
      ...
    }

  }