> 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-integration.md).

# Sentry integration

## Sentry integration

AIT SDK is [Sentry Unity SDK](https://docs.sentry.io/platforms/unity/)supports automatic integration with. 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**: In projects where the Sentry SDK is not installed, 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. 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 to:

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

#### Supported version

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

***

### Settings

Only Sentry SDK configuration itself is needed. AIT integration works automatically without separate setup.

#### DSN setup

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

DSN can be found in the Sentry project's `Settings > Client Keys (DSN)`The configuration value can be found in `Assets/Resources/Sentry/SentryOptions.asset`is saved in.

***

### Automatically injected AIT context

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

#### Tags

| Tag                    | Description           | Examples                |
| ---------------------- | --------------------- | ----------------------- |
| `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`      | Operating 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

```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 (automatic build-time injection)

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

| Variable             | Purpose                                    | Examples                    |
| -------------------- | ------------------------------------------ | --------------------------- |
| `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 to upload debug symbols and source maps. Set it in your CI/CD pipeline.

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

#### CI/CD pipeline example

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

***

### How it works

#### Conditional compilation

Sentry integration uses Unity's `versionDefines`and is implemented with 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` of the assembly `defineConstraints`are set to `AIT_SENTRY_AVAILABLE`is set to.
3. If the Sentry SDK is not installed, the entire assembly is excluded from compilation.

#### IL2CPP stripping protection

Three layers of protection are applied so code is not stripped in WebGL (IL2CPP) builds:

| Protection measure               | Role                                                           |
| -------------------------------- | -------------------------------------------------------------- |
| `[assembly: AlwaysLinkAssembly]` | Prevents the assembly itself from being stripped 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 to the exact source code line.

***

### Troubleshooting

<details>

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

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

</details>

<details>

<summary>There are no AIT tags in IL2CPP builds</summary>

The integration code may have been removed by IL2CPP stripping.

1. `Assets/link.xml`make sure the following is included:

```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 happens when an AIT platform API call fails. Each API can fail independently, and the remaining context is still injected normally.

* In the mock bridge environment, some APIs may not be supported.
* 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-integration.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.