> 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/ios/event-tracking/ios-track-screen.md).

# Screen Tracking

The Hackle SDK collects screen information at the ViewController level. For apps using a single ViewController structure or [SwiftUI](https://developer.apple.com/swiftui/), 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 iOS SDK 2.59.0 and above.
{% endhint %}

The `setCurrentScreen(screen)` method accepts the screen name and screen class name as arguments to track the screen.

* The minimum tracking time unit is 1 second.
* `$engagement` for pages changed within 1 second is not measured.

<table><thead><tr><th width="150">Parameter</th><th width="120">Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td><code>string</code></td><td>Required. The name of the current screen.</td></tr><tr><td>className</td><td><code>string</code></td><td>Required. If you do not need a separate class name, you can enter the same value as name.</td></tr></tbody></table>

{% 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 Swift UI, it is recommended to track screens when both `onAppear` and `onChange` events occur.

{% tabs %}
{% tab title="Swift" %}

```swift
let screen = Screen.builder(name: "screenName", className: "screenName")
    .build()

Hackle.app()?.setCurrentScreen(screen: screen)
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
HackleScreen *screen = [[[HackleScreenBuilder alloc] initWithName:@"screenName"
                                                         className:@"screenName"] build];
[[Hackle app] setCurrentScreenWithScreen:screen];
```

{% endtab %}

{% tab title="SwiftUI" %}

```swift
struct MainView: View {
    @Environment(\.scenePhase) var scenePhase

    let screen = Screen.builder(name: "screenName", className: "screenName")
      .build()

    var body: some View {
        VStack {
            Text("메인 화면")
        }
        .onAppear {
            // 뷰가 나타날 때 화면 추적
            Hackle.app()?.setCurrentScreen(screen: screen)
        }
        .onChange(of: scenePhase) { oldPhase, newPhase in
            // 백그라운드 -> 포그라운드 전환될 때 화면 추적
            // 전환될 때 앱의 화면이 변하는 케이스가 없으면 호출하지 않아도 무방합니다.
            if newPhase == .active {
                Hackle.app()?.setCurrentScreen(screen: screen)
            }
        }
    }
}
```

{% endtab %}
{% endtabs %}

### Property

The Hackle SDK supports adding properties to Event objects.

* A maximum of 64 properties can be added to an event object.

<table><thead><tr><th width="133.04296875">Category</th><th width="127.60546875">Type</th><th>Constraints</th></tr></thead><tbody><tr><td>Property Key</td><td><code>string</code></td><td><ul><li>Character limit is 128 characters.</li><li>Case-insensitive.</li><li>For example, AGE and age are recognized as the same Property Key.</li></ul></td></tr><tr><td>Property Value</td><td><code>boolean</code>, <code>string</code>, <code>number</code>, <code>array</code></td><td><ul><li>For string type, the character limit is 1024 characters.</li><li>String type is case-sensitive.</li><li>For example, APPLE and apple are recognized as different Property Values.</li><li>For number type, up to 15 integer digits and up to 6 decimal places are supported.</li></ul></td></tr></tbody></table>

#### Example

{% tabs %}
{% tab title="Swift" %}

```swift
let screen = Screen.builder(name: "screenName", className: "screenName")
    .property("key", "value")
    .build()

Hackle.app()?.setCurrentScreen(screen: screen)
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
HackleScreen *screen = [[[[HackleScreenBuilder alloc] initWithName:@"screenName"
                                                          className:@"screenName"]
                          property:@"key" value:@"value"]
                         build];
[[Hackle app] setCurrentScreenWithScreen:screen];
```

{% endtab %}
{% endtabs %}

## Disable automaticScreenTracking

By default, `automaticScreenTracking` is enabled in the SDK. If you do not want automatic screen information collection at the ViewController 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="Swift" %}

```swift
let config = HackleConfigBuilder()
  .automaticScreenTracking(false)
  .build()

Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY, config: config) {
    // SDK ready to use.
}
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
HackleConfigBuilder *builder = [[HackleConfigBuilder alloc] init];
[builder automaticScreenTracking:false];
HackleConfig *config = [builder build];

[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:config completion:^{
    // 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/ios/event-tracking/ios-track-screen.md?ask=<question>
```

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.