가이드 및 설문조사 Android SDK

Amplitude의 가이드 및 설문조사 Android SDK를 사용하면 안드로이드 애플리케이션에 가이드 및 설문조사를 배포할 수 있습니다.

설치 및 확인

다음 단계에 따라 SDK를 설치하고, 앱을 Amplitude 프로젝트에 연결하며, 가이드 및 설문조사가 앱에 도달하는지 확인하십시오.

요구 사항

가이드 및 설문조사 Android SDK를 사용하려면 다음이 필요합니다.

• Android API 레벨 24(Android 7.0) 이상.
• 코틀린 1.8.22 이상.

가이드 및 설문조사는 Amplitude 애널리틱스와 별도로 사용할 수 있습니다.

SDK 설치 및 초기화

가이드 및 설문조사는 기존 Amplitude 구현(있는 경우)과 가장 잘 작동하도록 다양한 설치 옵션을 지원합니다.

Amplitude 애널리틱스 Android-Kotlin SDK 사용

앱에서 Amplitude 애널리틱스 Android-Kotlin SDK를 사용하는 경우 버전 1.0 이상을 사용하고 있는지 확인하십시오. 그런 다음 다음 종속성을 애플리케이션의 build.gradle.kts파일에 추가하십시오.

dependencies {
    // Amplitude Engagement SDK
    implementation("com.amplitude:amplitude-engagement-android:3.+")
    // Amplitude Analytics SDK (required dependency)
    implementation("com.amplitude:analytics-android:1.+")
}

SDK 초기화

import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions
// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions()
)
// Add the plugin to your Amplitude instance
val amplitude = Amplitude(applicationContext)
amplitude.add(amplitudeEngagement.getPlugin())

이 호출은 Amplitude 애널리틱스 Android SDK의 플러그인 시스템을 사용하여 가이드 및 설문조사를 기존 분석 설정과 통합합니다. 플러그인을 추가하면 가이드 및 설문조사가 분석과 함께 초기화됩니다. 가이드 및 설문조사는 동일한 API 키와 사용자 ID를 공유하며 분석과 직접 통신합니다. 별도로 호출하실 필요는 없습니다boot.

구성 옵션

Amplitude 애널리틱스 Android-Kotlin SDK 1.0 이상을 사용하지 않음

앱에서 Amplitude 애널리틱스 Android-Kotlin SDK 1.0 이상을 사용하지 않는 경우에도 가이드 및 설문조사를 설치할 수 있지만 분석 SDK 플러그인 시스템을 사용하는 대신 직접 .boot호출해야 합니다.

응용 프로그램의 build.gradle.kts 파일에 다음 종속성을 추가하십시오.

dependencies {
    // Amplitude Engagement SDK
    implementation("com.amplitude:amplitude-engagement-android:2.+")
}

SDK 초기화

import com.amplitude.android.engagement.AmplitudeEngagement
import com.amplitude.android.engagement.AmplitudeInitOptions
// Initialize the SDK
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions()
)

구성 옵션

SDK 부팅

// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
    userId: "USER_ID",
    deviceId: "DEVICE_ID",
    userProperties: mapOf("key" to "value")
    integrations = arrayOf({ event: BaseEvent ->
        // Custom event handler
        // Dummy example here:
        println("event: ${event.eventType} properties: ${event.eventProperties}")
    })
)
amplitudeEngagement.boot(options: bootOptions)

프로젝트 설정에 애플리케이션 추가

SDK를 설치한 후에는 Android 애플리케이션을 Amplitude 프로젝트 설정에 추가하여 가이드 및 설문조사를 만들 때 플랫폼 옵션으로 표시되도록 하세요.

애플리케이션을 추가하려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 가이드 및 설문조사 탭으로 이동합니다.
4. 앱 관리 섹션에서 확장하고 + 앱 추가를 클릭합니다.
5. 드롭다운에서 Android를 선택합니다.

앱을 추가한 후에는 Android 앱 사용자를 위한 가이드 및 설문조사를 만들거나 편집할 때 이를 플랫폼 옵션으로 선택할 수 있습니다.

미리보기 모드 설정 및 확인

애플리케이션에서 직접 가이드 및 설문조사를 미리 보고 사용자에게 제공되는 것과 동일한 경험을 확인하십시오. 미리 보기를 사용하면 문구, 타겟팅 규칙 및 트리거 로직을 쉽게 반복할 수 있으며 설치가 제대로 작동하는지 확인할 수 있습니다.

모바일 URL 체계 찾기

URL 체계를 찾으려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 일반 탭으로 이동합니다.
4. URL 스키마(모바일) 필드를 찾습니다.
5. 해당 값을 복사합니다(예: amp-abcdefgh12345678).

Android Studio에서 URL 스키마 추가

다음 인텐트 필터를 프로젝트의 AndroidManifest.xml 파일 내 메인 액티비티에 추가하십시오.

<activity android:name=".MainActivity">
    <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Add your URL scheme from Amplitude Dashboard here -->
    <!-- ex: android:scheme="amp-12345" -->
    <data android:scheme="<your-unique-scheme-id>" />
    </intent-filter>
</activity>

미리보기 링크에 대한 URL 처리

// In your Activity
override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    amplitudeEngagement.handleLinkIntent(intent)
}

QR 코드 스캔을 통해 설치 상태를 확인하십시오.

설치가 처음부터 끝까지 제대로 작동하는지 확인하십시오.

1. Amplitude에서 가이드 또는 설문조사를 열고 미리보기를 클릭합니다.
2. 기기의 카메라로 표시된 QR 코드를 스캔하거나, 앱이 설치된 기기에서 미리보기 URL을 엽니다.
3. 앱 내에서 가이드 또는 설문조사가 열리는지 확인하십시오.
4. 화면 하단에 있는 작은 Amplitude 로고를 찾아 누르면 슈퍼 디버거가 열립니다. 여기서 확인할 내용은 슈퍼 디버거를 참조하십시오.

앱에서 미리보기가 열리지 않거나 로고가 나타나지 않는 경우, 계속하기 전에 위의 URL 구성표 설정 단계를 검토하세요.

참조

최소 SDK 버전 설정(필요한 경우)

SDK 버전 3.0.0및 이후 버전에서 지원합니다Minimum SDK version. 이전 SDK 릴리스에서 심각한 문제를 확인할 때 이 설정을 안전 제어로 사용하십시오.

최소 SDK 버전을 구성하려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 가이드 및 설문조사 탭으로 이동합니다.
4. 앱 관리 섹션에서 확장하고 + 앱 추가를 클릭합니다.
5. 드롭다운에서 Android를 선택합니다.
6. 최소 SDK 버전에 값을 입력합니다.

이 값을 설정하면 가이드 및 설문조사는 각 앱 빌드의 SDK 버전과 구성된 최소 값을 비교합니다.

• 앱 빌드에서 이전 SDK 버전을 사용하는 경우 SDK가 해당 빌드에서 초기화되지 않습니다.
• 앱 빌드에서 동일하거나 최신 버전의 SDK를 사용하는 경우 SDK가 예상대로 초기화됩니다.

이 설정을 사용하면 애플리케이션 릴리스를 롤백하지 않고 문제가 있는 알려진 SDK 버전에서 가이드 및 설문조사를 중지할 수 있습니다.

최소 SDK 버전의 사용 예제

앱 버전 120이 가이드 및 설문조사 SDK 3.0.2를 사용하고, 앱 버전 121이 버그 수정이 포함된 가이드 및 설문조사 SDK 3.1.0를 사용한다고 가정해 보겠습니다. 최소 SDK 버전을 다음과 같이 3.1.0설정한 경우

• 앱 버전120은 더 이상 가이드 및 설문조사를 로드하지 않습니다.
• 앱 버전121은 계속해서 가이드 및 설문조사를 로드합니다.

화면 추적 및 요소 타겟팅

화면 추적 활성화

화면 기반 타겟팅 및 화면 시간 트리거를 호출하십시오screen. 가이드 및 설문조사는 화면 문자열(예: '홈스크린')을 가이드 또는 설문조사 페이지 타겟팅 섹션의 문자열과 비교합니다.

// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")

요소 타겟팅 활성화

핀, 툴팁 및 카드 삽입 가이드는 SDK가 화면의 특정 요소를 대상으로 삼는 데 필요합니다.

Jetpack 컴포지션 핀 및 툴팁

Amplitude Engagement의 .amplitudeView 수정자를 사용하여 핀과 툴팁에 대한 Jetpack Compose 뷰에 태그를 지정하십시오. AmplitudeEngagement의 인스턴스를 매개변수로 .amplitudeView전달합니다. CompositionLocalProvider를 구성하고 뷰 계층 구조에서 이에 액세스하거나 인스턴스를 매개변수로 구성 가능 뷰에 전달합니다.

// Jetpack Compose tagging for pins and tooltips
@Composable
fun MyView() {
    // Use your instance of Amplitude Engagement by creating a Composition context or passing as a param
    val engagement = LocalEngagement.current
    Box {
        Button(
            modifier = Modifier.amplitudeView(
                engagement,
                tag = "my-button",
                onTrigger = {
                    // Optional code to run with tap element action
                }
            )
        )
    }
}

Jetpack Compose 카드 임베드

카드 임베드에는 수정자가 AmplitudeView아닌 컴포저블이 필요합니다. .amplitudeView는 SDK가 대상 이전, 이후 또는 대상 위치에 카드를 삽입할 수 있도록 콘텐츠를 래핑합니다.AmplitudeView 수정자는 상위 레이아웃에 형제 콘텐츠를 삽입할 수 없습니다.

다음 예제에서는 가이드 및 설문조사 대시보드에서 welcome-banner을 요소 타겟팅 문자열로 사용하십시오.

import com.amplitude.android.engagement.ui.anchoring.AmplitudeView
@Composable
fun MyView() {
    val engagement = LocalEngagement.current
    AmplitudeView(
        engagement = engagement,
        tag = "welcome-banner",
    ) {
        Text("Welcome")
    }
}

Jetpack Compose를 위한 ProGuard 규칙

릴리스 빌드에서 ProGuard 또는 R8 코드 축소를 활성화한 경우 앱의 proguard-rules.pro 파일(또는 이에 상응하는 ProGuard 구성)에 규칙을 추가하십시오. 축소를 수행하면 가이드 및 설문조사 SDK가 요소 태그를 해석하고 Compose 요소에 핀, 툴팁 및 카드 임베드를 배치하는 데 사용하는 Jetpack Compose 메타데이터와 주석이 제거될 수 있습니다.

ProGuard 구성에 다음을 추가하십시오.

-keepclassmembers class androidx.compose.ui.platform.AndroidComposeView {
  androidx.compose.ui.semantics.SemanticsOwner semanticsOwner;
}
# Keep Jetpack Compose runtime and compiler tags
# (This allows analytics tools to read composable structures)
-keep class androidx.compose.runtime.** { *; }
-keepclassmembers class * {
  @androidx.compose.runtime.* <fields>;
  @androidx.compose.runtime.* <methods>;
}
-keepnames class androidx.compose.ui.platform.** { *; }
# Keep attributes required for UI inspection and layout reflection
-keepattributes *Annotation*,Signature,InnerClasses,EnclosingMethod
-keepclassmembers class * {
  @com.amplitude.** <fields>;
  @com.amplitude.** <methods>;
}

이러한 규칙이 없으면 핀, 툴팁 및 카드 임베드가 Jetpack Compose 화면의 올바른 대상 요소에 연결되지 않을 수 있습니다.

Non-Jetpack Compose

가이드 및 설문조사는 Jetpack Compose 이외의 뷰도 지원합니다. SDK는 tag, contentDescription또는 resourceName 필드를 사용하여 일치하는 선택기가 있는지 확인합니다. 이 중 하나만 설정하면 됩니다.

기존 레이아웃 XML에서 이를 구성하거나 뷰 인스턴스의 속성을 설정하여 프로그래밍 방식으로 이를 구성할 수 있습니다.

<!-- in my_layout.xml -->
<LinearLayout>
    <!-- Set either contentDescription or tag to your desired selector -->
    <Button
        android:contentDescription="my-button"
        android:tag="my-button" />
</LinearLayout>

// Non Jetpack Compose Programmatic Tagging
val button = Button(this)
// Set the contentDescription
button.contentDescription = "my-button"
// Or set the tag
button.tag = "my-button"

현지화

초기화 다음 기간동안 locale옵션을 설정하여 가이드 또는 설문조사를 현지화합니다. 언어나 로케일을 설정하지 않은 경우, Amplitude는 기본 언어를 사용합니다.

// Set locale during initialization
val amplitudeEngagement = AmplitudeEngagement(
    context = applicationContext,
    apiKey = "YOUR_API_KEY",
    options = AmplitudeInitOptions(locale = "fr-FR")
)

SDK가 초기화된 후 언어를 동적으로 업데이트하려면 updateLanguage메서드를 사용하십시오. updateLanguage를 호출하면 새 로케일로 구성을 다시 가져옵니다.

amplitudeEngagement.updateLanguage(locale: String)

// Example: Update language to French with full locale
amplitudeEngagement.updateLanguage("fr-FR")
// Example: Update language to English with language code
amplitudeEngagement.updateLanguage("en")

기타 SDK 방법

Amplitude 가이드 및 설문조사용 Android SDK에는 다음과 같은 추가 메서드가 포함되어 있습니다.

• 생애주기 분석: enable()및 disable()를 사용하여 가이드 및 설문조사를 일시적으로 일시 중지하거나 재개할 수 있습니다.
• 타겟팅 새로 고침: 타겟팅 데이터를 수동으로 새로 고칠 때 refresh()사용합니다. 부팅 후 자동 새로 고침 간격을 변경하거나 비활성화하는 데 setAutoRefreshInterval()사용합니다.
• 테마 관리: 가이드 및 설문조사의 시각적 테마(밝은, 어두운 또는 자동)를 설정하는 데 사용합니다.setThemeMode
• 콜백 추가하기: 명명된 콜백을 등록하고 콜백 실행 작업을 사용하여 가이드나 설문조사에서 이를 트리거하여 사용자 지정 앱 로직을 실행하세요.
• 라우터 구성: 라우터 콜백을 정의하여 가이드 및 설문조사가 앱에서 화면 탐색을 처리하는 방법을 사용자 지정하세요setRouter.
• 가이드/설문조사 재설정하기: 가이드나 설문조사를 특정 단계로 다시 이동하는 데 사용합니다.reset
• 가이드/설문조사 목록: 이 list() 방법을 사용하여 라이브 가이드 및 설문조사의 전체 목록과 해당 현재 상태를 검색합니다.
• 스마트 상호작용: 캐시된 레이지 탭, 비활성 상태 및 요소 탭 상태를 지우는 데 사용됩니다.resetSmartInteractions()

SDK 활성화 및 비활성화

가이드 및 설문조사가 disable()일시적으로 표시되지 않도록 하고 현재 표시된 전체 가이드 및 설문조사를 숨길 때 사용합니다. 정상 작동을 재개하는 데 enable()사용하십시오.

// Temporarily disable the SDK
amplitudeEngagement.disable()
// Re-enable the SDK
amplitudeEngagement.enable()

타겟팅 데이터 새로 고침

사용자 속성 업데이트 후 Amplitude에서 타겟팅 평가를 다시 가져오는 데 사용하십시오refresh(). 가이드 또는 설문조사가 표시될 경우 SDK는 새로 고침을 건너뛰습니다.

amplitudeEngagement.refresh()

자동 새로 고침 간격 설정

타겟팅 데이터의 주기적 새로 고침을 활성화합니다. 부팅 후에 이 옵션을 호출하여 간격을 변경하거나 비활성화할 수 있습니다. 활성화된 경우 최소 간격은 60초입니다. 비활성화하려면 0로 설정하거나 음수 값을 입력하십시오.

amplitudeEngagement.setAutoRefreshInterval(seconds = 3600) // Every hour
amplitudeEngagement.setAutoRefreshInterval(seconds = 0)    // Disable

테마 관리

앱이 밝은 모드와 어두운 모드를 지원하는 경우 시각적 테마 모드를 구성하십시오.

// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: AUTO, LIGHT, DARK

콜백 등록

가이드 또는 설문조사 버튼에 콜백 실행 동작을 설정하여 콜백을 실행합니다.

engagement.addCallback(key: String, func: () -> Unit)

engagement.addCallback("show-alert") {
    this.runOnUiThread {
        android.app.AlertDialog.Builder(this)
            .setTitle("Callback")
            .setMessage("Callback has been executed!")
            .setPositiveButton("OK", null)
            .show()
    }
}

라우터 구성

가이드 및 설문조사가 화면 탐색을 처리하는 방법을 구성합니다.

engagement.setRouter { identifier ->
    // Your screen handling and navigation
}

라우터를 제거하려면 unsetRouter()를 호출하십시오.

amplitudeEngagement.unsetRouter()

재설정

안내서 또는 설문조사를 특정 단계로 재설정합니다.

amplitudeEngagement.reset(key = "GUIDE_KEY", stepIndex = 0)

목록

모든 라이브 가이드 및 설문조사의 목록과 해당 상태를 검색합니다.

val guidesAndSurveys = amplitudeEngagement.list()

보기

특정 가이드 또는 설문조사를 표시합니다. 화면 타겟팅을 제외한 전체 타겟팅 규칙과 제한을 무시합니다.

amplitudeEngagement.show(key = "GUIDE_KEY")

전달 이벤트

Amplitude 애널리틱스 Android SDK 플러그인을 사용하지 않는 경우(즉, 직접 boot를 호출한 경우), forwardEvent를 사용하여 가이드 및 설문조사에서 On 이벤트 추적 트리거를 활성화하십시오. 전달된 이벤트는 Amplitude 서버로 전송되지 않습니다. SDK는 이를 로컬 트리거 평가에만 사용합니다.

// Forward events from Amplitude to trigger guides
val event = BaseEvent()
amplitudeEngagement.forwardEvent(event)

스마트 상호 작용 재설정

분노 탭, 사용자 비활성 상태 및 요소 탭 감지 등 스마트 상호 작용 감지기에서 캐시된 상태를 모두 지우려면 resetSmartInteractions()호출하십시오.

amplitudeEngagement.resetSmartInteractions()

모두 닫기

모든 활성 가이드 및 설문조사를 닫습니다.

amplitudeEngagement.closeAll()

슈퍼 디버거

Amplitude 대시보드에서 미리보기 QR 코드를 스캔하면 화면 하단에 작은 Amplitude 로고가 나타납니다. 이를 눌러 슈퍼 디버거 패널을 엽니다.

슈퍼 디버거에는 세부 정보와 설정이라는 두 가지 탭이 있습니다.

세부 정보 탭

세부 정보 탭에는 미리 보고 있는 가이드 또는 설문조사에 대한 정보가 표시되며 미리 보기 세션을 검토하고 제어할 수 있습니다.

가이드/설문조사: 활성 가이드나 설문조사의 이름입니다. 이를 탭하여 다른 가이드나 설문조사로 전환하세요.

세부 정보:

• 단계: 총 단계 중 현재 단계 번호입니다(예: "3단계 중 1"). 복사 아이콘을 눌러 값을 복사합니다.
• 사용자: 미리 보기 세션의 사용자 ID입니다. 복사 아이콘을 눌러 이를 복사합니다.
• 화면: SDK가 현재 보고하는 화면 이름입니다. 복사 아이콘을 눌러 이를 복사합니다.

디버그: 가이드 또는 설문조사가 각 조건 검사를 통과했는지 여부를 표시합니다. 각 행은 확장되어 세부 정보를 표시합니다.

• 제한: 가이드 또는 설문조사가 표시 제한에 도달했는지 여부입니다. 확장하여 구성된 제한을 검토합니다. 제한을 구성한 경우 사용자 기록 재설정을 눌러 기록을 재설정하면 가이드 또는 설문조사가 다시 표시될 수 있습니다.
• 트리거: 가이드 또는 설문조사가 트리거 조건을 충족하는지 여부입니다. 트리거 유형, 화면 조건 및 핀 대상 요소(해당되는 경우)를 검토하려면 확장합니다.
• 스로틀: 가이드 또는 설문조사가 스로틀 조건을 충족하는지 여부입니다. 스로틀 설정을 검토하려면 확장합니다. 미리보기 세션 동안 스로틀 제한을 우회하려면 제한 무시를 토글합니다.

고급:

• 핀 디버깅: 5초마다 핀 위치 변경을 활성화하도록 확장합니다. 디버거는 동적 레이아웃에서의 핀 배치를 디버깅하는 데 도움이 되도록 핀 위치를 정기적으로 재평가합니다.

패널 맨 아래에:

• 미리 보기 다시 시작: 가이드 또는 설문조사를 첫 번째 단계로 재설정하고 미리 보기를 다시 시작합니다.
• 미리 보기 닫기: 미리 보기 모드를 종료하고 수퍼 디버거를 종료합니다.

설정 탭

설정 탭에는 현재 세션에 대한 SDK 구성 및 환경 세부 정보가 표시됩니다.

SDK 버전: 앱에 설치된 참여 SDK의 버전입니다.

설치:

• 유형: SDK 설치 방법(예: 플러그인 또는 독립형)입니다.
• 구성: 적용된 사용자 지정 구성 옵션의 수와 유형입니다.

사용자:

• 사용자 ID: 부팅 시 SDK에 전달된 사용자 ID입니다.
• 속성: 현재 세션에 대해 설정된 사용자 속성입니다.

이벤트 흐름: 이벤트가 올바르게 흐르고 있는지 확인합니다:

• 가이드 및 설문조사 SDK로 흐르는 이벤트: 분석 인스턴스의 이벤트는 참여 SDK에 도달합니다.
• 가이드 및 설문조사 SDK에서 발생하는 이벤트: 참여 SDK는 이벤트를 Amplitude로 전송합니다.

지원

**?**를 누르십시오. 지원 패널을 여는 버튼입니다. 여기에서 다음을 수행할 수 있습니다.

• SDK 문서와 가이드 및 설문조사 요약에 대한 링크를 엽니다.
• 버그 리포트 제출: 디버거에서 직접 버그 리포트를 제출합니다. 재현할 단계, 예상 결과 및 실제 결과를 입력한 다음 보내기를 누릅니다.

알려진 제한 사항

오프라인 지원 없음

SDK는 가이드 및 설문조사를 가져오고 표시하기 위해 활성 인터넷 연결이 필요합니다. 앱이 처음 로드될 때 기기가 오프라인 상태인 경우 해당 앱 세션에 대해 가이드 및 설문조사가 표시되지 않습니다.

애니메이션된 요소와 움직이는 컨테이너 내부의 요소를 대상으로 설정

핀과 툴팁은 다음과 같은 뷰나 요소를 대상으로 삼을 수 없습니다.

• 애니메이션되거나 애니메이션된 컨테이너에 있습니다(화면 주위를 이동).
• 사용자 상호 작용에 따라 이동할 수 있는 컨테이너에 있습니다.

변경 기록

Mobile SDK 변경 기록으로 이동하십시오.