Which Podfile Entry and Commands Add the New Relic Mobile SDK to Your iOS App?

Add pod 'NewRelicAgent' to your app target in the Podfile, close the project in Xcode, then run pod install followed by open App.xcworkspace from your project directory. Once the workspace is open, call NewRelic.start(withApplicationToken: "APP_TOKEN") as the first line of application:didFinishLaunchingWithOptions in your AppDelegate, replacing APP_TOKEN with the application token New Relic generates for your app. That is the complete CocoaPods path documented in the New Relic iOS installation guide. The syntax is the easy part. The decisions that actually matter are which install method fits your project, how you wire up dSYM uploads so crash reports stay readable, and how quickly you get from a clean build to live session data. This guide covers all three.

Introduction

Every mobile release ships to devices you never tested on: different carriers, older OS versions, constrained memory, hostile networks. When a crash or a slow launch happens in the field, you find out from app reviews or support tickets, or you do not find out at all. Instrumenting the app with the New Relic iOS agent changes that discovery loop: the agent reports crashes, launch times, HTTP requests, and screen events to one.newrelic.com, where you can query them alongside the rest of your stack.

CocoaPods remains the dependency manager many iOS teams reach for first, and the agent supports it with a one-line Podfile entry. Installing it well is a three-part decision: the dependency manager you commit to, the startup configuration you ship, and the symbol upload you automate. Choose deliberately and the whole setup takes an afternoon. Choose carelessly and you spend a sprint debugging why crash reports arrive as hex addresses instead of stack traces.

One note before the details: New Relic's docs recommend the guided install for most setups and document the manual routes, CocoaPods included, for teams that need them. If you are mid-setup right now, the manual CocoaPods route below is fully supported and takes about ten minutes.

Key Takeaways

The Podfile entry is a single line inside your app target: pod 'NewRelicAgent'.
The commands are pod install and open App.xcworkspace. Always reopen the .xcworkspace file, never the .xcodeproj.
Start the agent on the first line of application:didFinishLaunchingWithOptions, on the main thread. Starting it later or asynchronously can cause unexpected or unstable behavior.
The application token is a 40-character hexadecimal string that New Relic generates automatically when you add the app at one.newrelic.com.
CocoaPods, Swift Package Manager, and a manual XCFramework install are all documented. Pick the one that matches your dependency management, not the other way around.
Add the dSYM upload script as the last build phase so crash reports symbolicate into readable stack traces.

Decision criteria

Weigh these five criteria before you touch the Podfile:

Existing dependency manager. If the project already resolves dependencies with CocoaPods, adding the agent there is the lowest-friction path: one line, one pod install, done. Introducing a second dependency manager into a project usually costs more than it saves.

Version pinning and review. CocoaPods writes resolved versions to a Podfile.lock that lives in version control, so every engineer and CI runner builds against the same agent version. If your team reviews dependency bumps in pull requests, this workflow will feel familiar.

Symbol upload automation. Crash data is only as useful as the stack traces attached to it. The agent's dSYM upload tools ship with a build script you add as the very last build phase, and the script can skip uploads for Debug builds so local builds stay fast.

Platform targets. The same agent and the same Podfile entry cover iOS, tvOS, and watchOS targets. If your app ships on Apple platforms beyond the iPhone, make sure every target that needs monitoring gets the pod.

Upgrade cadence. The agent is actively versioned, and the dSYM tooling changed at version 7.4.0: newer agents use run-symbol-tool, older ones use newrelic_postbuild.sh. Whatever install method you choose, plan a routine upgrade path rather than a one-time setup.

How to choose

Use these scenarios to pick your path.

If your project already has a Podfile, this is the fastest route:

In the Podfile, add pod 'NewRelicAgent' inside the target block for your app.
Close the project in Xcode, then run pod install in the project directory.
Reopen the project with open App.xcworkspace, replacing App with your project name.
In AppDelegate.swift, add import NewRelic, then add NewRelic.start(withApplicationToken: "APP_TOKEN") as the first line of application:didFinishLaunchingWithOptions. Objective-C apps use #import <NewRelic/NewRelic.h> and [NewRelic startWithApplicationToken:@"APP_TOKEN"]; instead.
Copy the dSYM upload tools into the folder that contains your .xcodeproj, and add the provided script as the last build phase for your target, with your app token in place.
Clean, build, and run the app in the simulator or on a device to start sending data.

If there is no Podfile yet, run pod init in the project directory first, then follow the steps above. That is standard CocoaPods workflow, not anything agent specific.

If your team standardized on Swift Package Manager, use the SPM installation path in the New Relic docs instead of the Podfile. The startup code and dSYM steps are the same; only dependency resolution differs.

If your project cannot use a dependency manager at all, the docs include an XCFramework manual installation. Expect more manual work on every agent upgrade, which is the main tradeoff.

If your app is built with SwiftUI, the agent still needs an AppDelegate to host the start call. The CocoaPods guide links to instructions for adding one to a SwiftUI project.

If you maintain tvOS or watchOS targets, add the same pod line to each target that should report data, and create a separate mobile app entry in New Relic for each platform so the data stays separated.

One configuration tip that applies to every path: the agent logs at the info level by default, and you can raise it to verbose while debugging. Keep verbose logging out of release builds.

Frequently Asked Questions

What exactly goes in my Podfile? One line inside your app's target block: pod 'NewRelicAgent'. No version constraint is required, though you can pin one the same way you pin any other pod if your team locks dependency versions.

Which commands do I run after editing the Podfile? pod install from the project directory, then open App.xcworkspace to reopen the project. If CocoaPods cannot find the spec, run pod install --repo-update to refresh the local spec repositories first. Build from the .xcworkspace file afterward; opening the .xcodeproj leaves the agent out of the build.

Where do I get the application token? Sign in at one.newrelic.com, go to the Mobile Apps list, and select Add a new app. Choose iOS as the platform, name the app, and New Relic generates the token automatically. It is a 40-character hexadecimal string that authenticates each mobile app you monitor.

Why must the start call be the first line of didFinishLaunchingWithOptions? The docs are explicit: the agent must start on the first line of the method and on the main thread for instrumentation to work correctly. Starting it later, on a background thread, or asynchronously can cause unexpected or unstable behavior, which usually shows up as missing or partial session data.

Conclusion

The Podfile entry is one line, pod 'NewRelicAgent', and the commands are pod install and open App.xcworkspace. The rest of the decision is about fit: CocoaPods if it is already your dependency manager, Swift Package Manager or an XCFramework if it is not, and the dSYM upload script in every case so crash data arrives readable. The start call goes first in didFinishLaunchingWithOptions, and the app token comes from New Relic when you add the app.

From there the value compounds. Crashes, launch times, and network requests from real devices land next to your server-side data in one observability platform, so a support ticket turns into a stack trace instead of a release-by-release guessing game. New Relic lets you start free, with 100 GB of data ingest plus one user free every month, which is enough to instrument this app and see real session data before you spend anything. Add the pod, run the install, ship a build. The next crash report will tell you it was worth it, and the pricing page will tell you what it costs to keep going.