API Integration Guide

Introduction

Information given in this document will enable you to send data related to page views, product views, add to cart, and purchases 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, like conversion tracking, you might also want to use our REST API.

Quick Outline

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

These are available in your account's Domain Settings page as shown here.

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 which is required to load the Rejoiner library.

Basic Snippet:

<script type="text/javascript">
var _rejoiner = _rejoiner || [];
_rejoiner.push(['setAccount', 'YOUR-SITE-ID']);
_rejoiner.push(['setDomain', 'YOUR-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

NOTE: Please remember that all prices should be given **in cents** (e.g. $45.99 => 4599)

In order to have an effective campaign, it is useful to gather information about a customer's cart. There are two endpoints that allow you to collect cart data:  setCartData and setCartItem

To collect general information about a transaction, use the  setCartData endpoint.

setCartData Call 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
}]);

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 Call 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 Call 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.

Important: While it is possible to call sendConversion without any arguments, we highly encourage you to provide the cart_data and cart_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 the addPageView 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 which 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': 'test@example.com'}]);

Additionally, there are several endpoints which 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.

Still need help? Contact Us Contact Us