Aliases

Introduction to Aliases

Server-side tracking and stitching challenges

A common challenge with server-side tracking is the ability to link server-side conversions with their corresponding browser sessions. If conversions cannot 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.
Inability to attribute conversions properly.

Converge resolves this issue through the use of aliases.

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.

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. 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, the customer’s browser session cookie is used as the default alias. Additionally, Converge provides a set of default aliases for its integrations.

Code Examples

cvg({
  method: "track",
  eventName: "Subscribed To Newsletter",
  properties: {},
  profileProperties: {},
  aliases: ["urn:email:john.smith@apple.com"],
});

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 server-side order to a website session

There are two main guidelines for choosing aliases:

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 will not be stitched correctly.
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: Then an optimal stitching setup would look something like: Note that:

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.
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 and profile properties are two different things. Profile properties persist across events but are not necessarily unique across profiles. As an example, $first_name is a clear profile property (it persists across events) yet it does not uniquely define this profile so it would not be a correct alias.

Aliases for re-identification

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 cannot be re-identified. For a full list of browsers and their cookie lifetimes, see here

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.

Leveraging server-side first-party cookies within Converge

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

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.
Extend the lifetime of third-party cookies: Converge stores third-party cookies that are relevant for your Destinations in its profile properties
. Converge can then retrieve these third-party cookies when it recognizes a customer after the 7-day period.

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 on your website, then you will need to implement this directly yourself.

Installation Instructions

Set up a first-party server-side cookie

We provide a minimal code example below for Node.js, but any server web framework should be able to handle server-side cookies.

 // 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}`);
 });

Pass the cookie as an alias in all of your client-side ConvergeJS calls

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.

NextJS

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;

Getting started

Implementation

Sources

Destinations

Data Warehouse

Attribution

Insights & Dashboards

Marketing Sources

Data Management

Settings

Introduction to Aliases

Server-side tracking and stitching challenges

What are aliases?

What aliases should I pass?

Example

Aliases vs Profile Properties

Aliases for re-identification

Server-side first-party cookies

Leveraging server-side first-party cookies within Converge

Installation Instructions

Getting started

Implementation

Sources

Destinations

Data Warehouse

Attribution

Insights & Dashboards

Marketing Sources

Data Management

Settings

​Introduction to Aliases

​Server-side tracking and stitching challenges

​What are aliases?

​What aliases should I pass?

​Example

​Aliases vs Profile Properties

​Aliases for re-identification

​Default cookie behavior

​Server-side first-party cookies

​Leveraging server-side first-party cookies within Converge

​Setting up a server-side first-party cookie

​Installation Instructions

Introduction to Aliases

Server-side tracking and stitching challenges

What are aliases?

What aliases should I pass?

Example

Aliases vs Profile Properties

Aliases for re-identification

Default cookie behavior

Server-side first-party cookies

Leveraging server-side first-party cookies within Converge

Setting up a server-side first-party cookie

Installation Instructions