# Working with Identities To send an event, you have to provide at least one identifier: the **session ID**. When a visitor arrives at your website or app, they may initially be anonymous until they log in. During their visit, you can generate an anonymous session ID to track their journey. Store the session ID locally (in a cookie or local storage) and include it with every event using the `user.identities.sessionId` field. In the sections below, we go into detail about how to implement identities with each [implementation method](/product-discovery/tracking-and-sending-events/implementation-guide.md). ## SDK ### Session ID If you are using the Javascript SDK, a random **session ID** is created for the visitor and automatically stored in local storage as `attraqtsessionid`. This **session ID** is then attached to any event sent through the library. {% hint style="info" %} If you have a different **session ID** that's generated elsewhere in your system and want to use it, add it through the `addUserIdentity` method: ```javascript xo.activity.addUserIdentity('sessionId', 'session-id'); ``` {% endhint %} {% hint style="warning" %} The SDK **only** stores the **session ID** in local storage. You will need to re-add any additional identities each time a page is loaded. {% endhint %} ### Logins Once the shopper logs in, you know exactly who they are through the ID you have for them in your system, for example an **e-commerce ID**. The **e-commerce ID** can then be added to subsequent events along with the already existing **session ID**. #### Adding an identity Use `addUserIdentity` to add a different identity, e.g. the **e-commerce ID**: ```javascript xo.activity.addUserIdentity('ecommerceId', 'e-commerce-id'); ``` #### Adding multiple identities Use the `setUserIdentities` method to add multiple identities at once or to overwrite any pre-existing identities added with `addUserIdentity`: ```javascript const identities = { ecommerceId: 'e-commerce-id', sessionId: 'session-id' }; xo.activity.setUserIdentities(identities); ``` ### Example: Handling user identities The following sequence demonstrates how the SDK handles user identities and ensure accurate tracking throughout a user's journey on your platform: 1. **User arrives on your platform**: The SDK assigns a default **session ID** and stores it in local storage. 2. **User performs actions**: The SDK attaches the **session ID** to any activity event you send out through the SDK. 3. **User logs in**: You retrieve the user's **e-commerce ID** from the login and attach it to all subsequent events. 4. **User performs more actions**: The SDK attaches both the newly added **e-commerce ID** as well as the already existing **session ID** to any activity event you send out. On the first activity sent this way, we attribute the **session ID** to the **e-commerce ID**, so all previous actions are now assigned to the same user. ### Segments and Traits (XO specific) {% hint style="info" %} This section is relevant for **XO** customers only. {% endhint %} Apart from **identities**, the SDK can also handle **segments** and **traits**. Segments constitute labels to qualify groups of users sharing common traits or behaviors, such as "Frequent buyer" or "Prospect". Traits constitute various qualifying values related to the user in question, including profile, and preference data, age, gender, likes, etc. #### Setting a user segment Use the `addUserSegment` method to set a user segment. For example: ```javascript xo.activity.addUserSegment('new'); ``` #### Setting multiple user segments Use the `setUserSegments` method to set multiple segments at once and overwrite any pre-existing ones set by `addUserSegment`. For example: ```javascript const segments = ['new', 'prospect']; xo.activity.setUserSegments(segments); ``` #### Adding a trait Use the `addUserTrait` method to add a trait for the user. For example: ```javascript xo.activity.addUserTrait('age', '45'); ``` #### Adding multiple traits Use the `setUserTraits` method to set multiple traits for the user at once and overwrite any pre-existing ones set by `addUserTrait`. For example: ```javascript var traits = { age: 45, buyer: true }; xo.activity.setUserTraits(traits); ``` {% hint style="danger" %} Traits are information you know about your users and that you want to use in our platform. You **must** **only** send information relevant to the platform usage and avoid sending personal information. {% endhint %} ### Logouts If a user logs out, you shouldn't continue to attribute any future events to the same user until they log in again. To clear all user information (and generate a new **session id**) use the `clearUser` method: ```javascript xo.activity.clearUser(); ``` ### Opting Out In order to be compliant with GDPR policies, you must allow your users to opt-out of saving cookies and having their information tracked. You should not be tracking any information on such users, and should refrain from sending any events. When using the SDK to send activity events and the user decides to opt-out, call the following method: ```javascript xo.activity.optOut(); ``` If the user decides to opt-in again, use the following method: ```javascript xo.activity.optIn(); ``` ### Handling the user object yourself If you would like to set the complete user object, you can override any pre-existing configuration through the `setUser` method: ```javascript const user = { 'identities': { 'sessionId': 'session-id', }, 'segments': ['new'] } attraqt.activity.setUser(user); ``` You can also attach the user object as part of the activity object every time you send an activity, for example: ```javascript const activity = { "action": "view", "target": { "product": "123" }, "user": { "identities": { "sessionId": "f49c75a2-6994-41e2-875d-97ec4d19254b", "ecommerceId":"0ca79556-2fee-11eb-adc1-0242ac120002" }, "segments": ["new", "prospect"], "traits": { "age": 45, "buyer": true } } }; xo.activity.send(activity); ``` ## GTM If you are using our [GTM templates](/product-discovery/tracking-and-sending-events/implementation-guide/google-tag-manager.md), identities are added as key-value pairs in the **Identities** section. To add **segments** or **traits**, include them in the **User information** section. ## REST API If you are using the **REST API** to send events, you can attach the user object as part of the activity object every time you send an activity. For example: ``` curl "https://collect-eu.attraqt.io/30cbb5fc-375f-4cf2-8efd-ed86d909718e" -X POST -H "Content-Type: application/json" -d '{ "action": "view", "target": { "product": "123" }, "user": { "identities": { "sessionId": "session-id", "ecommerceId":"e-commerce-id" }, "segments": ["new", "prospect"], "traits": { "age": 45, "buyer": true } } }' ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://crownpeak.gitbook.io/product-discovery/tracking-and-sending-events/identities/working-with-identities.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.