> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/development-guide/android/event-tracking/android-track-screen.md). # Screen Tracking The Hackle SDK collects screen information at the Activity level.\ For apps using a SAA (Single Activity Architecture) or [Compose UI](https://developer.android.com/develop/ui/compose/architecture), it is difficult to automatically collect screen information. To properly collect `$page_view` and `$engagement` events, you must call the `setCurrentScreen` method manually whenever the screen changes. ## setCurrentScreen {% hint style="info" %} This feature is officially supported in Android SDK 2.64.0 and above. {% endhint %} Use the `setCurrentScreen(screen)` method to track screens. * The minimum tracking time unit is 1 second. * `$engagement` for pages changed within 1 second is not measured.
ParameterTypeRequiredDescription
namestringRequiredThe name of the current screen.
classNamestringRequiredIf you do not need a separate class name, you can enter the same value as name.
{% hint style="warning" %} Screen Tracking for the same screen is not supported. If `setCurrentScreen` is called with a Screen that is identical to the previous screen (both name and className are the same), it is recognized as no screen transition and no action is taken. * `$page_view` and `$engagement` are not triggered. {% endhint %} #### Example When using Compose UI, it is recommended to track screens when the `ON_RESUME` event occurs. {% tabs %} {% tab title="Kotlin" %} ```kotlin val hackleApp = Hackle.app val screen = Screen.builder("screenName", "className") .build() Hackle.app.setCurrentScreen(screen) ``` {% endtab %} {% tab title="Java" %} ```java HackleApp hackleApp = HackleApp.getInstance(); Screen screen = Screen.builder("screenName", "className") .build(); hackleApp.setCurrentScreen(screen); ``` {% endtab %} {% tab title="Compose UI" %} ```kotlin @Composable fun TrackScreen(screenName: String, className: String) { val lifecycleOwner = LocalLifecycleOwner.current DisposableEffect(lifecycleOwner, screenName, className) { val observer = LifecycleEventObserver { _, event -> // 뷰가 나타날 때 & 백그라운드 -> 포그라운드 전환될 때 화면 추적 if (event == Lifecycle.Event.ON_RESUME) { val screen = Screen.builder(screenName, className).build() hackleApp.setCurrentScreen(screen) } } lifecycleOwner.lifecycle.addObserver(observer) onDispose { lifecycleOwner.lifecycle.removeObserver(observer) } } } @Composable fun MainScreen() { TrackScreen("Main", "MainScreen") } ``` {% endtab %} {% endtabs %} ### Property The Hackle SDK supports adding properties to Event objects. * A maximum of 64 properties can be added to an event object.
CategoryTypeConstraints
Property Keystring
  • Character limit is 128 characters.
  • Case-insensitive.
  • For example, AGE and age are recognized as the same Property Key.
Property Valueboolean, string, number, array
  • For string type, the character limit is 1024 characters.
  • String type is case-sensitive.
  • For example, APPLE and apple are recognized as different Property Values.
  • For number type, up to 15 integer digits and up to 6 decimal places are supported.
#### Example {% tabs %} {% tab title="Kotlin" %} ```kotlin val hackleApp = Hackle.app val screen = Screen.builder("screenName", "className") .property("key", "value") .build() Hackle.app.setCurrentScreen(screen) ``` {% endtab %} {% tab title="Java" %} ```java HackleApp hackleApp = HackleApp.getInstance(); Screen screen = Screen.builder("screenName", "className") .property("key", "value") .build(); hackleApp.setCurrentScreen(screen); ``` {% endtab %} {% endtabs %} ## Disable automaticScreenTracking By default, `automaticScreenTracking` is enabled in the SDK.\ If you do not want automatic screen information collection at the Activity level, you must disable `automaticScreenTracking`. You can configure `automaticScreenTracking` when initializing the SDK. {% hint style="danger" %} If `automaticScreenTracking` is enabled and you manually collect screens via `setCurrentScreen`, `$page_view` and `$engagement` may be over-collected or collected with unintended properties. **If you manually collect screen information, it is recommended to disable `automaticScreenTracking`.** {% endhint %} #### Example {% tabs %} {% tab title="Kotlin" %} ```kotlin import io.hackle.android.Hackle import io.hackle.android.HackleConfig import io.hackle.android.initialize val config = HackleConfig.builder() .automaticScreenTracking(false) .build() Hackle.initialize(applicationContext, YOUR_APP_SDK_KEY, config) { // SDK ready to use. } ``` {% endtab %} {% tab title="Java" %} ```java import io.hackle.android.HackleApp; import io.hackle.android.HackleConfig; HackleConfig config = HackleConfig.builder() .automaticScreenTracking(false) .build(); HackleApp.initializeApp(getApplicationContext(), YOUR_APP_SDK_KEY, config, () -> { // SDK ready to use. }); ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hackle.io/en/development-guide/android/event-tracking/android-track-screen.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.