From 44f00867f5da4604e48627e08ef632ee3de1e37a Mon Sep 17 00:00:00 2001 From: Chunwai Li Date: Tue, 11 Mar 2025 15:37:41 -0500 Subject: [PATCH] Modify spa docs for soft nav feature --- .../browser-apis/createtracer.mdx | 2 +- .../new-relic-browser/browser-apis/end.mdx | 2 +- .../browser-apis/interaction.mdx | 63 +++++++++++-- .../new-relic-browser/browser-apis/save.mdx | 4 +- .../get-started/browser-spa-v2.mdx | 91 ------------------- ...ntroduction-single-page-app-monitoring.mdx | 15 ++- .../use-spa-data/spa-data-collection.mdx | 56 ++++-------- .../use-spa-data/view-spa-data-browser-ui.mdx | 16 +--- .../manage-data/manage-data-retention.mdx | 2 +- .../events-reported-browser-monitoring.mdx | 8 +- .../improve-customer-experience.mdx | 1 - src/nav/browser.yml | 5 - 12 files changed, 92 insertions(+), 173 deletions(-) delete mode 100644 src/content/docs/browser/single-page-app-monitoring/get-started/browser-spa-v2.mdx diff --git a/src/content/docs/browser/new-relic-browser/browser-apis/createtracer.mdx b/src/content/docs/browser/new-relic-browser/browser-apis/createtracer.mdx index 817bb7493d8..fbea1941129 100644 --- a/src/content/docs/browser/new-relic-browser/browser-apis/createtracer.mdx +++ b/src/content/docs/browser/new-relic-browser/browser-apis/createtracer.mdx @@ -17,7 +17,7 @@ freshnessValidatedDate: never --- - 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! ## Syntax diff --git a/src/content/docs/browser/new-relic-browser/browser-apis/end.mdx b/src/content/docs/browser/new-relic-browser/browser-apis/end.mdx index a811cd80955..34a3188088d 100644 --- a/src/content/docs/browser/new-relic-browser/browser-apis/end.mdx +++ b/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 diff --git a/src/content/docs/browser/new-relic-browser/browser-apis/interaction.mdx b/src/content/docs/browser/new-relic-browser/browser-apis/interaction.mdx index a49d4d447ea..3535746838b 100644 --- a/src/content/docs/browser/new-relic-browser/browser-apis/interaction.mdx +++ b/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. -* **New interaction:** If the API calls it when New Relic is not currently monitoring an interaction, a new interaction is created. -* **New object:** If the API calls it again within the same interaction, a new object referencing the current interaction is created. +* **New interaction:** 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. +* **New object:** 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. + + + + + + + + + + + + + +
+ Parameter + + Description +
+ `$options` + + _JSON object_ + + 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. +
## 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. +``` \ No newline at end of file diff --git a/src/content/docs/browser/new-relic-browser/browser-apis/save.mdx b/src/content/docs/browser/new-relic-browser/browser-apis/save.mdx index 805a4e660ac..94d73c43e9a 100644 --- a/src/content/docs/browser/new-relic-browser/browser-apis/save.mdx +++ b/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. } }); diff --git a/src/content/docs/browser/single-page-app-monitoring/get-started/browser-spa-v2.mdx b/src/content/docs/browser/single-page-app-monitoring/get-started/browser-spa-v2.mdx deleted file mode 100644 index 01bfc2d66dd..00000000000 --- a/src/content/docs/browser/single-page-app-monitoring/get-started/browser-spa-v2.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Browser SPA monitoring 2.0 -metaDescription: "The new browser SPA monitoring capability is a streamlined way to monitor your users' experience and app performance." -freshnessValidatedDate: 2024-09-04 ---- - - - This feature is in public preview. It will eventually replace the existing browser SPA experience. - - -For customers monitoring browser single page applications (SPA), we're excited to announce an overhaul of our SPA monitoring functionality, meant to address numerous pain points: - -* Unusable latest versions: Frequent conflicts with third-party libraries and unreliable interaction capture plagued the existing agent, often rendering the latest version unusable. -* Patchwork solutions: Addressing one issue with SPA patches often introduced another, creating a frustrating cycle of fixes and regressions. -* Third-party library conflicts: Global wrapping, particularly around `Promises`, often disrupted code functionality due to conflicts with other libraries. -* Performance bottlenecks: Conflicts with code using timers, RAF, and promise chaining led to performance issues, ranging from slowdowns to freezes. - -The updated SPA monitoring experience is designed to eliminate these problems and provide a significantly improved monitoring experience. Key changes include: - -* Unwrapped execution: By not wrapping core globals, the new SPA experience unleashes execution speed boosts for your application. -* Aligned with soft navigation heuristics: The new experience adopts Google Chrome's soft navigation, providing more accurate interaction tracking and improved alignment with browser behavior. -* Simplified interaction determination: Interactions are now defined as a UI event (click/keydown/submit -> route change -> DOM modification), offering a clearer and more efficient capture approach. - * Potential event disassociation: You might observe previously associated `AjaxRequest` and `JavascriptError` events becoming disassociated from interactions, reflecting the focus on UI-driven interactions. -* Focus on key metrics: While reported data remains largely unchanged, the new experience no longer tracks JavaScript execution or callback duration within interactions, streamlining the reported information. -* Reduced interaction durations: Expect significantly shorter interaction durations, particularly for route changes. Initial page loads will see a slight reduction. -* API updates: - * New optional argument `.interaction({waitForEnd: true})` added to the [`.interaction()`](/docs/browser/new-relic-browser/browser-apis/interaction/) function: This allows customization of user interaction end time. The existing `.interaction()` functionality remains unchanged. - * Deprecated API: The function [`createTracer`](/docs/browser/new-relic-browser/browser-apis/createtracer/): While still functional, the `createTracer` function is deprecated as it no longer keeps interactions open or times callbacks. Note: If you continue to use `createTracer` with the new SPA experience,`BrowserTiming` events will not be created. - -## Try out the new browser SPA monitoring experience [#enable-feature] - - - - - ### Review the requirements [#review-requirements] - - This feature is tested and supported in line with our standard [browser support statement](https://docs.newrelic.com/docs/release-notes/new-relic-browser-release-notes/browser-agent-release-notes/#support-statement). - - - - - - ### Add the feature flag [#add-feature-flag] - - If your agent was installed with the APM method, contact our support team and we'll enable the feature flag on your account. - - If your agent was installed with NPM or the UI-based, copy/paste method, add the following feature flag your browser agent code: - - 1. Find the New Relic browser agent code in your webpage HTML. - - 2. In the `init` configuration object, add the `soft_nav` feature flag. Here's an example: - - ```js -