Introduction to New Relic for Capacitor

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:

Install

bash

$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 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

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.