interaction (SPA API)

Syntax

newrelic.interaction([JSON object $options])

Returns a new handle object that is bound to the current SPA interaction, or a new interaction if one does not exist.

Requirements

The .interaction() API requires Browser Pro+SPA agent (v963 or higher).
Supplying an $options object to the API is only supported in versions v1.285.0 and higher.
The waitForEnd option is only supported in v1.285.0 and higher.
The targetPageLoad option is only supported in v1.315.0 and higher.

If you're installing the browser agent via npm and building a custom agent with selected features, you must enable the spa feature when creating the Agent instance. In the features array, add the following:

import { Agent } from '@newrelic/browser-agent/loaders/agent'
import { Spa } from '@newrelic/browser-agent/features/spa';

const options = {
  info: { ... },
  loader_config: { ... },
  init: { ... },
  features: [
    ... other features ...
    Spa
  ]
}

new Agent(options)

For more information, see the npm browser installation documentation.

Description

The SPA monitoring interaction() API call allows you to control and customize SPA interactions tracked by the browser agent. Use this API to:

Manually create custom interactions for patterns that the browser agent doesn't automatically detect.
Modify existing interactions by adding custom attributes, naming them, or controlling when they complete.

How it works

When you call newrelic.interaction(), you get a handle (a JavaScript object) that references a BrowserInteraction event. This handle lets you call methods like .save(), .ignore(), .setName(), and .setAttribute() to control the interaction.

API behavior by interaction state

The API behaves differently depending on the current state of the interaction:

State	Behavior
No interaction in progress	Creates a new custom interaction. The custom interaction automatically closes when the next soft navigation completes (following default SPA heuristics), unless you set `waitForEnd: true`. Use this to track user actions that don't trigger route changes, such as opening a modal or expanding a section.
Interaction already in progress	Returns a new handle that references the currently active interaction. You can create multiple handles for the same interaction. This is useful when you want to control different aspects of an interaction from different parts of your code. The existing interaction continues—this API can't replace or overwrite an interaction that's already in progress. Works for both user-triggered interactions (like clicks) and API-triggered custom interactions.
Targeting the initial page load	When you use the `targetPageLoad: true` option, the handle always references the initial page load BrowserInteraction event. This is the only way to access and modify the initial page load interaction. Prior to this option, the initial page load wasn't accessible through the API.

State

Behavior

No interaction in progress

Creates a new custom interaction.

The custom interaction automatically closes when the next soft navigation completes (following default SPA heuristics), unless you set waitForEnd: true.
Use this to track user actions that don't trigger route changes, such as opening a modal or expanding a section.

Interaction already in progress

Returns a new handle that references the currently active interaction.

You can create multiple handles for the same interaction. This is useful when you want to control different aspects of an interaction from different parts of your code.
The existing interaction continues—this API can't replace or overwrite an interaction that's already in progress.
Works for both user-triggered interactions (like clicks) and API-triggered custom interactions.

Targeting the initial page load

When you use the targetPageLoad: true option, the handle always references the initial page load BrowserInteraction event.

This is the only way to access and modify the initial page load interaction.
Prior to this option, the initial page load wasn't accessible through the API.

Key behaviors

Behavior	Description
Multiple handles are independent	Each call to `newrelic.interaction()` creates a separate handle object, even when referencing the same underlying interaction. Methods called on one handle don't affect other handles, but they all modify the same BrowserInteraction event.
Can't overwrite interactions	If a user clicks a button (starting an interaction) and your code then calls `newrelic.interaction()`, the API returns a handle to the click interaction—it doesn't create a new one. The browser agent prioritizes real user interactions.
Handles become inactive	Once an interaction completes, any handles referencing it become inactive. Method calls on inactive handles have no effect and don't throw errors.
Use `waitForEnd` for precise control	By default, interactions close based on SPA heuristics (route changes, AJAX completion, DOM settling). Setting `waitForEnd: true` keeps the interaction open until you explicitly call `.end()` on the handle.

Prudence

Using waitForEnd: true together with targetPageLoad: true will keep the initial page load BrowserInteraction event open indefinitely until .end() is called, changing the default definition of the initial page load BrowserInteraction event. This is an advanced use case and should be used with caution.

Parameters

Parameter	Description
`$options` JSON object	Optional: Specifies options that affect the behavior of the interaction. `waitForEnd` - (v1.285.0+) Default is `false`. To forcibly keep the interaction open until the `.end` method is called on its handle, set it to `true`. After an interaction is earmarked with this, it cannot be undone. `targetPageLoad` - (v1.315.0+) Default is `false`. If set to `true`, the returned handle is bound to the initial page load interaction instead of creating or targeting a soft navigation interaction. This is the only way to target the initialPageLoad interaction.

Parameter

Description

$options

JSON object

Optional: Specifies options that affect the behavior of the interaction.

waitForEnd - (v1.285.0+) Default is false. To forcibly keep the interaction open until the .end method is called on its handle, set it to true. After an interaction is earmarked with this, it cannot be undone.
targetPageLoad - (v1.315.0+) Default is false. If set to true, the returned handle is bound to the initial page load interaction instead of creating or targeting a soft navigation interaction. This is the only way to target the initialPageLoad interaction.

Return values

This method returns an native JS object that points to a potential BrowserInteraction event. Each time this method is called for the same BrowserInteraction while it has not yet ended, a new object is created, but it still references the same interaction.

Examples

SPA API methods can be applied to the returned output of newrelic.interaction(). You can assign the returned value or handle to another variable for later use. For example:

let myInteraction = newrelic.interaction();
...
myInteraction.save();

For a list of interaction APIs, see Track single page apps.

While the named handle can be saved and used from outside an interaction, note that SPA methods will have no effect after the interaction has ended.

Interaction duration can also be customized using the following method:

// Say an interaction is already open from a user click.
const userInteraction = newrelic.interaction({ waitForEnd: true }); // grabs the current interaction in-progress & keep it open
// URL changes & DOM is modified. Because of those condition being met, interaction will be saved but is kept open.
fetch('myurl.com/endpoint').then(() => userInteraction.end()) // associate this request to the interaction before completing this BrowserInteraction

const myCustomIxn = newrelic.interaction({ waitForEnd: true }) // create a new api-triggered interaction
// This interaction will be kept open indefinitely until `.end` is called, and no new interaction will start, custom or otherwise. AjaxRequest will continue to buffer under this interaction until it is closed.

Syntax.css-21sua1{background:none;border:none;width:0;padding:0;}

Requirements

Description

How it works

API behavior by interaction state

Key behaviors

Prudence

Parameters

Return values

Examples

Syntax