Custom Integration Guide
Introduction
Information given in this guide will enable you to send page view, product view, add to cart,
and purchase behavior to Rejoiner.
The API offered by Rejoiner consists of two complementary parts: Javascript API and REST API.
For most situations, you would only be using the Javascript API; However, in some cases
(for conversion tracking) you might also want to use our REST API.
Preparation
In order to use our services, you need to properly authenticate your application with Site ID and Domain.
In the case of using our REST API, you would also be required to authorize your requests using your API Key, available in your account's Domain Settings.
Javascript Based Tracking
For a full specification of the endpoints available, please see the Javascript Endpoints documentation.
Basic Code Snippet
The Rejoiner Javascript API tracks browsed pages and products by default and is called whenever the library is loaded. This means that you should place the following base snippet on every page loaded by end-users in order to be able to track page views. Tracking product views requires you to explicitly call the trackProductView
endpoint.
The base snippet also automatically scans forms to find a customer's email address and associates it with the current browsing session. If you want to restrict forms and fields for us to scan, or if you want to set customer data explicitly, see Storing Information About Customers
The following is the basic code snippet that is required to load the Rejoiner library:
Basic Code Snippet:
<script type="text/javascript">
var _rejoiner = _rejoiner || [];
_rejoiner.push(['setAccount', '{{ site_id }}']);
_rejoiner.push(['setDomain', '{{ site_domain }}']);
(function() {
var s = document.createElement('script'); s.type = 'text/javascript'; s.async = true;
s.src = '//cdn.rejoiner.com/js/v4/rj2.lib.js';
var x = document.getElementsByTagName('script')[0];
x.parentNode.insertBefore(s, x);
})();
</script>
Tracking Cart Activity
Please remember that all prices should be given in cents (e.g. $45.99 => 4599)
There are two endpoints that allow you to collect cart data:
[setCartData
]({% site_url 'docs_article' category='api' slug='javascript-api-endpoints' %}#setcartdata)
and
[setCartItem
]({% site_url 'docs_article' category='api' slug='javascript-api-endpoints' %}#setcartitem)
setCartData
To collect general information about a transaction, use the setCartData
endpoint.
setCartData Example:
_rejoiner.push(['setCartData', {
'cart_value': 7996, // Total Value (in cents)
'cart_item_count': 4, // Total Number of Items in Cart
'promo': 'PROMO', // Promo Code applied to cart (if applicable)
'return_url': '...', // URL to Regenerate Cart
}]);
setCartItem
To collect more specific information about items in a cart, use the setCartItem
endpoint. This should be
called for each item in a cart.
setCartItem Example:
_rejoiner.push(['setCartItem', {
'product_id': 'SKU-1000', // Unique ID identifying product
'name': 'Product Name',
'category': ['product', 'categories'],
'price': 2999, // Unit Price (in cents)
'item_qty': 2, // Quantity of Item in Cart
'qty_price': 5998, // Total Price (in cents)
'product_url': '...', // URL of Product Listing
'image_url': '...', // URL of Product Image/Thumbnail
'description': '...',
}])
These two endpoints will either add or update cart data and cart item data. In order to remove an item from a customer's cart, the removeCartItem
endpoint should be called.
removeCartItem Example:
_rejoiner.push(['removeCartItem', {'product_id': 'SKU-1000'}]);
You should also call
setCartData
with updated parameters after removing a cart item.
To remove a customer's cart data entirely, use the clearCartData
endpoint.
clearCartData Endpoint:
_rejoiner.push(['clearCartData']);
Tracking Conversions
After an order has been completed, Rejoiner needs information about the conversion that happened.
For tracking a conversion, you should call the sendConversion
endpoint.
While it is possible to call
sendConversion
without any arguments, we highly encourage you to provide thecart_data
andcart_item
parameters in addition. Doing so will provide greater accuracy as to the value of the conversion.
sendConversion Example Without Parameters:
_rejoiner.push(['sendConversion']);
sendConversion Example With Parameters:
var cartData = {
'cart_value': 2998,
'cart_item_count': 2,
'return_url': 'http://example.com/cart/12345'
};
var cartItems = [
// First Item
{
'product_id': 'SKU-1000',
'name': 'Product Name',
'category': ['product', 'categories'],
'price': 2999,
'item_qty': 2,
'qty_price': 5998,
'product_url': '...',
'image_url': '...',
'description': '...',
},
// Second Item
{ ... }
];
_rejoiner.push(['sendConversion', {
'cart_data': cartData,
'cart_items': cartItems
}]);
Tracking Browse Behavior
Tracking Page Views
The Rejoiner Library will automatically track page views every time the library is loaded. If you wish to disable this functionality, you can do so with the trackPageView
endpoint like so:
Disabling trackPageView.
_rejoiner.push(['trackPageView', false]);
Manually Tracking Page Views
If you need to manually track page views in situations like a single-page-app where the library is only loaded once, you can do so with theaddPageView
endpoint.
addPageView Example:
_rejoiner.push(['addPageView', {
'url': '...' // URL of the Page
}]);
Tracking Product Views
In order to provide effective recommendations and product information for browse abandonment campaigns, it is useful to provide information about the products that a customer views. This is done similarly to setCartItem
calls using the trackProductView
endpoint.
The data provided by this endpoint is also used by Rejoiner to build up information about your site's catalog. It can be considered as an endpoint to provide Rejoiner with information about a product in your store, in addition to marking it as a product the customer viewed.
trackProductView Example:
_rejoiner.push(['trackProductView', {
'product_id': 'SKU-1000',
'name': 'Product Name',
'category': ['product', 'categories'],
'price': 2999,
'product_url': '...',
'image_url': '...',
'description': '...',
}]);
Storing Information About Customers
There are several endpoints that will help you define what information is sent about a current visitor.
The setCustomerData
endpoint can be used to send additional information about the demographics of a customer.
setCustomerData Example:
_rejoiner.push(['setCustomerData', {
'age': 27,
'gender': 'm',
'language': 'en',
'first_name': 'John',
'last_name': 'Doe'
}]);
The setCustomerEmail
endpoint can be used to manually identify the customer based on their email. This is useful if a customer is logged in or you have identified the customer in another way, instead of waiting for the customer to enter their email into a form.
setCustomerEmail Example:
_rejoiner.push(['setCustomerEmail', {'email': '[email protected]'}]);
Additionally, there are several endpoints that can restrict the forms and fields we collect data from
documented here.
REST API Usage
The REST API can be utilized in addition to the Javascript API to provide a complete set of data to Rejoiner. The most common use case is to send conversion data via the REST API's /customer/convert
endpoint.
Updated over 3 years ago