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

# Screen Tracking

{% hint style="info" %}
For screen navigation in React Native, refer to the following React Native developer documentation.

* [React Native: Navigating Between Screens](https://reactnative.dev/docs/navigation)
* [React Navigation: Screen tracking for analytics](https://reactnavigation.org/docs/screen-tracking/)
  {% endhint %}

React Native uses a single Activity/ViewController structure by default, making automatic screen information collection difficult.

To properly collect `$page_view` and `$engagement` events, you must directly call the `setCurrentScreen` method every time the screen changes.

## setCurrentScreen

{% hint style="info" %}
This feature is supported in React Native SDK version 3.30.0 and above.
{% endhint %}

Track screens using the `setCurrentScreen(screen)` method.

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

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

{% hint style="warning" %}
Screen tracking for the same screen is not possible.

If `setCurrentScreen` is called with the same Screen (where both name and screenClass are identical) as the previous screen, it is recognized as no screen transition and nothing happens.

* `$page_view` and `$engagement` are not called.
  {% endhint %}

#### Example

{% tabs %}
{% tab title="기본" %}

```javascript
hackleClient.setCurrentScreen({
    name: screenName,
    screenClass: className,
});
```

{% endtab %}

{% tab title="@react-navigation/native" %}

```javascript
import * as React from 'react';
import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import { createInstance } from '@hackler/react-native-sdk';

export const hackleClient = createInstance('YOUR_SDK_KEY');

export default function App() {
  const navigationRef = useNavigationContainerRef();
  const routeNameRef = React.useRef<string | undefined>();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        const routeName = navigationRef.current?.getCurrentRoute()?.name;
        routeNameRef.current = routeName;

        if (initialRouteName) {
          hackleClient.setCurrentScreen({ name: routeName, screenClass: routeName });
        }
      }}
      onStateChange={() => {
        const previousRouteName = routeNameRef.current;
        const currentRouteName = navigationRef.current?.getCurrentRoute()?.name;

        if (currentRouteName && previousRouteName !== currentRouteName) {
          hackleClient.setCurrentScreen({ name: currentRouteName, screenClass: currentRouteName });
        }

        routeNameRef.current = currentRouteName;
      }}
    >
      {/* Navigator 구성 */}
    </NavigationContainer>
  );
}
```

{% endtab %}
{% endtabs %}

### Property

The Hackle SDK supports adding properties to Event objects.

* The maximum number of properties that can be added to an event object is 64.

<table><thead><tr><th width="150">Type</th><th width="200">Type</th><th>Constraints</th></tr></thead><tbody><tr><td>Property Key (key)</td><td><code>string</code></td><td><ul><li>Character limit is 128 characters.</li><li>Case-insensitive. For example, amount and AMOUNT are recognized as the same key.</li></ul></td></tr><tr><td>Property Value (value)</td><td><code>boolean</code>, <code>string</code>, <code>number</code>, <code>array</code></td><td><ul><li>For string type, character limit is 1024 characters.</li><li>For number type, a maximum of 15 integer digits and 6 decimal places are supported.</li></ul></td></tr></tbody></table>

#### Example

```javascript
hackleClient.setCurrentScreen({
    name: screenName,
    screenClass: className,
    properties: {
        productId: "12345",
        category: "Electronics",
        price: 99000,
        inStock: true,
    },
});
```

## Disabling automaticScreenTracking

By default, `automaticScreenTracking` is enabled in the SDK. If you do not want automatic screen information collection at the Activity/ViewController level, you must disable `automaticScreenTracking`.

You can configure `automaticScreenTracking` when initializing the SDK.

{% hint style="danger" %}
If you manually collect screen information via `setCurrentScreen` while `automaticScreenTracking` is enabled, `$page_view` and `$engagement` may be over-collected or collected with unintended properties.

**When manually collecting screen information, it is recommended to disable `automaticScreenTracking`.**
{% endhint %}

#### Example

```javascript
import { HackleApp } from '@hackler/react-native-sdk';

export const hackleClient = createInstance('YOUR_SDK_KEY', {
  automaticScreenTracking: false,
});
```


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/en/development-guide/react-native/event-tracking/react-native-track-screen.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.