JavaScript SDK

Integrating your business with Exponea is the first step in getting closer to your customers. After a quick integration, you will immediately see actions that customers do in your business. If you need any assistance in deciding which API is the best for your business, please contact our integration specialist.

When should I integrate through JavaScript?

Integration through JavaScript is recommended for web browser business or for business coded in other languages that still make use of JavaScript.


Basic integration

To integrate with Exponea using JavaScript, you need to copy-paste the following initialization code into the header of the webpage your business is running in. This step is an essential prerequisite for identifying your customers and tracking their actions.

<script type="text/javascript">!function(i,t){function e(e){return function(){var n=arguments;if("initialize"==e&&n&&n[0].modify&&n[0].modify.overlay&&"loading"==t.readyState){var a="__inf__overlay__";t.write('<div id="'+a+'" style="position:absolute;background:#fff;left:0;top:0;width:100%;height:100%;z-index:1000000"></div>'),setTimeout(function(){var e=t.getElementById(a);e&&t.body.removeChild(e),i.exponea.__=!0},n[0].modify.delay||500)}this._.push([e,arguments])}}if(!i.exponea){var n,a,o="initialize identify update track trackLink trackEnhancedEcommerce getHtml showHtml showForm ping getAbTest".split(" "),r=t.createElement("script"),d="https:"===t.location.protocol?"https:":"http:";for(i.exponea={_:[]},a=0;a<o.length;a++)n=o[a],i.exponea[n]=e(n);r.type="text/javascript",r.async=!0,r.src=d+"//api.exponea.com/js/exponea.min.js",t.getElementsByTagName("head")[0].appendChild(r)}}(window,document);</script>
<script type="text/javascript">
    exponea.initialize({
        token: 'PROJECT TOKEN'
    });
</script>

This will initialize Exponea with your project token (your unique project identifier) so that every action will be tracked into your project correctly. You can find your project token inside the Project overview by clicking Overview in the left menu. This code must be included in every page where you want to track actions of your customers.

How do I know that I initialized Exponea correctly?

After copy-pasting the initialization code, open your web business in a new window. This single page visit should be enough to identify whether your basic integration is working. Check if you integrated successfully in Project > Data management > Events section. Contact our JavaScript integration specialist.


Tracking your first event

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.

<script type="text/javascript">
    exponea.track('purchase', {
        item: 'Flying carpet',
        price: 7.99,
        margin_percent: 20,
        status: 'completed'
    });
</script>

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

Tip: 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.

You can delete events you tracked at any time easily.


Identifying your customers

To know your customers better, you need to identify them with a unique identifier, such as e-mail or username. Copy-paste the following snippet into the code where it is possible 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.

<script type="text/javascript">
    exponea.identify('gordon.freeman@blackmesa.com');
</script>

This will identify the customer with a username gordon.freeman@blackmesa.com. 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.

Tip: We recommend you to use something unique. It might be your internal database userId or email (in some cases).

Warning: If using caching on your webserver, you need to make sure not to put identifying customer script into this part.


Updating the customer’s profile

In addition to tracked events, 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. Copy-paste the following snippet into the code where you want to update customer attributes.

<script type="text/javascript">
    exponea.update({
        registration_date: '2014-04-10',
        email: 'gordon.freeman@blackmesa.com',
        first_name: 'Gordon',
        last_name: 'Freeman',
        company: 'Blackmesa'
    });
</script>

This will update the customer attributes registration_date, email, first_name, last_name and company.

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 identification attributes and the customer email.


This guide should have provided you with all the basics needed to start tracking your first events. We would love to help you get started as soon as possible, so if you have any questions, please contact our integration specialist.

Advanced tracking

Customizing default tracking

Default tracking behaviour can be adjusted in the exponea.initialize(options) call:

<script type="text/javascript"> 
    exponea.initialize({
        token: 'PROJECT TOKEN',
        customer: 'Insert unique identified of your customer or remove this line (so cookie identification will used)',
        ping: { enabled: true}, // enables tracking session_start, first_session and session_end events
        track: { visits: true }  // enables tracking page_visit event
    });
</script>

You can also specify custom properties to be emitted with the session_start and session_end events.

<script type="text/javascript">
    exponea.initialize({
        token: 'PROJECT TOKEN',
        customer: 'Insert unique identified of your customer or remove this line (so cookie identification will used)',
        ping: {
            // specify your custom properties here
            properties: {
                version: 2,
                subdomain: 'www'
            }
        }
    });
</script>

Show Banner

You are able to display a Web Layer by calling showBanner with ID of the specific banner. You can also send parameters to the banner, which can be then accessed by Jinja in the banner js code:

Without parameter:

<script type="text/javascript">
    exponea.showBanner('BANNER ID');
</script>

With parameter:

<script type="text/javascript">
    exponea.showBanner('BANNER ID', {
        product_id: 4247
    });
</script>

Anonymize

A good practice is to reset customers cookie after a successful logout. You can call anonymize in order to assign the current tracked user a new cookie. All following events will be tracked under the new cookie.

<script type="text/javascript">
    exponea.anonymize();
</script>

Action tracking

You can emit custom events when clicking links:

<a id="exponea_link" href="http://www.exponea.com">Exponea</a>
<script type="text/javascript">
   exponea.trackLink('#exponea_link', 'external_link', {
       site: 'Exponea'
   });
</script>

HTML campaigns

To display the content of your HTML campaign for the current user, use the following code:

<script type="text/javascript">
    exponea.showHtml('#content', 'Name of your HTML campaign node');
</script>

If you want to work with HTML yourself, use the getHtml method instead:

<script type="text/javascript">
    exponea.getHtml('Name of your HTML campaign node', function (html) {
        // Do whatever you want with html.
    });
</script>

Limitations

Characters . and $ are not allowed to be used in JSON keys. However, they can be used as values.

Updated on August 17, 2017

Was this article helpful?

Related Articles