Documentation

epica.js

Quick start

This tutorial will help you to start sending data from your website to EPICA using our epica.js library.

Step 1: Copy the Snippet

Installing EPICA is easy, just paste this code snippet between the <head> and </head> tags of your web page:

<script type="text/javascript">
!function(e,p,i,c,a,A,I){e.epica||(a=e.epica=function(){return a.queue.push(arguments)},
a.queue=[],A=p.createElement(i),A.async=!0,A.src='https://cdn.epica.ai/epica.js/v1/'+c+
'/epica.min.js',I=p.getElementsByTagName(i)[0],I.parentNode.insertBefore(A,I))}
(window,document,'script','YOUR_WRITE_KEY');
epica('page');
</script>

NOTE: You may already have other existing code between the <head> tags, so just place the pixel code underneath that, but above </head>.

When you paste it, you’ll need to replace YOUR_WRITE_KEY with your EPICA project’s Write Key, which is provided by our customer success team.

That’s it! The basic setup is finished and you are tracking page views now.

NOTE: The snippet loads epica.js asynchronously but already provides you an access to epica.js API. So it won’t affect your page load speed and allows you to call epica.js API methods while epica.js is still being loaded.

Step 2: Identify Users

By default we automatically assign an anonymousId to all visitors. This is how we know that for example page and track events came from the same visitor.

To tell EPICA more about your known users, pass User ID and any optional traits to identify method call.

An example how you would sent data about the user who is recognised in your system by ID 'f02321dka' and whose name and email you already know:

epica('identify', 'f02321dka', {
name: 'Max Fresh',
email: 'mxfresh@example.com'
});

To provide actual user data to identify API call you may use two strategies:

Step 3: Track Actions

To tell EPICA more about actions performed by users on your site, call the track method. The track method tells us a name of “event” and also may include properties associated with that event.

For example this snippet is telling us that your user triggered Search event and the user is looking for 'Wristwatch':

epica('track', 'Searched', {
query: 'Wristwatch'
});

You may track any user actions and send events which indicate metrics valuable for your business, like Signed Up, Item Searched or Added To Cart.

Keep on reading to know more about epica.js API.

Epica.js API

Read more about methods provided by epica.js.

Anonymous ID

epica.js takes care to track all visitors of your site. For visitors who are not identified in your system yet epica.js will automatically generate an anonymousId and will pass it along with all events triggered by the user even after user is identifyed.

Identify

The identify method is how you tell EPICA that a user is recognized in your system by userId and traits.

Definition:

epica('identify', [userId], [traits], [options]);

Arguments:

userId optional String The ID of the user in your system.
traits optional Object An object with data known about the user, like their age or name.

Track

The track method lets you record what actions performed by a users on your site.

Definition:

epica('track', event, [properties], [options]);

Arguments:

event String The name of the event you’re tracking.
properties optional Object An object with data associated with the event. If the event was 'Purchased', it might have properties like item, category and price.

The only required argument to track in epica.js is an event name string.

Example track call:

epica('track', 'Added Extras', {
item: 'Breakfast + Dinner',
price: '20.0',
});

Page

The page method lets you record page views and optional extra information about the page being viewed on your website.

By default a page call is present at the end of the epica.js snippet. You may modify this page call with options described below.

Definition:

epica('page', [category], [name], [properties], [options]);

Arguments:

category optional String The category of the page. Useful for cases like ecommerce where many pages might live under a single category. Note: if you pass only one string to page it is assumed to be name. You must include a name to send a category.
name optional String The name of the page.
properties optional Object An object with properties describing the page.
options optional Object An options object for epica.js tuning. Note: If you do not have traits for the user, pass an empty object (ie, ‘{}’) before options.

With each page event epica.js will include url, title, referrer and path properties by default. For example:

epica('page', 'Special offers');

would be equal to the following but don’t require any extra work from you:

epica('page', 'Special offers', {
title: 'Offer of the week',
url: 'https://example.com/offers',
path: '/offers',
referrer: 'https://example.com/catalog'
});

You can override default value if you pass property with same key.

Reset / Logout

Calling reset will reset the anonymousId and userId (for the identified user). New events will be recorded for the new anonymous user.

epica('reset');

NOTE: Use this method with a caution. EPICA may not be able to restore user historical data after it’s invocation. However, it may be useful in a case when a user revokes their consent for tracking their data.