Merge pull request #7005 from segmentio/prigiattiperrut-patch-4

Support for Multiple Versions of Analytics.js

Author: forstisabella

src/connections/sources/catalog/libraries/website/javascript/troubleshooting.md

@@ -22,16 +22,30 @@ Segment also provides a Chrome web extension, [Segment Inspector](/docs/connecti
 
 To learn more, follow the [Analytics.js Quickstart Guide](/docs/connections/sources/catalog/libraries/website/javascript/quickstart/).
 
-## Are you loading two instances of Analytics.js?
+## Loading multiple instances of Analytics.js
 
-Note that you *cannot* load Analytics.js twice on the same page, even if you're using different write keys. If you do, you might encounter `Uncaught RangeError: Maximum call stack size exceeded`. Instead, you can conditionally set the write key based on an environment variable.
+
+### Analytics.js snippet loaded more than once
+
+You cannot load the Analytics.js snippet twice on the same page, even if different write keys are used. Doing so might result in errors like `Uncaught RangeError: Maximum call stack size exceeded`. 
+
+However, you can conditionally set the write key based on an environment variable:
 
 Example:
 ```js
 var writeKey;
 ENV === 'production' ? writeKey = 'A' : writeKey = 'B';
 ```
 
+### Multiple Versions of Analytics.js
+
+You can load multiple versions of Analytics.js in the same environment. For example, you could have both a snippet version and an npm version on one page, each with different write keys. This allows the npm library and the browser snippet to coexist without conflicting. 
+
+Keep the following limitations in mind:
+
+- **Device-Mode Destination Conflicts**: If you are using the same device-mode destination in both instances (for example, across different write keys), conflicts may occur. This is due to third-party scripts that don't support global instances. To avoid issues, ensure you are not using the same device-mode destination with different write keys.
+- **CDN URL Customization:** Segment does not support overriding the CDNURL when using multiple instances of Analytics.js.
+
 ## How do I resolve the 'Failed to Load Analytics.js ChunkLoadError'?
 
 The error can occur for different reasons:
@@ -44,6 +58,7 @@ The error can occur for different reasons:
 
 - Cloudflare caching: If you use Cloudflare to proxy Segment, disable caching for the Segment JS file.
 
+
 ## Do you see events appear in your debugger?
 
 When you reload the page, does your debugger show a new [Page call](/docs/connections/spec/page)? You can also check the JavaScript console in the browser and manually fire an event, like an Identify call, which would show up in the debugger.