|
| 1 | +# Page Unload Event Handling |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +## Unload Events |
| 8 | + |
| 9 | +The SDK listens to the following events to detect when a page is being unloaded: |
| 10 | + |
| 11 | +1. **beforeunload** - Fired when the window, document, and its resources are about to be unloaded |
| 12 | +2. **unload** - Fired when the document or a child resource is being unloaded |
| 13 | +3. **pagehide** - Fired when the browser hides the current page in the process of navigating to another page |
| 14 | +4. **visibilitychange** (with 'hidden' state) - Fired when the content of a tab has become visible or hidden |
| 15 | + |
| 16 | +## Modern Browser Compatibility |
| 17 | + |
| 18 | +Modern browsers and frameworks are deprecating or changing how some page unload events work: |
| 19 | + |
| 20 | +- **jQuery 3.7.1+** has deprecated the use of the `unload` event, showing warning messages when it's used. |
| 21 | +- Some modern browsers are changing the behavior of `beforeunload` event for better performance and reduced tracking potential. |
| 22 | +- The `pagehide` event and `visibilitychange` events are becoming the recommended alternatives. |
| 23 | +- 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. |
| 24 | + |
| 25 | +## Configuration Options |
| 26 | + |
| 27 | +The SDK provides configuration options to control which page lifecycle events are used: |
| 28 | + |
| 29 | +### disablePageUnloadEvents |
| 30 | + |
| 31 | +This configuration option allows you to specify which page unload events should not be used by the SDK. |
| 32 | + |
| 33 | +**TypeScript Example:** |
| 34 | +```typescript |
| 35 | +import { ApplicationInsights } from '@microsoft/applicationinsights-web'; |
| 36 | + |
| 37 | +const appInsights = new ApplicationInsights({ |
| 38 | + config: { |
| 39 | + connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', |
| 40 | + disablePageUnloadEvents: ["unload"], |
| 41 | + /* ...Other Configuration Options... */ |
| 42 | + } |
| 43 | +}); |
| 44 | +``` |
| 45 | + |
| 46 | +**Important notes**: |
| 47 | + |
| 48 | +- The SDK requires at least one functioning page unload event to ensure telemetry is sent when the page is closed. |
| 49 | +- 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. |
| 50 | +- This option is especially useful for avoiding jQuery 3.7.1+ deprecation warnings by excluding the "unload" event. |
| 51 | + |
| 52 | +### disablePageShowEvents |
| 53 | + |
| 54 | +Similarly, this configuration option controls which page show events are not used by the SDK. Page show events include: |
| 55 | + |
| 56 | +1. **pageshow** - Fired when a page is shown, or when navigating to a page using browser's back/forward functionality |
| 57 | +2. **visibilitychange** (with 'visible' state) - Fired when a tab becomes visible |
| 58 | + |
| 59 | +**TypeScript Example:** |
| 60 | +```typescript |
| 61 | +import { ApplicationInsights } from '@microsoft/applicationinsights-web'; |
| 62 | + |
| 63 | +const appInsights = new ApplicationInsights({ |
| 64 | + config: { |
| 65 | + connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', |
| 66 | + disablePageShowEvents: ["pageshow"], |
| 67 | + /* ...Other Configuration Options... */ |
| 68 | + } |
| 69 | +}); |
| 70 | +``` |
| 71 | + |
| 72 | +## Fallback Mechanism |
| 73 | + |
| 74 | +The SDK implements a robust fallback mechanism to ensure that telemetry can be sent before the page unloads: |
| 75 | + |
| 76 | +1. The SDK first tries to use all available unload events except those listed in `disablePageUnloadEvents`. |
| 77 | +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. |
| 78 | +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. |
| 79 | +4. The SDK includes internal logic to detect when hooked events aren't firing as expected and will utilize alternative approaches to send telemetry. |
| 80 | +5. This ensures that critical telemetry data is always sent, even in constrained environments or when browser implementations change. |
| 81 | + |
| 82 | +## Use Cases |
| 83 | + |
| 84 | +### Avoiding jQuery 3.7.1+ Deprecation Warnings |
| 85 | + |
| 86 | +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: |
| 87 | + |
| 88 | +**TypeScript Example:** |
| 89 | +```typescript |
| 90 | +import { ApplicationInsights } from '@microsoft/applicationinsights-web'; |
| 91 | + |
| 92 | +const appInsights = new ApplicationInsights({ |
| 93 | + config: { |
| 94 | + connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', |
| 95 | + // Disable the deprecated 'unload' event to avoid jQuery deprecation warnings |
| 96 | + disablePageUnloadEvents: ["unload"], |
| 97 | + } |
| 98 | +}); |
| 99 | +``` |
| 100 | + |
| 101 | +### Optimizing for Modern Browsers |
| 102 | + |
| 103 | +For the best experience in modern browsers, you might want to prioritize newer events: |
| 104 | + |
| 105 | +**TypeScript Example:** |
| 106 | +```typescript |
| 107 | +import { ApplicationInsights } from '@microsoft/applicationinsights-web'; |
| 108 | + |
| 109 | +const appInsights = new ApplicationInsights({ |
| 110 | + config: { |
| 111 | + connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', |
| 112 | + // Use only modern events |
| 113 | + disablePageUnloadEvents: ["unload", "beforeunload"], |
| 114 | + } |
| 115 | +}); |
| 116 | +``` |
| 117 | + |
| 118 | +Note that the SDK will still use an older event if none of the modern events are supported in the browser environment. |
| 119 | + |
| 120 | +### Using Both Configuration Options Together |
| 121 | + |
| 122 | +You can configure both unload and show events simultaneously for fine-grained control: |
| 123 | + |
| 124 | +**TypeScript Example:** |
| 125 | +```typescript |
| 126 | +import { ApplicationInsights } from '@microsoft/applicationinsights-web'; |
| 127 | + |
| 128 | +const appInsights = new ApplicationInsights({ |
| 129 | + config: { |
| 130 | + connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE', |
| 131 | + // Disable specific unload events |
| 132 | + disablePageUnloadEvents: ["unload"], |
| 133 | + // Disable specific show events |
| 134 | + disablePageShowEvents: ["pageshow"], |
| 135 | + } |
| 136 | +}); |
| 137 | +``` |
| 138 | + |
| 139 | +### Progressive Enhancement |
| 140 | + |
| 141 | +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. |
0 commit comments