Android SDK 시작하기

OpenTester Android SDK는 앱에서 테스터 로그인, 참여 권한 확인, 버그·개선 의견 제출을 제공합니다. Kotlin의 suspend 함수로 호출하며 로그인은 시스템 브라우저에서 진행합니다.

지원 항목	현재 버전
SDK	0.1.0
플랫폼	Android API 26 이상
소스 빌드	JDK 17 이상, Android SDK Platform 36
주요 의존성	AndroidX Browser 1.8.0, Kotlin Coroutines Android 1.10.2
설치 방식	Maven Central, JitPack, 소스 모듈, 로컬 Maven

배포 상태

SDK v0.1.0은 JitPack에서 사용할 수 있습니다. Maven Central에서도 app.opentester:android-sdk:0.1.0으로 설치할 수 있습니다. 자동 오류 수집, 스크린샷 첨부, 오프라인 제출 큐는 현재 SDK에 포함되지 않습니다.

1. 앱과 테스터 준비

개발자 콘솔에서 앱을 등록하고 앱 ID를 복사합니다. SDK callback에는 앱이 수신할 HTTPS 주소를 등록합니다. 예: https://your-app.example.com/opentester/callback.

테스터는 해당 앱에 참여 신청을 해야 합니다. 앱의 참여 정책에 따라 승인된 후 SDK 인증을 사용할 수 있습니다. Google Group 가입과 Google Play 테스트 참여는 OpenTester의 앱별 참여 승인과 별개의 절차입니다.

2. SDK 설치

호스트 Android 프로젝트의 settings.gradle.kts에 Maven Central을 추가합니다.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

앱 모듈의 build.gradle.kts에 테스트 빌드 의존성을 추가합니다.

android {
    compileSdk = 36
    defaultConfig { minSdk = 26 }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = "17" }
}

dependencies {
    debugImplementation("app.opentester:android-sdk:0.1.0")
}

이 예제는 debug에만 SDK를 포함합니다. SDK를 참조하는 클래스와 manifest 설정도 src/debug/에 둡니다. 별도 테스트 flavor가 있다면 그 flavor의 의존성과 source set을 사용하세요. 일반 사용자용 빌드에는 테스트 로그인 게이트가 남지 않도록 구성합니다.

다른 설치 방식

• JitPack: 저장소에 maven { url = uri("https://jitpack.io") }를 추가하고 debugImplementation("com.github.opentesterapp:opentester-android-sdk:v0.1.0")을 사용합니다. Maven Central 좌표와 동시에 추가하지 마세요.

• 로컬 Maven: SDK 저장소에서 ./gradlew :opentester:publishToMavenLocal을 실행하고 mavenLocal() 및 app.opentester:android-sdk:0.1.0을 사용합니다. JitPack 좌표와 동시에 추가하지 마세요.

• 소스 모듈: SDK의 opentester 모듈을 호스트 Gradle 프로젝트에 포함한 뒤 debugImplementation(project(":opentester"))로 연결합니다. 플러그인 버전과 저장소 설정은 호스트 프로젝트에 맞춥니다.

• AAR: ./gradlew :opentester:assembleRelease로 만든 opentester/build/outputs/aar/opentester-release.aar를 사용할 수 있습니다. AAR 파일만 복사하면 전이 의존성이 포함되지 않으므로 AndroidX Browser와 Kotlin Coroutines도 추가해야 합니다.

3. 클라이언트 초기화

다음 예제의 앱 ID와 세 도메인을 실제 값으로 교체합니다. apiBaseUrl과 webBaseUrl은 경로가 없는 서버 주소입니다. SDK의 apiBaseUrl에는 /api/v1을 붙이지 않습니다.

// app/src/debug/java/com/example/app/TesterApplication.kt
package com.example.app

import android.app.Application
import dev.opentester.sdk.OpenTester
import dev.opentester.sdk.OpenTesterConfig

class TesterApplication : Application() {
    val tester by lazy {
        OpenTester(
            OpenTesterConfig(
                appId = "YOUR_APP_ID",
                apiBaseUrl = "https://api.example.com",
                webBaseUrl = "https://opentester.example.com",
                redirectUri = "https://your-app.example.com/opentester/callback",
                languageTag = "ko-KR",
            )
        )
    }
}

하나의 SDK 인스턴스를 Application이나 유지되는 객체에 보관합니다. Activity가 다시 생성될 때마다 새 인스턴스를 만들면 진행 중 로그인 정보가 사라집니다. 기존 Application 클래스가 있다면 위 초기화 코드를 해당 테스트 빌드 구현에 합칩니다.

src/debug/AndroidManifest.xml에서 위 Application을 등록하고 인증 가이드의 callback Activity와 App Links 설정을 적용합니다.

4. 로그인 후 보고서 제출

Activity의 메인 스레드에서 브라우저를 엽니다.

val tester = (application as TesterApplication).tester
tester.authenticate(this)

앱으로 돌아오면 coroutine에서 handleCallback(uri)를 호출합니다. 반환된 AccessGrant를 받은 뒤 버그를 제출할 수 있습니다. 아래 코드는 이미 인증된 tester를 coroutine에서 사용하는 예입니다.

import dev.opentester.sdk.BugReport

val report = BugReport(
    title = "저장 버튼이 동작하지 않아요",
    description = "제목을 입력하고 저장을 눌러도 화면이 바뀌지 않습니다.",
    steps = "새 프로젝트 → 제목 입력 → 저장",
    expected = "프로젝트 목록으로 이동",
    actual = "화면 변화 없음",
    appVersion = "1.0.0-test",
    deviceInfo = "Pixel; Android 16",
)
val issue = tester.submitBug(report)
// issue.id로 제출 결과를 표시합니다.

보고서를 보내기 전 사용자에게 전송할 내용을 보여주세요. 앱 버전과 기기 정보는 호스트 앱이 명시적으로 전달하며 SDK가 자동 수집하지 않습니다.

다음 단계

• 브라우저 인증 연결: callback Activity, App Links, 세션 관리
• 버그와 개선 의견: 입력 제한, 재시도, 오류 처리
• Kotlin API 레퍼런스: 함수와 데이터 모델
• 문제 해결: 에뮬레이터 연결과 인증 실패 확인