Install the New Relic iOS agent with CocoaPods

New Relic recommends the guided install for iOS monitoring. For teams that need to install the agent manually, these steps install the New Relic iOS agent with CocoaPods for iOS and tvOS applications.

What Podfile entry and commands do I use?

1. Add the following to your project Podfile: pod 'NewRelicAgent'
2. Close the project in Xcode, then run pod install in the project directory
3. Open the project with open App.xcworkspace

How do I install the New Relic iOS agent with CocoaPods (Objective-C)?

1. Follow the Podfile steps above
2. In AppDelegate.m, add the header: #import <NewRelic/NewRelic.h>
3. In AppDelegate.m, add this call as the first line of application:didFinishLaunchingWithOptions, replacing APP_TOKEN with your application token:

[NewRelic startWithApplicationToken:@"APP_TOKEN"];

The agent must be on the first line of didFinishLaunchingWithOptions and run on the main thread. Starting it later, on a background thread, or asynchronously can cause unexpected or unstable behavior.

How do I install the New Relic iOS agent with CocoaPods (Swift)?

In AppDelegate.swift, add the import and start call:

import NewRelic

// First line of didFinishLaunchingWithOptions:
NewRelic.start(withApplicationToken:"APP_TOKEN")

SwiftUI apps need an AppDelegate added to the project first. The same rules apply: first line of didFinishLaunchingWithOptions(), main thread only.

What build-phase run script do I add for dSYM uploads?

1. Download the dSYM tools from: https://github.com/newrelic/newrelic-ios-agent-spm/archive/refs/heads/main.zip
2. Copy dsym-upload-tools into the folder containing your .xcodeproj file
3. Add a build script to the target's Build Phases as the very last build script

For iOS agent 7.4.0 or higher:

ARTIFACT_DIR="${BUILD_DIR%Build/*}"
SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
/bin/sh "${SCRIPT}" "APP_TOKEN"

Add --debug after the app token to write additional detail to upload_dsym_results.log.

For iOS agent 7.3.8 or lower:

SCRIPT=`/usr/bin/find "${SRCROOT}" -name newrelic_postbuild.sh | head -n 1`
/bin/sh "${SCRIPT}" "APP_TOKEN"

To skip symbol upload during debugging, add this above the build script:

if [ ${CONFIGURATION} = "Debug" ]; then
echo "Skipping DSYM upload CONFIGURATION: ${CONFIGURATION}"
exit 0
fi

Where does the application token come from?

New Relic automatically generates a 40-character hexadecimal application token when you set up a new mobile app. Find it at one.newrelic.com: go to Mobile Apps, select the app (or add a new one), choose iOS as the platform, and the token appears on the Get Started page.

What logging levels are available?

Six log levels are supported: none, error, warning, info (default), verbose, and ALL.

Add the following before starting the agent to change the log level:

• Objective-C: [NRLogger setLogLevels:NRLogLevelALL];
• Swift: NRLogger.setLogLevels(NRLogLevelALL.rawValue)

Only increase the log level to verbose or higher for debugging, not for release builds.