> 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/add-features/sentry-integration.md).

# Sentry integration

[Sentry Unity SDK](https://docs.sentry.io/platforms/unity/)When installed, the SDK automatically attaches Apps in Toss platform context to crash and error events. This document explains how to enable that integration and exactly what values are attached automatically.

In projects where the Sentry SDK is not installed, the integration code **does not compile at all.** There is no runtime overhead and no compile errors, so if you're not using it, you don't need to read this document.

### Installation

`AIT > Install Sentry SDK` Clicking the menu installs the Sentry Unity SDK via Package Manager. If it's already installed, the menu is disabled.

To add it manually, `Packages/manifest.json`write it to

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

The minimum required version is `io.sentry.unity` **4.0.0**The version installed by the menu is **4.1.0**.

After installation, `Tools > Sentry`open it and enter the DSN, and you're done. There is nothing to configure for the AIT integration itself. The DSN is in the Sentry project `Settings > Client Keys (DSN)`You can find it at. The entered value is `Assets/Resources/Sentry/SentryOptions.asset`saved to

### Automatically attached context

#### Tags

| Tag                    | Source                          | Examples                |
| ---------------------- | ------------------------------- | ----------------------- |
| `ait.sdk_version`      | `AITVersion.FullVersion`        | `2.4.7`                 |
| `ait.unity_version`    | `Application.unityVersion`      | `6000.3.3f1`            |
| `ait.commit_hash`      | `AITVersion.CommitHash`         | `9d42c0b`               |
| `ait.current_scene`    | Currently active scene          | `MainMenu`              |
| `ait.device_id`        | `AIT.GetDeviceId`               | `abc123...`             |
| `ait.platform_os`      | `AIT.GetPlatformOS`             | `iOS`, `Android`        |
| `ait.locale`           | `AIT.GetLocale`                 | `ko-KR`                 |
| `ait.toss_app_version` | `AIT.GetTossAppVersion`         | `5.80.0`                |
| `ait.environment`      | `AIT.GetOperationalEnvironment` | `production`, `staging` |
| `ait.deployment_id`    | `AIT.EnvGetDeploymentId`        | `deploy-xyz`            |

The first four are set synchronously and immediately, and `ait.device_id` the following six are filled in by asynchronously calling platform APIs.

`ait.commit_hash`In builds where the commit hash cannot be determined, **it is not set at all.** If the remaining platform tags also cannot obtain values, the tag is not attached — not having a value and `unavailable`having a string entered as the value is different, and here it is the former.

`ait.current_scene`is updated every time a scene is loaded, so it points to the scene at the time the event occurs.

#### User

Only if the device ID was obtained, `User.Id`that value is put into. If the device ID cannot be obtained, `User`it is not touched.

#### Context object

`apps_in_toss` a custom context with that name is added.

```json
{
  "sdk_version": "2.4.7",
  "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"
}
```

Unlike tags, this object **also for items whose values could not be obtained `unavailable` fills them in as strings.** This is so you can read directly from the event which API failed. The commit hash, which is not in the tags, is not here either, and the `current_scene`that exists only in the tags is also not here.

#### Breadcrumb

A breadcrumb is recorded every time a scene is loaded.

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

### Analytics integration

`AITSentryAnalytics`is a wrapper that also records Analytics API calls as Sentry breadcrumbs. `AIT.AnalyticsScreen`If you call this instead of calling AIT.AnalyticsScreen directly, the same call is also left in the context of the Sentry event.

```csharp
using AppsInToss.Sentry;

// AIT.AnalyticsScreen call + Sentry breadcrumb recording
await AITSentryAnalytics.TrackScreen(new { screen_name = "MainMenu" });
await AITSentryAnalytics.TrackImpression(new { item_id = "banner_1" });
await AITSentryAnalytics.TrackClick(new { button = "start" });
```

To automatically record screens on every scene transition, turn on one flag.

```csharp
AITSentryAnalytics.AutoScreenTrackingEnabled = true;
```

When enabled, `SceneManager.sceneLoaded`in `TrackScreen(new { screen_name = scene name })`is called automatically. In this case, when one scene is loaded, breadcrumbs **two** are left — the above `scene` breadcrumb and the `analytics` breadcrumb from here.

The cumulative call count `ait_analytics` is also attached to events as a context object.

| Field                                               | Description                                                                  |
| --------------------------------------------------- | ---------------------------------------------------------------------------- |
| `screen_count` / `impression_count` / `click_count` | Cumulative call count by type                                                |
| `last_screen`                                       | The name of the last scene for which a screen was recorded (if none, `none`) |
| `auto_tracking`                                     | `AutoScreenTrackingEnabled` Current value                                    |

> **Note**: `AIT` Like the core API, the return type varies by Unity version. In Unity 6 and later, `Awaitable`, and below that, `Task`is used. For details, [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns).

### CI environment variables

#### Injecting the DSN at build time

Because WebGL runs in a browser sandbox, it cannot read environment variables at runtime. So `AITSentryDsnInjector`reads the environment variables during the build pre-processing stage and `SentryOptions.asset`bakes them into

| Variable             | Purpose                                                      | Examples                    |
| -------------------- | ------------------------------------------------------------ | --------------------------- |
| `SENTRY_DSN`         | DSN. If this value is missing, injection is skipped entirely | `https://key@sentry.io/123` |
| `SENTRY_ENVIRONMENT` | Force specify environment (optional)                         | `production`, `staging`     |
| `SENTRY_RELEASE`     | Force specify release (optional)                             | `my-app@1.0.0`              |

Injection **only in WebGL builds** works, and `SentryOptions.asset`if this already exists, it is skipped to protect user settings. In other words, this path actually creates files only in CI checkouts where the asset does not exist.

#### Automatic derivation of environment and release

`SENTRY_ENVIRONMENT` / `SENTRY_RELEASE`If not provided, `AITSentryReleaseResolver`derives the two values from the SDK version. Sentry's `environment`/`release`is an initialization-time-only option and cannot be changed at runtime scope, so there is no way other than baking it in at build time.

| SDK version | environment                             | release                        |
| ----------- | --------------------------------------- | ------------------------------ |
| stable      | *(unset → Sentry default `production`)* | `apps-in-toss.unity@{version}` |
| prerelease  | `beta`                                  | `apps-in-toss.unity@{version}` |
| unknown     | *(unset)*                               | *(unset)*                      |

* **Purpose**: Errors from beta pilot builds `environment:beta`are separated so they do not contaminate stable triage, notifications, or release health. Stable builds do not set an environment, so the existing behavior remains unchanged.
* **Priority**: If explicit environment variables are set, **they always override automatic derivation.**
* **Release consistency**: The derived release uses the same rules as the Sentry release identifier created by the release workflow, so release health and `Fixes` trailer-based auto-resolve linking lines up.

If the SDK version cannot be determined, neither value is baked in and a warning is logged. In that case Sentry uses its defaults, so if this was a prerelease build, events may flow into stable triage.

#### sentry-cli

These are values used for uploading debug symbols and sourcemaps. They are read by the CLI, not the SDK.

| Variable            | Purpose                           | Examples                       |
| ------------------- | --------------------------------- | ------------------------------ |
| `SENTRY_AUTH_TOKEN` | API authentication token          | `sntrys_...`                   |
| `SENTRY_ORG`        | Organization slug                 | `my-org`                       |
| `SENTRY_PROJECT`    | Project slug                      | `unity-game`                   |
| `SENTRY_URL`        | Self-hosted Sentry URL (optional) | `https://sentry.mycompany.com` |
| `SENTRY_LOG_LEVEL`  | CLI log level (optional)          | `info`, `debug`                |

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

### How it works

#### Conditional compilation

The Sentry integration assembly `AIT_SENTRY_AVAILABLE` compiles only when the define is present.

1. `io.sentry.unity` When 4.0.0 or later is installed `versionDefines`is `AIT_SENTRY_AVAILABLE`automatically enables
2. `AppsInToss.Sentry`and `AppsInToss.Sentry.Editor`the `defineConstraints`requires this define.
3. If the Sentry SDK is absent, both assemblies are completely excluded from compilation.

#### Automatic initialization

`[RuntimeInitializeOnLoadMethod(AfterSceneLoad)]`is initialized with. Since both the Sentry SDK and the SDK core are initialized at `BeforeSceneLoad`From BeforeSceneLoad, the later `AfterSceneLoad`is the first point at which it can safely access both sides.

1. `SentrySdk.IsEnabled`Check whether Sentry is enabled with — if it is off, stop here
2. Set version and commit hash tags
3. Subscribe to scene load events
4. Collect the remaining context by asynchronously calling platform APIs
5. Initialize Analytics integration

Step 4 is fire-and-forget, so each API can fail independently. Even if one fails, the remaining context is attached normally.

#### IL2CPP stripping protection

We block it in three layers so the integration code does not disappear entirely in WebGL (IL2CPP) builds.

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

`AlwaysLinkAssembly`is the key. Since no other assembly references this assembly, without this attribute the IL2CPP linker decides it is an "unused assembly" and removes it entirely.

#### Stack trace precision in Unity 6 and later

When building WebGL in Unity 6 or later, `AITSentryBuildProcessor`enables C# file and line information in IL2CPP stack traces.

```csharp
PlayerSettings.SetIl2CppStacktraceInformation(WebGL, MethodFileLineNumber)
```

Thanks to this, you can see crash locations in Sentry as exact source lines. Unity 2021.3/2022.3 do not have this API, so it is automatically skipped, and the build continues even if configuration fails.

### Troubleshooting

#### Events are not being sent

If the following log appears in the Console, the Sentry SDK itself is disabled. This is a DSN problem, not an AIT integration problem.

```
[AITSentry] The Sentry SDK is disabled. Skipping AIT context integration. (Check DSN settings: Tools > Sentry)
```

If it attached successfully, this log appears.

```
[AITSentry] Initialized - AIT context will be automatically added to Sentry events.
```

If this is a CI build, in the build log `Created SentryOptions.asset`look for a line starting with. Immediately below it, the masked DSN and automatically derived Environment and Release will be printed together. If this line is missing, `SENTRY_DSN`it was empty or the asset already existed, so injection was skipped.

#### AIT tags are missing in IL2CPP builds

This happens when stripping removes the integration code. The preservation declarations are already shipped with the SDK in `Runtime/Sentry/link.xml`so **you do not need to add them yourself.** If the tags are still missing, the build cache is usually the cause.

`Library/Bee/artifacts/WebGL/`Delete and do a clean build. Cached results do not `link.xml` reflect changes.

If you separately modified stripping settings in the project, `Assets/link.xml`you can reinforce it by adding the same declarations to

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

#### Some context is unavailable

This happens when a platform API call fails. It does not retry and `unavailable`finalizes it as

In a mock bridge environment, some APIs are unsupported, so it is normal for this value to appear. In this case, the tag does not contain that item at all, and `apps_in_toss` it appears only in the context `unavailable`as

### Related documents

* [SDK event logging](https://developers-apps-in-toss.toss.im/documentation/unity/add-features/metrics) — runtime events automatically collected by the SDK
* [Getting Started](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/getting-started) — SDK installation and basic setup
* [Troubleshooting](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) — general troubleshooting
* [Sentry Unity SDK documentation](https://docs.sentry.io/platforms/unity/) — Sentry official documentation


---

# 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/add-features/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.