안드로이드-코틀린 SDK

Kotlin Android SDK를 사용하면 이벤트를 Amplitude로 전송할 수 있습니다.

시스템 요구 사항

Android Kotlin SDK는 Android API 레벨 21(Android 5.0 Lollipop) 이상을 지원합니다.

SDK 설치

Amplitude는 Android Studio를 IDE로 사용하고 Gradle을 사용하여 종속성을 관리할 것을 권장합니다.

dependencies {
    implementation 'com.amplitude:analytics-android:1.+'
}

SDK 구성

일괄 처리 동작 구성

고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. SDK는 메서드가 기록하는 모든 이벤트를 메모리에 대기열에 넣고 백그라운드에서 track배치로 플러시합니다.flushQueueSize 및 flushIntervalMillis을 사용하여 일괄 처리 동작을 사용자 지정할 수 있습니다. 기본적으로 serverUrl은 https://api2.amplitude.com/2/httpapi입니다. 한 번에 대량의 데이터를 전송하려면 useBatch를 true로 설정하여 setServerUrl를 배치 이벤트 업로드 API https://api2.amplitude.com/batch로 설정하십시오. 일반 모드와 배치 모드 모두 동일한 이벤트 업로드 임계값과 플러시 시간 간격을 사용합니다.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    flushIntervalMillis = 50000
    flushQueueSize = 20
}

EU 데이터 상주

Amplitude의 EU 서버로 데이터를 전송하도록 클라이언트를 초기화할 때 서버 영역을 구성하십시오. SDK는 사용자가 서버 영역을 설정한 경우 이를 기반으로 데이터를 전송합니다.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    serverZone = ServerZone.EU
}

사용자 지정 HTTP 클라이언트

SDK는 기본적으로 네트워크 요청에 HttpURLConnection을 사용합니다. 사용자 지정 HTTP 클라이언트를 사용하려면 HttpClientInterface를 구현하여 httpClient 구성 옵션에 전달하십시오.

OkHttp - gzip 압축

샘플 앱은 이벤트 업로드를 위해 gzip 압축을 사용하는 사용자 지정 OkHttp 클라이언트를 만드는 방법을 보여줍니다.

• GzipRequestInterceptor - 요청 본문을 압축하는 OkHttp 인터셉터입니다.
• CustomOkHttpClient - OkHttp를 사용한 HttpClientInterface구현.

사용자 지정 클라이언트를 사용하려면 다음과 같이 하십시오.

val httpClient = CustomOkHttpClient()
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    this.httpClient = httpClient
}
httpClient.initialize(amplitude.configuration)

추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 "재생된 노래"는 메모해야 할 동작일 수 있습니다.

amplitude.track("Song Played")

또한 이벤트 속성을 선택적으로 포함할 수도 있습니다.

amplitude.track(
  "Song Played",
  mutableMapOf<String, Any?>("title" to "Happy Birthday")
)

var event = BaseEvent()
event.eventType = "Song Played"
event.eventProperties = mutableMapOf<String, Any?>("title" to "Happy Birthday")
event.groups = mutableMapOf<String, Any?>("test-group-type" to "test-group-value")
event.insertId = 1234
amplitude.track(event)

Identify

Identify 는 전체 이벤트를 전송하지 않고 특정 사용자의 사용자 속성을 설정합니다. SDK는 개별 사용자 속성에 대한 set, setOnce, unset, add, append, prepend, preInsert, postInsert, remove 및 clearAll 작업을 지원합니다. Identify 인터페이스를 사용하여 작업을 선언합니다. 하나의 Identify 객체에 여러 작업을 연결한 다음 Identify 객체를 Amplitude 클라이언트에 전달하여 서버로 전송할 수 있습니다.

identify 메서드를 사용하여 사용자의 ID를 처리하십시오. 이러한 방법을 적절하게 사용하면 이벤트가 장치, 브라우저 및 기타 플랫폼 간에 이동할 때 올바른 사용자에게 연결됩니다. 이러한 사용자 속성 작업이 포함된 identify 호출을 Amplitude 서버로 전송하여 사용자의 이벤트를 특정 사용자 속성과 연결합니다.

val identify = Identify()
identify.set("color", "green")
amplitude.identify(identify)

식별 작업

Identify 객체는 다음 작업을 지원합니다.

val identify = Identify()
identify
    .set("color", "green")
    .setOnce("initial_source", "organic")
    .add("login_count", 1)
    .append("visited_pages", "home")
    .prepend("notifications", "new_feature")
    .unset("temporary_property")
amplitude.identify(identify)

모든 사용자 속성 지우기

clearAll()을 사용하여 현재 사용자의 모든 사용자 속성을 지웁니다. 이 작업은 되돌릴 수 없습니다.

val identify = Identify()
identify.clearAll()
amplitude.identify(identify)

자동 캡처

v1.18.0 릴리스부터 SDK는 수동 계측 없이 더 많은 이벤트를 추적할 수 있습니다. 다음 이벤트를 자동으로 추적하도록 SDK를 구성하십시오.

• 세션.
• 앱 수명 주기.
• 화면 보기.
• 딥 링크.
• 요소 상호 작용.
• 불만스러운 상호 작용:
  • 레이지 클릭.
  • 데드 클릭.

Amplitude를 구성하여 오토캡처 이벤트 추적을 시작합니다. 그렇지 않으면 구성을 생략하여 세션 추적만 활성화된 상태로 유지하십시오.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +sessions               // or `+AutocaptureOption.SESSIONS`
        +appLifecycles          // or `+AutocaptureOption.APP_LIFECYCLES`
        +deepLinks              // or `+AutocaptureOption.DEEP_LINKS`
        +screenViews            // or `+AutocaptureOption.SCREEN_VIEWS`
        +elementInteractions    // or `+AutocaptureOption.ELEMENT_INTERACTIONS`
        +frustrationInteractions // or `+AutocaptureOption.FRUSTRATION_INTERACTIONS`
    }
}

import com.amplitude.android.Amplitude
import com.amplitude.android.AutocaptureOption
// Using AutocaptureOption.ALL constant
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = AutocaptureOption.ALL
}
// Or using addAll() method with builder
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        addAll()
    }
}

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = setOf(AutocaptureOption.APP_LIFECYCLES)  // or use `setOf()` to disable autocapture.
}

세션 추적

Amplitude는 기본적으로 세션 추적을 활성화합니다. AutocaptureOption.SESSIONS을 autocapture 구성에 포함하여 SDK가 세션 이벤트를 추적하도록 명시적으로 구성하거나, 다른 자동 캡처 구성과 함께 세션 이벤트 트래킹을 활성화할 수 있습니다.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +sessions    // or `+AutocaptureOption.SESSIONS`
    }
}

애플리케이션 수명주기 추적

autocapture 구성에 AutocaptureOption.APP_LIFECYCLES을 포함시켜 애플리케이션 생애주기 분석 이벤트 트래킹을 활성화하십시오. 다음 코드 샘플을 참조하십시오.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +appLifecycles    // or `+AutocaptureOption.APP_LIFECYCLES`
    }
}

이 설정을 활성화하면 Amplitude는 다음 이벤트를 추적합니다.

• [Amplitude] Application Installed: 설치 직후 사용자가 애플리케이션을 처음 열 때 발생합니다.
• [Amplitude] Application Updated: 사용자가 애플리케이션을 업데이트한 후 애플리케이션을 열 때 발생합니다.
• [Amplitude] Application Opened: 사용자가 처음 연 후 애플리케이션을 실행하거나 포그라운드로 전환할 때 발생합니다.
• [Amplitude] Application Backgrounded: 사용자가 애플리케이션을 백그라운드로 전환할 때 발생합니다.

화면 뷰 추적

autocapture 구성에 AutocaptureOption.SCREEN_VIEWS을 포함시켜 화면 및 프래그먼트 보기 이벤트 트래킹을 활성화하십시오. 다음 코드 샘플을 참조하십시오.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +screenViews    // or `+AutocaptureOption.SCREEN_VIEWS`
    }
}

이 설정을 활성화하면 Amplitude는 [Amplitude] Screen Viewed및 [Amplitude] Fragment Viewed 이벤트를 모두 추적합니다. 두 이벤트 모두 화면 이름 속성을 포함합니다. [Amplitude] Fragment Viewed이벤트의 경우 Amplitude는 추가 프래그먼트 관련 속성을 캡처합니다.

딥 링크 추적

autocapture 구성에 AutocaptureOption.DEEP_LINKS을 포함시켜 딥링크 이벤트 트래킹을 활성화하십시오. 다음 코드 샘플을 참조하십시오.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +deepLinks    // or `+AutocaptureOption.DEEP_LINKS`
    }
}

이 설정을 활성화하면 Amplitude는 URL 및 리퍼러 정보를 사용하여 [Amplitude] Deep Link Opened이벤트를 추적합니다.

단일 작업 활동에서 딥 링크 처리

활동이 singleTop, singleTask, 또는 singleInstance 시작 모드를 사용하는 경우, Android는 새 활동을 생성하는 대신 해당 활동이 이미 실행되고 있는 동안 도착하는 딥 링크를 onNewIntent()로 전달합니다. 이 경우, Amplitude가 딥링크를 추적할 수 있도록 setIntent()를 호출하여 활동의 인텐트를 업데이트하십시오.

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent) // Required for Amplitude to track the deep link
}

요소 상호 작용 추적

Amplitude는 클래식 Android Views와 Jetpack Compose를 모두 지원하며 클릭 가능한 요소를 사용한 사용자 상호 작용을 추적할 수 있습니다. 이 옵션을 활성화하려면 AutocaptureOption.ELEMENT_INTERACTIONS를 autocapture구성에 포함하십시오.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +elementInteractions    // or `+AutocaptureOption.ELEMENT_INTERACTIONS`
    }
}

이 설정을 활성화하면 Amplitude는 사용자가 애플리케이션의 요소와 상호작용할 때마다 [Amplitude] Element Interacted이벤트를 추적합니다.

// Example: Adding testTag for better identification
Button(
    onClick = { /* handle click */ },
    modifier = Modifier.testTag("login_button")
) {
    Text("Log In")
}
Card(
    onClick = { /* handle click */ },
    modifier = Modifier.testTag("product_card_${product.id}")
) {
    // Card content
}

불만 유발 상호작용 추적

Amplitude는 Android Views와 Jetpack Compose에서 클릭 가능한 UI 요소를 사용하여 좌절감을 주는 상호작용(분노 클릭과 죽은 클릭)을 추적할 수 있습니다. 이 옵션을 활성화하려면 AutocaptureOption.FRUSTRATION_INTERACTIONS를 autocapture구성에 포함하십시오.

import com.amplitude.android.Amplitude
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +frustrationInteractions    // or `+AutocaptureOption.FRUSTRATION_INTERACTIONS`
    }
}

레이지 클릭은 사용자가 1초 이내에 동일한 요소를 4회 이상 클릭하고, 각 클릭 간격이 50픽셀(장치 독립) 이내인 경우 발생합니다.

레이지 클릭(Rage Click)이 발생하면 Amplitude는 해당 [Amplitude] Rage Click이벤트를 추적합니다.

데드 클릭은 사용자가 상호작용 가능 요소에 대해 상호 작용했지만, 이후 3초 동안 화면에 아무런 변화가 없는 경우입니다.

데드 클릭이 발생하면 Amplitude는 [Amplitude] Dead Click 이벤트를 추적합니다.

불만족 상호 작용 유형 구성

FRUSTRATION_INTERACTIONS을 활성화하면 레이지 클릭과 데드 클릭을 모두 추적합니다. interactionsOptions 매개변수를 사용하여 각 유형을 개별적으로 활성화 또는 비활성화할 수 있습니다.

import com.amplitude.android.Amplitude
import com.amplitude.android.InteractionsOptions
import com.amplitude.android.RageClickOptions
import com.amplitude.android.DeadClickOptions
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = autocaptureOptions {
        +frustrationInteractions
    }
    interactionsOptions = InteractionsOptions(
        rageClick = RageClickOptions(enabled = true),
        deadClick = DeadClickOptions(enabled = false)
    )
}

불만족 분석에서 특정 요소를 무시하십시오.

일부 UI 요소는 예상되는 빠른 클릭을 생성하거나 의미있는 불만감 신호를 제공하지 않습니다. 무시 API를 사용하여 이러한 요소를 불만 분석에서 제외하면서도 일반적인 상호작용 이벤트는 계속 추적할 수 있습니다.

일반적인 활용 사례:

• 탐색 요소: 뒤로 버튼, 닫기 버튼 및 서랍 토글.
• 멀티클릭 요소: 증분/감소 버튼과 좋아요/즐겨찾기 버튼.
• 로딩 표시기: 진행률 표시줄, 스피너 및 로딩 버튼
• 장식 요소: 비기능적 UI 구성 요소입니다.

Android 보기

Android 보기에 대한 좌절 분석을 무시하는 데 FrustrationAnalyticsUtils사용하십시오.

import com.amplitude.android.FrustrationAnalyticsUtils
// Ignore all frustration analytics for this view
val backButton = findViewById<Button>(R.id.back_button)
FrustrationAnalyticsUtils.ignoreFrustrationAnalytics(backButton)
// Ignore only rage clicks (allow dead click detection)
val incrementButton = findViewById<Button>(R.id.increment_button)
FrustrationAnalyticsUtils.ignoreFrustrationAnalytics(
    incrementButton,
    rageClick = true,
    deadClick = false
)
// Remove ignore marker from a view
FrustrationAnalyticsUtils.unignoreView(backButton)

Jetpack Compose

Modifier.ignoreFrustrationAnalytics()확장 기능을 사용하여 컴포즈 요소에 대한 좌절 분석을 무시하십시오.

import com.amplitude.android.ignoreFrustrationAnalytics
// Ignore all frustration analytics
Button(
    onClick = { finish() },
    modifier = Modifier.ignoreFrustrationAnalytics()
) { Text("Back") }
// Ignore only dead clicks (allow rage click detection)
Button(
    onClick = { submitForm() },
    modifier = Modifier.ignoreFrustrationAnalytics(
        rageClick = false,
        deadClick = true
    )
) { Text("Submit") }

매개변수 조합

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 실행할 수 있도록 지원합니다. 그룹 구성원 중 하나 이상이 특정 이벤트를 수행하는 경우 해당 그룹도 수행 회수가에 포함됩니다.

예를 들어, orgId를 사용하여 사용자를 조직별로 그룹화하려는 경우를 생각해 보겠습니다. Joe는 orgId 10에 속하고, Sue는 orgId 15에 속합니다. 수와 조 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예시에서 orgId는 groupType이고 10와 15은 groupName의 값입니다. groupType의 또 다른 예로는 sport이 있으며, groupName 값은 tennis 및 baseball와 같이 구성됩니다.

또한 그룹을 설정하면 groupType:groupName이 사용자 속성으로 설정되며, 해당 사용자의 groupType에 대한 모든 기존 groupName 값과 해당 사용자 속성 값을 덮어씁니다. groupType은 문자열이며, groupName은 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열입니다.

// set group with a single group name
amplitude.setGroup("orgId", "15");

// set group with multiple group names
amplitude.setGroup("sport", arrayOf("tennis", "soccer"))

groups을 포함한 Event 객체를 track에 전달하여 이벤트 수준 그룹을 설정할 수도 있습니다. 이벤트 수준 그룹의 경우, 그룹 지정은 사용자가 기록하는 특정 이벤트에만 적용되며 setGroup를 사용하여 명시적으로 설정하지 않는 한 해당 지정이 사용자에게 계속 적용되지는 않습니다.

val event = BaseEvent()
event.eventType = "event type"
event.eventProperties = mutableMapOf("event property" to "event property value")
event.groups = mutableMapOf("orgId" to "15")
amplitude.track(event)

그룹 식별

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 다음 고려 사항에 유의하십시오.

• 업데이트는 향후 이벤트에만 영향을 미치며 과거 이벤트를 업데이트하지는 않습니다.
• 최대 5개의 고유 그룹 유형과 총 10개의 그룹을 추적할 수 있습니다.

groupIdentify 메서드는 그룹 유형 문자열 매개변수, 그룹 이름 객체 매개변수 및 Amplitude가 그룹에 적용하는 Identify 객체를 허용합니다.

val groupType = "plan"
val groupName = "enterprise"
val identify = Identify().set("key", "value")
amplitude.groupIdentify(groupType, groupName, identify)

매출 추적

Amplitude는 사용자가 창출한 수익을 추적할 수 있습니다. Amplitude는 Amplitude의 이벤트 세분화 및 수익 LTV (Lifetime Value) 차트에서 사용하는 특수 필드를 갖춘 별개의 수익 객체를 통해 수익을 추적합니다. 수익 객체는 플랫폼의 수익과 관련된 데이터를 자동으로 표시합니다. 수익 객체는 다음과 같은 특수 속성과 eventProperties필드를 통해 사용자 정의 속성을 지원합니다.

val revenue = Revenue()
revenue.productId = "com.company.productId"
revenue.price = 3.99
revenue.quantity = 3
amplitude.revenue(revenue)

사용자 정의 사용자 식별자

앱에 자체 로그인 시스템이 있고 이를 이용하여 사용자를 추적하려는 경우, 언제든지 setUserId을 호출하십시오.

amplitude.setUserId("user@amplitude.com")

현재 사용자 ID를 가져오려면 getUserId()을(를) 호출하십시오.

val userId = amplitude.getUserId()

사용자 지정 장치 식별자

deviceId를 사용하여 새 장치 ID를 할당하십시오. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID 사용을 권장합니다.

import java.util.UUID
amplitude.setDeviceId(UUID.randomUUID().toString())

사용자가 로그아웃할 때 재설정

reset는 사용자가 로그아웃한 후 익명화하는 바로 가기입니다. 방법은 다음과 같습니다.

• userId을 null로 설정합니다.
• deviceId을 현재 구성에 따라 새 값으로 설정합니다.

userId이 비어 있고 deviceId가 완전히 새로운 값인 경우, 현재 사용자는 대시보드에 완전히 새로운 사용자로 표시됩니다.

amplitude.reset()

SDK 플러그인

플러그인을 사용하면 이벤트 속성을 수정하거나(보강 유형), 타사 API로 전송(목적지 유형)하는 등의 방법으로 Amplitude SDK의 동작을 확장할 수 있습니다. 플러그인은 setup() 및 execute() 메서드를 가진 객체입니다.

플러그인 유형

SDK는 플러그인을 각 이벤트에 고정된 순서로 적용합니다. 즉, Before 플러그인이 먼저 실행된 다음, Enrichment 플러그인, 그 다음에 Destination 플러그인이 실행됩니다. Observe와(과) 같은 다른 플러그인 유형은 이 파이프라인 외부에서 실행됩니다.

• Before 플러그인(Plugin.Type.Before)은 모든 보강 플러그인 앞에 실행됩니다. IT를 사용하면 다른 플러그인들이 이벤트 필드를 읽기 전에 일찍 설정하거나 보호할 수 있습니다. 이것은 보강 플러그인과 동일한 형태를 가지며, type은(는) Plugin.Type.Before(으)로 설정되어 있습니다.
• Enrichment플러그인(Plugin.Type.Enrichment)은 이벤트 속성을 추가하는 등, 각 이벤트를 전달할 때 이벤트를 수정하거나 보강합니다. 보강 유형 플러그인 예제로 이동하십시오.
• Destination플러그인(Plugin.Type.Destination)은 이벤트를 타사 API 등의 목적지로 전송하고 파이프라인을 종료합니다. 목적지 유형 플러그인 예제로 이동하십시오.
• Observe 플러그인(Plugin.Type.Observe)은 이벤트 파이프라인 외부에서 실행됩니다. 이것은 이벤트를 처리하는 대신 onUserIdChanged, onDeviceIdChanged, onSessionIdChanged 및 onOptOutChanged 콜백을 통해 ID 및 세션 변경에 대응합니다. ObservePlugin 클래스를 확장하고 필요한 콜백을 재정의합니다. onUserIdChanged 및 onDeviceIdChanged은(는) 필수입니다.

다음 관찰 플러그인은 사용자가 로그인하거나 로그아웃할 때 반응합니다.

import com.amplitude.core.Amplitude
import com.amplitude.core.platform.ObservePlugin
class LoginObserverPlugin : ObservePlugin() {
    override lateinit var amplitude: Amplitude
    override fun onUserIdChanged(userId: String?) {
        // React to login or logout.
    }
    override fun onDeviceIdChanged(deviceId: String?) {}
}
amplitude.add(LoginObserverPlugin())

Plugin.setup

이 메서드는 플러그인을 사용할 준비를 위한 amplitude로직을 포함하며 인스턴스를 매개변수로 취합니다. 예상 반환 값은 null입니다. 이 메서드의 일반적인 용도는 플러그인 종속성을 인스턴스화하는 데 사용됩니다. SDK는 플러그인이 amplitude.add()를 통해 클라이언트에 등록될 때 이 메서드를 호출합니다.

Plugin.execute

이 메서드는 이벤트를 처리하기 위한 로직을 포함하고 있으며 인스턴스를 event매개변수로 사용합니다. 강화 유형 플러그인으로 사용될 경우 예상되는 반환 값은 수정 또는 강화된 이벤트입니다. 목적지 유형 플러그인으로 사용될 경우 예상되는 반환 값은 event(BaseEvent), code(number), message(string) 키가 있는 맵입니다. SDK는 Identify, GroupIdentify 및 Revenue 이벤트를 비롯하여 클라이언트 인터페이스를 사용하여 계측하는 각 이벤트에 대해 이 메서드를 호출합니다.

보강 유형 플러그인 예제

다음 플러그인은 추가 이벤트 속성을 추가하여 각 계측된 이벤트를 수정합니다.

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import com.amplitude.core.Amplitude;
import com.amplitude.core.events.BaseEvent;
import com.amplitude.core.platform.Plugin;
import java.util.HashMap;
public class EnrichmentPlugin implements Plugin {
  public Amplitude amplitude;
  @NonNull
  @Override
  public Amplitude getAmplitude() {
    return this.amplitude;
  }
  @Override
  public void setAmplitude(@NonNull Amplitude amplitude) {
    this.amplitude = amplitude;
  }
  @NonNull
  @Override
  public Type getType() {
    return Type.Enrichment;
  }
  @Nullable
  @Override
  public BaseEvent execute(@NonNull BaseEvent baseEvent) {
    if (baseEvent.getEventProperties() == null) {
      baseEvent.setEventProperties(new HashMap<String, Object>());
    }
    baseEvent.getEventProperties().put("custom android event property", "test");
    return baseEvent;
  }
  @Override
  public void setup(@NonNull Amplitude amplitude) {
    this.amplitude = amplitude;
  }
}
amplitude.add(new EnrichmentPlugin());

목적지 유형 플러그인 예제

목적지 플러그인에서 , identify(), groupIdentify()``revenue(), 및 flush()함수를 track()덮어쓸 수 있습니다.

import com.amplitude.core.Amplitude;
import com.amplitude.core.events.BaseEvent;
import com.amplitude.core.platform.DestinationPlugin;
import com.segment.analytics.Analytics;
import com.segment.analytics.Properties;
public class SegmentDestinationPlugin extends DestinationPlugin {
  android.content.Context context;
  Analytics analytics;
  String writeKey;
  public SegmentDestinationPlugin(android.content.Context appContext, String writeKey) {
    this.context = appContext;
    this.writeKey = writeKey;
  }
  @Override
  public void setup(Amplitude amplitude) {
    super.setup(amplitude);
    analytics = new Analytics.Builder(this.context, this.writeKey)
    .build();
    Analytics.setSingletonInstance(analytics);
    }
  @Override
  public BaseEvent track(BaseEvent event) {
    Properties properties = new Properties();
    for (Map.Entry<String,Object> entry : event.getEventProperties().entrySet()) {
      properties.putValue(entry.getKey(),entry.getValue());
    }
    analytics.track(event.eventType, properties);
    return event;
    }
}
amplitude.add(
new SegmentDestinationPlugin(this, SEGMENT_WRITE_KEY)
)

플러그인 제거

플러그인이 이벤트를 처리하지 못하도록 막으려면, 동일한 플러그인 인스턴스를 remove()에 전달하십시오.

val plugin = EnrichmentPlugin()
amplitude.add(plugin)
// Later, remove it.
amplitude.remove(plugin)

네트워크 추적 플러그인

네트워크 추적 플러그인은 URL, 상태 코드, 타이밍 정보를 포함하여 OkHttp를 통해 이루어진 네트워크 요청과 응답을 캡처합니다. 네트워크 추적은 자동 캡처의 일부가 아니며 수동 연동이 필요합니다. 추적하려는 각 OkHttp 클라이언트에 플러그인을 인터셉터로 추가한 다음, Amplitude 인스턴스에 추가하십시오. 이 플러그인은 사용자가 계측하는 OkHttp 클라이언트를 통해 전달되는 요청만 캡처합니다.

설치

네트워크 추적 플러그인은 OkHttp 종속성을 필요로 합니다. 프로젝트에 IT를 추가하려면 다음과 같이 하십시오.

dependencies {
    // OkHttp is required for the NetworkTrackingPlugin
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
}

구성

기본 구성을 사용하고 OkHttp와 통합하기 위해 플러그인을 인터셉터로 추가하십시오:

import com.amplitude.android.network.NetworkTrackingPlugin
// Create the plugin with default configuration
val networkPlugin = NetworkTrackingPlugin()
// Add the plugin as an interceptor to your OkHttp client
val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(networkPlugin)
    .build()
// Add the plugin to your Amplitude instance
amplitude.add(networkPlugin)

기본 구성은 상태 코드 500~599인 *.amplitude.com을 제외한 모든 호스트를 추적합니다.

추적 동작을 사용자 정의하고 추적할 요청을 제어하려면 NetworkTrackingOptions설정하십시오.

import com.amplitude.android.Amplitude
import com.amplitude.android.network.NetworkTrackingOptions
import com.amplitude.android.network.NetworkTrackingPlugin
import com.amplitude.android.network.NetworkTrackingOptions.CaptureRule
// Create custom capture rules
val options = NetworkTrackingOptions(
    captureRules = listOf(
        // Track all responses from your API domain with status code from 400 to 599
        CaptureRule(
            hosts = listOf("*.example.com", "example.com"),
            statusCodeRange = (400..599).toList()
        )
    ),
    // Ignore specific domains
    ignoreHosts = listOf("analytics.example.com", "*.internal.com"),
    // Whether to ignore Amplitude API requests
    ignoreAmplitudeRequests = true
)
// Create the plugin with options
val networkPlugin = NetworkTrackingPlugin(options)
// Add the plugin to your Amplitude instance
amplitude.add(networkPlugin)

captureRules = listOf(
    CaptureRule(
        hosts = listOf("\*"),
        statusCodeRange = (400..599).toList()
    ),
    CaptureRule(
        hosts = listOf("\*.example.com", "example.com"),
        statusCodeRange = (500..599).toList()
    )
)

URL, 헤더 및 요청 본문 캡처

호스트 대신 URL을 기준으로 요청을 일치시키거나 요청 및 응답 헤더와 본문을 캡처하려면 URL 기반 CaptureRule 생성자를 사용하십시오. URL을 URLPattern.Exact또는 URLPattern.Regex과 매칭시키고, HTTP 메소드로 필터링하고, CaptureHeader및 CaptureBody를 사용하여 헤더 및 본문 캡처를 선택하십시오.

import com.amplitude.android.network.NetworkTrackingOptions
import com.amplitude.android.network.NetworkTrackingOptions.CaptureRule
import com.amplitude.android.network.NetworkTrackingOptions.CaptureHeader
import com.amplitude.android.network.NetworkTrackingOptions.CaptureBody
import com.amplitude.android.network.NetworkTrackingOptions.URLPattern
val options = NetworkTrackingOptions(
    captureRules = listOf(
        CaptureRule(
            urls = listOf(
                URLPattern.Exact("https://api.example.com/v1/login"),
                URLPattern.Regex("^https://api\\.example\\.com/v1/.*")
            ),
            methods = listOf("POST"),
            statusCodeRange = (200..599).toList(),
            requestHeaders = CaptureHeader(allowlist = listOf("X-Request-Id")),
            responseHeaders = CaptureHeader(allowlist = listOf("X-Response-Id")),
            requestBody = CaptureBody(allowlist = listOf("user/*"), excludelist = listOf("**/password")),
            responseBody = CaptureBody(allowlist = listOf("profile/**"))
        )
    )
)
amplitude.add(NetworkTrackingPlugin(options))

추적되는 이벤트 속성

플러그인이 네트워크 요청을 추적할 때 다음과 같은 속성을 가진 유형의 이벤트를 전송합니다[Amplitude] Network Request.

개인정보 보호 고려 사항

네트워크 추적 플러그인은 기본적으로 다음과 같은 민감한 정보를 마스킹합니다.

1. URL에 있는 인증 자격 증명(사용자 이름:암호@domain.com).
2. 일반적인 민감한 쿼리 매개 변수(예: 사용자 이름, 암호, 이메일, 전화 번호)입니다.

디버깅

구성과 페이로드가 정확한지 확인하고, 디버깅 중에 비정상적인 메시지가 있는지 확인하십시오. 모든 것이 문제없어 보이면 flushQueueSize 또는 flushIntervalMillis의 값을 확인하십시오. 기본적으로 SDK는 이벤트를 대기열에 넣고 일괄적으로 전송하므로, 개별 이벤트가 즉시 서버로 전송되지는 않습니다. SDK가 서버에 이벤트를 전송할 때까지 기다린 후 차트에서 해당 이벤트를 확인하십시오.

로그

• 디버깅 중에 유용한 정보를 수집하려면 로그 수준을 디버그로 설정하십시오.
• LoggerProvider에서 loggerProvider 클래스를 사용자 정의하고 프로덕션 환경의 서버에 오류 메시지를 기록하는 것과 같은 고유한 논리를 구현하십시오.

플러그인

목적지 플러그인을 사용하여 구성 값과 이벤트 페이로드를 서버로 전송하기 전에 출력하십시오. logLevel을 디버그로 설정하고 다음 TroubleShootingPlugin를 프로젝트에 복사한 다음 Amplitude 인스턴스에 플러그인을 추가하십시오.

• Java TroubleShootingPlugin 예제입니다.
• Kotlin TroubleShootingPlugin 예제입니다.

이벤트 콜백

고급옵션 항목

사용자 세션

Amplitude는 앱이 포그라운드로 이동하거나 SDK가 백그라운드에서 이벤트를 추적할 때 세션을 시작합니다. 앱이 minTimeBetweenSessionsMillis 옵션 이상 백그라운드에 머물면서 어떤 이벤트도 추적하지 않으면 세션이 종료됩니다. configuration.trackingSessionEvents, configuration.defaultTracking 또는 configuration.autocapture을 통해 세션 추적을 활성화했는지 여부와 관계없이 앱이 포그라운드에 있는 동안 세션은 계속됩니다.

앱이 포그라운드에 진입하면 Amplitude는 세션 시작을 추적하고 minTimeBetweenSessionsMillis에 따라 카운트다운을 시작합니다. Amplitude는 세션을 연장하고 IT가 새 이벤트를 추적하는 전체 시간마다 카운트다운을 다시 시작합니다. 카운트다운이 만료되면 Amplitude는 다음 이벤트가 있을 때까지 기다리며 세션 종료 이벤트를 추적합니다.

Amplitude는 기본적으로 세션 이벤트에 대한 사용자 속성을 설정하지 않습니다. 이러한 속성을 추가하려면 identify() 및 setUserId()를 사용하십시오. Amplitude는 사용자 속성 상태를 집계하고 device_id 또는 user_id에 따라 사용자를 이벤트와 연결합니다.

Amplitude가 세션을 관리하는 방식 때문에 이벤트가 누락된 것처럼 보이거나 세션 추적이 정확하지 않은 것처럼 보이는 경우에도 SDK는 예상대로 작동할 수 있습니다.

• 사용자가 앱으로 돌아오지 않는 경우, Amplitude는 세션 시작 이벤트와 일치하도록 세션 종료 이벤트를 추적하지 않습니다.
• 백그라운드에서 이벤트를 추적하는 경우 Amplitude가 사용자가 포그라운드에서 앱에 소비한 시간보다 세션 길이를 더 길다고 인식할 수 있습니다.
• 마지막 이벤트와 세션 종료 이벤트 대상 구간 사용자 속성을 수정하는 경우 세션 종료 이벤트는 업데이트된 사용자 속성을 반영하며, 이 속성은 동일한 세션의 이벤트와 연관된 다른 속성과 다를 수 있습니다. 이 문제를 해결하려면 보강 플러그인을 사용해 세션 종료 이벤트에서 event['$skip_user_properties_sync']을 true로 설정하십시오. 이렇게 하면 Amplitude가 해당 특정 이벤트에 대한 속성을 동기화하지 못하게 됩니다. 자세한 내용은 컨버터 구성 참조 문서의 $skip_user_properties_sync를 참조하십시오.

Amplitude는 이벤트를 세션별로 그룹화합니다. 동일한 세션 내에서 기록된 이벤트는 동일한 session_id를 공유합니다. Amplitude는 세션을 자동으로 처리하므로 수동으로 startSession() 또는 endSession()을 호출할 필요가 없습니다.

세션 연장을 위한 시간 범위를 조정하십시오. 기본 세션 만료 시간은 30분입니다.

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    minTimeBetweenSessionsMillis = 10000
}

기본적으로 Amplitude는 [Amplitude] Start Session 및 [Amplitude] End Session 이벤트를 자동으로 전송합니다. SDK가 이러한 이벤트를 전송하지 않더라도 Amplitude는 session_id를 사용하여 세션을 계속 추적합니다. 이러한 세션 이벤트를 비활성화할 수도 있습니다.

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    autocapture = setOf()
}

현재 세션 ID를 가져오려면 sessionId 속성을 읽으십시오. Java에서는 합성된 getSessionId() 액세서를 사용하십시오.

val sessionId = amplitude.sessionId

또한 이벤트를 세션 외에도 추적할 수 있습니다. 세션 외 이벤트는 -1의 sessionId 값을 갖고 있으며 다음과 같이 동작합니다.

1. 현재 세션의 일부가 아닙니다.
2. 현재 세션을 연장하지 않습니다.
3. 새로운 세션을 시작하지 않습니다.
4. 이들은 후속 이벤트에 대해 sessionId를 변경하지 않습니다.

잠재적 사용 사례는 푸시 알림에서 추적되는 이벤트이며, 이는 일반적으로 고객의 앱 사용 외부에서 발생합니다.

EventOptions에서 sessionId를 -1로 설정하면 track(event, options) 또는 identify(identify, options)을 호출할 때 이벤트가 세션 외 이벤트로 표시됩니다.

val outOfSessionOptions = EventOptions().apply {
 sessionId = -1
}
amplitude.identify(
 Identify().set("user-prop", true),
 outOfSessionOptions
)
amplitude.track(
 BaseEvent().apply { eventType = "test event" },
 outOfSessionOptions
)

로그 수준

개발자 콘솔에 출력되는 로그 수준을 제어합니다.

• INFO: 이벤트에 대한 유용한 정보성 메시지를 표시합니다.
• WARN: 오류 메시지와 경고를 표시합니다. 이 수준은 데이터에 문제나 특이 사항을 일으킬 수 있는 문제를 기록합니다. 예를 들어 이 수준은 Null 값을 가진 속성에 대한 경고를 표시합니다.
• ERROR: 오류 메시지만 표시합니다.
• DISABLE: 모든 로그 메시지를 숨깁니다.
• DEBUG: 디버깅에 유용할 수 있는 오류 메시지, 경고 및 유용한 정보를 표시합니다.

원하는 수준을 지정하여 setLogLevel을 호출하여 로그 수준을 설정하십시오.

amplitude.logger.logMode = Logger.LogMode.DEBUG

로그아웃된 사용자 및 익명 사용자

익명 사용자에게 이벤트를 기록하려면 다음을 수행하십시오.

1. userId를 null로 설정합니다.
2. 새 deviceId를 생성합니다.

현재 사용자 또는 기기에서 발생한 이벤트는 Amplitude에서 새 사용자로 표시됩니다. 참고: 이 작업을 수행하면 두 사용자가 동일한 장치를 사용했는지 알 수 없습니다.

amplitude.reset()

추적 비활성화

기본적으로 Android SDK는 carrier, city, country, ip_address, language 및 platform과 같은 여러 사용자 속성을 추적합니다. 제공된 TrackingOptions 인터페이스를 사용하여 개별 필드를 사용자 정의하고 토글할 수 있습니다.

TrackingOptions 인터페이스를 사용하려면 클래스를 가져오십시오.

import com.amplitude.android.TrackingOptions

apiKey를 사용하여 SDK를 초기화하기 전에 사용자의 구성으로 TrackingOptions 인스턴스를 생성하고, 이를 SDK 인스턴스에 설정하십시오.

val trackingOptions = TrackingOptions()
trackingOptions.disableCity().disableIpAddress().disableLatLng()
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    this.trackingOptions = trackingOptions
}

각 필드에 대한 추적을 개별적으로 제어할 수 있습니다. 각 필드에는 해당하는 메서드가 있습니다(예: disableCountry, disableLanguage).

이동통신사

COPPA 제어

IDFA, IDFV, 도시, IP 주소 및 위치 추적에 대한 COPPA(아동 온라인 개인정보 보호법) 제한을 모두 활성화 또는 비활성화할 수 있습니다. 13세 미만의 어린이로부터 정보를 요청하는 앱은 COPPA를 준수해야 합니다.

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    enableCoppaControl = true // Disables ADID, city, IP, and location tracking
}

광고주 ID

Android 광고 ID를 사용하려면 다음 단계를 따르십시오.

1. play-services-ads-identifier을 종속성으로 추가하십시오.

   bash

   복사

   dependencies {
     implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
   }
   

2. AD_MANAGER_APP 권한 Google 모바일 광고 SDK 버전 17.0.0 이상을 사용하는 경우 AD_MANAGER_APP을 AndroidManifest.xml에 추가해야 합니다.

   xml <manifest> <application> <meta-data android:name="com.google.android.gms.ads.AD_MANAGER_APP" android:value="true"/> </application> </manifest>

3. ProGuard 예외 추가

   Amplitude Android SDK는 Java Reflection을 사용하여 Google Play 서비스의 클래스를 사용합니다. Amplitude SDK가 Android 애플리케이션에서 작동하도록 하려면 play-services-ads의 클래스에 대해 이러한 예외를 proguard.pro에 추가하십시오. -keep class com.google.android.gms.ads.** { *; }

4. AD_ID 권한

   Android 13 이상을 대상으로 앱을 업데이트하는 경우 ADID를 deviceId로 사용하려면 매니페스트 파일에 다음과 같이 Google Play 서비스 일반 권한을 선언해야 합니다.

   xml

   복사

   <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
   

   자세한 내용은 Google의 광고 ID 문서를 참조하십시오.

광고 ID를 장치 ID로 사용

광고 ID를 가져오도록 로직을 설정한 후, useAdvertisingIdForDeviceId을 활성화하여 광고 ID를 장치 ID로 사용하도록 설정하십시오.

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    useAdvertisingIdForDeviceId = true
}

앱 세트 ID

앱 세트 ID는 기기에 설치된 각 앱의 고유 식별자입니다. 사용자가 앱을 제거할 때 앱 세트 ID를 수동으로 재설정하거나, 앱을 열지 않은 지 13개월 후에 자동으로 재설정합니다. Google은 강력한 분석을 거부하려는 사용자를 위해 광고 ID에 대한 개인 정보 보호 친화적 대안으로 앱 세트 ID를 설계했습니다.

앱 세트 ID를 사용하려면 다음 단계를 따르십시오.

1. play-services-appset을 종속성으로 추가합니다. 2.35.3 이전 버전의 경우 'com.google.android.gms:play-services-appset:16.0.0-alpha1'을 사용합니다.

   bash

   복사

   dependencies {
   implementation 'com.google.android.gms:play-services-appset:16.0.2'
   }
   

2. 앱 세트 ID를 장치 ID로 사용하도록 설정합니다.

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    useAppSetIdForDeviceId = true
}

장치 ID 생애주기 분석

SDK는 다음 순서로 장치 ID를 초기화하고 장치 ID를 발견한 첫 번째 유효한 값으로 설정합니다.

1. 인스턴스의 장치 ID입니다.
2. ADID(활성화되어 있고 필요한 모듈이 설치되어 있는 useAdvertisingIdForDeviceId경우) 자세한 내용은 광고주 ID를 참조하십시오.
3. useAppSetIdForDeviceId가 활성화되어 있고 필요한 모듈이 설치되어 있는 경우, S이 추가된 앱 세트 ID. 자세한 내용은 애플리케이션 세트 ID를 참조하십시오.
4. R이 추가된 임의로 생성된 UUID.

한 명의 사용자가 여러 장치를 사용

단일 사용자는 각각 다른 장치 ID를 가진 여러 장치를 가질 수 있습니다. 일관성을 유지하려면 이러한 모든 장치에서 사용자 ID를 일관되게 설정하십시오. 장치 ID가 서로 다른 경우에도 Amplitude는 이를 단일 Amplitude ID로 병합하여 고유 사용자로 식별할 수 있습니다.

새 장치로 전송

사용자가 새 장치로 전환할 때 여러 장치가 동일한 장치 ID를 가질 수 있습니다. 사용자가 새로운 장치로 이동할 때 사용자는 종종 다른 관련 데이터와 함께 자신의 애플리케이션을 전송합니다. 전송되는 특정 콘텐츠는 애플리케이션에 따라 다릅니다. 일반적으로 IT에는 앱과 관련된 데이터베이스 및 파일 디렉토리가 포함됩니다. 포함되는 정확한 항목은 앱의 설계와 개발자의 선택에 따라 달라집니다. 데이터베이스 또는 파일 디렉토리가 한 장치에서 다른 장치로 전송되는 경우에도 첫 사용 후 저장된 장치 ID가 여전히 존재할 수 있습니다. SDK가 초기화 다음 기간동안 해당 장치 ID를 검색하는 경우 다른 장치가 동일한 장치 ID를 사용하게 될 수 있습니다.

장치 ID 가져오기

현재 deviceId의 값을 얻으려면 헬퍼 메소드 getDeviceId()을 사용하십시오.

val deviceId = amplitude.getDeviceId();

위치 추적

Amplitude는 기본적으로 사용자 이벤트의 IP를 위치(GeoIP 조회)로 변환합니다. 앱의 자체 추적 솔루션 또는 사용자 데이터는 이 정보를 무시할 수 있습니다.

val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    locationListening = true
}

사용자를 추적에서 해제합니다

사용자는 추적을 완전히 거부할 수 있으며, 이 경우 Amplitude는 사용자의 이벤트나 브라우징 기록을 전혀 추적하지 않습니다. OptOut은 사용자의 개인정보 보호 요청을 이행할 수 있는 방법을 제공합니다.

optOut가 true인 동안 Amplitude는 이벤트를 저장하거나 전송하지 않습니다.

// At initialization
val amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    optOut = true
}
// At runtime
amplitude.optOut = true
amplitude.optOut = false // Re-enable tracking

푸시 알림 이벤트

Android SDK를 사용하여 클라이언트 측에 푸시 알림 이벤트를 전송하지 마십시오. 사용자가 앱을 열어 Amplitude SDK를 초기화해야 SDK가 이벤트를 전송할 수 있기 때문에, SDK는 다음에 사용자가 앱을 열 때까지 Amplitude 서버에 이벤트를 전송하지 않습니다. 이로 인해 데이터 지연이 발생할 수 있습니다.

import com.amplitude.common.Logger
import com.amplitude.core.LoggerProvider
class sampleLogger : Logger {
override var logMode: Logger.LogMode
 get() = Logger.LogMode.DEBUG
 set(value) {}
 override fun debug(message: String) {
 TODO("Handle debug message here")
 }
 override fun error(message: String) {
 TODO("Handle error message here")
 }
 override fun info(message: String) {
 TODO("Handle info message here")
 }
 override fun warn(message: String) {
 TODO("Handle warn message here")
 }
}
class sampleLoggerProvider : LoggerProvider {
 override fun getLogger(amplitude: com.amplitude.core.Amplitude): Logger {
 return sampleLogger()
 }
}
amplitude = Amplitude(AMPLITUDE_API_KEY, applicationContext) {
    loggerProvider = sampleLoggerProvider()
}

다중 인스턴스

val amplitude1 = Amplitude("api-key-1", applicationContext) {
    instanceName = "one"
}
val amplitude2 = Amplitude("api-key-2", applicationContext) {
    instanceName = "two"
}

오프라인 모드

버전 1.13.0부터 Amplitude Android Kotlin SDK는 오프라인 모드를 지원합니다. SDK는 이벤트를 추적할 때마다 네트워크 연결을 확인합니다. 장치가 네트워크에 연결되어 있는 경우 SDK는 플러시를 예약합니다. 그렇지 않은 경우 이벤트를 스토리지에 저장합니다. 또한 SDK는 네트워크 연결의 변경 사항을 수신하고 장치가 다시 연결될 때 저장된 모든 이벤트를 플러시합니다.

이 기능을 활성화하려면 AndroidManifest.xml에 ACCESS_NETWORK_STATE 권한을 추가하십시오. 그렇지 않으면 SDK는 flushIntervalMillis 및 flushQueueSize에 따라 이벤트를 플러시합니다.

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

또한 자신만의 오프라인 로직을 구현할 수도 있습니다.

1. 기본 오프라인 로직을 비활성화하려면 config.offline을 AndroidNetworkConnectivityCheckerPlugin.Disabled로 설정하십시오.
2. 직접 config.offline토글하십시오.