--- title: Monitor your Ionic Capacitor mobile app source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ionic-capacitor/get-started/introduction-new-relic-ionic-capacitor --- Our New Relic Ionic Capacitor agent monitors your Ionic Capacitor mobile app and provides deep insights into your app's performance, errors, and user experience. The agent automatically includes New Relic's native agents to provide mobile monitoring and performance visibility. Once you install and configure the agent, you'll be able to: - **Capture JavaScript 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. For more information, see [New Relic Ionic Capacitor agent on Github](https://github.com/newrelic/newrelic-capacitor-plugin). ## Compatibility requirements [#requirements] Before you install the agent, ensure your app meets these requirements: - [Android-native requirements](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/get-started/new-relic-android-compatibility-requirements) - [iOS-native requirements](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/get-started/new-relic-ios-compatibility-requirements) ## (Recommended) Guided installation [#guided-install] To install the agent, follow our [guided install](https://onenr.io/0VRVoxJW1ja), located directly in the UI. ## Manual installation [#manual-install] If you need to install the agent manually, follow these steps: ### Create an application token(s) [#app-token] 1. Go to **[one.newrelic.com](https://onenr.io/0EjOpynz0Q6) > Browser & Mobile > (choose Android or iOS)**, then complete the instrumentation steps in the UI. 2. From **Step 4** in the UI, copy the application token(s) (one for iOS and Android if applicable). ### Add the Capacitor agent [#install] In your project directory, add the Capacitor agent to your project using your command line tool: ````bash npm install @newrelic/newrelic-capacitor-plugin npx cap sync ``` ```` ### Configure the Capacitor [#configure] 1. Start the Capacitor agent in the initialization of your app in `main.ts` (Angular or Vue) or `index.tsx` (React). 2. Add the following code: ```tsx import { NewRelicCapacitorPlugin, NREnums, AgentConfiguration, } from "@newrelic/newrelic-capacitor-plugin"; import { Capacitor } from "@capacitor/core"; let appToken; if (Capacitor.getPlatform() === "ios") { appToken = "IOS_APP_TOKEN"; } else { appToken = "ANDROID_APP_TOKEN"; } if (Capacitor.getPlatform() === "ios") { appToken = "IOS_APP_TOKEN"; } else { appToken = "ANDROID_APP_TOKEN"; } let agentConfig: AgentConfiguration = { // Android Specific // Optional:Enable or disable collection of event data. analyticsEventEnabled: true, // Optional:Enable or disable crash reporting. crashReportingEnabled: true, // Optional:Enable or disable interaction tracing. Trace instrumentation still occurs, but no traces are harvested. // This will disable default and custom interactions. interactionTracingEnabled: true, // Optional:Enable or disable reporting successful HTTP requests to the MobileRequest event type. networkRequestEnabled: true, // Optional:Enable or disable reporting network and HTTP request errors to the MobileRequestError event type. networkErrorRequestEnabled: true, // Optional:Enable or disable capture of HTTP response bodies for HTTP error traces, and MobileRequestError events. httpResponseBodyCaptureEnabled: true, // Optional:Enable or disable agent logging. loggingEnabled: true, // Optional:Specifies the log level. Omit this field for the default log level. // Options include: ERROR (least verbose), WARNING, INFO, VERBOSE, AUDIT (most verbose). logLevel: NREnums.LogLevel.INFO, // iOS Specific // Optional:Enable/Disable automatic instrumentation of WebViews webViewInstrumentation: true, // Optional:Set a specific collector address for sending data. Omit this field for default address. // collectorAddress: "", // Optional:Set a specific crash collector address for sending crashes. Omit this field for default address. // crashCollectorAddress: "", // Optional:Enable or disable sending JS console logs to New Relic. sendConsoleEvents: true, // Optional:Enable or disable reporting data using different endpoints for US government clients // fedRampEnabled: false, // Optional: Enable or disable offline data storage when no internet connection is available. offlineStorageEnabled: true, // iOS Specific // Optional: Enable or disable Background Reporting. backgroundReportingEnabled: true, // iOS Specific // Optional: Enable or disable to use our new, more stable event system for iOS agent. newEventSystemEnabled: true, }; NewRelicCapacitorPlugin.start({ appKey: appToken, agentConfiguration: agentConfig, }); ``` Make sure you paste your application token(s) into `appToken = ""` in the code above. If you deployed your hybrid app to both iOS and Android platforms, you'll need to add two separate tokens: one for iOS and one for Android. ### (Android only) If you're monitoring an Android-native app, follow these steps: 1. [Install the New Relic native Android agent](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-apps-gradle-android-studio). 2. Add the following changes to apply the Gradle plugin: If your project is using plugin DSL, add this snippet: 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 } ``` Or, if your project is older, you can use the legacy `newrelic` plugin ID by adding this snippet: ```groovy buildscript { ... repositories { ... mavenCentral() } dependencies { ... classpath "com.newrelic.agent.android:agent-gradle-plugin:7.5.1" } } ``` In `android/app/build.gradle`, apply the `NewRelic` plugin to the top of the `android/app/build.gradle` file: ```groovy apply plugin: "com.android.application" apply plugin: 'newrelic' // <-- include this ``` ```` 3. To automatically link the package, rebuild your project: ```shell # Android apps ionic capacitor run android # iOS apps ionic capacitor run ios ``` ### Deploy your app [#deploy] Then, deploy your app. After some app activity, you should see data in New Relic (it may take a few minutes after deploying your app). ## 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 Capacitor 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 errors. | [Record custom errors](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-errors) | | Record custom metrics. | [Record custom metrics](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-metrics/) | | 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) For more about which would be the best method to use and why, 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) | | Enable/disable default mobile monitoring settings. | [Enable/disable monitoring features](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/configure-settings) | | Run a test crash report. | [Test crash reporting](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/test-crash-reporting) | ## Troubleshoot JavaScript errors [#javascript-errors] **Capacitor agent v1.2.0 and above** JavaScript errors can be seen in the `Handled Exceptions` tab or as a `MobileHandledException` event. You can also see these errors in the NRQL explorer using this query: You can also find these errors by running this query: ````sql SELECT * FROM MobileHandledException SINCE 24 hours ago ``` ```` **Capacitor agent v1.1.1 and below** The Capacitor agent creates custom events for JavaScript errors and reports them to New Relic. In the UI, you can track these JavaScript error events with a custom dashboard. To create a custom dashboard: 1. Go to [one.newrelic.com](https://one.newrelic.com/all-capabilities). 2. Click **Query builder**. 3. Run this query: ```sql SELECT * FROM JavaScriptError ``` 4. Click **Add to dashboard**. ![This is an image of a sample query in the Query builder.](https://docs.newrelic.com/images/mobile_screenshot-full_query-example.webp "Query builder") **[one.newrelic.com](https://one.newrelic.com/all-capabilities) > Query builder**: Use the **Query builder** to create a custom dashboard for tracking JavaScript errors from your Capacitor app. If you need help getting started with dashboards, see [Introduction to dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards#get-started).