본문으로 건너뛰기
sstreamzet/docs
Android SDK 0.2.0-rc.2콘솔 열기
개발자 문서 / Android SDK
API와 연동 가이드 · 수정 2026-09-22

앱에 연동하기

받은 Maven 패키지부터 컴파일 가능한 Activity, 권한, 수명주기와 릴리스 확인까지.

1. 준비물과 호환 범위

SDK 0.2.0-rc.2, Android 8/API 26 이상 선언, compileSdk 35, JDK/JVM target 17 기준입니다. 이 문서의 예제는 AGP 8.7.3·Kotlin 2.0.21·Gradle 8.14.3으로 빌드했습니다. RC는 통합 검토용이며 모든 제조사 기기 인증을 뜻하지 않습니다.

관리자에게 HTTPS backend origin, 클라이언트 공개 anon JWT, WSS signaling origin, 테스트 대시보드 계정과 페어링 절차를 받습니다. SDK에는 서버 값이나 계정이 들어 있지 않습니다. registrationKey는 선택적 테넌트 등록용 비밀값이므로 일반 배포 APK에 넣지 않습니다.

2. Maven 의존성 추가

ZIP의 maven 디렉터리를 호스트 프로젝트의 vendor/streamzet-maven에 복사합니다. 아래 설정은 호스트 프로젝트 루트 기준입니다. POM과 Gradle module 파일을 함께 보존하세요. 타사 의존성 다운로드에는 Google Maven과 Maven Central 접근이 필요합니다.

kotlin
// settings.gradle.kts — inside dependencyResolutionManagement
repositories {
    google()
    mavenCentral()
    maven { url = uri("vendor/streamzet-maven") }
}

// app/build.gradle.kts
android {
    compileSdk = 35
    defaultConfig { minSdk = 26 }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = "17" }
}
dependencies {
    implementation("com.streamzet:remote-support-android:0.2.0-rc.2")
}

3. 완전한 최소 Activity

아래 파일에는 필요한 import와 화면 코드가 모두 들어 있습니다. 세 가지 YOUR_* 값을 제공받은 공개 연결 정보로 바꾸세요. 기존 업무 앱에는 SDK 초기화, bind, 상태 표시, start/stop 호출만 옮기면 됩니다. 테스트 프로젝트의 package·namespace는 com.example.support입니다.

kotlin
package com.example.support

import android.os.Bundle
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import androidx.activity.ComponentActivity
import com.streamzet.sdk.StreamzetSupport
import com.streamzet.sdk.SupportConfig
import com.streamzet.sdk.SupportLauncher

/** Replace the three endpoint placeholders with the public settings supplied to your project. */
class MinimalSupportActivity : ComponentActivity() {
    private lateinit var launcher: SupportLauncher

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val status = TextView(this)
        val code = TextView(this)
        val start = Button(this).apply { text = "Start support" }
        val stop = Button(this).apply { text = "Stop support" }
        setContentView(LinearLayout(this).apply {
            orientation = LinearLayout.VERTICAL
            setPadding(32, 96, 32, 32)
            addView(status)
            addView(code)
            addView(start)
            addView(stop)
        })
        val support = StreamzetSupport.getInstance() ?: StreamzetSupport.initialize(
            applicationContext,
            SupportConfig(
                supabaseUrl = "https://YOUR_BACKEND",
                publishableKey = "YOUR_PUBLIC_ANON_KEY",
                signalingUrl = "wss://YOUR_SIGNALING",
                deviceName = "Integration test",
            ),
        )
        launcher = SupportLauncher.bind(this, support) { ui ->
            status.text = ui.message
            code.text = ui.deviceCode.orEmpty()
            start.isEnabled = ui.canStart
            stop.isEnabled = ui.canStop
        }
        start.setOnClickListener { launcher.start() }
        stop.setOnClickListener { launcher.stop() }
    }
}
xml
<!-- app/src/main/AndroidManifest.xml: standalone example Activity -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application android:theme="@android:style/Theme.Material.Light.NoActionBar">
        <activity android:name=".MinimalSupportActivity" android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

4. 권한과 앱 식별

AAR manifest가 INTERNET, foreground service/mediaProjection, POST_NOTIFICATIONS와 캡처·접근성 서비스를 병합합니다. 동일 서비스를 다시 선언하지 말고 Android Studio의 Merged Manifest에서 확인하세요. 사용자에게 매 세션 화면공유 승인을 받고, 원격 입력에는 해당 앱의 접근성 허용이 추가로 필요합니다.

접근성 설정에서 다른 앱과 구별되도록 호스트 리소스에 아래 이름을 정의하고 앱 지원 언어별로 번역하세요. Android의 제한된 설정 안내가 나오면 해당 기기의 공식 관리 정책에 따라 사용자 승인 경로를 사용합니다.

xml
<!-- app/src/main/res/values/strings.xml -->
<resources>
    <string name="streamzet_accessibility_label">My Store remote support</string>
</resources>

5. 수명주기와 오류 처리

  1. Activity의 onCreate에서 bind를 한 번 호출합니다. 시작 버튼 안이나 onStart에서는 bind하지 않습니다. 회전으로 재생성되면 동일 SDK 인스턴스를 다시 bind합니다.
  2. start/stop은 메인 스레드의 사용자 동작에서 호출합니다. ACCEPTED는 요청 접수이며 CONNECTED 상태가 실제 연결입니다. canStart/canStop으로 버튼을 제어하고 error·stopReason·preparationError enum으로 처리합니다.
  3. 업무 화면의 onStop/onDestroy에서 SDK stop/close를 호출하지 않습니다. 화면 이동은 지원 종료가 아닙니다. 명시적인 종료 버튼이 캡처와 입력을 종료합니다.
  4. 사용자에게 ui.message를 표시하되 번역 문자열을 비교해 로직을 분기하지 않습니다. 기존 ViewBinding·Compose·Fragment는 호스트 Activity에서 만든 launcher를 전달받아 연결할 수 있습니다.

6. 호스트 앱 출시 전 확인

debug 빌드 성공만으로 끝내지 말고 실제 서명된 minify release 앱에서 공유·입력·종료·재연결을 확인합니다. 동일 applicationId와 서명, 앱 데이터를 유지한 업데이트는 등록을 유지합니다. 앱 데이터 삭제·제거·backend 변경은 새 등록이 필요할 수 있습니다. SDK는 호스트 APK를 자동 업데이트하지 않습니다.