tencent cloud

Tencent Smart Advisor-Tencent RTC Copilot

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

Android

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

업무 프로세스

본 섹션에서는 온라인 클로 머신에서 자주 사용되는 업무 프로세스를 요약하여 전체 시나리오 구현 과정을 더 잘 이해할 수 있는 데에 도움을 줍니다.
온라인 클로 머신의 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는 mavenCentral 저장소에 게시되었으며 gradle을 구성하여 자동 다운로드 및 업데이트가 가능합니다.
1. dependencies에 적합한 버전의 SDK 종속성을 추가합니다.
// RTC Engine 경량판 SDK에 RTC와 라이브 방송 재생 두 가지 기능을 포함합니다.
dependencies {
implementation 'com.tencent.liteav:LiteAVSDK_TRTC:latest.release'
}
설명:
자동 로딩(aar) 방안은 repositories에 mavenCentral 저장소를 반드시 추가해야 합니다
2. defaultConfig에서 App이 사용하는 CPU 아키텍처를 지정합니다.
defaultConfig {
ndk {
abiFilters "armeabi-v7a", "arm64-v8a"
}
}

단계 3: 프로젝트 구성

1. 권한의 설정.
AndroidManifest.xml에서 App 권한을 구성하고, 온라인 클로 머신 시나리오에서 LiteAVSDK는 다음 권한이 필요합니다.
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera.autofocus" />
주의:
android:hardwareAccelerated="false"을 설정하지 마십시오. 하드웨어 가속을 끄면 상대방의 비디오 스트림이 렌더링되지 않습니다.
LiteAVSDK에는 권한 요청 로직이 내장되어 있지 않으므로 해당 권한을 직접 선언해야 합니다. 일부 권한(예: 저장, 녹음, 카메라 등)은 런타임에 동적으로 요청해야 합니다.
Android 프로젝트의 targetSdkVersion이 31이거나 대상 기기가 Android 12및 그 이상 시스템 버전과 관련된 경우, 블루투스 기능을 정상적으로 사용하기 위해 코드에서 android.permission.BLUETOOTH_CONNECT 권한을 동적으로 신청해야 합니다. 자세한 내용은 Android 공식 설명를 참조하십시오.
2. 혼동 구성.
SDK 내부에서 Java의 리플렉션 기능을 사용하기 때문에 proguard-rules.pro 파일에서 SDK 관련 클래스를 혼동 제외 목록에 추가해야 합니다.
-keep class com.tencent.** { *; }

단계 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 인스턴스의 생성(싱글톤 모드)
TRTCCloud mTRTCCloud = TRTCCloud.sharedInstance(context);
// 이벤트 리스너의 설정
mTRTCCloud.setListener(trtcSdkListener);

// SDK의 다양한 이벤트 알림(예: 오류 코드, 경고 코드, 오디오및 비디오 상태 매개변수 등)
private TRTCCloudListener trtcSdkListener = new TRTCCloudListener() {
@Override
public void onError(int errCode, String errMsg, Bundle extraInfo) {
Log.d(TAG, errCode + errMsg);
}
@Override
public void onWarning(int warningCode, String warningMsg, Bundle extraInfo) {
Log.d(TAG, warningCode + warningMsg);
}
};

// 이벤트 리스너의 제거
mTRTCCloud.setListener(null);
// TRTC SDK 인스턴스(싱글톤 모드)를 파기합니다.
TRTCCloud.destroySharedInstance();
설명:
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 방에 입장합니다.
public void enterRoomByAudience(String roomId, String userId) {
TRTCCloudDef.TRTCParams params = new TRTCCloudDef.TRTCParams();
// 문자열 방 번호를 예로 들면
params.strRoomId = roomId;
params.userId = userId;
// 업무 백엔드에서 가져온 UserSig
params.userSig = getUserSig(userId);
// 손님의 SDKAppID로 교체합니다
params.sdkAppId = SDKAppID;
mTRTCCloud.enterRoom(params, TRTCCloudDef.TRTC_APP_SCENE_VIDEOCALL);
}

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

@Override
public void onUserVideoAvailable(String userId, boolean available) {
// 원격 사용자가 메인 비디오 화면을 게시/취소했습니다
if (available) {
// 원격 사용자의 비디오 스트림을 구독하고 비디오 렌더링 컨트롤을 바인딩합니다
mTRTCCloud.startRemoteView(userId, TRTCCloudDef.TRTC_VIDEO_STREAM_TYPE_BIG, TXCloudVideoView view);
} else {
// 원격 사용자의 비디오 스트림 구독을 중지하고 렌더링 컨트롤을 릴리스합니다
mTRTCCloud.stopRemoteView(userId, TRTCCloudDef.TRTC_VIDEO_STREAM_TYPE_BIG);
}
}
3. 시청자가 원격 화면의 렌더링 모드를 설정합니다(선택 사항).
TRTCCloudDef.TRTCRenderParams params = new TRTCCloudDef.TRTCRenderParams();
params.mirrorType = TRTCCloudDef.TRTC_VIDEO_MIRROR_TYPE_AUTO;// 화면 미러 모드
params.fillMode = TRTCCloudDef.TRTC_VIDEO_RENDER_MODE_FILL;// 화면 채우기 모드
params.rotation = TRTCCloudDef.TRTC_VIDEO_ROTATION_0;// 화면 회전 각도
// 원격 화면의 렌더링 모드를 설정합니다
mTRTCCloud.setRemoteRenderParams(userId, TRTCCloudDef.TRTC_VIDEO_STREAM_TYPE_BIG, params)

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

1. 사용자가 방에서 나갑니다.
public void exitRoom() {
mTRTCCloud.stopLocalAudio();
mTRTCCloud.stopLocalPreview();
mTRTCCloud.exitRoom();
}

// 방 나가기 이벤트의 콜백
@Override
public void onExitRoom(int reason) {
if (reason == 0) {
Log.d(TAG, "exitRoom을 자동으로 호출하여 방에서 나가기");
} else if (reason == 1) {
Log.d(TAG, "서버에 의해 현재 방에서 나가게 됩니다");
} else if (reason == 2) {
Log.d(TAG, "현재 방 전체가 해체됩니다");
}
}
주의:
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 콜백이 여러 번 트리거된 후 시청자의 스트림 화면이 마지막 프레임에서 멈추는 경우가 있습니다. 이러한 상황이 발생하면 먼저 대시보드에서 상세한 통화 정보를 확인할 수 있습니다. 대시보드 특징에 스트리머가 방을 여러 번 들어가고 나간 것을 나타낸다면, 문제는 상호 강제 퇴장으로 인한 것임을 기본적으로 확인할 수 있습니다.
솔루션: 현재 기기의 스트리밍을 종료하여 문제를 해결할 수 있습니다. 문제가 계속 해결되지 않으면 동일한 기기에 두 개의 동일한 스트리밍 주소가 구성되었는지 확인하세요.

도움말 및 지원

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

피드백