Monitor your Ionic Capacitor application

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.

Compatibility requirements

Before you install the agent, ensure your app meets these requirements:

Install the agent

To install the agent, follow our guided install, located directly in the UI.

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

Step 1 of 5

Create an application token(s)

Go to one.newrelic.com > Browser & Mobile > (choose Android or iOS), then complete the instrumentation steps in the UI.
From Step 4 in the UI, copy the application token(s) (one for iOS and Android if applicable).

Step 2 of 5

Add the Capacitor agent

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

Step 3 of 5

Configure the Capacitor

Start the Capacitor agent in the initialization of your app in main.ts (Angular or Vue) or index.tsx (React).
Add the following code:

import { NewRelicCapacitorPlugin, NREnums, AgentConfiguration } from '@newrelic/newrelic-capacitor-plugin';
import { Capacitor } from '@capacitor/core';
var 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
}
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.

Step 4 of 5

(Android only) If you're monitoring an Android-native app, follow these steps:

Install the New Relic native Android agent.

Update build.gradle:

buildscript {
    ...
    repositories {
      ...
      mavenCentral()
    }
    dependencies {
      ...
      classpath "com.newrelic.agent.android:agent-gradle-plugin:6.11.1"
    }
  }

Update app/build.gradle:

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

Make sure your app requests INTERNET and ACCESS_NETWORK_STATE permissions by adding these lines to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

To automatically link the package, rebuild your project:

bash

$# Android apps
$ionic capacitor run android
$# iOS apps
$ionic capacitor run ios

Step 5 of 5

Deploy your app

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

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
Track a method as an interaction.	Start interactions Stop interactions
Record custom errors.	Record custom errors
Record custom metrics.	Record custom metrics
Record custom attributes and events.	There are several ways to report custom attributes and events: Record custom attributes Increment session attribute count Remove an attribute Remove all attributes Record custom events Set the maximum size of an event pool Set maximum time the agent stores events in memory Get a current session's ID Set a custom user ID to associate with events and attributes For more about which would be the best method to use and why, see Add custom data.
Track custom network requests and failures.	Track HTTP requests Track failing HTTP requests
Shut down the agent.	Shut down the agent.
Enable/disable default mobile monitoring settings.	Enable/disable monitoring features
Run a test crash report.	Test crash reporting

Troubleshoot JavaScript errors

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:

SELECT * FROM `MobileHandledException` SINCE 24 hours ago

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:

Go to one.newrelic.com.
Click Query builder.
Run this query:
```
SELECT * FROM `JS Errors`
```
Click Add to dashboard.
one.newrelic.com > 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.