> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/common/growth/analytics/user-behavior.md).

# 사용자 행동 기록

`Analytics`는 사용자의 행동을 기록하고 분석하기 위한 객체예요. 화면 진입, 버튼 클릭, 컴포넌트 노출 등의 이벤트를 수집해서 서비스 개선과 사용자 흐름 분석에 활용할 수 있어요.

{% hint style="info" %}
**사전 요구사항을 확인해 주세요**

* SDK 버전 **`v1.0.3`** 이상이어야 해요.
* 샌드박스나 QR 테스트 환경에서는 이벤트가 수집되지 않아요. 라이브 환경에서만 수집돼요.
* 서비스 런칭 **다음 날(+1일)** 부터 콘솔 **분석 > 이벤트** 화면에서 데이터를 확인할 수 있어요.
  {% endhint %}

자세한 로깅 전략과 베스트 프랙티스는 로그(이벤트) 가이드를 참고해 주세요.

***

**시그니처**

```typescript
Analytics: {
    readonly init: typeof init;
    readonly Screen: typeof LoggingScreen;
    readonly Press: import("react").ForwardRefExoticComponent<import(".").LoggingPressProps & import("react").RefAttributes<unknown>>;
    readonly Impression: typeof LoggingImpression;
    readonly Area: typeof LoggingArea;
}
```

**프로퍼티**

* inittypeof init

  분석 기능을 시작할 때 설정을 적용하는 함수예요. 앱 초기화 시점에 한 번 호출해야 해요.
* Presstypeof LoggingPress

  버튼이나 터치 가능한 컴포넌트의 클릭 이벤트 로그를 남기는 컴포넌트예요.
* Impressiontypeof LoggingImpression

  사용자가 화면에 특정 컴포넌트를 실제로 보았는지 판단하고 로그를 남기는 컴포넌트예요.
* Areatypeof LoggingArea

  여러 컴포넌트를 하나의 영역으로 묶어서 분석할 수 있는 컴포넌트예요.

***

### 분석 초기화하기

**`Analytics.init`**

`Analytics.init`은 분석 기능을 시작할 때 설정을 적용하는 함수예요. `Analytics.Press`, `Analytics.Impression`, `Analytics.Area`를 사용하기 전에 반드시 호출해야 해요.

**시그니처**

```typescript
declare function init(options: AnalyticsConfig): void;
```

**파라미터**

* **options** · 필수 · `AnalyticsConfig`

  분석 기능을 사용하기 위한 설정 객체예요.

***

### 클릭 이벤트 기록하기

**`Analytics.Press`**

`Analytics.Press`는 사용자가 요소를 눌렀을 때 클릭 이벤트를 기록하는 컴포넌트예요. 버튼 클릭, 구매 액션처럼 사용자 인터랙션이 발생하는 지점을 감싸서 사용해요.

{% hint style="info" %}
**클릭 이벤트는 라이브 환경에서만 수집돼요**

샌드박스나 QR 테스트 환경에서는 클릭 이벤트가 실제로 쌓이지 않아요. 콘솔에서 데이터를 확인할 수 있는 시점은 **런칭 다음 날(+1일)** 이에요.
{% endhint %}

**시그니처**

```typescript
LoggingPress: import('react').ForwardRefExoticComponent<LoggingPressProps & import('react').RefAttributes<unknown>>;
```

**예제**

```tsx
import { Analytics } from '@apps-in-toss/framework';
import { Button } from 'react-native';

// 클릭 가능한 요소의 클릭 이벤트를 자동으로 수집해요.
function TrackElements() {
  return (
    <Analytics.Press>
      <Button label="Press Me" />
    </Analytics.Press>
  );
}
```

***

### 노출 이벤트 기록하기

**`Analytics.Impression`**

`Analytics.Impression`은 요소가 뷰포트에 표시되었는지 감지하고 노출 이벤트를 기록하는 컴포넌트예요. 스크롤 아래에 위치한 상품, 배너, 카드 등의 노출 여부를 추적할 때 사용해요.

**시그니처**

```typescript
function LoggingImpression({
  enabled,
  impression: impressionType,
  ...props
}: LoggingImpressionProps): import('react/jsx-runtime').JSX.Element;
```

**예제**

```tsx
import { Analytics } from '@apps-in-toss/framework';

// 영역 안의 노출 정보를 자동으로 수집해요.
function TrackElements() {
  return (
    <Analytics.Impression>
      <Text>Hello</Text>
    </Analytics.Impression>
  );
}
```

***

### 영역 단위로 묶어 기록하기

**`Analytics.Area`**

`Analytics.Area`는 여러 컴포넌트를 하나의 영역으로 묶어 노출과 클릭 이벤트를 함께 기록하는 컴포넌트예요. 지정한 영역이 노출되거나 클릭됐을 때 하나의 로그로 집계할 수 있어요.

**시그니처**

```typescript
function LoggingArea({
  children,
  params: _params,
  ...props
}: LoggingAreaProps): import('react/jsx-runtime').JSX.Element;
```

**예제**

```tsx
import { Analytics } from '@apps-in-toss/framework';
import { View, Text } from 'react-native';

// 영역 안의 노출이나 클릭 정보를 자동으로 수집해요.
function TrackElements() {
  return (
    <Analytics.Area>
      <View>
        <Text>Hello</Text>
        <Text>World!</Text>
      </View>
    </Analytics.Area>
  );
}
```


---

# 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://developers-apps-in-toss.toss.im/documentation/common/growth/analytics/user-behavior.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.