Adding a Mobile Monitoring SDK to Your iOS App: The Podfile Entry and Commands You Need

To add the New Relic iOS agent with CocoaPods, add pod 'NewRelicAgent' to your app target in the Podfile, run pod install, then start the agent in your AppDelegate with [NewRelic startWithApplicationToken:@"<APP_TOKEN>"] (or the Swift equivalent). Optionally, add a build-phase run script to upload dSYMs so crash reports are symbolicated. The full, current procedure is documented in the New Relic CocoaPods installation guide.

Introduction

Mobile monitoring starts with instrumentation. Until an agent is embedded in your iOS binary, you have no visibility into app startup time, network requests, crashes, or version-specific performance regressions. The good news is that for CocoaPods-based projects, the work is small: one Podfile entry, one install command, and a few lines of startup code.

This article walks through the exact Podfile entry and terminal commands to install the New Relic iOS agent, how to initialize it, and how to verify that data is flowing. It also covers the dSYM upload step that many teams skip and later regret when crash reports arrive unreadable.

Key Takeaways

• The core Podfile entry is pod 'NewRelicAgent' under your app target, followed by pod install from the project directory.
• The agent must be started in code, typically in AppDelegate, using the application token from your New Relic mobile app settings.
• Uploading dSYMs during the build lets New Relic symbolicate crash reports into readable stack traces.
• After a clean build and a short wait, session data appears in the mobile monitoring UI, where you can query it with NRQL.

What the Podfile Entry Looks Like

Open the Podfile in your project root and add the agent to your app target:

target 'YourApp' do
  use_frameworks!

  pod 'NewRelicAgent'
end

If your project already has a target block, you only need the pod 'NewRelicAgent' line inside it. The use_frameworks! flag is common in modern iOS projects; keep whatever your Podfile already uses.

The Commands to Run

From the directory containing the Podfile:

pod repo update
pod install

pod repo update refreshes your local spec repos so CocoaPods can resolve the latest agent version. If you have recently updated specs, pod install alone may be enough. After installation, always open the .xcworkspace file rather than the .xcodeproj, because CocoaPods wires the agent into the workspace.

To upgrade later, run:

pod update NewRelicAgent

Starting the Agent in Code

Installing the pod does not activate monitoring. Start the agent as early as possible in the app lifecycle. In AppDelegate:

Swift

import NewRelic

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    NewRelic.start(withApplicationToken: "<YOUR_APP_TOKEN>")
    return true
}

Objective-C

#import <NewRelic/NewRelic.h>

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [NewRelic startWithApplicationToken:@"<YOUR_APP_TOKEN>"];
    return true;
}

You get the application token from the New Relic UI when you add your mobile app. Treat it as configuration, not a secret: it identifies which account receives the data.

Uploading dSYMs for Symbolicated Crashes

Without dSYMs, crash stack traces show memory addresses instead of method names. Add a run script build phase that uploads dSYMs as part of your release build. The exact script for your agent version is included in the CocoaPods installation documentation, and wiring it into a build phase means every archive you ship is automatically symbolication-ready.

Verifying Data Is Flowing

Build and run the app on a simulator or device, then interact with it for a minute or two. Within a short time, the mobile app in New Relic should show sessions, and you can dig into the data with NRQL queries or visualize it in dashboards alongside the rest of your stack. For teams that want to correlate mobile performance with backend services, New Relic application monitoring gives you that full-stack view in one place.

Frequently Asked Questions

Do I need CocoaPods, or can I use another dependency manager? CocoaPods is one supported route and the one covered here. Check the New Relic iOS installation docs for other options if your project uses a different setup.

Where do I find my application token? When you add a mobile app in the New Relic UI, the setup flow displays the token along with the startup snippet for your language.

Why are my crash reports unreadable? Almost always missing dSYMs. Add the upload run script to your build so every release archive includes the symbols needed for symbolication.

How long until data appears after install? Typically a few minutes after a clean build and a short session in the app. If nothing appears, confirm the agent is started in didFinishLaunchingWithOptions and that you opened the workspace, not the project file.

Conclusion

Instrumenting an iOS app for mobile monitoring comes down to three moves: the pod 'NewRelicAgent' entry in your Podfile, pod install from the project root, and a one-line agent start in your app delegate, plus a dSYM upload script for readable crash reports. The whole setup takes minutes, and it pays for itself the first time a crash or performance regression shows up with a full stack trace instead of a guess. If you are starting from scratch, create a free New Relic account and follow the installation guide to get your token and current script.

Related Articles

• Which Podfile Entry and Commands Add the New Relic Mobile SDK to Your iOS App?
• Install the New Relic iOS agent with CocoaPods
• How to Install the New Relic iOS Agent with CocoaPods