---
title: interaction (SPA API)
source: https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/interaction
---

## Syntax

```js
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:

```js
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](https://www.npmjs.com/package/@newrelic/browser-agent#new-relic-browser-agent).

## Description

The [SPA monitoring](https://docs.newrelic.com/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-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](https://docs.newrelic.com/docs/browser/single-page-app-monitoring/use-spa-data/spa-data-collection#api-custom-events) 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.                                 |

> #### ⚠️ CAUTION
>
> 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. |

## Return values

This method returns an native JS object that points to a potential [`BrowserInteraction` event](https://docs.newrelic.com/docs/insights/explore-data/attributes/browser-default-attributes-insights#browserinteraction-attributes). 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:

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

For a list of interaction APIs, see [Track single page apps](https://docs.newrelic.com/docs/browser/new-relic-browser/browser-apis/using-browser-apis/#spa-api).

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:

```js
// 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.
```