The official New Relic Capacitor plugin for iOS and Android allows developers to easily embed the mobile agents into Capacitor applications. Written in JavaScript, the plugin automatically includes New Relic's native agents to provide mobile monitoring and performance visibility.
Features
The New Relic Capacitor plugin will:
- Automatically instrument mobile applications built via Capacitor
- Capture JavaScript errors
- Generate distributed traces
- Track promise rejection (an unhandled exception in JavaScript)
- Track warnings and errors with console logs
- Capture interactions and their sequences
- Track user sessions
For more information, see New Relic Capacitor Plugin on Github.
Requirements
Before you install the Capacitor plugin, ensure your app meets these requirements:
- Android API 24+
- iOS 10
- iOS native requirements
- Android native requirements
Install
$npm install @newrelic/newrelic-capacitor-plugin$npx cap sync
Ionic Capacitor Setup
You can start the New Relic agent in the initialization of your app in main.ts
(Angular or Vue) or index.tsx
(React). Add the following code to launch NewRelic (don't forget to put proper application tokens):
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}
NewRelicCapacitorPlugin.start({appKey:appToken, agentConfiguration:agentConfig})
AppToken is platform-specific. You need to generate separate tokens for Android and iOS apps.
Android Setup
Install the New Relic native Android agent (instructions here).
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 thisMake 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:
$# Android apps$ionic capacitor run android$
$# iOS apps$ionic capacitor run ios
API calls
Our Capacitor plugin utilizes the same API calls as our iOS and Android SDK agents. Please refer to our iOS SDK doc or Android SDK doc.
For errors specific to Capacitor, you can call NewRelicCapacitorPlugin.recordError
as follows:
try { throw new Error('Example error message'); } catch (error: any) { NewRelicCapacitorPlugin.recordError({ name: error.name, message: error.message, stack: error.stack, isFatal: false, }); }
JavaScript errors
Capacitor Plugin 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:
SELECT * FROM `MobileHandledException` SINCE 24 hours ago
Capacitor Plugin v1.1.1 and below:
The Capacitor plugin 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.