You can store up to 255 customer attributes with the maximum value size of 128Kbits (or 16KBytes) per attribute. After reaching the storage limit any tracking containing new customer attributes will be discarded.
Only use ASCII characters for attributes naming.
To know your customers better, you need to identify them with a unique identifier, such as email or username. Use the snippet in the Example section below to identify the customer for the first time (for example right after login or registration) so that every event the customer creates from this point on will be tracked correctly and directly to him.
The example will identify the customer with a username [[email protected].](🔗) Without identification, events are added to anonymous customers. Please note that you don’t lose any information about these events after you identify the customer – these events will be transferred to a newly identified customer.
|customerIds **(Required)**||String / Number / Object||Customer's unique identifier|
|customerProperties||Object||Pass customer attributes|
|successCallback||Function||Defines a success callback function. Function is called after the event is successfully sent to the backend. At this point, there is no knowledge of how the request was processed by Bloomreach Engagement backend.|
|errorCallback||Function||Defines an error callback function.|
|immediate||Boolean||Defaults to **FALSE**. If true, SDK sends the request right away. Otherwise, it waits a little and sends this request in bulk with other requests|
If you use email as your hard or soft ID, it should also be passed as a customer attribute so you can contact your customers. If you only pass one customer ID, it will be matched against your customer´s hard ID. SDK always uses `
registered` as the default hard ID if none is specified. The hard ID used in this example is `
registered`, however, your hard ID may differ, so replace it if applicable. If you are unsure ask your CSM, Consultant, or VDM.
### Best practice
Always make sure that you pass lowercased and trimmed email.
#### Custom IDs
When using another identity (for instance user_id from your system), always make sure that this attribute is created in your Bloomreach Engagement project (Administration -> Projects -> Your project -> Identifiers). Otherwise, these calls will be discarded.
If you do not have the Instance Manager role, contact your Consultant or CSM.
Do not set a cookie field value, this value will be ignored.
Please note that if you obtain another identity parameter over time and you want to identify a customer (previously identified by email) with your customer_id for instance, you need to call identify with BOTH customer identifiers. Otherwise, if you only pass user_id into the second identify call, a new customer will be created.
We recommend you to use something unique. It might be your internal database userId or email.
When using caching on your web server, you need to make sure not to put identifying customer script into this part.
Every customer in Bloomreach Engagement has a set of attributes. Attributes can be used to contact the customer using a campaign or to specify the customer in your business more accurately. Use the snippet in the Example section below to update customer attributes.
If a customer property doesn’t exist at the time the code is executed, the property will be created. You can create properties as you need them without worrying about their management. If you don’t need them anymore, you can delete them easily.
Please note that if you choose to identify your customer with an email, you still need to specify the customer attribute email. This is needed because of the distinction between “customer IDs” and “customer attributes”.
Displayed in Customer view.
URL for the photo displayed in Customer view.
Used in email campaigns.
Used in SMS campaigns.
Use full international format:
leading +, no spaces
Use if your website has multiple language mutations or you store preferred customer's language for communication.
Make sure the language attribute matches the format as it is defined in Project settings (i.e. both „cs“ for Czech, not „cs“ and „cz“).
Use when you track multiple domains under one account.
|customerAttributes **(Required)**||Object||Pass customer attributes. Max 255 attributes of 128Kbit size each|
exponea.anonymize()` allows you to ensure that multiple people using the same device are not tracked as a single customer. When `
exponea.anonymize()` function is used it resets the cookie generated by the Bloomreach Engagement initialization script (`
__exponea_etc__`) and replaces it with a new one for every new `
session_start`. This means that all new events will be tracked under the new customer profile. However, all the customer events and attributes tracked under the original cookie will continue to be stored under the original separate profile.
Incompatibility with Google Analytics
exponea.anonymize()` cannot modify the Google Analytics ID. Thus, it’s usage is limited if a client is using GA retargeting because the function does not reset Google Analytics IDs which leads to an immediate merge of user with original and newly assigned cookie back into one customer.
You can track up to 255 event types with 255 event attributes for each event type with a value up to 128Kbit for the attribute.
Only use ASCII characters for events and attributes naming.
Customers in your business do different actions. These actions are called events and by tracking them you gain insights vital for developing the perfect business. To track your first event, you need to copy-paste the following code into an appropriate place in your business.
|eventName **(Required)**||String||Name your event|
|eventProperties||Object||Pass event properties (max 255 entries)|
|successCallback||Function||Called after the event is successfully tracked|
|errorCallback||Function||Called when an error occurs|
This will track the event named purchase with the three attributes of item, price and margin_percent to currently identified customer. For example, the attribute price has number value 7.99.
Of course your event doesn’t have to be named purchase and it doesn’t have to have this set of attributes. Other useful examples of events would be registration or added to cart. You can also get creative and make your own events with custom attributes – only you decide what to track about your customers. However, remember that in business analytics, less is more and you want to start with a few basic events first.
We recommend you to avoid using internal IDs or numbers as values for attributes where string is available. Purchase status ‘canceled’ is much more comprehensible than a purchase status 3.
Bloomreach Engagement JS SDK adds some default properties (which can be extended in initialize call - please refer to [Config Object](🔗)) to the event itself.
|os||Customer's operating system||iOS|
For automatically tracked events (first_session, session_start, session_end and page_visit) Bloomreach Engagement additionally tracks:
|path||Customer's path, striped of URL parameters||/contact-us|
|referer||Previous location of the customer||<https://www.google.com/search?q=lorem#element>|
Event tracking is asynchronous
If you need to track an event before page navigation, make sure to wait until the event is successfully tracked by utilizing the `
successCallback` parameter before redirecting to a new URL. This is especially important for events like `
consent` which you absolutely need to make sure are tracked in the customer's profile.
You can easily track your users clicking activity by adding tracking to any element of your webpage. Just set the CSS selector (if more elements fulfil the CSS selector condition, tracking will occur on all of them).
For instance you can use this function to track visitors who are leaving your page by clicking some external link.
|CSS selector **(Required)**||String or Element||CSS selector of item(s) you want to track|
|eventName **(Required)**||String||Name your event|
|eventProperties||Object||Pass event properties|
Bloomreach Engagement JS SDK lets you easily push your existing Google Analytics Enhanced Ecommerce tracking into Bloomreach Engagement.
|Ecommerce object **(Required)**||Object||GA EE object||See GA EE [documentation](🔗)|
|Kind||String||Name of GA EE Event It is optional with default value of "all"||click / detail / add / remove / promoView / promoClick / checkout / checkout_option / purchase / refund / all|
Bloomreach Engagement will track 'detail' event with provided properties along with default event properties and 'tracked_via':'ecommerce' attribute.