---
title: Monitor your Unity mobile app
source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-unity/monitor-your-unity-application
---

Our New Relic Unity agent monitors your Unity mobile app and provides deep insights into your app's performance, errors, and user experience. Once you install and configure the Unity agent, you'll be able to:

-   **Capture C# and Native C++ errors:** Identify and fix problems quickly.
-   **Track network requests:** See how your app interacts with the backend.
-   **Use distributed tracing:** Drill down into handled exceptions and find the root cause.
-   **Create custom events and metrics:** Understand how your users interact with your app.

![Summary view of a Unity app in New Relic](https://docs.newrelic.com/images/mobile_screenshot-full_hybrid-summary.webp "Unity summary view in the UI")

**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Summary**: View Unity data, track HTTP requests and errors, and monitor how your app is performing over time.

## (Recommended) Guided installation [#guided-install]

To install the Unity agent, follow our [guided install](https://onenr.io/0gR70k5oZjo), located directly in the UI.

![Screenshot of the guided install UI for Unity](https://docs.newrelic.com/images/mobile_screenshot-crop_unity-guided-install.webp "Guided install for monitoring Unity mobile apps")

## Manual installation [#manual-install]

If you need to install the agent manually, follow these steps:

### Review the requirements [#requirements]

Before you install the Unity agent, make sure your Unity app meets these version requirements:

-   For Android-native apps:
    -   Android API 24 or higher
    -   See [Android-native requirements](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/get-started/new-relic-android-compatibility-requirements)
-   For iOS-native apps:
    -   See [iOS-native requirements](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/get-started/new-relic-ios-compatibility-requirements)

### Add the Unity agent to your project [#add-agent]

In the Unity package manager, add the following GitHub URL:

````
https://github.com/newrelic/newrelic-unity-agent.git
```

<img
  title="Unity Agent Install Package Manager"
  alt="Unity Agent Install From Package Manager"
  src="/images/unity_package_manager_github.webp"
  style={{ maxWidth: '70%' }}
/>

````

### Add application token(s) [#app-token]

To enable New Relic to authenticate your Unity app's data, follow these steps:

1.  Get your application token from New Relic:

    1.  Go to **[one.newrelic.com](https://one.newrelic.com/all-capabilities)**, click **Integrations & Agents**, then click **Mobile**.
    2.  Select your Unity app.
    3.  Go to **Settings > Application** and copy the displayed **Application token**.

2.  Add the token to your Unity project:

    1.  Open your Unity IDE.
    2.  Go to **Tools > New Relic > Getting Started** to open the editor window.
    3.  Paste the appropriate application token into the corresponding field for each platform your app supports:

        -   Android: Paste the Android token into the "Android App Token" field.
        -   iOS: Paste the iOS token into the "iOS App Token" field.

        If your app runs on both Android and iOS, provide separate tokens for each platform. Do not use the same token for both.

    ![Add App Token in Unity Apps](https://docs.newrelic.com/images/unity_agent_newrelic_app_token_setup.webp "Unity AppToken Setup")

### (Android-only) Configure your Android app [#configure-android]

To configure your Android app you need to customize your Gradle templates. If you're using Unity 2019 or later, follow the steps below.

1.  In your Gradle build settings, you'll need to include the New Relic Maven repository URL. To do this, open your `mainTemplate.gradle` file, which is usually located in the `Assets/Plugins/Android` folder. Add the following snippet:

    ```groovy
    allprojects {
      buildscript {
        repositories {
          ARTIFACTORY_REPOSITORY
          google()
          jcenter()
          mavenCentral()
        }
      }
    }
    ```

2.  In your `baseProjectTemplate.gradle` file (usually located in your Unit project's Android folder), add the New Relic `classpath` at the project level:

    ```groovy
    dependencies {
      // If you are changing the Android Gradle Plugin version,
      // make sure it is compatible with the Gradle version preinstalled with Unity.
      // See which Gradle version is preinstalled with Unity here:
      //    https://docs.unity3d.com/Manual/android-gradle-overview.html
      // See the official Gradle and Android Gradle Plugin compatibility table here:
      //    https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
      // To specify a custom Gradle version in Unity, go to "Preferences > External Tools",
      // uncheck "Gradle Installed with Unity (recommended)",
      // and specify a path to a custom Gradle version.
      classpath 'com.newrelic.agent.android:agent-gradle-plugin:7.2.0'
      BUILD_SCRIPT_DEPS
    }
    ```

    If you're using an older Unity version that requires Gradle 7.0 or lower, you'll need to use a specific classpath dependency to ensure compatibility:

    ```groovy
    dependencies {
      // If you are changing the Android Gradle Plugin version,
      // make sure it is compatible with the Gradle version preinstalled with Unity.
      // See which Gradle version is preinstalled with Unity here:
      //    https://docs.unity3d.com/Manual/android-gradle-overview.html
      // See official Gradle and Android Gradle Plugin compatibility table here:
      //    https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
      // To specify a custom Gradle version in Unity, go to "Preferences > External Tools",
      // uncheck "Gradle Installed with Unity (recommended)",
      // and specify a path to a custom Gradle version.
      classpath 'com.newrelic.agent.android:agent-gradle-plugin:6.11.0'
      BUILD_SCRIPT_DEPS
    }
    ```

    If your project is using plugin DSL, make the following changes (and skip step 3):

    In android/app/build.gradle:

    ````groovy
    plugins {
        id "com.android.application"
        id "kotlin-android"
        id "com.newrelic.agent.android" version "7.5.1"  //<-- include this
    }
    ```

    ````

3.  In your `launcherTemplate.gradle` file (usually located in your Unity project's Android folder), apply the `newrelic` plugin to the top of your `launcherTemplate.gradle` file:

    ```groovy
    apply plugin: "com.android.application"
    apply plugin: 'newrelic' // <-- add this
    ```

### (iOS-only) Manage dependencies [#manage-dependencies]

For iOS, check your External Dependency Manager settings:

1.  In your Unity IDE, go to **Assets** and open the **External Dependency Manager**.

2.  Click **iOS Resolver**.

3.  In the Podfile Configurations section, verify these settings:

    -   **Add use_frameworks! to Podfile** is disabled
    -   **Always add the main target to Podfile** is enabled

    ![Add iOS Dependency in Unity App](https://docs.newrelic.com/images/unity_agent_ios_depedency_setup.webp "Unity iOS Setup")

4.  If you're not using the Podfile for iOS dependency management, follow these steps:

    1.  Download and unzip the New Relic XCFramework SDK (iOS agent). You can get the latest iOS agent from our [iOS agent release notes](https://docs.newrelic.com/docs/release-notes/mobile-release-notes/ios-release-notes).
    2.  Add the New Relic XCFramework to your Xcode project:
        1.  Unzip the SDK download.
        2.  From your Finder, drag the `NewRelicAgent.xcframework` folder into your Xcode project, placing it onto your Targets Frameworks pane.
        3.  Under the **Embed** column, click **Embed & Sign**.

    And you're done! You should start seeing data in New Relic within 5 minutes.

## Customize the agent instrumentation [#mobile-sdk]

Need to customize your agent instrumentation? Our public mobile SDK API methods let you collect custom data, configure default settings, and more.

The following customizations are available for the Unity agent.

| If you want to...                                                                         | Use this method                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Record breadcrumbs to track app activity that may be helpful for troubleshooting crashes. | [Record breadcrumbs](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-breadcrumb)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Track a method as an interaction.                                                         | [Start interactions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/start-interaction) [Stop interactions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/stop-interaction)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Record custom metrics.                                                                    | [Record custom metrics](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-metrics/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Record an exception.                                                                      | [Record errors](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-handled-exceptions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Record custom attributes and events.                                                      | There are several ways to report custom attributes and events: - [Record custom attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute) - [Increment session attribute count](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/increment-session-attribute-count) - [Remove an attribute](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-attribute) - [Remove all attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-all-attributes) - [Record custom events](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-events) - [Set the maximum size of an event pool](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-pool-size) - [Set maximum time the agent stores events in memory](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-buffer-time) - [Get a current session's ID](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/current-session-id) - [Set a custom user ID to associate with events and attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-custom-user-id) To determine which method to use, see [Report mobile monitoring custom events and attributes](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/report-mobile-monitoring-custom-events-attributes/). |
| Track custom network requests and failures.                                               | [Track HTTP requests](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-success) [Track failing HTTP requests](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-failures)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Shut down the agent.                                                                      | [Shut down the agent](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/shut-down-agent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Run a test crash report.                                                                  | [Test crash reporting](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/test-crash-reporting)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Monitor C# errors [#monitor-errors]

In the New Relic UI, you can view your fatal and non-fatal C# errors and handled exceptions, including details like event trails, attributes, and stack traces for each recorded error.

![Mobile Handled Exceptions](https://docs.newrelic.com/images/mobile_screenshot-full_handled-exceptions-summary.webp "Mobile Handled Exceptions")

To view your errors:

1.  Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile**.
2.  Select your Unity app.
3.  Click **Exceptions > Handled exceptions**.

You can also build a dashboard for these errors using this query:

```sql
SELECT * FROM MobileHandledException SINCE 24 hours ago
```

## Query log data [#query-logs]

New Relic stores your Unity logs as custom events. You can query these logs and build dashboards for them using this NRQL query:

```sql
SELECT * FROM `Mobile Unity Logs` SINCE 30 MINUTES AGO
```

For more information on NRQL queries, see [Introduction to NRQL](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/introduction-nrql-new-relics-query-language/#where).