Customer

You can store up to 255 customer attributes with the maximum value size of 128Kbits (or 16KBytes) per attribute.

The customer parameter can use any object with identifier same as exponea.identify(). When string is used, it will use identifier registered only.

📘

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

Name

Value

Description

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 Exponea 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

Example

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',
  },
  {
    '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 Exponea 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 in 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 Exponea 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
    • if your website has multiple language mutations or you store preferred customer's language for communication
    • two lower-case letter code ISO-639-1
  • domain
    • domainname
    • when you track multiple domains under one account

Attributes

Name

Value

Description

customerAttributes (Required)

Object

Pass customer attributes. Max 255 attributes of 128Kbit size each

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 Exponea initialization script (__exponea_etc__) and replaces it with a new one for every new session_start. This means that al new events will be tracked in under a 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.

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

Name

Value

Description

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

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.

📘

Exponea JS SDK adds some default properties (which can be extended in initialize call - please refer to Config Object) to the event itself.

Property name

Description

Example

os

Customer's operating system

iOS

browser

Customer's browser

Chrome

device

Customer's device

iPhone

location

Customer's URL

https://www.yourwebsite.com/contact-us?utm=lorem#element

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

Property name

Description

Example

path

Customer's path, striped of URL parameters

/contact-us

referer

Previous location of the customer

https://www.google.com/search?q=lorem#element

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

Name

Value

Description

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

Example

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

trackEnhancedEcommerce()

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

Arguments

Name

Value

Description

Example

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

Example

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

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

Updated 6 days ago


Tracking


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


We rely on cookies

to optimize our communication and to enhance your customer experience. By clicking on the Accept and Close button, you agree to the collection of cookies. You can also adjust your preferences by clicking on Manage Preferences. For more information please see our Privacy policy.

Manage cookies
Accept & close

Cookies preferences

Accept & close
Back