GITBOOK-5: Initial V16 breaking changes

Author: cornehoskam

16/umbraco-engage/upgrading/version-specific-upgrade-notes.md

@@ -1,37 +1,37 @@
 ---
-description: Version-specific documentation for upgrading to new major versions of Umbraco Engage.
+description: >-
+  Version-specific documentation for upgrading to new major versions of Umbraco
+  Engage.
 ---
 
-# Version Specific Upgrade Notes
+# Version specific Upgrade Notes
 
-This article provides specific upgrade instructions for migrating to major version of Umbraco Engage
+This article provides specific upgrade instructions and breaking changes introduced when migrating from major version 13 of Umbraco Engage to version 16.
 
 {% hint style="info" %}
 When upgrading to a new minor or patch version, learn about the changes in the [Release Notes](../release-notes.md) article.
 {% endhint %}
 
 ## Breaking changes
-#### v13.2.0 (Umbraco Engage) & v13.1.0 (Umbraco Engage Forms)
-Introduced Razor Class Library support to serve static files for Engage, removing physical backoffice, views, and assets files from development projects.
 
-While this is not considered a breaking change, it is recommended that such folders be removed from the project to avoid conflicts in the future.
+### v16.0.0 (Umbraco Engage v16 Launch)
 
-The following folders should be manually removed from your project upon updating Umbraco Engage:
+With the introduction of Engage version 16, several breaking changes have been introduced to accommodate the transitions between multiple major versions of the core CMS.
 
-  * `App_Plugins\Umbraco.Engage`
-  * `Assets\Umbraco.Engage`
-  * `Views\Partials\Umbraco.Engage`
+#### Clientside Analytics
 
-The same changes apply to the Forms add-on `Umbraco.Engage.Forms`.
+Engage includes various optional scripts that can be included in the front-end, which interact with various API endpoints. Some of these endpoints have changed. If any firewall rules are in place involving the front-end reaching Umbraco APIs, the following paths need to be allowed through:
 
-The following folder should be manually removed from your project upon updating Umbraco Engage Forms:
+```
+/umbraco/engage/pagedata/collect
+/umbraco/engage/pagedata/collect-event
+/umbraco/engage/pagedata/ping
+```
 
-  * `App_Plugins\Umbraco.Engage.Forms`
+#### Umbraco Member Detection & Storage
 
-Health checks have been added to verify whether these folders are present in your project. If they are, you will receive a warning in the Health Check dashboard.
+The detection and storage of logged-in Umbraco Members have changed significantly between versions 13 and 16 of Engage. In older versions of v13, any kind of login claim would be detected as a valid member, causing the visitor to be marked as 'Identified' and get linked to any member claim ID. This has changed over various minor versions of v13 to only allow for Umbraco Members to prevent other login methods from interfering with Engage. 
 
-#### v13.0.0 (Umbraco Engage Launch)
+Engage v16 will strictly enforce the storage of Umbraco Members only, attempting to update any existing pageview data that detects a logged-in member.  This migration includes switching from integer IDs to GUID keys, validating the GUIDs against the existing Umbraco Members, and enforcing the datatype to a unique identifier. 
 
-Umbraco Engage contains a number of breaking changes from the previous uMarketingSuite product.
-
-See the [Migrate from uMarketingSuite](migrate-from-umarketingsuite.md) for full details.
+This **will** result in data loss if non-Umbraco members or no longer existing members were stored in the `MembershipProviderKey` column in the `umbracoEngageAnalyticsPageview` table.