Skip to content

Latest commit

 

History

History
354 lines (270 loc) · 13.9 KB

monitor-your-unity-application.mdx

File metadata and controls

354 lines (270 loc) · 13.9 KB
Raw
title tags metaDescription isTutorial freshnessValidatedDate
Monitor your Unity mobile app
Unity
Mobile monitoring
New Relic Mobile Unity
Get started
New Relic's Unity agent for Android and iOS: Features, compatibility, requirements, installation, and upgrade procedures.
true
2024-01-05

import mobileHybridSummary from 'images/mobile_screenshot-full_hybrid-summary.webp'

import unityGuidedInstall from 'images/mobile_screenshot-crop_unity-guided-install.webp'

import unitypackageManagerGithub from 'images/unity_package_manager_github.webp'

import unitAgentiOSSetup from 'images/unity_agent_ios_depedency_setup.webp'

import unityAgentAppTokenSetup from 'images/unity_agent_newrelic_app_token_setup.webp'

import mobileHandledExceptionsSummary from 'images/mobile_screenshot-full_handled-exceptions-summary.webp'

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.

<img title="Unity summary view in the UI" alt="Summary view of a Unity app in New Relic" src={mobileHybridSummary} style={{ maxWidth: '70%' }} />

**[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, located directly in the UI.

<img title="Guided install for monitoring Unity mobile apps" alt="Screenshot of the guided install UI for Unity" src={unityGuidedInstall} style={{ maxWidth: '70%' }} />

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](/docs/mobile-monitoring/new-relic-mobile-android/get-started/new-relic-android-compatibility-requirements) * For iOS-native apps: * See [iOS-native requirements](/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={unitypackageManagerGithub} 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, click Add data, 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.

<img title="Unity AppToken Setup" alt="Add App Token in Unity Apps" src={unityAgentAppTokenSetup} style={{ maxWidth: '70%' }} />

(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, complete the following steps:

  1. Include the New Relic Maven repository URL in the Gradle build settings. To do this, open your mainTemplate.gradle file. This file is usually located in the Assets/Plugins/Android folder. Now, open the New Relic Maven URL like this:

    allprojects {
buildscript {
    repositories {<DoNotTranslate>**ARTIFACTORYREPOSITORY**</DoNotTranslate>
        google()
        jcenter()
        mavenCentral()
    }
}

  2. Add the New Relic classpath to your project-level baseProjectTemplate.gradle file. You can usually find this file located in the Android folder in your Unity project.

    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'
    <DoNotTranslate>**BUILD_SCRIPT_DEPS**</DoNotTranslate>
    }
}

    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:

    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'
    <DoNotTranslate>**BUILD_SCRIPT_DEPS**</DoNotTranslate>
}

  3. Apply the newrelic plugin to the top of your launcherTemplate.gradle file. This file is typically located in the Android folder of your Unity project.

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

  4. Add INTERNET and ACCESS_NETWORK_STATE permissions in your AndroidManifest.xml file:

    <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
### (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

<img title="Unity iOS Setup" alt="Add iOS Dependency in Unity App" src={unitAgentiOSSetup} style={{ maxWidth: '70%' }} />

  1. 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.
    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.

  <th>
    Use this method
  </th>
</tr>

  <td>
    [Record breadcrumbs](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-breadcrumb)
  </td>
</tr>

<tr>
  <td id="creating">
    Track a method as an interaction.
  </td>

  <td>
    [Start interactions](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/start-interaction)

    [Stop interactions](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/stop-interaction)
  </td>
</tr>

<tr>
  <td id="create-custom">
    Record custom metrics.
  </td>

  <td>
    [Record custom metrics](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-metrics/)
  </td>
</tr>

<tr>
  <td id="create-custom">
    Record an exception.
  </td>

  <td>
    [Record errors](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-handled-exceptions)
  </td>

</tr>
<tr>
  <td id="attributes-events-insights">
    Record custom attributes and events.
  </td>

  <td>
    There are several ways to report custom attributes and events:

      * [Record custom attributes](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute)
      * [Increment session attribute count](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/increment-session-attribute-count)
      * [Remove an attribute](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-attribute)
      * [Remove all attributes](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-all-attributes)
      * [Record custom events](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-events)
      * [Set the maximum size of an event pool](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-pool-size)
      * [Set maximum time the agent stores events in memory](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-buffer-time)
      * [Get a current session's ID](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/current-session-id)
      * [Set a custom user ID to associate with events and attributes](/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. 

  <td>
    [Track HTTP requests](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-success)

    [Track failing HTTP requests](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-failures)
  </td>
</tr>
<tr>
  <td>
    Shut down the agent.
  </td>

  <td>
    [Shut down the agent](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/shut-down-agent)
  </td>
</tr>
<tr>
  <td>
    Run a test crash report.
  </td>

  <td>
    [Test crash reporting](/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/test-crash-reporting)
  </td>
</tr>
If you want to...
Record breadcrumbs to track app activity that may be helpful for troubleshooting crashes.
Track custom network requests and failures.

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

To view your errors:

  1. Go to 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:

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:

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

For more information on NRQL queries, see Introduction to NRQL.