Customer

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.

identify()

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.

Arguments

Example

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.

// if hard-id is 'registered'
exponea.identify('[email protected]');
// if hard-id is named 'somethingelse'
exponea.identify({'somethingelse':'[email protected]'});

exponea.identify(
  {
    'registered':'[email protected]', //the registered attribute is handled as hard ID and required
    'user_id': 'user_id_123',
  },
  {
    'email':'[email protected]'
    'first_name':'Gordon',
    'last_name':'Freeman',
    ...
  },
  function(){
    //successCallback
  },
  function(){
    //errorrCallback
  },
  false
);

Best practice

Email

Always make sure that you pass lowercased and trimmed email.

var email = customerEmailFromWebsite.toLowerCase().trim();

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.

Cookies

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.

update()

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”.

'Special attributes'

• first_name, last_name, company_name
  • Displayed in Customer view.
• photo
  • URL for the photo displayed in Customer view.
• email
  • Used in email campaigns.
• phone
  • Used in SMS campaigns.
  • Use full international format:
    • leading +, no spaces
    • e.g. +421905123456
• language
  • 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“).
• domain
  • domainname
  • Use when you track multiple domains under one account.

Attributes

Example

exponea.update({
  email: '[email protected]',
  first_name: 'Gordon',
  last_name: 'Freeman',
  company: 'Blackmesa',
  ...
});

anonymize()

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.

Implications for browser push notification ids

By default, calling exponea.anonymize() does not remove the browser push notification ID from the source profile, which means that, even though the original customer is anonymized in the browser, they can still continue receiving browser push notifications.

If your desired behavior is to move the browser push notification id to the new profile, then the following approach could be used:

// unsubscribe current customer first
exponea.notifications.unsubscribe(status => {
    if (status === 'unsubscribed') {
      	// after unsubscription is finished, anonymize the customer
        exponea.anonymize();
      	// and track the browser push token, if it's available, to the new customer profile
        exponea.notifications.subscribe();
    } else {
        console.log('Failed to unsubscribe the user from push notifications:', status);
    }
});

Implications for weblayers

By default, exponea.anonymize() does not hide or re-trigger currently shown weblayers. This can lead to situations like: the customer saw a weblayer (and got banner event with action = show tracked); then the profile was anonymized and a new customer was generated; then the new customer may submit or close the weblayer — then the customer may have banner event with action = subscribe but no event with action = show (as it is still in the old profile).

To re-trigger the weblayers, you may call exponea.reloadWebLayers() after anonymization:

exponea.anonymize();
exponea.reloadWebLayers();

🚧

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.

Events

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.

track()

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.

Attributes

Example

exponea.track('purchase', {
  purchase_status: 'success',
  product_list: [ {product_id: "abc123", quantity: 2}, {product_id: "abc456", quantity: 1} ],
  total_price: 7.99,
  payment_type: 'credit_card',
  ...
});

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.

For automatically tracked events (first_session, session_start, session_end and page_visit) Bloomreach Engagement additionally tracks:

🚧

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.

trackLink()

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.

Attributes

Example

exponea.trackLink('#exponea_link', 'external_link', {
  site: 'Exponea'
});

trackEnhancedEcommerce()

Bloomreach Engagement JS SDK lets you easily push your existing Google Analytics Enhanced Ecommerce tracking into Bloomreach Engagement.

Arguments

Example

exponea.trackEnhancedEcommerce(
  {
    // pass the same attributes as you pass to the EE GA tracking
  },
  'detail',
);

Bloomreach Engagement will track 'detail' event with provided properties along with default event properties and 'tracked_via':'ecommerce' attribute.