docs: Modify Browser SPA docs for soft nav feature GA

src/content/docs/browser/new-relic-browser/browser-apis/createtracer.mdx

@@ -17,7 +17,7 @@ freshnessValidatedDate: never
 ---
 
 <Callout variant="important">
-  The `createTracer` method in the SPA API has been deprecated. The recommended way to trace the duration of a task is to capture a performance [mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) and/or [measure](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure). Future browser agent versions will capture marks and measures automatically, at which point support for `createTracer` will cease.     
+  The `createTracer` method in the SPA API has been deprecated. The recommended way to trace the duration of a task is to capture a performance [mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) and/or [measure](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) for timing callback execution time. This has become a dummy method that no longer work to tie JS execution to interactions or keep them open!
 </Callout>
 
 ## Syntax

src/content/docs/browser/new-relic-browser/browser-apis/end.mdx

@@ -45,7 +45,7 @@ Ends the SPA interaction at the current time.
 
 ## Description
 
-This SPA method will end the browser interaction at the current time. Any subsequent callbacks or requests will not be included as part of the SPA interaction.
+This SPA method will end the browser interaction at the current time. Any subsequent network requests after this call will not be included as part of the current SPA interaction.
 
 ## Return values
 

src/content/docs/browser/new-relic-browser/browser-apis/interaction.mdx

@@ -19,14 +19,15 @@ freshnessValidatedDate: never
 ## Syntax
 
 ```js
-newrelic.interaction()
+newrelic.interaction([JSON object $options])
 ```
 
-Returns a new API object that is bound to the current SPA interaction.
+Returns a new handle object that is bound to the current SPA interaction, or a new interaction if one does not exist.
 
 ## Requirements
 
 * Browser Pro+SPA agent (v963 or higher)
+* The `$options` parameter requires v1.285.0+
 * If you're using npm to install the browser agent, you must enable the `spa` feature when instantiating the `BrowserAgent` class. In the `features` array, add the following:
 
   ```js
@@ -46,26 +47,68 @@ Returns a new API object that is bound to the current SPA interaction.
 
 ## Description
 
-The [SPA monitoring](/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring) `interaction()` call returns a new API object that is bound to the current interaction.
+The [SPA monitoring](/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring) `interaction()` call returns a new handle that is bound to the current interaction.
 
-* <DNT>**New interaction:**</DNT> If the API calls it when New Relic is not currently monitoring an interaction, a new interaction is created.
-* <DNT>**New object:**</DNT> If the API calls it again within the same interaction, a new object referencing the current interaction is created.
+* <DNT>**New interaction:**</DNT> If this function is called and no interaction is open or in-progress, then a new [custom](/docs/browser/single-page-app-monitoring/use-spa-data/spa-data-collection#api-custom-events) interaction is created.
+  * A custom interaction will still follow the default heuristic and close automatically on the next complete soft navigation, _unless_ `waitForEnd` is specified.
+* <DNT>**New object:**</DNT> If this function is called while an interaction is ongoing, a new handle referencing the current interaction is created.
+  * Multiple handles can point to the same interaction. Each `.interaction` call creates a new handle.
+  * The handle will point to the open interaction, whether it began from an user event like a `click` or from a previous api-triggered `.interaction` call.
+  * This function cannot replace its own effect or that of an user event. That is, it cannot overwrite any existing open interaction with a new api-driven interaction.
 
 ## Parameters
 
-The parameters depend on the specific SPA interaction API call.
+<table>
+  <thead>
+    <tr>
+      <th width="25%">
+        Parameter
+      </th>
+      <th>
+        Description
+      </th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        `$options`
+
+        _JSON object_
+      </td>
+      <td>
+        Optional. Specified options that affects the behavior of the interaction. Optional properties:
+
+        * `waitForEnd` - If `true`, the interaction is forcibly kept open until the `.end` method is called on its handle. Defaults to `false`. Once an interaction is earmarked with this, it cannot be undone.
+      </td>
+    </tr>
+  </tbody>
+</table>
 
 ## Return values
 
-This method returns an API object that is bound to a specific [`BrowserInteraction` event](/docs/insights/explore-data/attributes/browser-default-attributes-insights#browserinteraction-attributes). Each time this method is called for the same `BrowserInteraction`, a new object is created, but it still references the same interaction.
+This method returns an native JS object that points to a potential [`BrowserInteraction` event](/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 used on `newrelic.interaction()`. The methods can also be used on a handle you assign with a variable. For example:
+SPA API methods can/must be used on `newrelic.interaction()`. You can assign the returned value or handle to another variable for later use. For example:
 
 ```js
-myInteraction = newrelic.interaction();
+let myInteraction = newrelic.interaction();
+...
 myInteraction.save();
 ```
 
-The named handle can be saved and used from outside an interaction, but methods will have no effect after the interaction has ended.
+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 this 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.
+```

src/content/docs/browser/new-relic-browser/browser-apis/save.mdx

@@ -46,7 +46,7 @@ Ensures a SPA browser interaction will be saved when it ends.
 
 ## Description
 
-This SPA method ensures a browser interaction will be saved when it ends. Normally an interaction is only saved and sent to New Relic if it is an initial page load or if it results in a URL or hash change. You must call this method to override this behavior and guarantee the interaction will be recorded.
+This SPA method ensures a browser interaction will be saved when it ends. Normally an interaction is only saved and sent to New Relic if it is the initial page load or if it is a route change subject to the [default heuristic](/docs/browser/single-page-app-monitoring/use-spa-data/spa-data-collection#browser-interaction). You must call this method to override this behavior and guarantee the interaction will be recorded.
 
 ## Return values
 
@@ -59,7 +59,7 @@ window.addEventListener('scroll', () => {
   if (atBottomOfPage()) {
     newrelic.interaction() // Start monitoring this interaction.
       .setName('loadNextPage') // Set name of interaction.
-      .save(); // Ensure that this interaction will be saved as a BrowserInteraction event when it ends.
+      .save(); // Ensure that this interaction will be saved as a BrowserInteraction event when it ends, even if URL change and DOM modification did not occur.
     loadNextPage(); // Start loading the next page.
   }
 });

src/content/docs/browser/single-page-app-monitoring/get-started/introduction-single-page-app-monitoring.mdx

@@ -13,11 +13,11 @@ redirects:
 freshnessValidatedDate: never
 ---
 
-New Relic <InlinePopover type="browser"/> offers single-page application (SPA) monitoring to give you deeper visibility and actionable insights into real user interactions with single-page apps or any app that uses AJAX requests.
+New Relic <InlinePopover type="browser"/> offers single-page application (SPA) monitoring to give you deeper visibility and actionable insights into real user interactions with single-page apps.
 
-In addition to monitoring route changes automatically, our SPA API allows you to monitor virtually anything that executes inside the browser. Developers and their teams can use the API to:
+The SPA feature monitors [soft navigations](https://developer.chrome.com/docs/web-platform/soft-navigations-experiment#what_is_a_soft_navigation) automatically, and our SPA API allows you to modify the interactions. Developers and their teams can use the API to:
 
-* Create faster, more responsive, highly interactive apps.
+* Track user journeys through URL paths on their SPA.
 * Monitor the throughput and performance that real users are experiencing.
 * Troubleshoot and resolve problems within the context of the page load.
 * [Query your data](/docs/using-new-relic/data/understand-data/query-new-relic-data) to assist with business decisions.
@@ -33,7 +33,7 @@ For compatibility information about SPA-related features, see [SPA requirements]
 
 ## Analyze throughput and performance data [#spa-data]
 
-Improving on traditional industry standards for measuring page load timing, we give you a complete picture of the activity, both synchronous and asynchronous, associated with page loads and route changes.
+`BrowserInteraction` events drives the UI page views tab whenever SPA is enabled. Both the initial page load (hard nav) and route changes (soft navs) are shown.
 
 <img
   title="browser_SPA.png"
@@ -49,7 +49,6 @@ SPA data monitored by browser monitoring includes:
 
 * Performance data and throughput for page loads and route changes
 * AJAX request data
-* JavaScript activity, both synchronous and asynchronous
 * Dynamic page updates, monitored using the [SPA API](/docs/browser/new-relic-browser/browser-agent-spa-api)
 
 With this data, you will gain a clear understanding of how your users experience your app's page loads and route changes, and be able to solve bottlenecks and troubleshoot errors. For more about how New Relic handles SPA data, see [Understand SPA data collection](/docs/browser/single-page-app-monitoring/use-spa-data/understand-spa-data-collection).
@@ -82,7 +81,7 @@ Here is a summary of SPA monitoring features:
       </td>
 
       <td>
-        When a user initiates a page load or route change, New Relic begins to monitor all subsequent JavaScript, and ends the timing once all AJAX events are complete. This provides a more accurate view of when a page is actually ready for a user compared to the traditional method of ending the timing when the window load event is fired.
+        When a user initiates an interaction event, New Relic tracks the time until the url path changes and the next frame is repainted.
 
         When SPA monitoring is enabled, the [<DNT>**Page views**</DNT> page](/docs/browser/single-page-app-monitoring/browser-ui/view-spa-data-new-relic-browser) in browser shows event-driven data about application usage levels (throughput) and user experience (performance), including:
 
@@ -100,7 +99,7 @@ Here is a summary of SPA monitoring features:
       </td>
 
       <td>
-        [Metrics and events](/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer) supports three SPA-specific event types: [`BrowserInteraction`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#browserinteraction-attributes), [`AjaxRequest`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#ajaxrequest-attributes), and [`BrowserTiming`](/docs/insights/insights-data-sources/default-events-attributes/browser-default-events-attributes-insights#browsertiming-attributes). You can query these events in the [query builder](/docs/query-your-data/explore-query-data/query-builder/use-advanced-nrql-mode-specify-data) to analyze your app's performance and make business decisions.
+        [Metrics and events](/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer) supports two SPA-specific event types: [`BrowserInteraction`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#browserinteraction-attributes) and [`AjaxRequest`](/docs/insights/new-relic-insights/decorating-events/browser-default-attributes-insights#ajaxrequest-attributes). You can query these events in the [query builder](/docs/query-your-data/explore-query-data/query-builder/use-advanced-nrql-mode-specify-data) to analyze your app's performance and make business decisions.
       </td>
     </tr>
 
@@ -110,7 +109,7 @@ Here is a summary of SPA monitoring features:
       </td>
 
       <td>
-        Use [SPA API](/docs/browser/new-relic-browser/browser-agent-spa-api) to obtain the specific data you need, such as custom naming, custom timing, `finishline` API, or other custom attributes.
+        Use [SPA API](/docs/browser/new-relic-browser/browser-agent-spa-api) to obtain the specific data you need, such as custom naming, custom timing, or other custom attributes.
       </td>
     </tr>
   </tbody>