# Migrate Tracking SDK v1 -> v2

This section is aimed to touch on the most important topics related to migrating from our old tracking SDK to the new SDK. If there are any questions/uncertainties in the process of migration, please [reach out to the CrossEngage support](https://documentation.crossengage.io/data-and-engagement-platform/help-and-support/reach-out-to-customer-support). 

### Tracking SDK Setup

Exchange the HTML snippet loading the tracking SDK with our tracking template or with the updated HTML snippet visible in the System Setup section of your CrossEngage instance and apply the same trigger logic as previously used.

Please read the [setup ](https://documentation.crossengage.io/data-and-engagement-platform/web-tracking/web-tracking-v2)section of our documentation for information around using the GTM-Template as well as further information on additional options and configurations.

{% hint style="warning" %}
The new Tracking SDK **opts any user out** from tracking by default. This means that no user tracking will occur until the configuration `ce({trackingOptIn: true})`; has been set.
{% endhint %}

### Tracking, Identify and Updating Users

Formats and payloads of the tracking data has not changed. Only the API to provide these is slightly different**.** 

Please make sure to visit all your tags triggering updates to CrossEngage and change the tags according to the documentation below. 

{% hint style="info" %}
Because **identifying** and **updating** are now separated, you might need to split a previous `analytics.identify` where both was done in one API call. In that case, just send the **update** with the attributes after the **identify.**
{% endhint %}

| Tracking SDK v1 (Legacy)                                                                                                                   | Tracking SDK v2                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| <p>Viewed Page tracking event </p><p></p><p><code>analytics.page();</code></p>                                                             | <p>Viewed Page tracking event </p><p></p><p><code>ce('track', 'Viewed Page');</code></p>                                             |
| <p>Any tracking event (default or custom) </p><p></p><p><code>analytics.track('Added Product', {properties});</code></p>                   | <p>Any tracking event (default or custom) </p><p></p><p><code>ce('track', 'Added Product', {properties});</code></p>                 |
| <p>Identify a user by externalId</p><p></p><p><code>analytics.identify('123-456');</code></p>                                              | <p>Identify a user by externalId</p><p></p><p><code>ce('identify', '123-456');</code></p>                                            |
| <p>Identify a user by email</p><p></p><p><code>analytics.identify({ email: '<test@test.com>' });</code></p>                                | <p>Identify a user by email</p><p></p><p><code>ce('identify', { email: '<test@test.com>' });</code></p>                              |
| <p>Setting or updating user attributes</p><p></p><p><code>analytics.identify({ name: 'Peter Smith', age: 59, city: 'Berlin' });</code></p> | <p>Setting or updating user attributes</p><p></p><p><code>ce('update', { name: 'Peter Smith', age: 59, city: 'Berlin' });</code></p> |

### Additional options

You might have used a global additionalOptions variable to make sure that certain properties always get added to the event payload of every tracking event.

In the new tracking SDK this functionality can be recreated by configuring it with globalEventProperties(see **Configuration & Config Commands**).\
In the new tracking SDK this configuration is readable and can be set and updated at any time.

All properties within globalEventProperties will get added to the properties property of any track, identify or update event call.

{% hint style="warning" %}
When migrating this to the new SDK, make sure your additional properties are nested in the correct and desired way as they were before.
{% endhint %}

### Accessing the xngGlobalUserId and xngSessionId

To provide a safer and more future proof way to maintain cookies and other forms of persistent storage, we strongly recommend to **never** read or write any cookies or other CrossEngage related storage values directly.&#x20;

Instead the **xngGlobalUserId** and **xngSessionId** can be read and set as part of the configuration (see [**Configuration & Config Commands**](https://documentation.crossengage.io/data-and-engagement-platform/web-tracking/broken-reference)) if needed.\
We have also changed and update various cookie names and references. Old cookies will be converted and deleted when the new tracking SDK detects them.

| Tracking SDK v1 (Legacy) | Tracking SDK v2    |
| ------------------------ | ------------------ |
| xng.gid                  | ce.guid            |
| xng.sid                  | ce.sid             |
| xng.tracking-opt-out     | ce.tracking-opt-in |

### Tracking Opt-Out

The old tracking library provided multiple methods to set the tracking optIn/OptOut status, like\
xng.setTrackingOptOut() etc. and other methods to check the opt out status.

To ensure user privacy is handled correctly, the new tracking SDK will opt out from tracking by default and tracking opt in must be enabled via the configuration to enable tracking like this:\
ce({trackingOptIn: true});\
\
As the tracking optIn status is now a configuration, it can be set and read as described in [Configuration](https://documentation.crossengage.io/data-and-engagement-platform/web-tracking/web-tracking-v2/configuration-and-config-commands).