Onboarding guide

The below integration guide provides information about implementing Exposebox on your website. Integration is the first step for data exchange. The step-by-step guide will walk you through the needed steps and scripts.

Table of content

Onboarding wizard – General info and events overview

Once logged in to your Exposebox account, a setup wizard will be displayed.

Steps to access the onboarding wizard:

Go to https://my.exposebox.com/v3/
Insert your account credentials.
The onboarding wizard will be displayed.

The onboarding wizard is composed of 3 parts:

General info – inserting information about your website.
Events – the list of required events to implement on your website.
Product catalog – set up a product catalog feed. Configuring the product catalog will allow Exposebox to access your most updated product catalog.

You can access the setup from the setup wizard and also from the settings screen. If you wish to exit the setup, you can return to it at any time by clicking the setting icon on the right-hand side of the main screen of the dashboard:

General info

As a first step, we need to know basic information about your site:

- Site label – Insert your company/site’s name
- URL – Insert your website URL
- Site logo – Fetch site logo – your logo will be automatically fetched from your website and displayed on the email & SMS unsubscribed page. We support png/jpg formats.
- Currency – Select your store currency.
- Time zone – Select your preferred time zone. The system will use the time zone definition when sending emails and/or SMSs. The system will deliver emails and SMS based on the selected time zone.

Events

Implementing the Exposebox script will allow Exposebox to track and analyze users’ behavior on your website, i.e view product, click on a product, etc.

The events section includes the following:

Overview of the required events to implement.
Validating the implementations of the script.

Exposebox’s scripts and details are displayed in the Events page section of the dashboard’s setup wizard.

Exposebox scripts include the following events:

Basic script

This script needs to be added to every website page regardless of integration type and the information transferred. We recommend implementing the basic script at theof all your webpages.

The script loads asynchronously; and, it won’t affect the page loading time or the user experience.

Additionally, we recommend the script on every future page template so that all future pages on your website will include the script to run the ExposeBox actionable data.

Below, you will find the code snippets for the implementation, with detailed explanations and examples in the following steps.

var companyId = 123456789;//Replace with your actual Company ID provided by Exposebox.

var script = document.createElement(“script”); script.type = “text/javascript”; script.async = true; script.src = “https://sf.Exposebox.com/widget/predictl.min.js?c=” + companyId; //http(s): protocol depends on your website document.getElementsByTagName(“head”)[0].appendChild(script); window.predictlApi = window.predictlApi || function (cb) { var pa = window.predictlApi; pa.or = pa.or || []; pa.or.push(cb); }

</script>

Note: Replace the variable value with the CompanyID provided by Exposebox.

Product pages

The following script reports to Exposebox that visitors to your website viewed a specific product. Integrate the script on every product page.

The product event should send Exposebox the product ID of the product page the visitor is viewing.

Below, there is a general example of the product event. Replace the product-id string with the actual product ID of the product page.

The product ID you send in the product events has to be the same product ID you have provided in the product feed.

window.predictlApi(function () {

window.predictlApi.setProducts([‘product-id‘]);

//replace the product-id string with the actual product-id

});

In case that page contains multiple variants, the product event should use an array of their product IDs:

window.predictlApi(function () {

window.predictlApi.setProducts([“variant-1”,“variant-2”,“variant-3”]);

});

Category pages

This event reports to Exposebox the categories’ breadcrumbs users are viewing. Implement the category page event on all your category pages. This event is required.

The categories breadcrumbs sent in the event have to match the categories provided in the product catalog feed.

The category array order goes from the top category to the lowest category.

Example:

window.predictlApi(function () {

window.predictlApi.setCategories([‘electronics’,‘tv’,’oled_televisions’]);

});

Add to cart

The ‘Add to Cart’ event reports when users added products to their carts.

The event includes:

productID – the ID of the product that is added to the cart.
Quantity – the number of items of the product that were added to cart.
Unit price – the unit price of the item added to cart.

Example:

window.predictlApi(function () {

var productId = “12345”;

var quantity = 3;

var unitPrice= 40.00;

window.predictlApi.events.addToCart(productId, quantity,unitPrice);

});

Remove from cart

The ‘Remove from cart’ event reports when a user has removed a product from their cart. In case a user removes 3 items from their cart in one action, make sure to send in the quantity variable the number of items removed.

window.predictlApi(function () {

var productId = “p34212332”;

var quantity = 3;

window.predictlApi.events.removeFromCart(productId, quantity);

});

Add to Cart and Remove from Cart events example:

Scenario:

A user added three items to cart ( event= “add 3”)
Then the user removed two items from the cart ( event= “remove 2”)
Then the user added an additional item to cart ( event= “add 1”)

For this scenario, you will need to send us the following events:

Add to cart:

window.predictlApi(function () {

var productId = “p34444”;

var quantity = 3;

var unitPrice= 76.50;

window.predictlApi.events.addToCart(productId, quantity,unitPrice); }

);

Remove from cart:

window.predictlApi(function (){

var productId = “p34444”;

var quantity = 2;

window.predictlApi.events.removeFromCart(productId, quantity);

});

Add to cart:

window.predictlApi(function () {

var productId = “p34444”;

var quantity = 1;

var unitPrice= 76.50;

window.predictlApi.events.addToCart(productId, quantity,unitPrice); }

);

Purchase/Conversion

The purchase event reports to Exposebox the purchase information a user completed. The event needs to be sent after the user completes their purchase at the ‘Thank You’ page.

The event includes the following variables –

order ID – purchase order number

total price – the total price of all the purchased products- the total needs to be the amount paid by the customer deducting discounts, coupons, and delivery fees.

cart products – purchased products, quantity, and unit price.

Example:

window.predictlApi(function () {

var orderId = “order-45215”; // Store order id

var totalPrice = 254;// Order total price after discounts, coupons and delivery.

var cartProducts = [

{productId: “p34212332”,quantity: 2, unitPrice: 43.00},

{productId: “p34212345”,quantity: 3, unitPrice: 56.00}

];

predictlApi.events.conversion(cartProducts, orderId, totalPrice);

});

Customer

In order to collect customers’ information, the customer event should be implemented. This script is also required in order to send emails and SMS messages.

Please implement this event in the following scenarios:

Users complete the sign-up process.
Users log in to your website.
Users who checked out and confirmed to receive marketing material (subscribed).

The event includes the following fields:

- customerId – mandatory field.
- email
- firstName
- lastName
- phone
- address1
- address2
- city
- country
- zipCode
- freeData
- subscribedUserLists – mandatory when a user agrees to receive marketing materials (emails and SMS messages).
- unsubscribedUserLists

Customer ID– the customer ID from your system. If you don’t have one, an email address can be used as the customer identifier; meaning the CustomerID will be the email address. The customer ID field is mandatory. All other fields are optional.
freeData – free data field allows you to provide any additional customer information you would like to use. For example (date of birth, club membership, branch, etc).
subscribedUserLists – this field is required in order to add the user to the marketing user list. Please add this code in the setCustomerData event only if the user opted-in marketing materials, otherwise don’t include it.
unsubscribedUserLists – Include this code in the setCustomerData event only if the user wishes to unsubscribe in the website’s personal account section.

Example of customer event when the user agrees to receive marketing materials:

window.predictlApi(function () {

window.predictlApi.setCustomerData({

customerId: ‘123456’, //the customer ID as defined in your systems

email: ‘testing@exposebox.com’,

name: ‘John’,

lastName: ‘Snow’,

phone: ‘540542643454’, //phone can be sent with “-” separators and without

freeData: { //allow you to send us any extra information about the user

Gender: ‘Male’,

DateOfBirth:‘1992-12-24’,

ClubMembershipEndDate: ‘2022-01-05’

}

subscribedUserLists:[‘master-email’,’master-sms’] //send us subscribedUserLists command only if the user agreed to receive marketing materials, otherwise omit this command.

})

});

Example of customer event when the user does not agrees to receive marketing materials:

window.predictlApi(function () {

window.predictlApi.setCustomerData({

customerId: ‘123456’, //the customer ID as defined in your systems

email: ‘testing@exposebox.com’,

name: ‘John’,

lastName: ‘Snow’,

phone: ‘540542643454’, //phone can be sent with “-” seperators and without

freeData: { //allow you to send us any extra information about the user

Gender: ‘Male’,

DateOfBirth:‘1992-12-24’,

ClubMembershipEndDate: ‘2022-01-05’

}

})

});

Example of customer event for registered users during checkout:

window.predictlApi(function () {

window.predictlApi.setCustomerData({

customerId: ‘123456’, //the customer ID as defined in your systems

email: ‘testing@exposebox.com‘,

name: ‘John’,

lastName: ‘Snow’,

phone: ‘540542643454’, //phone can be sent with “-” separators and without

freeData: { //allow you to send us any extra information about the user

Gender: ‘Male’,

DateOfBirth:‘1992-12-24’,

ClubMembershipEndDate: ‘2022-01-05’

}

subscribedUserLists:[‘master-email’,’master-sms’] //send us subscribedUserLists command only if the user agreed to receive marketing materials, otherwise omit this command.

})

});

Example of customer event on a user wishes to unsubscribe in the website’s personal account section:

window.predictlApi(function () {

window.predictlApi.setCustomerData({

customerId: ‘123456’, //the customer ID as defined in your systems

email: ‘testing@exposebox.com‘

unsubscribedUserLists:[‘master-email’,’master-sms’] //send us subscribedUserLists command only if the user agreed to receive marketing materials, otherwise omit this command.

})

});

Search and filter (optional)

Implement this event only if you would like to show product recommendations on the search and filter page.

Adding the search and filter tags allows Exposebox to identify current user interests and optimize the recommended products. This event should be sent when users search or filter based on their shopping preferences.

In the example below, a user searched for “Men winter coats” and filtered the results by category, min prices, and fabric type.

Example of a search event for query:

window.predictlApi(function () {

var products = [‘p34212332’,‘p3426678’,‘p3426888′,’p31426648′,’p2426831′,’p5826888’];
//Top 6 product results of the query

window.predictlApi.events.sendEvent(“searchAndFilter”,{

products: products,

query: ‘Men winter coats’, //The search query products

});

Example of a filtered event based on the filtered parameters:

window.predictlApi(function () {

var products = [‘p34212332’,‘p3426678’,‘p3426888′,’p31426648′,’p2426831′,’p5826888’];//Top 6 product results of the query

window.predictlApi.events.sendEvent(“searchAndFilter”,{

products: products,

//All the search parameters filtered by the user

categories: [‘Men’,‘Coats’],

minPrice: 11.0,

maxPrice: 51.0,

fabric: [‘tweed’,‘wool’]

});

Checkout (optional)

The event needs to be sent once the customer clicks on the checkout button or when the checkout page loads.

window.predictlApi(function () {

window.predictlApi.events.sendEvent(‘checkout’,{type:‘cartPage’});

});

In case your checkout process is built from several steps, please send a different event, for every checkout page.

For example, if your checkout process has the following three pages:

Cart page
Customer details
Insert more customers details

You will need to send checkout events with multiple checkout types, for example:

Cart page

window.predictlApi(function () {

window.predictlApi.events.sendEvent(‘checkout’,{type:‘cartPage’});

});

Customer details

window.predictlApi(function () {

window.predictlApi.events.sendEvent(‘checkout’,{type:‘customer_details’});

});

More details page

window.predictlApi(function () {

window.predictlApi.events.sendEvent(‘checkout’,{type:‘more_details’});

});

Segmentation tags (optional)

Segmentation tags allow you to segment users based on customized attributes, which you can later group to specific audiences. When creating product recommendations and email campaigns, you can use these audience-based segments.

The segmentation tag contains a key-value pair that you define based on your marketing/business agenda.
Segmentation tags must be defined prior to integration.

Example: An article page with the keyword ‘Hobbies’ and contains values such as ‘knitting’ or ‘gardening’ will enable you to create audience groups sharing an interest in knitting or gardening.

window.predictlApi(function () {

var tags = {

hobbies:[‘knitting’,‘gardening’],

priceRange: [‘0-100’]

};

window.predictlApi.setTags(tags);

});

*Exposebox platform allows you to segment users without the need to implement the script above. The script above is an alternative way to allow you to segment users.

Wishlist – Add and remove (optional)

The wishlist events allow Exposebox to know when users added or removed an item from their wishlist.

Add to wishlist

window.predictlApi(function () {

var productId = ‘p34212332’;

window.predictlApi.events.addToWishlist(productId);

});

Remove from wishlist

window.predictlApi(function () {

var productId = ‘p34212332’;

window.predictlApi.events.removeFromWishlist(productId);

});

Validating events implementation

The validation of the implementation should be done only after configuring the product feed in our platform.

Validating the events includes two parts:

Validating that events were successfully received by Exposebox
Validating that Exposebox processed the events successfully.

Validating that events were successfully received by Exposebox. In order to validate that the scripts are implemented as required, go to Settings -> Events, you will see a list of the events.

A green icon will be displayed next to every event we received successfully.

Validating that Exposebox processed the events successfully

In this section please check that the events are valid and processed successfully by the platform.

On the events page, scroll down to the ‘Event List’ section.

In the example above, you can see that in the last seven days, 324,110 product events were sent and processed successfully.

A green button in the Status column next to the date indicates that the events are received and processed by the platform.
A yellow button indicates that events were partially processed successfully.
A red button indicates that all the events were not processed successfully.

To view more information about the events you sent, click on the ‘View Details’ button.

The screen displays the last 100 received events of this event type.
The number of received events by domain for the selected event type.

Product catalog (feed)

A product feed is required to allow Exposbox to receive your up-to-date products. Our onsite product recommendation widget and personalized emails use this data when displaying your products.

Exposebox platform will access the URL you provide us. It will read your product catalog at the predetermined frequency you will set, and update our database with your latest product updates

The product feed configuration requires setting up the following parameters:

Feed formats

We support three types of feed format:

Google Merchant – Google feed format. For more information click here.
Facebook Ads – Facebook feed format. For more information click here
Exposebox – Exposebox feed format. For more information continue further below.

File types

We support the following file types:

Frequency run product catalog

The platform will access your feed based on the predetermined frequency:

Every 4 hours
Every 8 hours
Every 12 hours
Once a day

Feed URL

Add your feed URL. The provided URL should not be protected by username and password.

Exposebox feed format

In the following section, we will specify requirements to create the Exposebox feed format.

Example for Exposebox CSV feed file:

https://storage.googleapis.com/ex-tmp/ProductFeedImporter/ExposeBox%20feed%20example%20-%20for%20Onboarding.csv

Example for Exposebox XML feed file:

https://storage.googleapis.com/ex-tmp/ProductFeedImporter/Exposebox%20-%20feed%20-%20%20XML.xml

The feed should contain the following fields:

Name	Type	Mandatory/Optional	Description
id	String	Man.	Your product ID is a unique identifier for your products in the system.
item_group_id	String	Opt.	Use a Unique Identifier for every group of variants. Use the item Group IDproperty for products that vary by various attributes. E.g., a shirt with various colors and sizes (all of those variants will have the same item GroupID).
title	String	Man.	Product name
price	Decimal	Man.	Product price
sale_open	Boolean / (TRUE or FALSE)	Man.	Your product’s availability. If you don’t want a product to be recommended, set it as 0 or FALSE.
url	String	Man.	Product page URL
image_url	String	Man.	Product image URL
supplier_id	String	opt.	SupplierID determined by the marketplace
catalog_id	String	Opt.	A product catalog (typically the highest classification/categorization of products). For example, one feed will contain two different catalogs – products and blog articles.
category	String/Array of strings/ Strings separated by “>”	Man.	The category must match the category’s breadcrumbs sent in the category events. The array should represent the breadcrumbs / categories path leads to a specific product. The order in the array will be from the category at the lowest level of filtering to the highest level (the latter category will be last). For example: [“Clothing”,”Unisex T-Shirts and Tops”] or Electronics > Televisions > OLED TVs > Samsung Oled TV. If the category is only one level, please send the category as a string. Example For XML: <category>Electronics > Televisions > OLED TVs > Samsung Oled TV</category>
on_sale	Boolean	Opt.	Is the product currently discounted or on sale.
description	String	Opt.	Product description
brand	String	Opt.	Product brand
currency	String	Opt.	Currency
original_price	String	Opt.	Original price of product
free_data	JSON/ Object	Opt.	Any additional data that is not part of Exposebox default fields mentioned above can be added to free_data field as a JSON object. An additional way to include more data is to add columns to the feed. In this method, the platform will automatically import the extra columns to the free data field. For reference please see CSV feed file example below: https://storage.googleapis.com/ex-tmp/ProductFeedImporter/ExposeBox%20feed%20example%20-%20for%20Onboarding.csv
tags	tag element	Opt.	Product tags. Similar to category field, without a hierarchy. Example for XML file: <tags> <tag>example-1</tag> <tag>example-2</tag> </tags>

Once the feed is processed, you will be able to see the feed importing process results in the Product catalog setup screen where you previously configured your feed.

In case the platform encounters issues importing the feed or some of the products due to incorrect data fields or format issues, a View Errors button will be displayed to review the issues and fix the product catalog.

HTML required design for onsite product recommendation

When creating an onsite product recommendation campaign, you can use Exposebox pre-sets design templates or use an HTML design you provide.

Our platform doesn’t have any restrictions about the HTML design you provide. Typically, the product recommendation design will include a product title, product description, price, but it can include any information you desire to display and you provide us in the product feed catalog.

Email campaigns – DNS configuration

In order to send emails from the platform, the following steps are required:

Define your subdomain for email delivery. For example marketing.exposebox.com. Email address is composed of two parts: local-part and subdomain: local_part@subdomain. For example adam@marketing.exposebox.com. This is the domain name that will be used when sending emails.
Share your subdomain name with Exposebox. Once the subdomain is received, Exposebox will create the requested subdomain on our platform.
Exposebox will send you a DNS configuration you are required to set up on your end.
Once you complete the DNS configuration please update Exposebox so we can verify that your configuration was done properly

SMS campaigns

SMS configuration is done by Exposebox. Please inform your contact person if you would like to send promotional and automated SMS messages.

Need help?

Cookie	Duration	Description
cookielawinfo-checkbox-advertisement	1 year	Set by the GDPR Cookie Consent plugin, this cookie is used to record the user consent for the cookies in the "Advertisement" category .
cookielawinfo-checkbox-analytics	12 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	12 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	12 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	12 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	12 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
elementor	never	This cookie is used by the website's WordPress theme. It allows the website owner to implement or change the website's content in real-time.
viewed_cookie_policy	12 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.
__hssrc	session	This cookie is set by Hubspot whenever it changes the session cookie. The __hssrc cookie set to 1 indicates that the user has restarted the browser, and if the cookie does not exist, it is assumed to be a new session.

Cookie	Duration	Description
__cf_bm	30 minutes	This cookie, set by Cloudflare, is used to support Cloudflare Bot Management.
__hssc	30 minutes	HubSpot sets this cookie to keep track of sessions and to determine if HubSpot should increment the session number and timestamps in the __hstc cookie.

Cookie	Duration	Description
hubspotutk	1 year 24 days	This cookie is used by HubSpot to keep track of the visitors to the website. This cookie is passed to Hubspot on form submission and used when deduplicating contacts.
_ga	2 years	The _ga cookie, installed by Google Analytics, calculates visitor, session and campaign data and also keeps track of site usage for the site's analytics report. The cookie stores information anonymously and assigns a randomly generated number to recognize unique visitors.
_ga_SGNK47PP0Y	2 years	This cookie is installed by Google Analytics.
_gcl_au	3 months	Provided by Google Tag Manager to experiment advertisement efficiency of websites using their services.
__hstc	1 year 24 days	This is the main cookie set by Hubspot, for tracking visitors. It contains the domain, initial timestamp (first visit), last timestamp (last visit), current timestamp (this visit), and session number (increments for each subsequent session).

Cookie	Duration	Description
fr	3 months	Facebook sets this cookie to show relevant advertisements to users by tracking user behaviour across the web, on sites that have Facebook pixel or Facebook social plugin.
_fbp	3 months	This cookie is set by Facebook to display advertisements when either on Facebook or on a digital platform powered by Facebook advertising, after visiting the website.

Cookie	Duration	Description
HappyLocalTimeZone	session	No description available.
m	2 years	No description available.
_calendly_session	21 days	No description available.