tencent cloud

Tencent Smart Advisor-Tencent RTC Copilot

시나리오 기반 솔루션
Overview of Scenario-Based Solutions
소셜 엔터테인먼트
이커머스 라이브 방송
Audio/Video Call
원거리 실시간 조작
스마트 고객 서비스
AI 인터뷰
모듈화 솔루션
모듈화 솔루션의 개요
네트워크 품질의 모니터링
모바일 앱 생존 유지 방안
비디오 화면 속 화면 솔루션
라이브 방송 위-아래로 스크롤
스트리머 간 크로스 룸 PK 연결 방안
AI 대화 Chat 시그널링 솔루션

iOS

PDF
포커스 모드
폰트 크기
마지막 업데이트 시간: 2025-12-24 10:30:38

업무 프로세스

본 섹션에서는 온라인 클로 머신에서 자주 사용되는 업무 프로세스를 요약하여 전체 시나리오 구현 과정을 더 잘 이해할 수 있는 데에 도움을 줍니다.
온라인 클로 머신의 Real-Time Communication Engine(RTC Engine) 스트리밍
온라인 클로 머신의 RTMP 스트리밍
아래 그림은 온라인 클로 머신의 RTC Engine 스트리밍의 시퀀스 다이어그램을 보여주며, 여기에는 네트워크 카메라 RTC Engine 스트리밍, 사용자 스트리밍 풀링 등의 프로세스가 포함되어 있습니다.



아래 그림은 온라인 클로 머신의 RTMP 스트리밍의 시퀀스 다이어그램을 보여주며, 여기에는 네트워크 카메라 RTMP 스트리밍, 사용자 스트리밍 풀링 등의 프로세스가 포함되어 있습니다.




접수 준비

단계 1: 서비스의 개통

온라인 클로 머신 시나리오는 일반적으로 Tencent Cloud RTC Engine 유료 PaaS 서비스를 이용하여 구축해야 합니다. 여기서 RTC Engine은 실시간 오디오및 비디오 인터랙션 기능을 제공합니다. 실제 업무 요구에 따라 위 서비스를 자유롭게 선택하여 개통할 수 있습니다.
1. 먼저 RTC Engine 콘솔 > 애플리케이션 관리에 로그인하여 애플리케이션을 생성해야 합니다. 필요에 따라 RTC Engine 애플리케이션 버전을 업그레이드할 수 있으며, 예를 들어 플래그십 버전은 더 많은 부가 기능 서비스를 이용할 수 있습니다.



설명:
두 개의 애플리케이션을 생성하고 테스트 환경과 프로덕션 환경에 각각 적용하는 것을 권장하며, RTC Engine 서비스를 처음 개통할 경우 10,000분 무료 사용 패키지가 제공됩니다.
RTC Engine 월정액 요금제(체험판, 라이트, 스탠다드, 프로페셔널)는 다양한 부가 기능 서비스를 이용할 수 있습니다. 자세한 내용은 월정액 요금제 설명을 참조하세요.
2. 애플리케이션 생성이 완료되면 애플리케이션 > 애플리케이션 개요에서 해당 애플리케이션의 기본 정보를 확인할 수 있습니다. 이후 사용을 위해 SDKAppIDSDKSecretKey을 안전하게 보관해야 하며 키 유출로 인한 트래픽 도용되지 않도록 주의해야 합니다.


단계 2: SDK 가져오기

RTC Engine SDK가 CocoaPods에 이미 게시되었으며, CocoaPods를 통해 SDK를 통합하는 것을 권장합니다.
1. CocoaPods의 설치
터미널 창에서 다음 명령을 실행하여 CocoaPods를 설치하세요. 이미 CocoaPods 설치를 완료한 경우 이 단계를 건너뛸 수 있습니다.
sudo gem install cocoapods
2. Podfile 파일의 생성
프로젝트 경로로 이동한 후 다음 명령어를 입력하면 프로젝트 경로에 한 개의 Podfile 파일이 생성됩니다.
pod init
3. Podfile 파일의 편집.
프로젝트 필요에 따라 적합한 버전을 선택하고 Podfile 파일을 편집하세요.
platform :ios, '8.0'
target 'App' do

# RTC Engine 라이트 버전 (추천)
# 설치 패키지 크기 증가가 최소화되었지만 RTC Engine와 라이브 방송 플레이어(TXLivePlayer) 두 가지 기능만 지원됩니다.
pod 'TXLiteAVSDK_TRTC', :podspec => 'https://liteav.sdk.qcloud.com/pod/liteavsdkspec/TXLiteAVSDK_TRTC.podspec'

#LiteAVSDK 전체 기능 버전
# RTC (RTC Engine), 라이브방송 플레이어(TXLivePlayer), RTMP 푸시 스트리밍(TXLivePusher), VOD 플레이어(TXVodPlayer), 짧은 비디오 레코딩 및 편집(UGSV) 등 다양한 기능을 포함합니다.
pod 'TXLiteAVSDK_Professional', :podspec => 'https://liteav.sdk.qcloud.com/pod/liteavsdkspec/TXLiteAVSDK_Professional.podspec'

end
4. SDK를 업데이트하고 설치합니다.
로컬 라이브러리 파일을 업데이트하기 위해 터미널 창구에 다음 명령을 입력하고SDK를 설치하세요.
pod install
또는 다음 명령을 사용하여 로컬 라이브러리 버전을 업데이트해도 됩니다.
pod update
pod 명령 실행 후 SDK가 통합된 .xcworkspace 확장자의 프로젝트 파일이 생성되며, 더블 클릭하여 열 수 있습니다.
설명:
pod 검색이 실패할 경우, pod의 로컬 repo 캐시를 업데이트해 보는 것이 좋습니다. 업데이트 명령은 다음과 같습니다.
pod setup
pod repo update
rm ~/Library/Caches/CocoaPods/search_index.json

단계 3: 프로젝트 구성

1. 온라인 클로 머신 시나리오에서 RTC Engine SDK는 App의 마이크 및 카메라 권한을 부여해야 합니다.App의 Info.plist에 다음 내용을 추가해야 합니다. 이는 시스템이 권한 부여 대화 상자를 표시할 때 마이크 및 카메라에 대한 안내 메시지에 해당합니다:
Privacy - Microphone Usage Description,마이크 사용 목적 안내문을 함께 입력하세요
Privacy - Camera Usage Description,그리고 카메라 사용 목적 안내문을 입력하세요.



2. App이 백그라운드에서도 관련 기능을 계속 실행하려면 XCode에서 현재 프로젝트를 선택하고 Capabilities에서 Background Modes 설정을 ON으로 설정한 후 Audio, AirPlay and Picture in Picture를 선택하면 됩니다. 아래 그림과 같이 설정하세요.




단계 4: 인증 및 허가

UserSig는 Tencent Cloud가 설계한 보안 서명이고 악의적인 공격자가 손님의 클라우드 서비스 사용 권한을 도용하는 것을 방지하기 위한 것입니다. RTC Engine은 방 입장 시 이 인증 자격 증명을 검증합니다.
디버깅 및 테스트 단계: 클라이언트 예시 코드 또는 콘솔으로 UserSig를 계산 및 생성할 수 있으며, 디버깅 및 테스트 용도로만 사용됩니다.
정식 운영 단계: 클라이언트가 역공학으로 키가 유출되는 것을 방지하기 위해 보안 등급이 더 높은 서버 UserSig 계산 방식의 사용을 권장합니다.
구체적인 구현 프로세스는 다음과 같습니다.
1. 손님의 App은 SDK 초기화 함수를 호출하기 전에 먼저 서버에 UserSig를 요청해야 합니다.
2. 손님의 서버는 SDKAppID와 UserID에 따라 UserSig를 계산합니다.
3. 서버는 계산된 UserSig를 손님의 App에 반환합니다.
4. 손님의 App은 획득한 UserSig를 특정 API를 통해 SDK에 전달합니다.
5. SDK는 SDKAppID + UserID + UserSig를 Tencent Cloud 서버에 제출하여 검증합니다.
6. Tencent Cloud는 UserSig를 검증하여 합법성을 확인합니다.
7. 검증이 완료되면 RTC Engine SDK에 실시간 오디오및 비디오 서비스를 제공합니다.



주의:
디버깅 단계의 로컬 UserSig 계산 방식은 온라인 환경에 적용하는 것을 권장하지 않습니다. 역공학으로 인해 키가 유출될 수 있기 때문입니다.
여러 언어 버전(Java/GO/PHP/Nodejs/Python/C#/C++)의 UserSig 서버 계산원 소스 코드를 제공하며 자세한 내용은 UserSig 계산 소스 코드을 참조하십시오.

단계 5: SDK의 초기화

// RTC Engine SDK 인스턴스의 생성(싱글톤 모드)
self.trtcCloud = [TRTCCloud sharedInstance];
// 이벤트 리스너의 설정
self.trtcCloud.delegate = self;

// SDK의 다양한 이벤트 알림(예: 오류 코드, 경고 코드, 오디오및 비디오 상태 매개변수 등)
- (void)onError:(TXLiteAVError)errCode errMsg:(nullable NSString *)errMsg extInfo:(nullable NSDictionary *)extInfo {
NSLog(@"%d: %@", errCode, errMsg);
}

- (void)onWarning:(TXLiteAVWarning)warningCode warningMsg:(nullable NSString *)warningMsg extInfo:(nullable NSDictionary *)extInfo {
NSLog(@"%d: %@", warningCode, warningMsg);
}

// 이벤트 리스너의 제거
self.trtcCloud.delegate = nil;
// RTC Engine SDK 인스턴스(싱글톤 모드)를 파기합니다.
[TRTCCloud destroySharedIntance];
설명:
SDK 이벤트 알림을 모니터링하고 일반적인 오류에 대한 로그 출력 및 처리를 권장합니다. 자세한 내용은 오류 코드 테이블을 참조하세요.

단계 6: RTMP 푸시 스트리밍 주소의 생성(RTMP 푸시 스트리밍)

RTMP 푸시 스트리밍 주소의 생성.
rtmp://intl-rtmp.rtc.qq.com/push/방번호?sdkappid=&userid=사용자명&usersig=서명
메인 도메인은 intl-rtmp.rtc.qq.com이며, 예비 도메인은 rtmp.rtc-web.com입니다. 메인 도메인 해석에 문제가 있을 경우 예비 도메인을 사용할 수 있습니다.
RTMP appName은 push입니다.
주소의 방 번호, 앱, 사용자명, 서명은 업무에 따라 변경해야 합니다.
매개변수를 단순화하기 위해 문자열 방 번호만 지원하며, 64자를 초과할 수 없고 문자는 숫자, 영문자, 밑줄만 가능합니다.
주의:
RTC Engine의 다른 단말에서 RTMP 스트림을 시청하려면 문자열 방 번호로 입장을 사용하세요.
UserSig의 생성 규칙은 UserSig 관련을 참조하세요(유효 기간 내에 서명해야 함에 유의하세요).
예시:
rtmp://intl-rtmp.rtc.qq.com/push/hello-string-room?sdkappid=140**66&userid=rtmp2&usersig=eJw1jdERBZ8qKGRj8Yp-wVbvmGMVZqS7w-mMDQL

접속 과정

API 시퀀스 다이어그램



단계 1: 클로 머신 푸시 스트리밍

RTC Engine의 푸시 스트리밍

1. 클라이언트 예시 코드콘솔 두 가지 방법으로 UserSig를 계산 및 생성합니다.
2. RTC Engine 네트워크 카메라 또는 스트리밍 박스로 SdkAppid, UserId, UserSig, RoomId 등의 정보를 구성하여 스트리밍을 시작합니다.
주의:
RTC Engine 방 번호는 숫자 유형 roomId과 문자열 유형 strRoomId으로 구분되며, 두 유형의 방은 서로 통하지 않으므로 방 번호 유형을 통일기키는 것을 권장합니다.
RTC Engine 사용자 역할은 스트리머와 청취자로 구분되며, 스트리머만 스트리밍 권한을 가집니다. 방 입장 시 사용자 역할을 지정해야 하며, 지정하지 않으면 기본적으로 스트리머 역할로 설정됩니다.
온라인 클로 머신 시나리오에서는 방 입장 모드를 TRTC_APP_SCENE_VIDEOCALL으로 선택하는 것을 권장합니다.이렇게 하면 지연 시간이 더 짧아집니다.

RTMP 푸시 스트리밍

1. RTMP 주소 생성기을 통해 RTMP 푸시 스트리밍 주소를 생성합니다.



2. RTMP 네트워크 카메라 또는 스트리밍 박스로 RTMP 푸시 스트리밍 주소를 구성하여 스트리밍을 시작합니다.

단계 2: 사용자가 방에 들어가서 스트리밍을 풀합니다.

1. 사용자가 RTC Engine 방에 입장합니다.
- (void)enterRoomByAudienceWithUserId:(NSString *)userId roomId:(NSString *)roomId {
TRTCParams *params = [[TRTCParams alloc] init];
// 문자열 방 번호를 예로 들면
params.strRoomId = roomId;
params.userId = userId;
// 업무 백엔드에서 가져온 UserSig
params.userSig = @"userSig";
// 손님의 SDKAppID로 교체합니다
params.sdkAppId = 0;
// 시청자 역할의 지정
params.role = TRTCRoleAudience;
// 인터랙티브 라이브 방송 시나리오로 방 입장하기
[self.trtcCloud enterRoom:params appScene:TRTCAppSceneVideoCall];
}

// 방 입장 결과 이벤트의 콜백
- (void)onEnterRoom:(NSInteger)result {
if (result > 0) {
// result는 방에 입장하는 데 소요된 시간(밀리초)을 나타냅니다.
NSLog(@"Enter room succeed!");
} else {
// result는 방 입장 실패의 오류 코드를 나타냅니다
NSLog(@"Enter room failed!");
}
}
2. 시청자가 스트리머의 오디오 및 비디오 스트림을 구독합니다.
- (void)onUserAudioAvailable:(NSString *)userId available:(BOOL)available {
// 원격 사용자가 자신의 오디오를 게시/취소했습니다
// 자동 구독 모드에서는 사용자가 아무런 작업을 하지 않아도 SDK가 원격 사용자의 오디오를 자동으로 재생합니다.
}

- (void)onUserVideoAvailable:(NSString *)userId available:(BOOL)available {
// 원격 사용자가 메인 비디오 화면을 게시/취소했습니다
if (available) {
// 원격 사용자의 비디오 스트림을 구독하고 비디오 렌더링 컨트롤을 바인딩합니다
[self.trtcCloud startRemoteView:userId streamType:TRTCVideoStreamTypeBig view:self.remoteView];
} else {
// 원격 사용자의 비디오 스트림 구독을 중지하고 렌더링 컨트롤을 릴리스합니다
[self.trtcCloud stopRemoteView:userId streamType:TRTCVideoStreamTypeBig];
}
}
3. 시청자가 원격 화면의 렌더링 모드를 설정합니다(선택 사항).
- (void)setupRemoteRenderParams {
TRTCRenderParams *params = [[TRTCRenderParams alloc] init];
// 화면 미러 모드
params.mirrorType = TRTCVideoMirrorTypeAuto;
// 화면 채우기 모드
params.fillMode = TRTCVideoFillMode_Fill;
// 화면 회전 각도
params.rotation = TRTCVideoRotation_0;
// 원격 화면의 렌더링 모드를 설정합니다
[self.trtcCloud setRemoteRenderParams:@"userId" streamType:TRTCVideoStreamTypeBig params:params];
}

단계 3: 사용자가 방을 나갑니다.

1. 사용자가 방에서 나갑니다.
- (void)exitRoom {
[self.trtcCloud stopLocalAudio];
[self.trtcCloud stopLocalPreview];
[self.trtcCloud exitRoom];
}

// 방 나가기 이벤트의 콜백
- (void)onExitRoom:(NSInteger)reason {
if (reason == 0) {
NSLog(@"exitRoom을 자동으로 호출하여 방에서 나가기");
} else if (reason == 1) {
NSLog(@"서버에 의해 현재 방에서 나가게 됩니다");
} else if (reason == 2) {
NSLog(@"현재 방 전체가 해체됩니다");
}
}
주의:
SDK가 점유한 모든 리소스가 릴리스된 후, SDK는 onExitRoom 콜백을 통해 알려줍니다.
enterRoom을 다시 호출하거나 다른 음성및 영상 SDK로 전환하려면 onExitRoom 콜백이 발생한 후에 관련 작업을 수행하십시오. 그렇지 않으면 카메라나 마이크 장치가 점유됨 등 다양한 오류 문제가 발생할 수 있습니다.
2. 방 해산하기.
서버에서 방 해산합니다
RTC Engine은 서버에서 숫자형 방을 해산하는 API DismissRoom과 문자열 방을 해산하는 API DismissRoomByStrRoomId을 제공합니다. 서버의 방 해산 인터페이스를 호출하여 방 내 모든 사용자를 방에서 나가게 시키고 방을 해산할 수 있습니다.
클라이언트에서 방 해산합니다
클라이언트에는 방을 직접 해산하는 API가 없으며, 각 클라이언트가 exitRoom을 호출하여 방을 나가게 시켜야 합니다. 방 내 모든 스트리머와 시청자가 방을 나가면 RTC Engine 방 라이프사이클 규칙에 따라 방이 자동으로 해산됩니다. 자세한 내용은 RTC Engine 방 나가기을 참조하십시오.

이상 처리

이상및 오류의 처리

RTC Engine SDK에서 복구할 수 없는 오류가 발생하면 onError 콜백에서 나오며, 자세한 내용은 RTC Engine 오류 코드표을 참조하십시오.
1. UserSig 관련입니다. UserSig 검증 실패로 인해 방 입장에 실패할 수 있으며 UserSig 생성 및 검증을 참조하여 검증 진행할 수 있습니다.
열거형
설명
ERR_TRTC_INVALID_USER_SIG
-3320
방 입장 매개변수 userSig가 올바르지 않습니다. TRTCParams.userSig이 비어 있는지 확인하세요.
ERR_TRTC_USER_SIG_CHECK_FAILED
-100018
UserSig 검증에 실패했습니다. 매개변수 TRTCParams.userSig이 올바르게 입력되었는지 또는 만료되지 않았는지 확인하세요.
2. 방 입장및 퇴장 관련입니다. 방 입장 실패 시 먼저 입장 매개변수가 올바른지 확인하고, 방 입장및 퇴장 인터페이스는 반드시 쌍으로 호출해야 합니다. 입장에 실패한 경우에도 퇴장 인터페이스를 호출해야 합니다.
열거형
설명
ERR_TRTC_CONNECT_SERVER_TIMEOUT
-3308
방 입장 요청이 시간을 초과하는 경우, 네트워크 연결이 끊겼는지 또는 VPN이 켜져 있는지 확인하세요. 4G로 전환하여 테스트할 수도 있습니다.
ERR_TRTC_INVALID_SDK_APPID
-3317
방 입장 매개변수 sdkAppId가 잘못되었습니다. TRTCParams.sdkAppId이 비어 있는지 확인하세요.
ERR_TRTC_INVALID_ROOM_ID
-3318
방 입장 매개변수 roomId가 잘못되었습니다. TRTCParams.roomId 또는 TRTCParams.strRoomId이 비어 있는지 확인하세요. roomId와 strRoomId는 혼용할 수 없습니다.
ERR_TRTC_INVALID_USER_ID
-3319
방 입장 매개변수 userId가 올바르지 않습니다. TRTCParams.userId이 비어 있는지 확인하세요.
ERR_TRTC_ENTER_ROOM_REFUSED
-3340
방 입장 요청이 거부되었습니다. enterRoom을 연속적으로 호출하여 동일한 ID의 방에 입장했는지 확인하세요.
3. 장치 관련입니다. 장치 관련 오류를 감지할 수 있으며, 관련 오류 발생 시 UI에서 사용자에게 알려줍니다.
열거형
설명
ERR_CAMERA_START_FAIL
-1301
Windows 또는 Mac 장치에서 카메라 구성 프로그램(드라이버)이 비정상일 경우, 카메라 열 수가 없습니다. 장치를 비활성화한 후 다시 활성화하거나, 기기를 재시작하거나, 구성 프로그램을 업데이트해보세요.
ERR_MIC_START_FAIL
-1302
Windows 또는 Mac 장치에서 마이크 구성 프로그램(드라이버)에 이상이 있어서 마이크를 열 수 없습니다. 장치를 비활성화한 후 다시 활성화하거나, 기기를 재시작하거나, 구성 프로그램을 업데이트해보세요.
ERR_CAMERA_NOT_AUTHORIZED
-1314
카메라 장치에 권한이 없습니다. 일반적으로 모바일 장치에서 발생하며, 사용자가 권한을 거부해서 발생했을 수 있습니다.
ERR_MIC_NOT_AUTHORIZED
-1317
마이크 장치에 권한이 없습니다. 일반적으로 모바일 장치에서 발생하며, 사용자가 권한을 거부해서 발생했을 수 있습니다.
ERR_CAMERA_OCCUPY
-1316
카메라가 사용 중입니다. 다른 카메라를 열어보세요.
ERR_MIC_OCCUPY
-1319
마이크가 사용 중입니다. 예를 들어 모바일 장치에서 통화 중일 때 마이크를 열 수가 없습니다.

시청자 스트리밍 진행 시 검은 화면 나옵니다

RTMP 클로 머신 스트리밍 시나리오에서 RTMP 스트리밍을 RTC Engine 방으로 전송하는 기능을 사용했으며 스트리밍 작업이 성공했습니다. 그러나 RTC Engine 방 내에서 정상적으로 스트림을 가져올 수 없었습니다. 문제 분석 결과에 따라 스트리밍 구성에 B 프레임이 포함되어 있었고 RTC Engine 방은 B 프레임이 포함된 시나리오를 지원하지 않기 때문에 RTMP 스트리밍을 가져올 수 없었습니다. 스트리밍 구성 참조는 다음과 같습니다.


시청자 풀 스트림 화면이 멈춤/풀 스트림에 제3자 화면이 나타남

클로 머신 시나리오에서 RTC Engine 시청자가 방에 들어가 스트림을 가져온 후 일정 시간이 지나면 자동으로 스트림이 멈추는 문제가 발생합니다. 특히 peer-join 또는 onUserVideoAvailable 콜백이 여러 번 트리거된 후 시청자의 스트림 화면이 마지막 프레임에서 멈추는 경우가 있습니다. 이러한 상황이 발생하면 먼저 대시보드에서 상세한 통화 정보를 확인할 수 있습니다. 대시보드 특징에 스트리머가 방을 여러 번 들어가고 나간 것을 나타낸다면, 문제는 상호 강제 퇴장으로 인한 것임을 기본적으로 확인할 수 있습니다.
솔루션: 현재 기기의 스트리밍을 종료하여 문제를 해결할 수 있습니다. 문제가 계속 해결되지 않으면 동일한 기기에 두 개의 동일한 스트리밍 주소가 구성되었는지 확인하세요.

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백