> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runconverge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aliases

> Introduction to Aliases

export const OutboundLink = ({linkText, linkTarget}) => {
  return <a target="_blank" href={linkTarget}> {linkText} 
    <div className="inline h-3 w-3 fill-gray-500 dark:fill-gray-100 text-gray-500 dark:text-gray-300 ml-1 mr-1">
      <svg className="inline w-2.5 h-2.5 bg-gray-500 dark:bg-gray-300" style={{
    maskImage: `url('https://mintlify.b-cdn.net/v6.5.1/solid/up-right-from-square.svg')`,
    maskRepeat: "no-repeat",
    maskPosition: "center center"
  }}></svg> 
    </div>
    </a>;
};

## Introduction to Aliases

### Server-side tracking and stitching challenges

A common challenge with server-side tracking is **linking server-side conversions with their corresponding browser sessions**.

If conversions can't be tied to browser sessions, it results in several downstream issues:

* **Missing browser-side data** (e.g., cookies, IP addresses), leading to reduced ad performance and lower matching rates for [Destinations](/destinations/integrations/overview).
* **Inability to attribute conversions** properly.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Started Checkout") -..- id3("*Server*<br/>Placed Order") ~~~ id4(["**Unstitched** ⚠️ "])
  style id4 stroke:none
```

Converge resolves this issue through the use of **aliases**.

<Warning>If your website uses caching, make sure your aliases aren’t cached. Cached aliases can cause stitching issues that seriously impact your analytics and tracking in Converge.</Warning>

### What are aliases?

An **alias** is a unique identifier for a profile across different data sources.

To address the stitching issue, you can pass a `checkout_token` alias in both the browser-side **Started Checkout** event and the server-side **Placed Order** event. This enables Converge to recognize that both events belong to the same profile and session.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Started Checkout<br/>**alias=checkout_token_xyz**") --> id3("*Server*<br/>Placed Order<br/>**alias=checkout_token_xyz**") ~~~ id4(["**Stitched** ✓ "])
  style id4 stroke:none
```

Aliases are primarily used to **link server-side conversions with browser sessions**, but they can also merge profiles across different websites, browsers, or devices.

In [Converge JS](/sources/website-integrations/converge-pixel), the customer's browser session cookie is used as the default alias. Additionally, Converge provides a set of default aliases for its integrations.

<Accordion title="Code Examples" icon="code">
  <CodeGroup>
    ```javascript Converge Pixel - Javascript theme={null}
    cvg({
      method: "track",
      eventName: "Subscribed To Newsletter",
      properties: {},
      profileProperties: {},
      aliases: ["urn:email:john.smith@apple.com"],
    });
    ```

    ```python Converge Webhook - Python theme={null}
    resp = requests.post(
        "{YOUR_POSTBACK_ENDPOINT}",
        json=
            {
            "event_name": "Subscribed To Newsletter",
            "properties": {},
            "profile_properties": {},
            "aliases": ["urn:email:john.smith@apple.com"],
        }
    )
    ```

    ```javascript Converge Pixel - Shopify Cart Token theme={null}
    cvg({
      method: "track",
      eventName: "Added To Cart",
      properties: {
        product_id: "123456",
        variant_id: "78910",
        sku: "MY_SKU",
        name: "My Product",
        variant_name: "Vanilla",
        price: 42,
        currency: "USD",
        quantity: 1,
        vendor: "My Store",
      },
      aliases: ["urn:shopify:cart_token:Z2NwLWV1cm9wZS13..."]
    });
    ```
  </CodeGroup>
</Accordion>

### What aliases should I pass?

The exact aliases you choose depend on your specific customer journey. Commonly used aliases are:

* **Cart Token** (e.g., `urn:cart_token:123xyz`): can be used to stitch a checkout on a different domain with the storefront session, or to stitch a server-side purchase to a website session.
* **Checkout Token** (e.g., `urn:checkout_token:456abc`): can be used to stitch a checkout on a different domain with the storefront session, or to stitch a server-side purchase to a website session.
* **Email** (e.g., `urn:email:john.smith@apple.com`): can be used to stitch a server-side order to a checkout session.
* **User ID** (e.g., `urn:user_id:123456`): can be used to stitch a server-side order to a website session.

There are two main guidelines for choosing aliases:

1. **Aim for redundancy**: Client-side events have no guarantee of being tracked, meaning that if the stitching of your customer journey depends on a single browser event and this browser event is missed, your server-side conversion won't be stitched correctly.
2. **As early in the customer journey as possible**: If your stitching alias is too late in the journey, then you run the risk that the server-side `Placed Order` event is received in Converge before the client-side event with the stitching alias has been received. As such, a `cart_token` you can pick up early in the journey is a much more reliable alias than an `email` property you receive very late in the journey.

#### Example

If you have a customer journey that looks like this:

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Added To Cart") --> id3("*Browser*<br/>Started Checkout") --> id4("*Browser*<br/>Added Payment Info") --> id5("*Server*<br/>Placed Order")
```

Then an optimal stitching setup would look something like:

```mermaid actions={false} theme={null}
flowchart LR
  id1("*Browser*<br/>Viewed Page") --> id2("*Browser*<br/>Added To Cart<br/>**alias=cart_token_xyz**") --> id3("*Browser*<br/>Started Checkout<br/>**alias=checkout_token_123**") --> id4("*Browser*<br/>Added Payment Info<br/>**alias=john&#64;smith.com**") --> id5("*Server*<br/>Placed Order<br/>**alias=cart_token_xyz**<br/>**alias=checkout_token_123**<br/>**alias=john&#64;smith.com**")
```

Note that:

1. There are multiple stitching identifiers on the browser events in the customer journey to stitch the server-side `Placed Order` to the corresponding website session.
2. Stitching identifiers are available early in the customer journey, ensuring that client-side events with relevant aliases will arrive before the server-side `Placed Order` event.

### Aliases vs Profile Properties

Note that [aliases](/sources/concepts/aliases) and [profile properties](/sources/concepts/profile-properties) are two different things.

Profile properties persist across events but **aren't necessarily unique** across profiles.

As an example, `$first_name` is a clear profile property (it persists across events) yet it doesn't uniquely define this profile so it wouldn't be a correct alias.

***

## Aliases for re-identification

### Default cookie behavior

Many browsers wipe all third-party cookies and all cookies that are set browser-side through JavaScript.
For example, **Safari will wipe all of those cookies after 7 days**.

This significantly impacts the accuracy of multitouch attribution.
Observe in the graph below how a customer who comes to your site in an interval longer than 8 days can't be re-identified.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*User* visits website<br/>with cookie **X**") -. 5 days later .-> id2("*User* visits website<br/>with cookie **X**") ~~~ id3(["**Re-identified**  ✓ "])
  style id3 stroke:none


  id4("*User* visits website<br/>with cookie **X**") -. 8 days later (cookie is lost).-> id5("*User* visits website<br/>with cookie **Y**") ~~~ id6(["**Not re-identified** ✖ "])
  style id6 stroke:none

```

For a full list of browsers and their cookie lifetimes, see <OutboundLink linkText="here" linkTarget="https://www.cookiestatus.com/#current-status" />

### Server-side first-party cookies

The reliable way to re-identify users over longer periods of time is through **server-side first-party cookies**.
As illustrated in the graph below, these do reliably re-identify users.

```mermaid actions={false} theme={null}
flowchart LR
  id1("*User* visits website<br/>with server-side cookie **X**") -. up to 365 days later .-> id2("*User* visits website<br/>with server-side cookie **X**") ~~~ id3(["**Re-identified**  ✓ "])
  style id3 color:#02b802,stroke:none

```

### Leveraging server-side first-party cookies within Converge

By using a server-side first-party cookie as an **alias**, Converge can:

1. **Reliably re-identify your customers for multitouch attribution**. This is especially important for brands where the buying cycle is longer than the cookie lifetime of 7 days.
2. **Extend the lifetime of third-party cookies**: Converge stores third-party cookies that are relevant for your destinations in its <OutboundLink linkText="profile properties" linkTarget="/sources/concepts/profile-properties" />. Converge can then retrieve these third-party cookies when it recognizes a customer after the 7-day period.

***

## Setting up a server-side first-party cookie

If you are using one of the Converge prebuilt integrations (e.g. for Shopify) then you are likely already using a server-side first-party cookie.
Check out your specific integration documentation to verify.

If you are integrating [Converge JS](/sources/website-integrations/converge-pixel) on your website, then you will need to implement this directly yourself.

### Installation instructions

<AccordionGroup>
  <Accordion title="Set up a first-party server-side cookie" icon="server">
    We provide a minimal code example below for Node.js, but any server web framework should be able to handle server-side cookies.

    <CodeGroup>
      ```js Node.JS Server theme={null}
       // server.js

       const express = require('express');
       const cookieParser = require('cookie-parser');
       const uuid = require('uuid');

       const app = express();
       const PORT = 3000;

       app.use(cookieParser());

       // Middleware to generate and set unique visitor cookie if not already set
       app.use((req, res, next) => {
       if (!req.cookies.visitorId) {
           const visitorId = uuid.v4(); // Generate a unique visitor ID
           res.cookie('mystore_uid', visitorId, { maxAge: 365 * 24 * 60 * 60 * 1000, httpOnly: true });
       }
       next();
       });

       // Route to serve Next.js application
       app.use('/', require('./frontend'));

       app.listen(PORT, () => {
       console.log(`Server is running on port ${PORT}`);
       });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Pass the cookie as an alias in all of your client-side ConvergeJS calls" icon="cookie">
    Modify the code where you set up the `page_load` to include the cookie you set up above as an `alias`.
    We provide an example for Next.js, but this should be straightforwardly implemented in any framework.

    ```js NextJS theme={null}
    import { useEffect } from "react";
    import Cookies from 'js-cookie';

    const MyApp = ({ Component, pageProps, router }) => {
    useEffect(() => {
        const visitorId = Cookies.get('mystore_uid');
        const handleRouteChange = (url) => {
        cvg({method: "track", eventName: "$page_load", aliases: [`urn:mystore_uid:${visitorId}`]})
        };
        router.events.on("routeChangeComplete", handleRouteChange);
        return () => {
        router.events.off("routeChangeComplete", handleRouteChange);
        };
    }, []);
    return <Component {...pageProps} />;
    };
    export default MyApp;
    ```
  </Accordion>
</AccordionGroup>

***