> 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/event-management/bot-traffic.md).

# 봇 트래픽 수집

{% hint style="warning" %}
**이 정책은 2026-11-01 부터 적용됩니다.** 봇 트래픽 차단을 원하지않는 경우 핵클 팀에 차단 제외 요청해주세요.
{% endhint %}

### 1. 요약 <a href="#summary" id="summary"></a>

핵클은 일반적으로 알려진 봇으로 판별된 트래픽에서 발생한 이벤트를 **수집하지 않습니다.**

기본 차단 정책 외에 조절할 수 있는 항목이 두 가지 있습니다.

| 하고 싶은 일                                   | 방법                    |
| ----------------------------------------- | --------------------- |
| 핵클 기본 차단 목록 외에, 특정 User Agent를 **추가로 차단** | 대시보드 > 이벤트 관리에서 직접 설정 |
| 기본 차단되는 크롤러 중 일부를 **수집하도록 허용**            | 핵클 팀에 요청              |

{% hint style="warning" %}
**차단된 이벤트는 복구할 수 없습니다.** 봇 필터링은 수집 단계에서 이벤트를 버리는 방식이어서 나중에 설정을 바꿔도 차단된 기간의 데이터는 되살릴 수 없습니다.
{% endhint %}

***

### 2. 기본 차단 (핵클 일괄 적용) <a href="#default-blocking-hackle-wide" id="default-blocking-hackle-wide"></a>

#### 왜 차단하나요 <a href="#why-block" id="why-block"></a>

봇 트래픽은 대부분 실제 사용자의 행동이 아니기 때문에 그대로 쌓이면 다음 문제가 생깁니다.

* **불필요한 비용** : 봇이 일으킨 이벤트가 과금됩니다.
* **지표 왜곡** : 방문자 수, 페이지뷰, 세션 수가 실제보다 부풀려집니다.
* **A/B 테스트 오염** : 봇은 전환하지 않고 노출만 만들기 때문에 전환율이 실제보다 낮게 측정되고 실험 판단이 흔들립니다.

#### 무엇을 봇으로 판별하나요 <a href="#bot-detection-criteria" id="bot-detection-criteria"></a>

핵클은 알려진 크롤러·스크래퍼·모니터링 봇의 User Agent 목록을 기준으로 봇을 판별합니다.

차단 대상 목록은 핵클이 주기적으로 갱신하며 워크스페이스별로 다르게 적용되지 않습니다.

{% hint style="info" %}
**서버 SDK/API는 봇 필터링이 적용되지 않습니다.** 서버 환경에서는 요청의 User Agent를 핵클이 알 수 없기 때문입니다. 서버에서 전송하는 이벤트는 기존과 동일하게 모두 수집됩니다.
{% endhint %}

| SDK                                   | 기본 차단 | User Agent 추가 차단 |
| ------------------------------------- | ----- | ---------------- |
| Web SDK (js, react)                   | 적용    | 가능               |
| App SDK (iOS, Android, RN, Flutter 등) | 미적용   | 가능               |
| Server SDK (Java, Node, Python 등)     | 미적용   | 불가               |
| API                                   | 미적용   | 불가               |

#### 적용 시점과 기존 데이터 <a href="#timing-and-existing-data" id="timing-and-existing-data"></a>

* 2026-11-01 **이후 발생하는 이벤트부터** 적용됩니다. 소급 적용되지 않습니다.
* 그 이전에 이미 수집된 봇 이벤트는 **그대로 유지됩니다.** 삭제되지 않습니다.
* 2026-11-01 전후로 지표에 **단절(step change)** 이 생길 수 있습니다. 봇 비중이 높았던 워크스페이스일수록 방문자 수·페이지뷰가 눈에 띄게 줄어 보일 수 있습니다.

***

### 3. User Agent로 추가 차단하기 <a href="#block-by-user-agent" id="block-by-user-agent"></a>

핵클 기본 차단 목록에 없는 트래픽도 직접 차단할 수 있습니다. 사내 모니터링 도구, 자체 제작 스크래퍼, 부하 테스트 스크립트처럼 **고객사만 아는 봇**을 걸러낼 때 사용합니다.

#### 설정 방법 <a href="#setup" id="setup"></a>

1. 대시보드에서 **이벤트 관리**로 이동해 설정할 이벤트를 선택합니다.
2. **이벤트 상세** 화면에서 **수집 제한** 영역을 찾습니다.
3. 차단할 User Agent 조건을 입력합니다. 텍스트 > 다음을 포함하는을 사용하시면 됩니다.
4. 저장하면 즉시 적용됩니다.

#### 알아두어야 할 점 <a href="#bot-block-notes" id="bot-block-notes"></a>

* 설정은 **이벤트 단위**입니다. 여러 이벤트를 차단하려면 각 이벤트에서 따로 설정해야 합니다. 자동 수집되는 $page\_view, $session\_start, $session\_end에 우선적으로 적용하는 것을 권장합니다.
* 설정 **이후에 발생하는 이벤트부터** 적용됩니다. 이미 수집된 이벤트는 삭제되지 않습니다.
* 조건에 걸린 이벤트는 수집되지 않으므로 **과금되지 않고, 복구할 수도 없습니다.**

{% hint style="info" %}
User Agent 조건을 너무 넓게 잡으면 실제 사용자의 이벤트까지 차단될 수 있습니다. 설정 전에 이벤트 조회에서 `userAgent` 속성으로 조건에 걸리는 트래픽을 먼저 확인해 보세요
{% endhint %}

***

### 4. 특정 크롤러 수집 허용 요청하기 <a href="#request-crawler-allowlist" id="request-crawler-allowlist"></a>

기본 차단 대상 중에 **측정하고 싶은 트래픽**이 있다면 핵클 팀(<support@hackle.io>)에 요청해 주세요.

#### 어떤 경우에 필요한가요 <a href="#when-needed" id="when-needed"></a>

* **AI 에이전트 트래픽** : ChatGPT, Perplexity 등 생성형 AI 크롤러의 방문을 유입 채널로 측정하려는 경우
* **검색엔진 크롤러** : 검색엔진이 서비스의 어떤 페이지를 수집해 가는지 확인하려는 경우, 검색 색인 요청에 따라 수집이 잘 되고있는지 확인하려는 경우
* **파트너사 연동 봇** : 비즈니스상 의미 있는 자동화 트래픽

#### 요청 방법 <a href="#how-to-request" id="how-to-request"></a>

요청할 때 아래 정보를 함께 전달해 주세요.

* 워크스페이스 이름
* 수집을 허용할 크롤러의 User Agent 또는 서비스 이름
* 허용이 필요한 이유

#### 비용 <a href="#cost" id="cost"></a>

허용된 크롤러의 이벤트는 수집되는 순간부터 일반 이벤트와 동일하게 집계되고 과금됩니다.

***

### 5. 자주 묻는 질문 <a href="#faq" id="faq"></a>

**Q. 기본 차단을 워크스페이스에서 끌 수 있나요?** 없습니다. 기본 차단은 핵클이 모든 워크스페이스에 일괄 적용합니다. 특정 크롤러만 예외로 허용하려면 위의 방법으로 요청해 주세요.

**Q. 봇 이벤트도 과금되나요?** 차단된 이벤트는 수집 자체가 되지 않으므로 과금 대상이 아닙니다. 허용 요청으로 수집하게 된 이벤트는 일반 이벤트와 동일하게 과금됩니다.

**Q. 차단된 데이터를 나중에 볼 수 있나요?** 없습니다. 수집 단계에서 버려지기 때문에 복구할 수 없습니다.

**Q. 내 워크스페이스에 봇 트래픽이 얼마나 되는지 알 수 있나요?** 이벤트 조회나 데이터 분석에서 User Agent 속성을 활용하여 측정할 수 있습니다.

**Q. A/B 테스트 분배에도 영향이 있나요?** 분배은 되지만, 해당 이벤트가 저장되지 않아, 영향은 없습니다.

**Q. User Agent 추가 차단 설정을 되돌리면 그동안 차단된 데이터가 복구되나요?** 아니요. 설정을 해제하면 그 이후 이벤트부터 다시 수집되며 차단된 기간의 데이터는 복구되지 않습니다.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/event-management/bot-traffic.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
