Hyperity Video SDK는 여러분의 앱에 아주 쉽고 간단하게 화상통화기능을 추가할 수 있습니다. 여기서는 Hyperity SDK의 기본적인 사용방법에 대한 가이드를 제공하고, 첫 통화를 위한 튜토리얼을 제공합니다.
Step 1: Project 내에서 Hyperity Video SDK를 초기화
첫째, 앱 시작시에 HyperCall 인스턴스를 생성해야 합니다. HyperCall을 초기화 하기 위해서는 아래와 같이 진행하세요
HyperCall.create() 로부터 얻은 인스턴스는 클라이언트 앱 내에서 singleton으로 한번만 호출해서 관리되어야 합니다.
var call = HyperCall.create();
Dart
복사
Step 2: 사용자 토큰을 이용한 인증
서비스 토큰을 이용한 인증 기능은 지원 예정입니다
Step 3: 이벤트 핸들러 등록
HyperCall의 간단한 코드만으로 기본적인 통신 및 방송이 가능 합니다. 사용자의 필요에 따라 UI처리 및 추가 작업이 필요한 경우가 발생 합니다. 아래의 다양한 이벤트 핸들러를 통해 보다 세부적인 제어가 가능합니다.
Hyperity Video는 화상통신에 적합한 event들을 가지고 있습니다. 이를 알아두면 각 상황 별 event를 활용하는데 도움이 됩니다. 이에 대한 내용은 아래를 참고하세요.
onConnect
서버 접속 및 채널 생성이 완료된 이후 호출되는 콜백입니다. 실질적으로 채널을 만들어 통화를 요청하는 Caller이거나 만들어진 채널에 접속하여 요청에 응답하는 Callee일때의 동작을 달리 하는 경우가 많으며 개발자가 Caller, Callee여부에 대한 상태를 관리해야 합니다.
Caller는 join()을 통해 채널을 새로 만들고 상대방이 입장하기를 기다립니다.
Callee는 join()을 통해 이미 만들어진 채널에 접속하게 됩니다. 이때 Caller가 만든 채널의 이름을 필수로 필요하게 됩니다. 정상적으로 완료되면 onConnect가 생기나, Callee라면 곧바로 발생하는 onComplete를 사용하는것을 권장합니다.
var call = HyperCall.create()
..onConnect = ((String channelId) {
// Do something
})
Dart
복사
onComplete
통신에만 사용됩니다. 상호간 연결이 완료 된후 미디어 전송이 가능해 졌을 때 호출 됩니다. 다른 사용자와 Peer 연결이 완료된 이후 호출되는 콜백입니다.
var call = HyperCall.create()
..onComplete = (() {
// Do something
})
Dart
복사
onDisconnect
상대방이 연결을 끊거나, close() 호출후 종료가 완료되면 호출됩니다.
•
MINE : 자신이 close() 를 통해 종료한 경우
•
OTHER : 상대방이 close() 를 통해 종료한 경우
•
OTHER_UNEXPECTED : 상대방이 끊어져서 연결이 종료된 경우
•
UNKNOWN : 에러에 의한 연결 종료, 기타 연결 종료 이유 불명확
var call = HyperCall.create()
..onDisconnect = ((String reason) {
// Do something
})
Dart
복사
onError
에러가 발생할 때 호출되는 콜백을 정의합니다.
연결이 종료되는 경우 에러 전달 후 onDisconnect가 호출 되므로, 시나리오에 따른 ux 처리는 onClose에서 진행되어야 합니다.
var call = HyperCall.create()
..onError = ((Error err) {
// Do something
})
Dart
복사
onMessage
연결된 peer 간에 메시지를 전달하는 경우 호출되는 콜백입니다.
// HyperMessage 는 hyperity_sdk_flutter 내에 정의되어있습니다.
class HyperMessage {
late String from;
late String to;
late Map<String, dynamic> data;
}
...
var call = HyperCall.create()
..onMessage = ((HyperMessage msg) {
// Do something
})
Dart
복사
Step 4: 전화 걸기
전화 걸기에 대해 설명하기에 앞서 아래 GitHub 웹사이트를 방문합니다.
아래와 같은 모습이 보입니다.
TODO: 사진 첨부
우측 상단의 Fork 버튼을 클릭합니다. 내 저장소가 생겼습니다. 내 저장소의 주소는 아래와 같습니다.
https://github.com/내 아이디/hyperity_video_app
Dart
복사
HyperCall 채팅룸 접속 방법
예제의 lib/pages/login/login_page.dart 에는 HyperCall을 통해 hyperity video server에 connect하는 방법이 실려있습니다. HyperCall.create()을 통해 HyperCall 인스턴스를 생성하며, 동시에 각 event handler들을 설정해 줍니다. 이후 handleJoin()에서 HyperCall의 join()메서드를 이용해 원하는 채널에 접속합니다.
class LoginBinding implements Bindings {
void dependencies() {
Get.lazyPut<HyperCall>(() {
var call = HyperCall.create();
// Callee와 연결시에 Caller는 onConnect event handler를 호출받게됩니다.
call.onConnect = ((channelId) => print("onConnect: ${channelId}"));
call.onComplete = (() => print("onComplete"));
call.onDisconnect = ((reason) => print("onDisconnect: ${reason}"));
call.onError = ((err) => print("onError: ${err}"));
call.onMessage = ((msg) => print("onError: ${msg}"));
return call;
});
}
}
...
class LoginController extends GetxController {
...
bool handleJoin() {
if (_uid.value.length == 0 || _sid.value.length == 0) {
return false;
}
prefs.setString('user', _uid.value);
prefs.setString('room', _sid.value);
// HyperCall을 이용해 hyperity video server에 접속하기위해 join() 메서드를 호출합니다.
// 이때 사용자 ID와 접속하려는 channel id (room name)을 함께 전달합니다.
controller.join(_uid.value, _sid.value);
Get.toNamed('/meeting');
return true;
}
}
Dart
복사
채팅룸으로부터 본인/상대방 비디오 렌더러를 얻는 방법
lib/pages/meeting/meeting_page.dart에는 접속한 채널로부터 video renderer를 얻는 방법이 나와있습니다. 본인의 video는 HyperCall.localVideo 변수를 통해 얻을 수 있으며, 원격 접속중인 상대방의 비디오는 HyperCall.remoteVideos 변수를 통해 얻어올 수 있습니다.
class MeetingView extends GetView<HyperCall> {
...
List<VideoRendererAdapter> get remoteVideos => controller.remoteVideos;
VideoRendererAdapter? get localVideo => controller.localVideo;
...
}
Dart
복사
Step 5: 전화 받기
HyperCall을 통한 전화받기 기능은 전화걸기와 유사합니다. 전화걸기와 동일하게 HyperCall.join()을 통해 Caller가 생성한 채팅룸에 접속하게 되며, Caller와의 차이점은 호출되는 event handler가 다르다는 점입니다.
class LoginBinding implements Bindings {
void dependencies() {
Get.lazyPut<HyperCall>(() {
var call = HyperCall.create();
call.onConnect = ((channelId) => print("onConnect: ${channelId}"));
// Callee의 경우 Caller와 연결 시 onComplete callback이 먼저 불리게 됩니다.
call.onComplete = (() => print("onComplete"));
call.onDisconnect = ((reason) => print("onDisconnect: ${reason}"));
call.onError = ((err) => print("onError: ${err}"));
call.onMessage = ((msg) => print("onError: ${msg}"));
return call;
});
}
}
...
class LoginController extends GetxController {
...
bool handleJoin() {
if (_uid.value.length == 0 || _sid.value.length == 0) {
return false;
}
prefs.setString('user', _uid.value);
prefs.setString('room', _sid.value);
// HyperCall을 이용해 hyperity video server에 접속하기위해 join() 메서드를 호출합니다.
// 이때 사용자 ID와 접속하려는 channel id (room name)을 함께 전달합니다.
controller.join(_uid.value, _sid.value);
Get.toNamed('/meeting');
return true;
}
}
Dart
복사
Step 6: 전화 끊기
상대방과 전화끊기는 HyperCall.cleanUp() 호출을 통해 이뤄지게 됩니다. cleanUp()이 호출되면 채팅룸에 함께 연결된 비디오 스트림들을 해지하고, 채팅룸과의 연결을 끊게됩니다.
lib/pages/meeting/meeting_page.dart
SizedBox(
width: 36,
height: 36,
child: RawMaterialButton(
shape: CircleBorder(
side: BorderSide(
color: Colors.white,
width: 1,
),
),
child: Icon(
CommunityMaterialIcons.phone_hangup,
color: Colors.red,
),
// 버튼이 눌렸을때 HyperCall.cleanUp을 호출합니다.
onPressed: controller.cleanUp,
),
),
...
Dart
복사