The Identify API allows you to pass data to us about your users with JavaScript, and save them as User Attributes. These User Attributes can be used to target surveys. You can send up to 100 user attributes on any site, with any number of users associated with those attributes.
- Overview
- Handling User IDs
- Making calls to Identify
- User Attribute values
- Handling email addresses
- Examples of passing User Attributes
- Disabling User Attributes
- Deleting User Attributes
- Best practices
Overview
User Attributes are data values about users of your site passed from your client-side code over the Identify API. This data is passed in key-value pairs as an asynchronous AJAX call to our servers. These values are associated with a User ID, a uniquely identifiable value passed to us in your code from a User ID value from your user database. This allows Contentsquare to associate data collected about them with the same user ID you use in your own database, as well as lookup user information held about that user.
There are 4 phases to the process of sending User Attributes to and using them with Contentsquare.
- Get the data from your site.
- Pass the data into Contentsquare via the Identify API.
- Contentsquare stores the data about each user as User Attributes against their user_id.
- You can now target and filter Surveys by User Attributes.
Making calls to Identify
Before you can begin making calls to Identify, User Attributes must be enabled in your settings for each site you want to use User Attributes with.
Enabling and disabling User Attributes
On your User Attributes page (Settings > User Attributes), find the Site you want to add User Attributes to using the selection drop-down.
You are also able to disable User Attributes on this page. Once you have selected a Site with User Attributes enabled, click Disable User Attributes. Once you have done this, further calls to the API will be blocked. The "Disable User Attributes" button will only appear after user attributes data has been received by Contentsquare, but not before.
If you want to prevent User Attributes from being sent in the future, you should remove the Identify API code on your site. Once the code is deleted from your site, previously collected User Attributes will still exist, but they will no longer be updated or added to new users to your site.
The API call
Here is the format for a call to the Identify API:
hj('identify', userId, {
user_attribute: value
});
- The first parameter should always contain the string value "identify".
- The second should be a string containing the user id for a user on your site, from your own user database, or null if it is not known.
- The third is a series of key-value pairs inside an object. The key provides the User Attribute name, and the value defines both the type of a User Attribute and its value for that user. User Attribute names have a maximum length of 50 characters.
The values passed into this call must come from your own site’s codebase. These values could be pulled directly from your servers or generated client-side.
Once sent to Contentsquare, these attributes and the values for each user are stored on Contentsquare’s servers. Each time a call to Identify is made, the values stored on Contentsquare’s servers will be replaced with the most recent values for these attributes.
You are able to look up all attributes sent to Contentsquare in your User Attributes settings page. You can use the User Lookup feature to inspect what values have been passed for a specific user on your site.
Handling User IDs
The second argument passed to Contentsquare through the Identify API call should be a uniquely identifiable user ID from your own site's database. User Attributes are associated with this User ID.
The User ID should be unique per user but it should not itself contain personal information. It should also be a value that never changes for this user. Once you have set a User ID in Contentsquare, it cannot be changed. If it changes, Contentsquare will consider this to be a totally new user.
If a user id is not known (by passing a null value), then any other User Attributes passed to Contentsquare must not contain any personally-identifying information (PII). Your ability to lookup User Attributes associated with an individual user depends on you being able to look up their User ID. We have no way of retrieving or deleting this data unless you delete the whole Site.
User Attribute values
You can pass the following values to a User Attribute key using the Identify API. Special characters cannot be used at this time.
Handling email addresses
At present, there is one User Attribute key for email addresses: email. Email addresses should be passed as strings to email. For example:
hj('identify', userId, {
email: 'test@test.com'
});
If any other User Attributes of a string type contain an email address, these will be rejected, meaning you should only use `email` to pass email addresses.
Email addresses and User IDs
user_id can take the form of email addresses, so if your database primary key for users is their email address this can be used as a user_id. This should be used only as a last resort. If a user’s primary key in your database exists other than an email, you should use that.
Because email addresses can usually change, if their email address is updated, Contentsquare will treat that user as a totally different user. This would prevent you from using User Lookup on the older email address, which may be in breach of your privacy requirements.
Examples of passing User Attributes
Identifying paying customers
Here is an example, where we want to be able to tell Contentsquare how much money someone has spent on your site.
hj('identify', userId, {
total_spend: 500
});Multiple attributes can be passed by adding further key-value pairs into the object. Maybe you wanted Contentsquare to know when they first became a customer?
hj('identify', userId, {
total_spend: 500,
first_purchase: '2019-06-20Z'
});
Here we are telling Contentsquare that your user became a customer to your service using an ISO8601 date string.
Identifying Attributes for De-identified Users
Sometimes it’s useful to track information about users on your site, even if they aren’t yet users or paying customers. Let’s say you wanted to track the referral source, and landing page A-B test variant a potential lead reached you from:
hj('identify', null, {
ab_test: 'variant-A',
referrer: 'facebook_paid'
});
This would be useful if you wanted to target a survey against users on variant-A, or only those who came to you from Facebook paid adverts, for example.
Handling User Lookup and Deletion Requests
It is possible to lookup and delete a user's data using their User ID. Read more about this in our Understanding the User Lookup Tool article. It is important to note that if you know a user’s User ID and email address, you should look up their information with both. This is the only way to make sure that all personal information about this user has been looked up & deleted.
Disabling User Attributes
To prevent further User Attributes being sent, you should disable User Attributes.
As long as User Attributes are enabled on your site, if you want to prevent them from being sent in the future, you should remove the relevant code on your site. Once the code is deleted from your site, previously collected User Attributes will still exist, though will no longer be updated or added to new users to your site.
Deleting User Attributes
User Attributes can be deleted from the User Attributes management page by clicking on the trash can icon to the right of the attribute.
Deleting a User Attribute will not remove it from any existing sessions or responses containing it. The attribute will only be removed from filtering and targeting. Remember to remove the deleted User Attribute from all Identify API calls, otherwise, it will reappear in the list.
When an attribute is deleted, it will immediately disappear. However, the attribute is still stored in the back end for 7 days before being permanently deleted. Data associated with the attribute is ignored during the 7-day period. This is to prevent data from being sent due to caching issues.
If you wish to re-create an attribute that was deleted, you'll need to wait 7 days before the attribute can be re-created successfully.
Best Practices
When to make API calls to Identify
You should make calls to Identify every time:
- A page is loaded with the most recent values (even if they haven’t changed).
- After a URL change in single-page apps.
- Every time a change is made. E.g. if you wanted to track their last purchase in a store, you would want to update this user attribute once a purchase has been made.
Each call will update the User Attributes with the most recent values. When a call is made, but values have not been updated, the network request will not be sent in order to avoid unnecessary AJAX requests.
Combining User Attribute targeting with other triggers for Surveys
If you plan on combining Events with User Attribute targeting for Surveys, you should ensure that the Identify call has happened before the trigger in your order of execution, bearing in mind any asynchronous calls to other services. If the trigger is executed before the Identify API call has finished execution, the Survey will not show.
Queuing calls to the API before the Contentsquare tag has loaded
If this script is added before your Contentsquare tag, there will be an error.
The hj() object cannot be accessed until the Contentsquare tag has executed. If for any reason you access the Identify API before the Contentsquare tag has executed you can add the following line of code before the API is called:
window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments)};