설치

Gradle 플러그인 적용, 저장소 인증, SDK 시작까지 Android SDK를 앱에 붙이는 과정을 설명합니다.

설치는 Gradle 플러그인 하나로 이루어집니다. 플러그인이 SDK 의존성을 추가하고 바이트코드 계측을 적용하므로, 앱 코드에서 직접 하는 일은 SDK를 시작하는 한 줄뿐입니다.

요구 사항

항목	요구 사항
minSdk	21 이상
compileSdk	34 이상
Android Gradle Plugin	8.0.2 이상
Gradle	8.0.2 이상
Kotlin	2.0.21 이상
JVM 타깃	11

compileSdk와 AGP 요구 사항은 AAR 메타데이터에 기록되어 있습니다. 조건을 만족하지 못하면 빌드가 실패하며, 경고로 넘어가지 않습니다.

CAUTION — minSdk가 26 미만인 경우

core library desugaring을 켜야 합니다. 추가로 AGP 8.3.0 이상과 gradle.properties의 android.useFullClasspathForDexingTransform=true가 필요합니다. 플러그인이 설정 시점에 검사하고, 빠진 경우 무엇을 켜야 하는지 알려줍니다.

저장소 등록

아티팩트는 GitHub Packages로 배포됩니다. 공개 패키지라도 GitHub Packages는 인증을 요구하므로 토큰이 필요합니다.

settings.gradle.kts

pluginManagement {
  repositories {
    maven {
      url = uri("https://maven.pkg.github.com/sophonz-labs/sophonz-android-sdk")
      credentials {
        username = providers.gradleProperty("gpr.user").orNull
        password = providers.gradleProperty("gpr.key").orNull
      }
    }
    gradlePluginPortal()
  }
}
 
dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven {
      url = uri("https://maven.pkg.github.com/sophonz-labs/sophonz-android-sdk")
      credentials {
        username = providers.gradleProperty("gpr.user").orNull
        password = providers.gradleProperty("gpr.key").orNull
      }
    }
  }
}

gpr.user와 gpr.key는 ~/.gradle/gradle.properties에 두어 저장소에 커밋되지 않게 합니다. read:packages 권한이 있는 토큰이면 충분합니다.

NOTE — 저장소를 두 곳에 모두 등록하는 이유

pluginManagement는 플러그인만 해석합니다. SDK 아티팩트는 앱 모듈의 의존성 해석 경로에서 찾으므로 dependencyResolutionManagement에도 같은 저장소가 있어야 합니다.

플러그인 적용

앱 모듈에 적용합니다. 라이브러리 모듈용 플러그인이 아니며, com.android.application이 함께 적용된 모듈에서만 동작합니다.

app/build.gradle.kts

plugins {
  id("com.android.application")
  id("io.sophonz.gradle") version "<version>"
}
 
dependencies {
  implementation("io.sophonz:sophonz-android-sdk:<version>")
}

implementation 한 줄은 지금은 생략해도 동작합니다. 플러그인이 자신과 같은 버전의 SDK를 클래스패스에 자동으로 추가하기 때문입니다. 다만 이 자동 추가(autoAddSophonzDependencies)는 소스에서 이미 제거 예정으로 표시되어 있으므로, 명시적으로 적어 두는 편이 앞으로를 위해 안전합니다.

CAUTION — 버전 확인이 필요합니다

SDK는 아직 정식 릴리스 태그가 없습니다. 저장소의 프로젝트 버전은 1.0.0-SNAPSHOT이고, README와 예제 앱이 서로 다른 번호를 사용하고 있습니다. 사용할 버전은 GitHub Packages에 실제로 게시된 것을 확인해 지정하세요.

SDK 시작

Application.onCreate()에서 시작합니다.

MainApplication.kt

import io.sophonz.android.sophonzsdk.Sophonz
 
class MainApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Sophonz.start(this)
  }
}

Sophonz는 오브젝트입니다. Sophonz.getInstance()도 아직 동작하지만 제거 예정으로 표시되어 있으므로 새 코드에서는 쓰지 마세요.

익스포터나 프로세서를 직접 추가하는 경우 start()보다 먼저 등록해야 합니다.

Sophonz.addSpanExporter(myExporter)
Sophonz.start(this)

NOTE — 자동 시작은 기본값이 아닙니다

바이트코드로 Application.onCreate()에 시작 코드를 주입하는 기능이 있지만 기본값은 꺼짐입니다. 켜려면 bytecodeInstrumentation { autoSdkInitializationEnabled.set(true) }를 지정합니다. 켜지 않았다면 위의 Sophonz.start(this)가 반드시 필요합니다.

이와 별개로 applicationInitTimingEnabled는 기본값이 켜짐입니다. 같은 onCreate를 계측하지만 시작 시간을 재는 것이지 SDK를 시작하지는 않습니다.

앱 키 지정

수집기 주소와 앱 키는 sophonz-config.json에 둡니다. 런타임이 아니라 빌드 시점에 SDK에 새겨집니다.

app/src/main/sophonz-config.json

{
  "sdk_config": {
    "ingest": {
      "service_key": "app-key-replace-me",
      "service_namespace": "my-project"
    }
  }
}

service_key는 SOPHONZ_SERVICE_KEY 환경 변수로도 지정할 수 있습니다. 파일에 값이 있으면 파일이 우선합니다. 전체 설정 항목은 설정에서 다룹니다.

권한

INTERNET과 ACCESS_NETWORK_STATE는 SDK의 매니페스트에 있어 자동으로 병합됩니다. 앱에서 다시 선언하지 않아도 됩니다.

확인

앱을 실행한 뒤 대시보드에서 세션이 보이면 설치가 끝난 것입니다. 보이지 않는다면 Sophonz.isStarted()로 SDK가 실제로 시작되었는지 먼저 확인하세요. 자동 시작을 켜지 않은 채 start() 호출을 빠뜨린 경우가 가장 흔합니다.