JavaScript API Library

Part of Sailthru’s onsite JavaScript library, these functions offer an easy alternative to using traditional server-to-server integrations to connect with Sailthru’s API.

Include these easily configurable JavaScript functions on your site, allowing the user’s browser to communicate directly with Sailthru to perform actions including signing up a user, adding an item to a cart, making a purchase, or a custom event. These functions are fully compatible with popular tag managers including Google Tag Manager, allowing for quick and easy implementation.

These JS calls offer a subset of the many capabilities of Sailthru’s API. If you have sufficient development resources, it is recommended that you consider coding a server-side API integration, as AJAX requests from the browser introduce the possibility of occasional dropped calls due to latency. However, the success/error responses provided by these functions offer the opportunity to compensate for any such issues that may arise.

It’s simple to get up and running. Use a tag manager or copy and paste the below Sailthru script tag into your site.

<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>Sailthru.init({ customerId: <yourId> });</script>

For details about setting up this latest JavaScript for all other Sailthru functions, please see Personalization Engine Setup. Note that these simple integration functions are also available for our clients using v0.0.4 of the Sailthru script tag.

userSignUp

Add a user to Sailthru by email address, or modify data for an existing user. You can optionally add or update Natural List membership(s), user var data, and an acquisition source. The function will update an existing user profile if the email address already exists as a user profile key.

Recent pageviews, recorded to a cookie while the user was browsing anonymously, are automatically passed into the function to build the new or existing user’s interest profile.

The capabilities of userSignUp can alternatively be performed with the Sailthru User API.

Note: Alternatively, you can use the userSignUpConfirmedOptIn function, which sends a confirmation email and only adds the user to a specified list after the user clicks a confirmation link within the email.

Usage

Sailthru.integration("userSignUp",
{
  "email" : "<address>" , 
  "lists" : { <list1> : <membership>, <list2> : <membership> },
  "vars" : { <var key and value> },
  "source" : <string>,
  "onSuccess": <response>,
  "onError": <response>
});

Parameters

  • email – Required
  • id – alternate user identifier – Required if email not included
    key – type of specified id – Required if email not included; must match a key type available via User API
  • lists – Natural lists to add the user. Required if vars or source not specified
    • Use key-value pairs, with listName as key.
    • Value of 1 to add to the list.
    • Value of 0 to remove from the list.
  • vars – Required if lists or source not specified
  • source – acquisition source name (e.g. “Facebook campaign”) – Optional
  • onSuccess – JavaScript function that is called on a successful submission – Optional
  • onError – JavaScript function that is called when the function fails – Optional

Example

Sailthru.integration("userSignUp", 
{ "email" : "user@example.com",
  "lists" : {
    "Master List" : 1, // list to add user to (must exist in Sailthru account)
    "Anonymous" : 0 // list to remove user from (must exist in Sailthru account)
  },
  "vars" : {
    "sign_up_date" : "today",
    "first_name" : "Bob"
  },
  "source" : "web",
  "onSuccess" : "function() {
    alert('Thank you for signing up for our list');"
  },
  "onError" : "function() {
  alert('We encountered an issue signing you up. Please try again');"
  }
});

userSignUpConfirmedOptin

Request that an opt-in confirmation email is sent to a user before they are added to a specified list. If the user does not already exist in Sailthru, the user is added to your account. In any case, the user will not be added to the list until they confirm via the link in the confirmation email.

Recent pageviews, recorded to a cookie while the user was browsing anonymously, are automatically passed into the function to build the new or existing user’s interest profile.

The capabilities of userSignUpConfirmedOptin can alternatively be performed with the Sailthru User API.

Usage

Sailthru.integration("userSignUpConfirmedOptIn", {
   "id" : "<user id>",
   "key" : "<user id type>",
   "source" : "<acquisition source>",
   "template" : {
       "name" : "<confirmed opt-in template name>",
       "vars" : {
           "<var name 1>": "<var value 1>",
           "<var name 2>": "<var value 2>"
       }
   }
}

Parameters

  • email – user’s email address – Required if ID/key object not included
  • id – alternate user identifier – Required if email not included
  • key – type of specified id – Required if email not included; must match a key type available via User API
  • name – Confirmed opt-in template to send – Required
  • vars – Template vars; vars accessible within the opt-in template – Optional
  • source – acquisition source name (e.g. “Facebook campaign”) – Optional

Example

Sailthru.integration('userSignUpConfirmedOptIn', {
   "id" : "user@example.com",
   "key" : "email",
   "source" : "Twitter campaign",
   "template" : {
       "name" : "twitter_welcome",
       "vars" : {
           "name": "Mike",
           "source_tweet": "https://twitter.com/sailthru/status/829425076672069632"
       }
   }
});

addToCart

Call this function each time a user adds an item to their cart or removes an item from their cart. Each time the cart contents changes, submit an array of all cart items.

By specifying reminder_template and reminder_time, you can configure an abandoned-cart message that the user should receive if they do not make a purchase before the reminder_time has elapsed.

All parameters available for a purchase in the Purchase API are available with this function, as well. Required parameters are email and URL or SKU.

Usage

Sailthru.integration("addToCart", {
  "<email>",
  "items": [{
    "url": <url>
  }],
  "reminder_template": <template name>,
  "reminder_time": <time span>
});

Parameters

  • email – Required
  • items – Required
    • url or sku – Required
    • title – Optional
    • images – Optional
    • vars – Item-specific vars for purchase – Optional
    • price – Optional
  • reminder_time – Required for reminder email to be sent if no purchase or additional addToCart is made within reminder_time – Optional
  • reminder_template – Required if reminder_time is set – Optional
  • onSuccess – JavaScript function that is called on a successful submission – Optional
  • onError – JavaScript function that is called when the function fails – Optional

Example

Sailthru.integration("addToCart", {
  "user@example.com",
  "items": [{
    "url": "http://example.com/item/12345",
    "sku": 123456789, 
    "title": "Great Boots",
    "price": 13900,
    "images": {"full": "http://example.com/image/12345.png"}, 
    "vars" : {"discount": 123} 
  }],
  "reminder_template": "Cart Reminder",
  "reminder_time":"+45 minutes",
  "vars" : {"free_shipping": "yes"} 
 });

purchase

Call this function each time a user completes a purchase, submitting an array of all purchased items. This will cancel any scheduled cart reminder email, and decrement stock levels if they are synced with Sailthru.

All parameters available for a cart update in the Purchase API are available for use with this function, as well. Required parameters are email and URL or SKU.

Usage

Sailthru.integration("purchase", {
  "<email>", 
  "items": [{
    "url": <url>,
    "qty": <quantity>
  }],
 });

Parameters

  • email – Required
  • items – Required
    • url or sku – Required
    • qty – Quantity of item – Optional
    • images – Optional
    • vars – Item-specific vars for purchase – Optional
    • price – Optional
  • For additional optional parameters, see the Purchase API POST call.
  • onSuccess – JavaScript function that is called on a successful submission – optional
  • onError – JavaScript function that is called when the function fails – optional

Example

Sailthru.integration("purchase", {
    "user@example.com",
    "items": [{
            "url": "http://example.com/item/12345",
            "sku": 123456789, 
            "qty": 1,
            "title": "Great Boots",
            "price": 13900,
            "images": {"full": "http://example.com/image/12345.png"}, 
            "vars" : {"discount": 123} 
            
        }],
    "tenders": [
            {
                "price":"13900",
                "title":"Amex"
            }
        ],
    "purchase_keys": {
        "extid":"123"
    },
    "vars" : {"free_shipping": "yes"} 
});

customEvent

Trigger a custom event call to add/update a user var, send an email, initiate a Lifecycle Optimizer flow, or other Sailthru event. The schedule_time parameter is not supported. The trigger time defaults to ‘now’.

Usage

Identify user by email

Sailthru.integration('customEvent', {
    "name" : "<eventName>", 
    "email" : "<userEmailAddress>",
    {"vars" :
    {
        "<varKey1>": "<varValue1>",
        "<varKey2>": "<varValue2>"
    }
});

Identify user by id and key

Sailthru.integration('customEvent', {
    "name" : "<eventName>",
    "id" : "<userIdentifier>",
    "key" : "<userIdentifierType>",
    "vars": {
        "<varKey1>": "<varValue1>",
        "<varKey2>": "<varValue2>"
    }
});

Parameters

  • event – the name of the event you want triggered in the Sailthru system – Required
  • email – user’s email address – Required if ID/key object not included
  • id – alternate user identifier – Required if email not included
  • key – type of specified id – Required if email not included; must match a key type available via User API
  • vars{} – user var names and values to add/update – Optional
  • onSuccess – JavaScript function that is called on a successful submission – Optional
  • onError – JavaScript function that is called when the function fails – Optional

Example

Sailthru.integration("customEvent", {
    "name" : "share", 
    "email" : "avi@example.com",
    "vars": {
        "latest_share_source": "facebook",
        "shared_item": "http://example.com/item/123"
    }
});

Sailthru.integration("customEvent", {
    "name": "Like"
    "id": "15551234567",
    "key": "sms",
    "vars": {
        "firstname": "Jack",
        "environment": "mobile"
    }
});
Top