Event API

The events are not intended to only be used with remarketing campaigns but to provide campaign conversion metrics and user behavior information as well. If you want to measure the efficiency of your campaigns down to the revenue level, you will need to deploy our JS event API code at least on your purchase page. This will pass the purchase information and conversion values to our platform.

There are two distinct methods of using Event API on your website. One relies on your website's Google Analytics Enhanced Ecommerce (EE) integration, the second is completely independent implementation. In both cases you need to initialize our EventAPI by loading the script and configuration. If you do have EE on your website you just need to enable EE and configure the EE elements - see Using with Google Analytics Enhanced E-commerce. This documentation covers use of EventAPI using Mailkit Events javascripts. If you intend to write your own scripts or communicate with the EventAPI backend in a server-to-server fashion please visit the EventAPI backend documentation.

Initializing Event API

Before you can start to manage events from your website you need to initialize the API by loading the support scripts of the Event API:

The API ID is set using setAIPPID and can be found in your Mailkit account in the menu Profile/Integration. The setDomain value must contain the hostname of the page without the http/https protocol. You will also have to add and verify the referrer address (eg. www.mywebsite.com) to the list of allowed domains to allow Event API access to your account. setMode is the script’s operational mode. If the mode is set to “debug”, the script will log the calls made to the event API endpoint. This log can be viewed from the JS console of your browser’s developer tools. 

Every eventAPI request is authorized using a triplet of referrer (the hostname of the page requesting the call), setDomain value and domain listing in the Profile. In case your website is available on multiple addresses (eg. www.domain.com and domain.com) you must make sure that the value in setDomain matches the current address in the browser URL field. The site needs to be listed in the allowed domains with www and without it.

Using with Google Analytics Enhanced E-commerce (syncing from DataLayer)

EventAPI is capable of syncing cart data from dataLayer. To enable this feature, you need to enable enhanced ecommerce using the following line:

This will create a new mailkit event tag called cart. Please make sure that there is no other event with a tag name cart if you plan on using enhancedEcommerce syncing. 

Mailkit’s eventAPI currently supports syncing addToCart, removeFromCart, checkout and purchase events. In order to let eventAPI listen to your custom events, you have to tell the script what to listen to. The following settings do that:

For more information on Google’s Enhanced Ecommerce cart measurement, visit this link.

In case you are using Google Analytics Enhance E-commerce syncing you are all set when it comes to shopping interactions. If that is not the case or you want additional types of events to be passed from your website you will have to implement individual calls for your events based on the following steps.

Creating event

Once the Event API has been initialized it's mandatory to call the function to initialize/refresh the actual event. It's required to call this function on every page where any manipulation with the event is to be done - for example on pages where you want to add items to shopping cart. Upon initEvent function call a unique event will be created or in case of an existing event the event will be reactivated for further use.

None of the variables are required as an event can last for a long period of time and therefore get updated with the data later on when they become available.

email - the email address of the visitor (if available) will be used to send messages. In case the value is "detect" instead of an email address an automatic detection of recipient's email address will be performed. Automatic detection is not always reliable and we suggest providing an email address for the event as soon as one is available. Providing an email address also helps to avoid duplicate events but most importantly it's required for reliable email delivery.
event_tag - is used to distinguish between multiple events on a website. While events may be untagged we strongly suggest all events to be tagged by a unique tag. Tag must not contain spaces or any special characters. This tag will be used later on during remarketing campaign setup as a condition to send the remarketing campaign only to events tagged with a specific tag.
return_url - return url for the event. Usually this will be the URL of an abandoned shopping cart (max. 1024 chars), URL must start with http/https
description - additional description that can be used to add variable text content to the body of the email (max 2048 chars)
language - language of the even in ISO 639-1 format. This two-letter code can be used in the message body to create conditionals to insert variable text based on language.
currency - item currency in ISO 4217 format - three-letter shorthand for example EUR, USD. Item currency should be used when running a multi-currency store. Mailkit will show the sale amounts unified to your home currency in the reports.
decimal_separator - since different countries use different decimal separators you can choose to define what separator will you be using. Based on that we will know how to store your numbers and if you are using . or , to separate decimals.
first_name - first name of the visitor if available. The value can be used in the content to personalize the message.
last_name - last name of the visitor if available. The value can be used in the content to personalize the message.
gender - gender of the visitor (M/F) if available. The value can be used in the content to personalize the message.
order_no - order number. Whenever it's possible try to provide a unique order number. This is one of the values that can help to avoid duplicate events that can occur when a visitor switches between devices.
promo - if your want to provide a discount code with an additional incentive you can pass it to the event and use it within your campaign body
promo_value - if you provide a discount code than you might want to post it's value as well to show in the campaign body.
lifetime - set a custom event tracking cookie lifetime (30 days by default), i.e. the value (in days) indicates how long the pending event should wait for finishing. Each time a pending event is updated, the counter is reset and the time set in the lifetime parameter starts running from the beginning.

Event items

Once your event has been created you need to add its content. You can do that at different points during your visitors activity on your website. It can be all done at once for example when the visitor enters the shopping cart or at different pages when the visitor adds an item to cart. Please note that events are not intended to replace your shopping cart and don't do any math or counting. It's solely on you as a developer to provide correct amounts, counts, prices when adding items as well to remove items when necessary.

The basic function to add items to the event is called addItem:
 

event_tag - event tag identifier as used during initEvent. The specific tag used to setup the even must be used.
product_id (required) - product identifier (stock keeping unit). This is a unique identifier for each item and therefor there could be only one item with a set product_id. If multiple items with the same product_id are passed the subsequent items will be ignored not added to item count (max. 32 chars)
name - product name to be used in the campaign body. (max. 256 chars(
description - product description to be used in the campaign body. (max. 2048 chars)
teaser - product teaser text. (max. 256 chars)
price - product price (per unit) to be used in the campaign body. Value must be a number without any characters or symbols.
price_orig - product price (per unit) before discounts. Value must be a number without any characters or symbols.​​​​​​​
item_qty - item quantity (decimals allowed). Value must be a number without any characters or symbols.
item_total - total product price for all the items (multiply price and item_qty). Math has to be done by the developer - Mailkit doesn't do any math on top of the passed values. Value must be a number without any characters or symbols.
item_discount - item discount amount as percentage or number. The value can later be used in the body of the remarketing message. (max. 8 chars)
item_available - availability of the item whether it's quantity or name of the store. This value can later be used in the body of the remarketing message. (max. 64 chars)
product_url - Product page URL to be used in the campaign body. (max. 256 chars)
product_category - Product category name to be used in the campaign body. (max. 64 chars)
product_cat_url - Product category page URL to be used in the campaign body. (max. 256 chars)
image_url - Product image URL to be used in the campaign body. (max. 256 chars)

Please don't forget that the product_id is the event item identifier that has to be always unique. If you want to change the quantity for an item you must first remove the item altogether and then add the item with the updated quantity.

Alternatively, you can also use the addItemU method to add/update products to the cart. The basic difference between this method and the addItem is the fact that, addItemU is meant as an additive update function. By calling the addItemU function for an item the quantities increase.

An example call for addItemU is following:

Please note that the item_total parameter is missing from this call. This is because, for addItemU the backend handles the sum calculation. So, in case you add 5 items of $5 each; and then add another 5 items of the $5 each; the total will be calculated as $50 by the backend. 

To remove an item from an event (eg. remove from cart) you can call the removeItem function:

Alternatively, you can also call removeItemU in order to remove specific quantities of a certain product. 

Like addItemU, removeItemU also doesn’t take item_total. Backend handles the sums by itself. 
 

Additionally you can remove all event items using clearItems function:

The eventAPI script also provides a function to pass pageviews for advanced visitor tracking. This is especially imporant in case you use 3rd party connection with a recommendation engine (eg. Recombee) using event forwarding. The page views of product detail pages should be passed using a viewItem call.

Resetting event

In some cases it is required to reset an event, meaning the current event cookie gets discarded and new event is created. To facilitate this the fuction resetEvent needs to be called that will destroy the existing cookie and start a new event:

When the resetEvent function is called, the cookie expires in the customer's browser, so the next time the initEvent function is called, a new empty event is created that needs to be filled with items again. The reseted event will remain and will continue to be displayed in the report of pending events (even with the items that were in it at the time of the reset), but the campaign that is connected to the event will no longer respond to this reset event.

Updating event

The initEvent function can be called at any time for a visitor with an existing event identified by a cookie using new event values to update the event. This comes very handy for example when a guest customer adds items to his cart and logs in later during his visit, or your eshop assigns a order id. Remember that more event values you have the better you can take advantage of remarketing events and personalization and increase the efficiency of your campaigns.

Finishing event

Once an event is succesfully completed, eg. an order is placed, you need to mark the event as completed using the finishEvent function:

At this point the event gets marked as completed, the provided invoice number and URLs are stored and the event becomes a succesfull conversion in case a remarketing email has been clicked to complete the event. In case the event has been completed without an remarketing message the conversion will be added to the originating campaign if such a connection can be made.

All of the variables passed to an event and its items can be used in the body of the remarketing campaign, eg. to notify about an invoice issued.