An introduction to Converge Datasources

An introduction to some key concepts in the Converge datasource model.

Table of contents

1. Profile properties
2. Deduplication
3. Aliases
   1. Set an alias when triggering an event
   2. Set an alias without triggering an event

1. Profile properties

It is possible to include profile properties in an event. These properties are characteristic of the customer browsing your website and will be added to their profile. This means that these properties are persisted across events, whereas the event properties are only available and relevant to the event itself.

Profile properties power server-side event enrichment.

Client-side code Example (Javascript)

cvg({
  method: "track",
  eventName: "Subscribed To Newsletter",
  properties: {
    formId: "your-form-id",
  },
  profileProperties: {
    // Only pass the relevant parameters
    $email: "john.smith@apple.com",
    $first_name: "John",
    $last_name: "Smith",
    $phone_number: "+199999999",
  },
});

Server-side code Example (Python)

resp = requests.post(
    "{YOUR_POSTBACK_ENDPOINT}",
    json=
        {
        "event_name": "Subscribed To Newsletter",
        "properties": {
          "formId": "your-form-id",
        },
        "profile_properties": {
            "$email": "john.smith@apple.com",
            "$first_name": "John",
            "$last_name": "Smith",
            "$phone_number": "+199999999",

        }
    }
)

2. Deduplication

Converge supports deduplication natively. You can deduplicate events with an optional eventID parameter. This is especially important for events that are used as conversions.

Converge will deduplicate events with the same eventID at ingestation time.

Client-side code Example (Javascript)

cvg({
  method: "forward",
  eventName: "Placed Order",
  properties: {}, // your event properties
  eventID: "X01",
});

Server-side code Example (Python)

📌 Note that for the webhook source, the eventID parameter should be passed as event_id.

resp = requests.post(
    "{YOUR_POSTBACK_ENDPOINT}",
    json=
        {
        "event_name": "Placed Order",
        "properties": {},
        "profile_properties": {},
        "event_id" : "XO1", # Note the different spelling of event_id
    }
)

3. Aliases

Converge excels at matching events across browser sessions and your server-side data. This is all possible through aliases. Your customer is linked to multiple aliases, i.e. multiple identifiers for the same customer. Converge uses the customer’s browser session cookie as the default alias.

When you add something as an alias, you are telling Converge that this alias is a unique identifier for this profile across datasources. In the examples below, we add email as an alias. Thus, Converge can merge a profile of browser events (e.g. Pageviews) with a profile with backend events (e.g. Started Subscription) if they have the same email.

In the examples below we add an email alias, other aliases that are useful:

• cart_token
• checkout_token: this is absolutely necessary if your checkout lives on a different domain than your storefront token.
• customer_id

a) Set an alias when triggering an event

Client-side code Example (Javascript)

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

Server-side Example (Python)

resp = requests.post(
    "{YOUR_POSTBACK_ENDPOINT}",
    json=
        {
        "event_name": "Subscribed To Newsletter",
        "properties": {},
        "profile_properties": {},
        "aliases": ["urn:email:john.smith@apple.com"],
    }
)

b) Set an alias without triggering an event

Sometimes you might want to set an alias without explicitly triggering an event. In that case, you will want to use the set method instead of the track method.

Client-side code Example (Javascript)

cvg({ method: "set", aliases: [`urn:checkout:${checkoutID}`] });