# 사용자 화면 추적

Hackle SDK는 ViewController 단위로 화면 정보를 수집합니다. ViewController를 1개만 사용하는 구조의 앱이거나 [SwiftUI](https://developer.apple.com/swiftui/) 를 사용하는 경우 자동으로 화면 정보를 수집하기 어렵습니다.

`$page_view` 및 `$engagement` 이벤트를 정상적으로 수집하려면, 화면이 변경될 때마다 setCurrentScreen 메소드를 직접 호출해야 합니다.

## setCurrentScreen

{% hint style="info" %}
iOS SDK 2.59.0 이상 버전에서 정식으로 지원하는 기능입니다.
{% endhint %}

`setCurrentScreen(screen)` 메소드에 인자로 화면 명과 화면의 클래스 명을 인자로 받아 화면을 추적합니다.

* 화면 추적의 최소 단위 시간은 1초 입니다.
* 1초 이내에 변경된 페이지의 `$engagement` 는 측정되지 않습니다.

<table><thead><tr><th width="150">파라미터</th><th width="120">타입</th><th>설명</th></tr></thead><tbody><tr><td>name</td><td><code>string</code></td><td>필수. 현재 화면의 명입니다.</td></tr><tr><td>className</td><td><code>string</code></td><td>필수. 별도의 클래스 명을 남기지 않을 경우 name과 동일한 값을 기입하면 됩니다.</td></tr></tbody></table>

{% hint style="warning" %}
동일 화면에 대한 화면 추적은 할 수 없습니다.

이전 화면과 동일한(name과 className이 모두 동일한) Screen으로 `setCurrentScreen`을 호출한 경우 화면 전환이 되지 않은 것으로 인식되어 아무런 동직을 하지 않습니다.

* `$page_view`, `$engagement`가 호출되지 않습니다.
  {% endhint %}

#### 예시

Swift UI를 사용하는 경우 `onAppear` 와 `onChange`가 발생할 때 모두 화면 추적을 하는 것을 추천합니다.

{% 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)

핵클 SDK는 이벤트(Event) 객체에 속성을 추가할 수 있도록 지원합니다.

* 이벤트 객체에 추가 가능한 속성 개수는 최대 64개입니다.

<table><thead><tr><th width="133.04296875">구분</th><th width="127.60546875">타입</th><th>제약사항</th></tr></thead><tbody><tr><td>속성 명(key)</td><td><code>string</code></td><td><ul><li>글자수 제한은 128자입니다. (128 characters)</li><li>대소문자를 구분하지 않습니다.</li><li>예를 들어 AGE와 age는 동일한 속성명으로 인식합니다.</li></ul></td></tr><tr><td>속성 값(value)</td><td><code>boolean</code>, <code>string</code>, <code>number</code>, <code>array</code></td><td><ul><li>string 타입인 경우 글자수 제한은 1024자입니다.<br>(1024 characters)</li><li>string 타입은 대소문자를 구분합니다.</li><li>예를 들어 APPLE과 apple은 서로 다른 속성값으로 인식합니다.</li><li>number 타입인 경우 정수 최대 15자리, 소수점 최대 6자리를<br>지원합니다.</li></ul></td></tr></tbody></table>

#### 예시

{% 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 %}

## automaticScreenTracking 비활성화

SDK에서는 기본적으로 `automaticScreenTracking`이 활성화되어 있습니다. ViewController 단위의 자동 화면 정보 수집을 원하지 않는 경우 `automaticScreenTracking`를 비활성화 해야 합니다.

SDK를 초기화 할 때 `automaticScreenTracking`을 설정할 수 있습니다.

{% hint style="danger" %}
`automaticScreenTracking`이 활성화 된 상태에서 `setCurrentScreen`를 통해 수동으로 화면 수집을 하는 경우, `$page_view`와 `$engagement`가 과수집 되거나 의도하지 않은 속성으로 수집될 수 있습니다.

**수동으로 화면 정보를 수집하는 경우 `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: 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/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.