[all hosts] (Initialization) Document browser state method null workaround (#4991)

AlexJerabek · web-flow · commit a606f8a84c03 · 2025-01-15T08:31:02.000-08:00
* Document browser state method null workaround

* Add Stack credit
diff --git a/docs/develop/referencing-the-javascript-api-for-office-library-from-its-cdn.md b/docs/develop/referencing-the-javascript-api-for-office-library-from-its-cdn.md
@@ -1,7 +1,7 @@
 ---
 title: Referencing the Office JavaScript API library
 description: Learn how to reference the Office JavaScript API library and type definitions in your add-in.
-ms.date: 01/07/2025
+ms.date: 01/14/2025
 ms.localizationpriority: medium
 ---
 
@@ -21,6 +21,31 @@ This will download and cache the Office JavaScript API files the first time your
 > [!IMPORTANT]
 > You must reference the Office JavaScript API from inside the `<head>` section of the page to ensure that the API is fully initialized prior to any body elements.
 
+## Office.js-specific web API behavior
+
+Office.js replaces the default [Window.history](https://developer.mozilla.org/docs/Web/API/History) methods of `replaceState` and `pushState` with `null`. This is done to [support older Microsoft webviews and Office versions](support-ie-11.md). If your add-in relies on these methods and doesn't need to run on Office versions that use the Internet Explorer 11 browser control, replace the Office.js library reference with the following workaround.
+
+```HTML
+<script type="text/javascript">
+    // Cache the history method values.
+    window._historyCache = {
+        replaceState: window.history.replaceState,
+        pushState: window.history.pushState
+    };
+</script>
+
+<script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
+
+<script type="text/javascript">
+    // Restore the history method values after loading Office.js
+    window.history.replaceState = window._historyCache.replaceState;
+    window.history.pushState = window._historyCache.pushState;
+</script>
+
+```
+
+Thank you to [@stepper and the Stack Overflow community](https://stackoverflow.com/questions/42642863/office-js-nullifies-browser-history-functions-breaking-history-usage) for suggesting and verifying this workaround.
+
 ## API versioning and backward compatibility
 
 In the previous HTML snippet, the `/1/` in front of `office.js` in the CDN URL specifies the latest incremental release within version 1 of Office.js. Because the Office JavaScript API maintains backward compatibility, the latest release will continue to support API members that were introduced earlier in version 1.
