> 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/api-and-sdk-en/unity/sentry.md).

# Sentry Integration

## Sentry integration

The AIT SDK [Sentry Unity SDK](https://docs.sentry.io/platforms/unity/)and supports automatic integration. If Sentry is installed, it automatically injects AIT platform context (device ID, environment, deployment ID, etc.) into crash and error events.

**Zero-cost opt-in**: If the Sentry SDK is not installed in the project, the related code is not compiled at all. There is no runtime overhead and no compile errors.

***

### Installation

#### Method 1: Unity menu (recommended)

1. In the Unity Editor, `AIT` > `Install Sentry SDK`click.
2. The Package Manager automatically installs Sentry Unity SDK 4.1.0.

{% hint style="info" %}
If the Sentry SDK is already installed, the menu is disabled.
{% endhint %}

#### Method 2: Add manifest.json directly

`Packages/manifest.json`can be added directly:

```json
{
  "dependencies": {
    "io.sentry.unity": "https://github.com/getsentry/unity.git#4.1.0"
  }
}
```

#### Supported versions

* **Minimum**: `io.sentry.unity` 4.0.0
* **Recommended**: 4.1.0 or later

***

### Configuration

Only the Sentry SDK itself needs to be configured. AIT integration works automatically without separate setup.

#### DSN setup

In the Unity Editor, `Tools` > `Sentry`open **DSN**and enter it.

The DSN is in your Sentry project’s `Settings > Client Keys (DSN)`You can check it in. The setting is saved in `Assets/Resources/Sentry/SentryOptions.asset`.

***

### Automatically injected AIT context

When the Sentry SDK is active, the AIT SDK automatically injects the following context.

#### Tags

| Tag                    | Description            | Example                 |
| ---------------------- | ---------------------- | ----------------------- |
| `ait.sdk_version`      | AIT SDK version        | `1.11.2`                |
| `ait.unity_version`    | Unity engine version   | `6000.3.3f1`            |
| `ait.device_id`        | Unique device ID       | `abc123...`             |
| `ait.platform_os`      | Platform OS            | `iOS`, `Android`        |
| `ait.locale`           | Device locale          | `ko-KR`                 |
| `ait.toss_app_version` | Toss app version       | `5.80.0`                |
| `ait.environment`      | Production environment | `production`, `staging` |
| `ait.deployment_id`    | Deployment ID          | `deploy-xyz`            |
| `ait.current_scene`    | Current Unity scene    | `MainMenu`              |

#### User

| Field     | Value                               |
| --------- | ----------------------------------- |
| `User.Id` | AIT device ID (`AIT.GetDeviceId()`) |

#### Context Object

`apps_in_toss` A custom context object named is added:

```json
{
  "sdk_version": "1.11.2",
  "unity_version": "6000.3.3f1",
  "device_id": "abc123...",
  "platform_os": "iOS",
  "locale": "ko-KR",
  "toss_app_version": "5.80.0",
  "environment": "production",
  "deployment_id": "deploy-xyz"
}
```

#### Breadcrumbs

A breadcrumb is automatically recorded every time a Unity scene is loaded:

| Field    | Value                                          |
| -------- | ---------------------------------------------- |
| message  | `Scene loaded: MainMenu`                       |
| category | `scene`                                        |
| level    | `Info`                                         |
| data     | `scene_name`, `scene_build_index`, `load_mode` |

***

### CI/CD environment variables

#### Sentry SDK core (build-time auto injection)

When building WebGL, the AIT SDK `SENTRY_DSN` from the environment variable `SentryOptions.asset`is automatically generated.

| Variable             | Purpose                                    | Example                     |
| -------------------- | ------------------------------------------ | --------------------------- |
| `SENTRY_DSN`         | DSN → `SentryOptions.asset` Auto-generated | `https://key@sentry.io/123` |
| `SENTRY_ENVIRONMENT` | Environment identifier (auto-injected)     | `production`, `staging`     |
| `SENTRY_RELEASE`     | Release version (auto-injected)            | `my-app@1.0.0`              |

#### sentry-cli (build time)

Used when uploading debug symbols and sourcemaps. Configure it in the CI/CD pipeline.

| Variable            | Purpose           | Example      |
| ------------------- | ----------------- | ------------ |
| `SENTRY_AUTH_TOKEN` | API auth token    | `sntrys_...` |
| `SENTRY_ORG`        | Organization slug | `my-org`     |
| `SENTRY_PROJECT`    | Project slug      | `unity-game` |

#### Example CI/CD pipeline

```yaml
# GitHub Actions
env:
  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  SENTRY_ORG: my-org
  SENTRY_PROJECT: unity-game
```

***

### How it works

#### Conditional compilation

The Sentry integration uses Unity's `versionDefines`to implement conditional compilation:

1. `io.sentry.unity` When 4.0.0 or later is installed, `AIT_SENTRY_AVAILABLE` the define is automatically enabled.
2. `AppsInToss.Sentry` assembly's `defineConstraints`to `AIT_SENTRY_AVAILABLE`are set.
3. If the Sentry SDK is not installed, the entire assembly is excluded from compilation.

#### IL2CPP stripping protection

Triple protection is applied so code is not stripped from WebGL (IL2CPP) builds:

| Protection method                | Role                                                          |
| -------------------------------- | ------------------------------------------------------------- |
| `[assembly: AlwaysLinkAssembly]` | Prevents the assembly itself from being removed by the linker |
| `[Preserve]`                     | Preserves individual types/methods                            |
| `link.xml`                       | Declares preservation of all types in the assembly            |

#### Unity 6+ IL2CPP stack traces

In Unity 6 and later, C# file/line information is automatically enabled in IL2CPP stack traces for WebGL builds. This lets you pinpoint crash locations in Sentry down to the exact source code line.

***

### Troubleshooting

<details>

<summary>Sentry events are not being sent</summary>

1. `Tools > Sentry`Please make sure the DSN is configured correctly.
2. In the console, `[AIT:Sentry] Sentry is not enabled` if you see this message, the Sentry SDK is disabled.
3. For WebGL CI/CD, `SENTRY_DSN` if you set the environment variables, at build time `SentryOptions.asset`it is automatically generated.

</details>

<details>

<summary>AIT tags are missing in IL2CPP builds</summary>

The integration code may have been removed by IL2CPP stripping.

1. `Assets/link.xml`Please make sure it includes the following:

```xml
<linker>
    <assembly fullname="AppsInToss.Sentry" preserve="all"/>
</linker>
```

2. `Library/Bee/artifacts/WebGL/` Delete the folder and run a clean build.

</details>

<details>

<summary>Some AIT context values are shown as `unavailable`</summary>

This means an AIT platform API call failed. Each API fails independently, and the remaining context is injected normally.

* Some APIs may not be supported in the mock bridge environment.
* In case of a network timeout, without retry `unavailable`is set to.

</details>


---

# 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/api-and-sdk-en/unity/sentry.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.