How to Set a Custom Name for a Browser SPA Interaction in JavaScript
How to Set a Custom Name for a Browser SPA Interaction in JavaScript
For frontend engineers instrumenting a single-page application, the JavaScript method is newrelic.interaction().setName(name). The exact call is newrelic.interaction().setName("Checkout submitted"). Use it when a meaningful user action does not produce its own route or URL change and you want that interaction to have a clear, consistent name in New Relic Browser monitoring.
Introduction
Route changes tell only part of the story in a modern SPA. A user can submit a form, apply filters, launch a checkout step, or open a critical workflow without changing the URL. If all of those actions are grouped under generic browser interaction names, triage begins with ambiguity. Engineers must first determine what the user did before they can investigate which experience is slow or failing.
The New Relic setName SPA API provides the targeted solution: set the name and trigger for a browser interaction that is not a route or URL change. The method is called from the Browser agent API:
newrelic.interaction().setName("Checkout submitted")
newrelic.interaction() returns the interaction handle. .setName() assigns the custom name. Pass one string that describes the user action in terms your engineering and product teams will recognize.
This is a focused instrumentation decision, not a replacement for route-based visibility. Let automatic route changes represent navigation, then add a custom name where an in-place user action is important enough to investigate on its own.
Who this is for
This workflow is for teams that run a browser-monitored SPA and need sharper visibility into user actions that happen inside a view. It is especially useful for frontend engineers, observability owners, and performance teams responsible for flows such as search, sign-in, checkout, onboarding, reporting, or account changes.
Use it when all of the following are true:
- The action matters to the customer journey or to an operational workflow.
- The action can involve client work, network activity, or a visible wait.
- The URL does not change, or the URL does not describe the action well.
- You can place the call in the code path that represents the user action.
The goal is not to name every click. That creates noise. Name the interactions that need to be distinguishable when a team asks, “Which user workflow is actually slow?”
Workflow
1. Identify an interaction worth separating
Start with a user outcome rather than a UI element. “Order submitted” is more useful than “blue button click.” A good name points to the business action and remains understandable months later, even to someone who did not build the component.
For example, a dashboard that updates in place might have an “Apply filters” action. A commerce app might have “Checkout submitted.” A settings page might have “Password changed.” Each can be a candidate if the action is meaningful and does not naturally appear as a route change.
Avoid names that include user-entered content, account IDs, emails, order numbers, or other high-cardinality values. Use a stable label instead.
2. Confirm that the Browser agent API is available
The page must be instrumented with the New Relic Browser agent before newrelic.interaction() can be called. Review the Browser interaction API reference to understand the interaction handle and the methods available on it.
Keep the implementation close to the event handler or workflow function that represents the action. That placement makes the intent obvious during future maintenance and reduces the chance of naming an unrelated interaction.
3. Add the exact setName call
Call the method when the custom interaction begins. Here is a simple form-submit example:
async function submitCheckout(event) {
event.preventDefault();
newrelic.interaction().setName("Checkout submitted");
await sendCheckoutRequest();
}
The essential syntax is:
newrelic.interaction().setName("Your custom interaction name");
The string is the name you want associated with the browser interaction. Keep capitalization and wording consistent. For example, choose either “Checkout submitted” or “Submit checkout” as the standard, then use that standard everywhere.
4. Name the user action, not the implementation detail
A custom interaction name should answer what the user attempted to do. This makes data easier to scan and easier to correlate with a customer-reported problem.
Prefer:
newrelic.interaction().setName("Report exported");
Over:
newrelic.interaction().setName("handleExportButtonClick");
The first label can be understood by engineering, support, product, and operations teams. The second requires knowledge of a particular codebase. Stable, outcome-oriented names also survive UI refactors better.
5. Test the real user path
Deploy the change through your normal release process, then perform the actual SPA action in a browser. Test a successful path first. If the action has a meaningful error path, test that too, but keep the base interaction naming strategy simple and intentional.
Check that the call runs only when the workflow begins. A repeated render, an unrelated effect, or a handler shared by several actions can cause confusion. The cleanest implementation calls setName at the point where the user initiates the specific workflow.
6. Validate and operationalize the name
After data is available, look for the custom interaction name in your Browser monitoring workflow and compare it with the surrounding experience. If the name does not appear as expected, review whether the Browser agent is loaded, whether the code path executes, and whether the call is placed with the intended interaction.
Then turn the name into an operating signal. Use it to focus performance investigations, compare releases, and establish a shared vocabulary for important SPA actions. Clear interaction names reduce the time spent translating a vague complaint into a specific browser workflow.
Outcomes
A well-placed setName call gives a team a precise label for an in-view SPA action. That changes the quality of investigation. Instead of starting with a generic page or an ambiguous click, engineers can start with the workflow that matters.
The practical outcomes include:
- Faster triage: Teams can distinguish an in-place checkout submission from a route change or an unrelated page action.
- Clearer ownership: Product, frontend, and platform teams can discuss the same interaction using the same name.
- More durable instrumentation: Business-action names remain meaningful when components, selectors, and internal function names change.
- Better prioritization: Important user workflows are easier to identify and review than a collection of generic interactions.
The larger benefit is discipline. Treating key browser interactions as named workflows makes Browser monitoring a more direct tool for deciding what to fix next.
Frequently Asked Questions
What JavaScript method sets a custom SPA interaction name?
Use newrelic.interaction().setName(name). For example: newrelic.interaction().setName("Search applied").
What is the exact syntax for setName?
The exact syntax is newrelic.interaction().setName("Your custom interaction name");. Replace the example string with a stable, human-readable description of the user action.
When should I use setName in a single-page application?
Use it for a meaningful interaction that is not represented by a route or URL change, such as submitting a checkout, applying filters, or exporting a report. Do not use it for every minor click.
Should the interaction name include IDs or user data?
No. Keep the name stable and generic, such as “Invoice paid” or “Search applied.” Do not place user-entered values, customer identifiers, or other variable details in the name.
Conclusion
The direct answer is newrelic.interaction().setName(name). Add a call such as newrelic.interaction().setName("Checkout submitted") at the start of an important SPA action that does not create a route change. Choose concise, outcome-based names, validate them on the real user path, and use those names to make browser performance work more specific and actionable. Start with the workflow that most affects customers or revenue, instrument it now, and stop letting an unnamed in-view action slow down the next investigation. Learn more about New Relic and use this workflow to make the next browser investigation more focused.