ApplicationInsights-JS/docs/upgrade/v3_BreakingChanges.md

V3.x Upgrade Breaking Changes (from v2.x))

Some of the major changes include

• Added support for dynamic (reactive) configuration changes after initialization
• Removed ES3 / IE8 Support, now only supports ES5 / IE9+
• Removed V1 API Backward Compatibility, Upgrading from V1 -> V3 is NOT supported and will require code changes in your application if you use the previous V1 API functions
• Requires Object.defineProperty support, the SDK now uses Object.defineProperty quite heavily and therefore support is limited to runtimes correctly implement this functionality. Without this the SDK will not function correctly.
• Many (mostly unused) exports from the NPM packages have been removed.

This document has attempted to identify all of the major breaking and behavior changes, it may be incomplete. If you encounter an issue that has not been documented please create an issue and we will review to determine whether this was unexpected and should be fixed or if it needs to be documented.

Extensions build for v2.x

If the extension is 100% self contained (all referenced code is included in it's own bundle), then apart from some TypeScript typing warnings / errors the SDK will load and initialize the plugin. It will most likely not support some of the newer functionality like dynamic configuration changes, complete unloading and removal.

However, for any extensions that contain references to the core components (import / require) the core components WILL likely not work with the v3.x (because of the breaking changes) and will need to be updated to use the external helpers or the alternate functions.

Removed ES3 (IE8) Support

Previous internal polyfills for JavaScript features that are supported by ES5 are no longer included.

As part of packaging ES3 reserved word usage ("catch") is not longer wrapped, this WILL cause the SDK to fail to load in an ES3 environment.

The SDK still uses internal polyfills for ES5 features that are not supported by IE9-11 (like. Symbol).

If your application is required to maintain support for IE8 (ES3) you WILL need to continue to use the latest v2.x (Supported) releases.

Configuration changes

Configuration	Change
enableDebugExceptions	This configuration has been removed and now only enableDebug is not used, as previously documented for v2

Behavior changes

Function	Change
strStartsWith	This is now uses the native startsWith or a polyfill if required that conforms the same functionality which will throw a TypeError for null, undefined values
strEndsWith	This is now uses the native endsWith or a polyfill if required that conforms the same functionality which will throw a TypeError for null, undefined values

IAppInsightsCore	Details
pollInternalLogs()	This now returns an ITimerHandler interface with a cancel() function rather than the number returned from the setInternal(). It is also now called automatically at the end of core initialize rather than being explicitly called via snippet initialization and loadAppInsights, this is a minor execution order change.

AISKU

• V1 Snippet Usage
• All V1 API Compatibility Support

V1 API	Details
trackPageView	Use V2 API trackPageView(pageView?: IPageViewTelemetry) V1 Removed track(name?: string, url?: string, properties?: {[key: string]: string }, measurements?: {[key: string]: number }, duration?: number)
trackEvent	Use V2 API trackEvent(event: IEventTelemetry, customProperties?: ICustomProperties) V1 Removed trackEvent(name: string, properties?: Object, measurements?: Object)
trackDependency	Use V2 API trackDependencyData(dependency: IDependencyTelemetry) V1 Removed trackDependency(id: string, method: string, absoluteUrl: string, pathName: string, totalTime: number, success: boolean, resultCode: number)
trackException	Use V2 API trackException(exception: IExceptionTelemetry, customProperties?: ICustomProperties) V1 Removed trackException(exception: Error, handledAt?: string, properties?: { [name: string]: string; }, measurements?: { [name: string]: number; }, severityLevel?: any)
trackMetric	Use V2 API trackMetric(metric: IMetricTelemetry, customProperties?: ICustomProperties) V1 Removed trackMetric(name: string, average: number, sampleCount?: number, min?: number, max?: number, properties?: { [name: string]: string; })
trackTrace	Use V2 API trackTrace(trace: ITraceTelemetry, customProperties?: ICustomProperties) V1 Removed trackTrace(message: string, properties?: { [name: string]: string; }, severityLevel?: any)
_onerror	Use V2 API _onerror(exception: IAutoExceptionTelemetry) V1 Removed _onerror(message: string, url: string, lineNumber: number, columnNumber: number, error: Error)
downloadAndSetup	Removed

Exported Globals (NPM)

• Telemetry
• ICoreUtils; CoreUtils
• IUtil; Util
• ICorrelationIdHelper
• IUrlHelper
• IDateTimeUtils
• DataSanitizer (from common module)
• IDataSanitizer (from common module)

Exported Globals (CDN)

The previously exported namespaced globals have been replaced with a reduced set of individual functions (Which where also exported by v2.8.x)

Note: Until the final release all of these "Removed" or "New Access" are subject to be changed. You should not be using the published beta for validation purposes and not in a production environment.

Previous CDN namespace / access		Replacement new access
Microsoft.ApplicationInsights.Telemetry		Removed
	BreezeChannelIdentifier	Microsoft.ApplicationInsights.BreezeChannelIdentifier
	PropertiesPluginIdentifier	Microsoft.ApplicationInsights.PropertiesPluginIdentifier
	AnalyticsPluginIdentifier	Microsoft.ApplicationInsights.AnalyticsPluginIdentifier
	DisabledPropertyName	Microsoft.ApplicationInsights.DisabledPropertyName
	ProcessLegacy	Removed
	SampleRate	"sampleRate"
	HttpMethod	"http.method"
	DEFAULT_BREEZE_ENDPOINT	Microsoft.ApplicationInsights.DEFAULT_BREEZE_ENDPOINT
Microsoft.ApplicationInsights.Telemetry.Util		Removed
	NotSpecified	Removed
	createDomEvent	Removed
	disableStorage	Removed
	isInternalApplicationInsightsEndpoint	Removed
	canUseLocalStorage	Removed
	getStorage	Removed
	setStorage	Removed
	removeStorage	Removed
	canUseSessionStorage	Removed
	getSessionStorageKeys	Removed
	getSessionStorage	Removed
	setSessionStorage	Removed
	removeSessionStorage	Removed
	disableCookies	Removed
	canUseCookies	Removed
	disallowsSameSiteNone	Removed
	setCookie	Removed
	stringToBoolOrDefault	Removed
	getCookie	Removed
	deleteCookie	Removed
	trim	Removed
	newId	Microsoft.ApplicationInsights.newId
	random32	Microsoft.ApplicationInsights.random32
	generateW3CId	Microsoft.ApplicationInsights.generateW3CId
	isArray	Removed
	isError	Removed
	isDate	Removed
	toISOStringForIE8	Removed
	getIEVersion	Removed
	msToTimeSpan	Removed
	isCrossOriginError	Removed
	dump	Removed
	getExceptionName	Removed
	addEventHandler	Microsoft.ApplicationInsights.addEventHandler
	removeEventHandler	Microsoft.ApplicationInsights.removeEventHandler
	IsBeaconApiSupported	Microsoft.ApplicationInsights.IsBeaconApiSupported
	getExtension	appInsights.getPlugin("<plugin id>")?.plugin
Microsoft.ApplicationInsights.Telemetry.CorrelationIdHelper		Removed
Microsoft.ApplicationInsights.Telemetry.UrlHelper		Removed
Microsoft.ApplicationInsights.Telemetry.DateTimeUtils		Removed
Microsoft.ApplicationInsights.Telemetry.ConnectionStringParser		Removed
Microsoft.ApplicationInsights.Telemetry.FieldType (enum)		Removed
Microsoft.ApplicationInsights.Telemetry.RequestHeaders (enum)		Microsoft.ApplicationInsights.RequestHeaders
Microsoft.ApplicationInsights.Telemetry.Envelope (class)		Removed
Microsoft.ApplicationInsights.Telemetry.Event (class)		Removed
Microsoft.ApplicationInsights.Telemetry.Exception (class)		Removed
Microsoft.ApplicationInsights.Telemetry.Metric (class)		Removed
Microsoft.ApplicationInsights.Telemetry.PageView (class)		Removed
Microsoft.ApplicationInsights.Telemetry.RemoteDependencyData (class)		Removed
Microsoft.ApplicationInsights.Telemetry.Trace (class)		Removed
Microsoft.ApplicationInsights.Telemetry.PageViewPerformance (class)		Removed
Microsoft.ApplicationInsights.Telemetry.Data (class)		Removed
Microsoft.ApplicationInsights.Telemetry.SeverityLevel (enum)		Microsoft.ApplicationInsights.SeverityLevel
Microsoft.ApplicationInsights.Telemetry.ConfigurationManager (class)		Removed
Microsoft.ApplicationInsights.Telemetry.ContextTagKeys (class)		Removed
Microsoft.ApplicationInsights.Telemetry.DataSanitizer		Removed
Microsoft.ApplicationInsights.Telemetry.TelemetryItemCreator		Removed
Microsoft.ApplicationInsights.Telemetry.CtxTagKeys		Removed
Microsoft.ApplicationInsights.Telemetry.Extensions (enum)		Removed
Microsoft.ApplicationInsights.Telemetry.DistributedTracingMode (enum)		Microsoft.ApplicationInsights.DistributedTracingMode
Microsoft.ApplicationInsights.Util		Removed: see Microsoft.ApplicationInsights.Telemetry.Util

AISKU Light

V2 API Changes

V1 API	Details
getSKUDefaults	Removed in V2

Exported Globals

• CoreUtils

@microsoft/applicationinsights-common

Exported Globals (NPM)

• IUtil; Util
  • Use the individual utl prefixed functions that are also exported in later v2 releases documented in the Tree Shaking Recommendations.
• ICorrelationIdHelper; CorrelationIdHelper
  • Use the individual correlationId prefixed functions that are also exported in later v2 releases documented in the Tree Shaking Recommendations.
• IDateTimeUtils; DateTimeUtils;
  • Use the individual dateTimeUtils prefixed functions that are also exported in later v2 releases documented in the Tree Shaking Recommendations.
• IUrlHelper; UrlHelper
  • Use the individual url prefixed functions that are also exported in later v2 releases documented in the Tree Shaking Recommendations.
• IDataSanitizer, DataSanitizer
  • Use the individual dataSanitizer prefixed functions that are also exported in later v2 releases documented in the Tree Shaking Recommendations.

@microsoft/applicationinsights-core-js

All previously @deprecated marked functions and the legacy "global" cookie handling functions

Exported Globals (NPM)

• BaseCore
  • Use AppInsightsCore (AppInsightsCore and BaseCore are now merged)
• ICoreUtils; CoreUtils
  • See the replacements documented in the Tree Shaking Recommendations.
• IEventHelper; EventHelper
  • See the replacements documented in the Tree Shaking Recommendations.
• EnumMap, createEnumMap
  • Removed as not used internally, use the ts-utils support versions if required -hasOwnProperty()
  • use objHasOwnProperty()

Exposed Runtime configuration values

• config.extensionConfig.NotificationManager In eariler versions this was assigned to the current notification manager, this is now removed
  • You can access the current notification manager via core.getNotifyMgr() which is more reliable as it will lazily create an instance if one is currently not assigned.

Removed no replacement

Functions

• disableCookies
• canUseCookies
• getCookie
• setCookie
• deleteCookie
• _legacyCookieMgr

Classes

• BaseCore

Browser Support

Minimum JavaScript Language Specification: ES5

Latest ✔	Latest ✔	9+ Full ✔	Latest ✔	Latest ✔

Note: ES3/IE8 compatibility has been removed, so if you need to retain ES3 compatibility you will need to remain on the 2.x.x versions of the SDK.