Properties Object Syntax

Before we trigger an event to CustomerLabs, we need to define the properties that is associated with the event.

Properties are the data that is sent to CustomerLabs along with the event in a structured format. There are 2 properties,

• Custom Properties
• Product Properties

Properties Syntax

The following is the syntax for a property,

Javascript

"<property_name>" : {
    "t": "<data_type>",
    "v": "<value>"
}

Properties Data Types

The following data types are supported for properties,

• string – Text values
• number – Numeric values (supports integers and float)
• boolean – True or False values
• array – List (array) of values
• object – Key-Value pairs collection

Best Practices

• Use snake_case for property names (words split by underscores)
• Avoid spaces in property names
• Use descriptive, human-readable names
• Keep the property names consistent across all events
• Avoid special characters

Custom Properties

Custom Properties are the data that contains,

• Event Properties – Page URL, currency, value, transaction id, etc.
• User Traits – first name, last name, email, phone, etc.
• Group Traits – Company name, company website, etc.
• External IDs – External IDs are any unique identifier that is associated with the user assigned from any other platform. (e.g. Customer ID, Facebook Click ID, etc.)
• Identify By – Identify By instructs the system to search the database using the identifier the identify_by is assigned to.

Javascript

var customProperties = {
    // event properties,
    user_traits : {
        // user traits
    },
    group_traits : {
        // group traits
    },
    external_ids : {
        // external ids
    }
};

Event Properties

Any properties that is associated with the event tracked are considered as “event properties”. These are directly stored under customProperties object.

Reserved Event Properties keys are,

• Page URL: page_url
• Currency: currency
• Value: value
• Transaction ID: transaction_id
• Order ID: order_id

Caution

The above standard Event properties keys should not be changed to ensure the events are processed correctly to Ad Platforms. For example, if you change the value to total_price, the value property will not be processed to Ad Platforms.

Note

Custom Event Properties that is associated with the event can also be used for granular tracking purposes. For example, coupon, payment_method, form_id, form_name etc.

UTM parameters are automatically captured by CustomerLabs. But if you wanted to capture the UTM parameters manually, you can add it to the event properties.

Example 1

Javascript

// sample variables
var totalPrice = 699;
var currency = "USD";

// custom properties
var customProperties = {
    "currency": {
      "t": "string",
      "v": currency
    },
    "content_type": {
      "t": "string",
      "v": "product_group"
    },
    "value": {
      "t": "number",
      "v": totalPrice
    },
    "total_items": {
      "t": "number",
      "v": 2
    },
    "payment_method": {
      "t": "string",
      "v": "Credit Card"
    },
    "coupon": {
      "t": "string",
      "v": "SUMMER20"
    },
    "transaction_id": {
      "t": "string",
      "v": "ORD-123456789"
    }
  };

Example 2

Javascript

// sample variables
var source = "web";
var formId = "form-123456789";

// custom properties
var customProperties = {
    "source": {
      "t": "string",
      "v": source
    },
    "form_id": {
      "t": "string",
      "v": formId
    },
    "form_name": {
      "t": "string",
      "v": "Sample Form"
    },
    "page_url": {
      "t": "string",
      "v": "https://www.example.com"
    }
  };

Tip

Custom Properties can be hard coded or can be fetched from the variable.

External IDs

External IDs are any unique identifier that is associated with the user assigned from any other platform or used to identify the user in another platform.

It acts as a common identifier between CustomerLabs and the other platform. For example, Customer ID, Facebook Click ID, etc.

Reserved External ID keys are,

• CustomerLabs User ID: customerlabs_user_id
• Identify by Email: identify_by_email
• Identify by Phone: identify_by_phone
• Shopify Cart Token: shopify_cart_token
• Facebook FBP: facebook__fbp
• GA4 client id: google_analytics__client_id
• Facebook Lead id (instant forms): facebook_lead_id

This external id can be used to associate the unified user events with other platforms.

Note

Custom External IDs that is associated with the user can also be used for granular tracking purposes. For example, user_id, lead_id, crm_id etc. These Custom External IDs will be attached to respective user profiles.

Javascript

// sample variables
var cluid = "cl123456789";
var email = "johndoe@example.com";

// external ids
var customProperties = {
    external_ids : {
        "customerlabs_user_id": {
            "t": "string",
            "v": cluid
        },
        "identify_by_email": {
            "t": "string",
            "v": email
        },
        "identify_by_phone": {
            "t": "string",
            "v": "123456789"
        },
        "facebook__fbp": {
            "t": "string",
            "v": "fb.1.1111111111111.1111111111111"
        },
        "crm_user_id": {
            "t": "string",
            "v": "crm_123456789"
        }
    }
}

Tip

External IDs can be hard coded or can be fetched from the variable.

User Traits

User Traits are the data that is related to the user. Unlike event properties, user traits are stored inside customProperties under a separate object called user_traits.

Note

user_traits are masked for privacy and security while viewing and will be hashed using SHA256 algorithm while sending to other Platforms as per the requirements.

To add all user_traits to a user’s profile in CustomerLabs, identify method should be used.

After this, all the user_traits of that particular user will be available in the 360-degree profile in CustomerLabs.

Reserved User Traits keys are,

• First Name: first_name
• Last Name: last_name
• Email: email
• Phone: phone
• Address line 1: address1
• Address line 2: address2
• City: city
• State/Province: state
• Country: country
• Country Code: country_code
• Postal Code: zip
• CustomerLabs User ID: customerlabs_user_id
• Shopify Cart Token: shopify_cart_token
• Facebook Lead id (instant forms): facebook_lead_id

Caution

The above standard User traits keys should not be changed to ensure the events are processed correctly to Ad Platforms. For example, if you change the email to email_id, then email trait will not be processed to Ad Platforms.

Note

Custom User Traits that is associated with the user can also be used for granular tracking purposes. For example, user_type, user_id, dob etc. These Custom User Traits will be attached to respective user profiles.

Javascript

// sample variables
var email = "johndoe@example.com";
var phone = "1234567890";

// user traits
var customProperties = {
    user_traits : {
        "first_name": {
            "t": "string",
            "v": "John"
        },
        "last_name": {
            "t": "string",
            "v": "Doe"
        },
        "email": {
            "t": "string",
            "v": email
        },
        "phone": {
            "t": "string",
            "v": phone
        }
    }
}

Tip

User Traits can be hard coded or can be fetched from the variable.

Identify By

When an identify method is called, it is important to assign all the tracked user traits to a particular user. The identify_by attribute helps the system to search for the user based on that identifier ib is associated with and assign all the properties inside user_traits to that particular user.

Note

identify_by should be used only when you use identify method. (_cl.identify()).

Syntax Rules

1. There should only be one identifier that ib is associated with per identify method call.
2. The identifier with ib should be also added under customProperties.
3. The value of ib should be set to true for the identifier when it is added to customProperties.

Caution

If ib attribute is not assigned to any of the properties under customProperties the system will send a 400 bad request.

Reserved Identify By keys are,

• Identify by Email: identify_by_email
• Identify by Phone: identify_by_phone
• CustomerLabs User ID: customerlabs_user_id
• All the reserved user_traits and external_ids keys can be used as identify by.

Note

Custom identify by that is associated with the user can also be used for adding common identifiers. For example, user_id, lead_id, etc.

Javascript

// sample variables
var email = "johndoe@example.com";

// identify_by
var customProperties = {
    "user_traits": {
        "first_name": {
            "t": "string",
            "v": "John"
        },
        "last_name": {
            "t": "string",
            "v": "Doe"
        },
        "email": {
            "t": "string",
            "v": email
        }
    },
    "identify_by_email": {
        "t": "string",
        "v": email
        "ib": true
    }
}

_cl.identify(customProperties);

Note

In the above example, ib is set to true under identify_by_email object. The system searches for email in the database.

If the email is already existing, the user profile will be updated with the user_traits. If the email is not existing, a new user profile will be created with the user_traits.

Tip

Identify By can be hard coded or can be fetched from the variable.

Example 2

Javascript

// sample variables
var email = "johndoe@example.com";
var phone = "123456789";

// identify_by
var customProperties = {
    "user_traits": {
        "first_name": {
            "t": "string",
            "v": "John"
        },
        "last_name": {
            "t": "string",
            "v": "Doe"
        },
        "email": {
            "t": "string",
            "v": email
        },
        "phone": {
            "t": "string",
            "v": phone
        }
    }
}

if (email && email !== "") {
  customProperties["identify_by_email"] = {
    "t": "string",
    "v": email,
    "ib": true
  };
  if (phone && phone !== "") {
    customProperties["external_ids"] = {
      "t": "Object",
      "v": {
        "identify_by_phone": {
          "t": "string",
          "v": phone
        }
      }
    };
  }
}
else if (phone && phone !== "") {
  customProperties["identify_by_phone"] = {
    "t": "string",
    "v": phone,
    "ib": true
  };
}

if (email || phone) {
  _cl.identify(customProperties);
}

Note

The above example illustrates how to use identify_by in case there are multiple identifiers. Since there can only be one ib per event, the other identifier is added under external_ids.

So, we are telling the system that this user is primarily identified by email, but also has an alternate identifier (phone).

Group External IDs

Group / Account External IDs are the data that is related to the group (Company / Account). For example, Company name, Company website, Account ID, etc.

It acts as a common identifier between CustomerLabs and the other platform. For example, Company name, Company website, etc.

Reserved External ID keys are,

• Identify by Company Name: identify_by_company
• Identify by Company Website: identify_by_website
• Company Name: company_name
• Company Website: company_website

This external id can be used to associate the events associated with a group / account with other platforms.

Note

Custom Group External IDs that is associated with the group can also be used for granular tracking purposes. For example, account_id, pipeline_id, etc. These Custom External IDs will be attached to respective group profiles.

Javascript

var customProperties = {
  "group_external_ids": {
    "identify_by_company": {
      "t": "string",
      "v": "ABC Corporation"
    },
    "identify_by_website": {
      "t": "string",
      "v": "www.example.com"
    }
  }
}

Tip

External IDs can be hard coded or can be fetched from the variable.

Group Traits

Group Traits are the data that is related to the group (Company / Account). For example, Company Name, Company Website, etc.

Reserved Group Traits keys are,

• Company Name: company_name
• Company Website: company_website

Javascript

// sample variables
var companyWebsite = "www.example.com";
var companyName = "ABC Corporation";

// group traits
var customProperties = {
    group_traits : {
        "company_name": {
            "t": "string",
            "v": companyName
        },
        "company_website": {
            "t": "string",
            "v": companyWebsite
        },
        "comapny_location": {
            "t": "string",
            "v": "New York"
        },
        "no_of_employees": {
            "t": "string",
            "v": "1-20"
        }
    }
}

Tip

Group Traits can be hard coded or can be fetched from the variable.

Identify Group By

When an group method is called, it is important to assign all the tracked group traits to a particular group. The identify_group_by attribute helps the system to search for the group based on that identifier igb is associated with and assign all the properties inside group_traits to that particular group.

Note

identify_group_by should be used only when you use group method. (_cl.group()).

Syntax Rules

1. There should only be one identifier that igb is associated with per group method call.
2. The identifier with igb should be also directly added under customProperties.
3. The value of igb should be set to true for the identifier when it is added to customProperties.

Caution

If igb attribute is not assigned to any of the properties under customProperties the system will send a 400 bad request.

Reserved Identify Group By keys are,

• identify_by_website
• identify_by_company
• All reserved group_traits keys can be used as igb.

Note

Custom identify group by that is associated with the group can also be used for adding common identifiers. For example, company_id, account_id, etc.

Javascript

// sample variables
var companyWebsite = "www.example.com";

// identify_by
var customProperties = {
    "group_traits": {
        "company_name": {
            "t": "string",
            "v": "ABC Corporation"
        },
        "company_website": {
            "t": "string",
            "v": companyWebsite
        }
    },
    "identify_by_website": {
        "t": "string",
        "v": companyWebsite,
        "igb": true
    },
    "external_ids": {
        "t": "Object",
        "v": {
            "identify_by_company": {
                "t": "string",
                "v": "ABC Corporation"
            }
        }
    }
}

_cl.group(customProperties);

Note

In the above example, igb is set to true under identify_by_website object. The system searches for identify_by_website in the database.

If the identify_by_website is already existing, the group profile will be updated with the group_traits. If the identify_by_website is not existing, a new group profile will be created with the group_traits.

In the above example, identify_by_company is added under external_ids object which can be used in future events for igb.

Product Properties

Product Properties are the data that is related to the products. For example, Product ID, Product Name, Product Price, etc.

The product properties are sent as an array of objects – [{product 1}, {product 2}, ...]

Reserved Product Properties keys are,

• Product ID: product_id
• Product Name: product_name
• Product Quantity: product_quantity
• Product Price: product_price
• Product Category: product_category
• Product Brand: product_brand
• Product Variant: product_variant
• Product Variant ID: variant_id
• Product Coupon: product_coupon
• Product Image: product_image
• Product Index: product_index
• Product Position: product_position
• Product Discount: product_discount

Caution

The above standard Product Properties keys should not be changed to ensure the events are processed correctly to Ad Platforms. For example, if you change the product_id to productId, then product ID will not be processed to Ad Platforms.

Example 1

Javascript

var productProperties = [
    // sample product 1
    {
        "product_id": {
            "t": "string",
            "v": "PRD-1-ID"
        },
        "product_name": {
            "t": "string",
            "v": "Sample Product 1"
        },
        "product_quantity": {
            "t": "number",
            "v": 1
        },
        "product_price": {
            "t": "number",
            "v": 100
        }
    },
    // sample product 2
    {
        "product_id": {
            "t": "string",
            "v": "PRD-2-ID"
        },
        "product_name": {
            "t": "string",
            "v": "Sample Product 2"
        },
        "product_quantity": {
            "t": "number",
            "v": 1
        },
        "product_price": {
            "t": "number",
            "v": 49
        }
    }
]

Example 2

This example shows how to convert the items array from a variable to the required format and store it in the productProperties variable.

Javascript

var items = [
    {
        item_id: "item id 1",
        item_name: "item name 1",
        price: 79.99,
        quantity: 1
    },
    {
        item_id: "item id 2",
        item_name: "item name 2",
        price: 109.99,
        quantity: 1
    }
]

function productsConversion(productsArr) {

    var products = [];

    for (var i = 0; i < productsArr.length; i++) {
        var productsStructure = {};

        for (var key in productsArr[i]) {
            switch (key) {

                case "item_name":
                productsStructure["product_name"] = {
                    t: "string",
                    v: productsArr[i][key]
                };
                break;

                case "item_id":
                productsStructure["product_id"] = {
                    t: "string",
                    v: String(productsArr[i][key])
                };
                break;

                case "price":
                productsStructure["product_price"] = {
                    t: "number",
                    v: productsArr[i][key]
                };
                break;

                case "quantity":
                productsStructure["product_quantity"] = {
                    t: "number",
                    v: productsArr[i][key]
                };
                break;

                default:
                if (productsArr[i][key] && typeof productsArr[i][key] !== "object") {
                    var isNum = /^\d+$/.test(productsArr[i][key]);
                    var type = Number.isFinite(productsArr[i][key]) || isNum ? "number" : typeof productsArr[i][key];

                    productsStructure["product_" + key] = {
                        t: type,
                        v: productsArr[i][key]
                    };
                }
            }
        }

        products.push(productsStructure);
    }

    return products;
}

var productProperties = productsConversion(items);

Next Steps

Now that we have covered the building the properties for the events, let’s move on to setting up the events triggers to CustomerLabs.

• Setting up the Identify event
• Tracking E-Commerce Events
• Capturing Form Submissions