API Overview
After the BouncePilot Snippet is loaded to your page, you can start sending events to BouncePilot via the BouncePilot
JavaScript object that became available on your DOM.
The calls that can be used to send data are following:
Call | Parameters | Description |
---|---|---|
setVisitId | visitId | Inform BouncePilot of your internal visit ID (e.g. cookie ID, session ID, other). This call is particularily useful when later synching/correlating BouncePilot data with your internal visit data. |
pageView | URL | Inform BouncePilot that your user has viewed a page. |
productCategoryView | dataJSON | Inform BouncePilot that your user has viewed a specific product category. |
productView | dataJSON | Inform BouncePilot that your user has viewed a product page. |
cartView | dataJSON | Inform BouncePilot that your user added an item into a cart. |
cartPurchase | dataJSON (optional) |
Inform BouncePilot that the user has purchased the content of his cart on your site and we should no longer remind him about ongoing shopping. |
setEmail |
In the event that the user is identified, and it is not desired to contact the user,
this call allows you to send us an unhashed version of your customers email. This call is typically invoked upon a login action where the identity of the user is known. These data will be annonymized (hashed and forgotten) immediately on client side (we don't want to send the email to our servers) and we definitely recommend that you avoid using this method of communicating the email whenever avoidable - handing sensitive customer data to 3rd parties is never a good way to go. |
|
setEmailHash | hash | This call has the same effect as setEmail above, however it allows you to send us a MD5 hash of your customer's email rather than in plain-text. |
doNotContact |
This call will inform BouncePilot not to contact the user for retargeting emails. At any time during a shopping session, you may wish to avoid calling this user for any reason, this is ideal for this situation. |
JSON Payloads
The JSON payloads that you need to prepare and send to us are completely customizable and under your complete control - the structure of the JSON product representation can be pretty match anything you desire as long as it is a valid JSON object.
The objects sent to the specific action should be standardized as the BouncePilot team will take care for going through your data and implementing the right set of parsers that will match the data structure that you want to send to us. This means whatever the JSON format you decide to utlize, please ensure these are consistent across all API calls of the same action.
One thing to keep in mind is that the retargeting email templates will only be able to send the data which is included within the JSON Payloads. Therefore, if you would like to send a product description within your campaign, then the description must be included in some way or another in the payload.
Only formal limitation for the data is that the mandatory data must be found in the payload.
Mandatory Data
While the API allows for a completely open format for the JSON payloads, there are a few mandatory fields which must always be present within the payloads for eventual deliverability to the user.
You may note that there are no requirements on the naming of the fields/attributes of the mandatory data. Our API will accept all objects, however if mandatory data is not provided as part of the payload, the email template will not success in populating an email with the minimally-required data and will ulitmately result in no emails being sent.
Call | Mandatory Parameters |
---|---|
productCategoryView | An identifier which you use to identify the specific product category. |
productCategoryView | The product category's name. |
productCategoryView | A resume link (in the form of a URL) which can be used to jump back into the shop. |
productView | An identifier which you use to identify the specific product. |
productView | The product's price. |
productView | The product's name. |
productView | A resume link (in the form of a URL) which can be used to jump back into the shop. |
cartView | A price for each item within the cart. |
cartView | A name for each item within the cart. |
cartView | A resume link (in the form of a URL) which can be used to jump back into the shop. |
API Examples
Calling setVisitId
Inform BouncePilot of your internal visit ID (e.g. cookie ID, session ID, other). This call is particularily useful when later synching/correlating BouncePilot data with your internal visit data.
The call accepts one parameter, which should be a String representation of your internal visit ID (e.g. cookie ID, session ID, other).
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['setVisitId', '81d72893-edf3-4957-a836-9b496b882099']);
</script>
Calling pageView
Inform BouncePilot that an user has viewed a page.
The call accepts one parameter, which should be an URL of the page the user is currently viewing.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['pageView', window.top.location.href]);
</script>
Calling productCategoryView
Inform BouncePilot that your user has viewed a specific product category.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['productCategoryView', 'productCategoryView_id',
{
"id": "product_category_id_1",
"name": "Awesome Products",
"description": "Category of Awesome Products that you cannot avoid buying!",
"image": "https://acme.com/product/product_category_id_1/image-main.png",
"url": "https://acme.com/product-category/product_category_id_1/"
}]);
</script>
Calling productView
Inform BouncePilot that the user has viewed a specific product page.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['productView', 'productView_id',
{
"id": "product_id_1",
"name": "Awesome Product",
"description": "Just another Awesome Product that you cannot avoid buying!",
"image": "https://acme.com/product/product_id_1/image-main.png",
"url": "https://acme.com/product/product_id_1/",
"price": "499",
"currency": "USD"
}]);
</script>
Calling cartView
Inform BouncePilot that your user has viewed a cart that so we can take care for preparing the abandoned cart campaign.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['cartView', 'cartView_id',
{
"items" : [
{
"id": "product_id_1",
"name": "First Awesome Product",
"description": "Just another Awesome Product that you cannot avoid buying!",
"image": "https://acme.com/product/product_id_1/image-main.png",
"url": "https://acme.com/product/product_id_1/",
"price": "499",
"currency": "USD",
"quantity": 1
},
{
"id": "product_id_2",
"name": "Secong Awesome Product",
"description": "Even better Awesome Product that you cannot avoid buying!",
"image": "https://acme.com/product/product_id_2/image-main.png",
"url": "https://acme.com/product/product_id_2/",
"price": "699",
"currency": "USD",
"quantity": 1
}
],
"cta_link":"acme.com/cart?ck=473-6978-44951"
}
]);
</script>
Calling cartPurchase
Inform BouncePilot that the user has purchased the content of his cart on your site and we should no longer remind him about ongoing shopping.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['cartPurchase',
'order_id', // please use the internal order ID (which you will use for conversion reporting) for this value
[{
id: 'abc',
quantity: '2',
price: '1.99',
name: 'Item Name',
currency: 'USD'
}
]]);
</script>
Calling setEmail
This call allows you to send us your customers email that you do not want us to contact if they abandon the shop.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['setEmail', 'bob@example.com']);
</script>
Calling setEmailHash
This call allows you to send us a MD5 hash of your customers email that you do not want us to contact if they abandon the shop.
Note: when hashing email addresses, it is very important to cast the email address string to lowercase AND trim all leading and trailing whitespaces. Hashed emails which to not follow this process will not be properly matched.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['setEmailHash', 'ff6e7e35d5d696365b729b7408d588f0']);
</script>
Calling doNotContact
This informs BouncePilot that you do not want us to contact if they abandon the shop. It requires no input parameters.
<script type="text/javascript">
window._bopiq = window._bopiq || [];
window._bopiq.push(['doNotContact']);
</script>