What are the different ways to get data into UserIQ?

There are three ways to get data into UserIQ:

1. Tracking Code Snippet
2. Server-side API Calls
3. Integrations (SFDC)

 

Quick Overview

1. Tracking code will pass and update 'Custom Variables'.

The tracking code is the primary method of passing data about users and accounts to UserIQ.

There are six mandatory custom variables. You can add additional custom variables (as many as you want). The custom variables will get updated with each call from the tracking code (at least every page view).

 

2. Server-side API calls will pass and update 'External Data'.

account_data/update call will update External Data for an account record. This call will create account records if they do not exist already.

user_data/update call will update External Data for a user record. This call does not create user records if they do not exist already.

Event/track call will perform a similar function to that of the UserIQ tracking code, but is meant to capture custom events outside of the browser and doesn't handle custom variable updates the same way.

These calls will simply tie a custom event to a user and/or account.

Note: this call will not update custom variables.

 

3. Integrations will pass and update External Data.

When a Salesforce integration is configured, a sync process will run nightly that will update External Data for each Account and/or User object.

The attributes that are included in the sync process are configurable in site settings.

 

Both Custom Variable and External Data are available in segment and audience filters for 'User Attributes' and 'Account Attributes'.

 

Q: What is the difference between Custom Variables and External Data?

A: Not much, in terms of how they are used in a segment and audience filtering. The main difference is that custom variables passed using the tracking code are constantly updated to the latest value. External data is updated only when an API call is made for that specific user/account/attribute.

 

Q: How do I decide whether to use the tracking code to send Custom Variables or to use API calls to send External Data?

A: Your default approach should be to use the tracking code to pass data using custom variables. It is the primary method, and it takes care of a lot of details for you automatically.

If you are concerned about the volume of data you are passing, the amount of time it takes to reflect the custom variables values on user details/account details, or the data simply isn't available to pass through the tracking code, then passing the data using a server-side API call should be preferred.

1. Tracking Code Snippet

The tracking code snippet is the primary method of passing data from your application to UserIQ.

Your tracking code snippet will include a unique 'site_id' which is used to group all data for your site. It is the highest level of grouping.

The tracking code also allows you to pass account and user-specific attributes to UserIQ.

These attributes are passed in what we call 'custom variables' because you can pass any data that you'd like.

However, there are 6 custom variables that are mandatory if you want to optimize your experience and outcomes with UserIQ.

 

Mandatory Custom Variables

Mandatory custom variables should be the first 6 custom variables and require specific names and data formats to be passed.

UserID - Used to uniquely identify each end user.

User Name - Used to display the user name in a friendly way inside the UserIQ tool for searching, reporting, and detailed analytics views.

Account ID- Used to group users into accounts. Also creates Account records for reporting and detail views. Also required to match accounts when performing the Salesforce sync process.

Account Name- Used to display the account name in a friendly way inside the UserIQ tool for searching, reporting, and detailed analytics views.

Signup Date - Signup date of the end user is important to positively identify new users (vs. existing users that are seen by UserIQ for the first time). This is very helpful for user cohort segments and reporting. Required date format is YYYY-MM-DD.

User Email - Required for email engagements. Also helpful for automatically identifying internal users based on email domain rules (e.g. mark all users as internal that have an email address with @yourcompany.com)

 

Additional Custom Variables

Again, you can pass any additional data as custom variables. There is no limit to the number of custom variables you can pass.

 

Mapping Custom Variables

In order to start using custom variables to create segments, you must map the custom variables.

The process is easy, but also easy to overlook after adding a new custom variable.

 

Q:  How many custom variables should I pass through the tracking code?

A: You can pass as many as you would like. As a rule of thumb, most customers pass between 10 and 20 custom variables.

 

Q: Does the order of customer variables matter?

You should pass the user_id as the first custom variable. It is also good practice to pass the 6 mandatory custom variables in the first 6 positions.

Beyond the mandatory custom variables, you can pass the custom variables in any order you prefer but keep the order consistent from user to user.

If you decide to add additional custom variables at any point, simply append them to the list of custom variables you are already passing.

If you choose to stop using a custom variable, leave it in place, but pass an empty string.

 

Q: How do I choose which custom variables to pass?

To decide what custom variables you should pass, think about the different ways you might want to segment users and accounts for reporting and targeted engagements.

You may also want to pass variables that have special meaning in UserIQ.

Specifically, any values in the Special Account Column Mapping configuration behave in specific way and will unlock additional capabilities in UserIQ.

 

Q: What is Variable Scope for custom variables?

Variable scope allows you to determine if the attribute you are passing is specific to a user or the account in general.

For example, a user_email custom variable has a variable scope of 'User'. Whereas, a custom variable of account_name has a variable scope of 'Account'.

Tip: Custom variables with the 'Account' scope can be used to build Account-level segments. Account-level segments can be used to build segment-specific customer health dashboards.

The default scope is 'User' unless changed.

 

Q: What is Data Type for custom variables?

By configuring a 'Data Type' for each custom variable, you can create smarter segmentation rules.

For example, if you are passing text (or a 'string' in developer terms) in your custom variable, you can use segment filter rules like 'Contains', 'Does not contain' to look for certain patterns.

If you are passing a date type in custom variable, you can configure it as a 'Date' data type so that you can use segment filter rules like 'Before' or 'After'.

The available data types include: boolean (e.g. true or false), date (e.g. YYYY-MM-DD), float (e.g. 3.14), integer (e.g. 42), string (e.g. Platinum), timestamp (e.g. '2017-08-21 14:35:00')

The default data type is String unless changed.

2. Server-side API Calls

There are 3 main API calls to pass data into UserIQ:

* account_data/update call will update 'Ext Data' (or external data) for an account record. This will create account records if they do not exist already.

The account_id passed should match the account_id that is passed for this account in the tracking code. These calls will NOT override custom variable values.

Note: do not send custom variable updates using this call.

 

* user_data/update call will update 'Ext Data' for a user record. This call does not create user records if they do not exist already.

The user_id passed should match the user_id that is passed for this account in the tracking code.

Note: do not send custom variable updates using this call.

 

* event/track call will perform a similar function to that of the UserIQ tracking code, but is meant to capture custom events outside of the browser and doesn't handle custom variable updates the same way.

These calls will simply tie a custom event to a user and/or account.

Note: this call will not update custom variables.

 

3. Integration (SFDC)

When a Salesforce integration is configured, a sync process will run nightly that will update External Data for each Account and/or User object.

The attributes that are included in the sync process are configurable in site settings.