-
Notifications
You must be signed in to change notification settings - Fork 255
Add documentation for disablePageUnloadEvents to address jQuery 3.7.1 deprecation warnings #2533
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
19 commits
Select commit
Hold shift + click to select a range
1a68c56
Initial plan for issue
Copilot 016492b
Add documentation for disablePageUnloadEvents to address jQuery 3.7.1…
Copilot 8e317df
Add detailed documentation for disablePageUnloadEvents in docs folder
Copilot c4d3fe2
Update documentation URLs and add TypeScript examples for page events…
Copilot e358348
Update documentation for disablePageUnloadEvents and disablePageShowE…
Copilot 8784a57
Add @example tag to TypeDoc for disablePageUnloadEvents and disablePa…
Copilot e344656
Add PageUnloadEvents.html link to docs/README.md FAQ section
Copilot 499ca51
Update disablePageUnloadEvents and disablePageShowEvents links to use…
Copilot 49cf4ee
Remove unnecessary lines and "Example usage:" heading
Copilot 0e3b129
Update PageUnloadEvents link to use relative markdown path
Copilot 5ec545b
Add details about handling missing events in PageUnloadEvents.md
Copilot 7a1ac27
Update disablePageUnloadEvents and disablePageShowEvents with TypeDoc…
Copilot a9c0fef
Update disablePageUnloadEvents and disablePageShowEvents links to 1ds…
Copilot 3f1ce44
Remove JavaScript examples from PageUnloadEvents.md
Copilot 27c9800
Clarify Page Unload and Visibility Event Handling section in README.md
Copilot b90a7dd
Update README.md to clarify page unload event handling description
Copilot ac6106d
Merge branch 'main' into copilot/fix-2508
MSNev 2812a59
Fix failing tests by correcting AITestClass import in Es5Rollup.Tests.ts
Copilot 54b5570
Revert to using "@microsoft/ai-test-framework" as requested
Copilot File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,141 @@ | ||
| # Page Unload Event Handling | ||
MSNev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Overview | ||
|
|
||
| Application Insights Web SDK tracks several page lifecycle events to ensure that telemetry data is sent before a page is unloaded, helping to prevent data loss during page navigation or browser closure. The SDK hooks into different unload and visibility change events depending on the browser environment. | ||
|
|
||
| ## Unload Events | ||
|
|
||
| The SDK listens to the following events to detect when a page is being unloaded: | ||
|
|
||
| 1. **beforeunload** - Fired when the window, document, and its resources are about to be unloaded | ||
| 2. **unload** - Fired when the document or a child resource is being unloaded | ||
| 3. **pagehide** - Fired when the browser hides the current page in the process of navigating to another page | ||
| 4. **visibilitychange** (with 'hidden' state) - Fired when the content of a tab has become visible or hidden | ||
|
|
||
| ## Modern Browser Compatibility | ||
|
|
||
| Modern browsers and frameworks are deprecating or changing how some page unload events work: | ||
|
|
||
| - **jQuery 3.7.1+** has deprecated the use of the `unload` event, showing warning messages when it's used. | ||
| - Some modern browsers are changing the behavior of `beforeunload` event for better performance and reduced tracking potential. | ||
| - The `pagehide` event and `visibilitychange` events are becoming the recommended alternatives. | ||
| - The SDK is designed to handle cases where certain events are unavailable or behave differently across browsers, gracefully adapting to the environment to ensure telemetry is sent. | ||
|
|
||
MSNev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ## Configuration Options | ||
|
|
||
| The SDK provides configuration options to control which page lifecycle events are used: | ||
|
|
||
| ### disablePageUnloadEvents | ||
|
|
||
| This configuration option allows you to specify which page unload events should not be used by the SDK. | ||
|
|
||
| **TypeScript Example:** | ||
| ```typescript | ||
| import { ApplicationInsights } from '@microsoft/applicationinsights-web'; | ||
|
|
||
| const appInsights = new ApplicationInsights({ | ||
| config: { | ||
| connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', | ||
| disablePageUnloadEvents: ["unload"], | ||
| /* ...Other Configuration Options... */ | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| **Important notes**: | ||
|
|
||
| - The SDK requires at least one functioning page unload event to ensure telemetry is sent when the page is closed. | ||
| - If all events are listed in `disablePageUnloadEvents` or if the only working events in the current browser environment are the ones you've disabled, the SDK will still use one of them to ensure functionality. | ||
| - This option is especially useful for avoiding jQuery 3.7.1+ deprecation warnings by excluding the "unload" event. | ||
|
|
||
| ### disablePageShowEvents | ||
|
|
||
| Similarly, this configuration option controls which page show events are not used by the SDK. Page show events include: | ||
|
|
||
| 1. **pageshow** - Fired when a page is shown, or when navigating to a page using browser's back/forward functionality | ||
| 2. **visibilitychange** (with 'visible' state) - Fired when a tab becomes visible | ||
|
|
||
| **TypeScript Example:** | ||
| ```typescript | ||
| import { ApplicationInsights } from '@microsoft/applicationinsights-web'; | ||
|
|
||
| const appInsights = new ApplicationInsights({ | ||
| config: { | ||
| connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', | ||
| disablePageShowEvents: ["pageshow"], | ||
| /* ...Other Configuration Options... */ | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| ## Fallback Mechanism | ||
|
|
||
| The SDK implements a robust fallback mechanism to ensure that telemetry can be sent before the page unloads: | ||
|
|
||
| 1. The SDK first tries to use all available unload events except those listed in `disablePageUnloadEvents`. | ||
| 2. If no events can be registered (either because all are disabled or not supported), the SDK will ignore the `disablePageUnloadEvents` setting and force registration of at least one event. | ||
| 3. Even when the SDK attempts to hook events that may be missing in certain browsers, it's designed to gracefully handle these cases without errors. | ||
| 4. The SDK includes internal logic to detect when hooked events aren't firing as expected and will utilize alternative approaches to send telemetry. | ||
| 5. This ensures that critical telemetry data is always sent, even in constrained environments or when browser implementations change. | ||
|
|
||
| ## Use Cases | ||
|
|
||
| ### Avoiding jQuery 3.7.1+ Deprecation Warnings | ||
|
|
||
| If you're using jQuery 3.7.1 or newer, you'll encounter deprecation warnings when the 'unload' event is used. Configure the SDK to not use this deprecated event: | ||
|
|
||
| **TypeScript Example:** | ||
| ```typescript | ||
| import { ApplicationInsights } from '@microsoft/applicationinsights-web'; | ||
|
|
||
| const appInsights = new ApplicationInsights({ | ||
| config: { | ||
| connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', | ||
| // Disable the deprecated 'unload' event to avoid jQuery deprecation warnings | ||
| disablePageUnloadEvents: ["unload"], | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| ### Optimizing for Modern Browsers | ||
|
|
||
| For the best experience in modern browsers, you might want to prioritize newer events: | ||
|
|
||
| **TypeScript Example:** | ||
| ```typescript | ||
| import { ApplicationInsights } from '@microsoft/applicationinsights-web'; | ||
|
|
||
| const appInsights = new ApplicationInsights({ | ||
| config: { | ||
| connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', | ||
| // Use only modern events | ||
| disablePageUnloadEvents: ["unload", "beforeunload"], | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| Note that the SDK will still use an older event if none of the modern events are supported in the browser environment. | ||
|
|
||
| ### Using Both Configuration Options Together | ||
|
|
||
| You can configure both unload and show events simultaneously for fine-grained control: | ||
|
|
||
| **TypeScript Example:** | ||
| ```typescript | ||
| import { ApplicationInsights } from '@microsoft/applicationinsights-web'; | ||
|
|
||
| const appInsights = new ApplicationInsights({ | ||
| config: { | ||
| connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', | ||
| // Disable specific unload events | ||
| disablePageUnloadEvents: ["unload"], | ||
| // Disable specific show events | ||
| disablePageShowEvents: ["pageshow"], | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| ### Progressive Enhancement | ||
|
|
||
| The SDK's approach to page lifecycle events reflects a progressive enhancement strategy, ensuring that telemetry works across diverse browser environments while offering configuration options for optimal behavior in modern contexts. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This new section is really confusing, visibility state is mentioned here, what does it mean? like what it was being displayed in the page?, for which telemetry types that is relevant?, what is this config actually doing? is it only for removing warnings or is it actually changing the way the telemetry is captured?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
After reading the actual new doc this make sense, but before that this text should be clear enough, this is in main readme so it should be as simple as possible
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've updated the section to clarify what "visibility state" means, explain which telemetry types are affected (all types), and describe what these configuration options actually do beyond just removing warnings. The explanation now includes details about how these events are used by the SDK for flushing telemetry and preventing data loss during page navigation or tab/browser closure. These changes are in commit 27c9800.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've updated the README.md section with clearer language that explains what these configurations do and why they matter. The updated section now explicitly describes what "visibility state" means, explains which telemetry types are affected, and clarifies that these options control when telemetry data is flushed during page navigation. These changes are in commit 27c9800.