SailPlay JS SDK

Methods and objects:

  • SDK Initialization
  • SP.api.getUserPoints - receiving information about user points
  • SP.api.loyalty.calcPoints - calculation of bonus points that the client receives after the purchase
  • SP.api.users.update - adding information about the client
  • SP.bindCallback - tracking showing/closing of the popup
  • SP.api.customVariables.add - adding variables
  • SP.events.subscribe - tracking user events in the popup
  • SP.leads - processing Lead-forms
  • SP.showPopup - showing popup 
  • SP.tags - processing tags

Example

To interact with SailPlay popup you can use SailPlay JS SDK. 

SDK Initialization

In order to have the SailPlay tab on all pages of your website, you need to add the JS-code that can be found here.


Code example: 

<script charset="utf-8" type="text/javascript">
  var _sp_options = {
      publicKey: "none",
      partnerId: "12334",
      depId: "22399",
      position: ["top", "right"],
      notifications: {
        enabled: true,
        skin: {type: 'horizontal', position: ['bottom', 'right']}
      }
  };
  (function() {
      var sp = document.createElement("script");
      sp.type = "text/javascript"; sp.async = true; sp.charset = "utf-8";
      sp.src = ("https:" == document.location.protocol ? "https://" : "http://") +
        "sailplay.net/popup-sdk/js/sailplay/334/";
      var scr = document.getElementsByTagName("script")[0]; scr.parentNode.insertBefore(sp, scr);
  })();
</script>

Additional Parameters

An object (in this case it is spOptions) within the following fields should be submitted as an argument of the constructor SailPlayExternalApp javascript when initializing the popup: 

  • depId:  ID of the relevant department if the SailPlay's system (more detailed see here and here)

  • partnerId: your ID in SailPlay (more detailed see here and here)
  • position: ['top'|'center'|'bottom', 'left'|'right'] -  it specifies the location of the SailPlay tab on your website

  • authHash: the unique hash that is used for automated authorization of the client in the popup (see here).

  • publicKey: the unique hash that you can receive after a successful purchase transaction via SailPlay API (see here). If the parameter publicKey has been sent when the page was generated, the popup will show automatically

  • link: Page URL on your website that the user can share in social networks (action "Tell about the purchase"). If the parameter was not sent, then your website URL will be automatically used (if you have not specified it, then the URL of your page on SailPlay will be used). Example: you can send the link to the product purchased in your online-store

  • pic: URL of the image that will be used when users share information in social networks. If the parameter was not sent, then your logo on SailPlay will be used.

  • isTicketEnabled: false allows hiding the widget and loading SDK without showing the popup
  • originUserId: User ID in your system, see here. It is used to connect the user in your system and SailPlay system. It is saved during the registration of the user of the transaction. Important: there is a length limit of 100 characters.

  • probableUserPhone: a phone number that will be added to the field if the person is not registered or not authorized

SP.api.getUserPoints - receiving information about user points

There is a special method in the SailPlay SDK to receive information about user's bonus points:

SP.api.getUserPoints({callback: function(data), originUserId: 'user id in your system'})

originUserId – an optional parameter; if you specified this parameter in the connection settings (_sp_options), it will be added automatically. If the user is authorized in the SailPlay popup and you specified originUserId, then the search of the user will be carried out based on the submitted originUserId.

ccallback function will be called after data about bonus points is loaded;
data – object with information about bonus points.

//object data format in case of a successful request
{
status: 'ok'
points: {
total: 800,
confirmed: 500, // confirmed bonus points
unconfirmed: 300, // unconfirmed bonus points
spent: 200 // spent bonus points
}
}

SP.api.loyalty.calcPoints - calculation of bonus points awarded for the purchase

The method allows to estimate the amount of bonus points that the client will receive after the purchase.

SP.api.loyalty.calcPoints({callback: function(),'product_sku': 'productSKU', 'category_sku': 'catSKU', 'price': 1000, 'email': 'some@email.com'});

email - user's email address used as the client's ID. A phone number and user ID in your system (origin_user_id) can also be used to identify the user. In this case parameter email is replaced with phone or origin_user_id, respectively.

price - product price. Mandatory parameter.

product_sku - product ID in SailPlay. Optional parameter.

catSKU - category ID in SailPlay. Optional parameter.

callback - a function that will be called after receiving the response from the SailPlay's server;

The object format in case of the successful request processing:

{status: "ok", points: 50} 

SP.api.users.update - adding information about the client 

The method allows adding surname, name, patronymic/middle name, date of birth and sex of the user.

SP.api.users.update({callback: function(), origin_user_id:"392329864", firstName:"Max", lastName:"Bennett", sex:1, birthDate:"MM-DD-YYYY",})

origin_user_id - client ID in your system A phone number or an email address can also be used to identify the user. In this case parameter origin_user_id is replaced with phone or email, respectively.

If there is no user with these Ids, a new user will be created.

firstName - client name

lastName - surname

sex - sex (1 - male. 2 - female)

birthDate - date of birth in the format MM-DD-YYYY

The data added before will not be rewritten/

callback -function will be called after receiving the response from the SailPlay's server;

 

SP.bindCallback - tracking events of showing/closing of the popup

To track events related to the showing/closing of the popup you can use SailPlay JS SDK and callbacks defined there:

 

// SPready function will be called after SDK is loaded
// callbacks should be announced from there’и
// SP is the main object of SDK

function SPready(SP) {

  SP.bindCallback('onTicketClick', function(){ alert('ticket clicked'); }); // event "click on the tab"
  SP.bindCallback('beforePopupOpen', function(){ alert('beforePopupOpen'); }); // event "right before showing the popup"”
  SP.bindCallback('afterPopupOpen', function(){ alert('afterPopupOpen'); }); // event after showing the popup (as an element)
  SP.bindCallback('beforePopupClose', function(){ alert('beforePopupClose'); }); // event before closing
  SP.bindCallback('afterPopupClose', function(){ alert('afterPopupClose'); }); // event after closing the popup’а
  SP.bindCallback('onPopupLoaded', function(){ alert('onPopupLoaded'); }); // event after showing the popup and loading its content’а
}

SP.api.customVariables.add - adding variables

function SPready(SP){
SP.api.customVariables.add({email: 'ipad@gmail.com', product: 'ipad mini'});
}

SP.events.subscribe - tracking user events in the popup

You can subscribe to relevant events to process user actions related to the popup:

SP.events.subscribe(eventName, callback);

callback(data) – callback(data) – a function that will be called when the user commits action eventName

data – data – it contains data of the tracked event

 

eventName can have the following values:

  • gift – event of the successful gift receiving in the popup. Data format:
    {
    eventName: 'gift',
    gift: {
    gift_sku: gift reference number,
    gift_type: gift type: gift || coupon,
    points_delta: spent points,
    gift_public_key: public key for the transaction of the gift awarding
    }
    }
  • ui/click - clicking the authorization button in the SailPlay's popup

SP.leads - processing Lead-forms

Interaction with the lead-form follows only via methods of the SP.leads module

You can find the example of a working form here.

Issues related to forms integration and settings have been covered in our blog.

Module's methods:

init() - initiates the script and processing of actions with lead-forms.

getLead ( lead name ) - returns the object of the  lead-form containing:

     container - DOM-element where the lead name is specified (data-sp-lead=”leadName” )

     fields - array of the type HTMLcollection containing DOM-elements of the type "input" that are inside container

     submit  - DOM-element with ( data-sp-lead-submit=”leadName” ). It is a default element for sending the form's data

     cancel - DOM-element with ( data-sp-lead-cancel=”leadName” ). It is a default element for closing the form

     status() -  the string that displays the status of the lead-form based on the variable stored in cookies:

          initial - a variable could not be found in cookies. Probably, the user opens the website in this browser for the first time

          submitted - a variable was found. The user has completed and submitted the form's data

          canceled - a variable was found. The user has seen the form but has not filled it in and closed it

     onSubmit - the method that will be called when the form's data has been successfully submitted

     onCancel - the method that will be called when the form will be successfully closed

submitLead( имя лида, callback ) -  the method for forced submission of the lead with the specified name If successful. callback function will be executed

cancelLead( lead name, callback ) -  the method for forced closing (cancel) of the lead with the specified name If successful. callback function will be executed

destroyLead( lead name ) - the method that removes all functionalities in the form

When the form is filled in, values of all fields are stored in the cookie  sp_lead_user. 

SP.showPopup - showing popup 

In addition to this method, you can show the popup by submitting public_key of the purchase This method is used to show the popup on the page of the order confirmation (success page).

After the SDK initialization you can show the popup from the software (i.e. not user-initiated when the user clicks on the tab or a custom element):

SP.showPopup();

 To show the popup on the right page you should submit to the method showPopup() the object with the following settings:

SP.showPopup({
  openReload: true,  //loading popup's content on each page loading
  openTo: {
    target: loaded page,
    giftSku: gift SKU
  }
});

Parameter target can have the following values:

  • history – history – activities history page;
  • earn_points – earn_points – the page with the list of useful actions allowing the user earn bonus points;
  • badges – badges – page with awards;
  • gift – gift – page with the gift.

giftSku – giftSku – reference number(sku) of the gift; this parameter is mandatory if you specify target = gift.

SP.tags - processing tags

Creating a tag:

function SPready(SP){
SP.tags({action: 'add', tags: ['Registration', 'A/B-test #11', 'A/B-test #11 var. А'], phone: '7XXXXXXXXXX'});
}

or

function SPready(SP){
SP.tags({action: 'add', tags: ['Boy', 'Loves strawberries', 'Comes from Facebook'], email: 'useremail@userdomain.com'});
}

Receiving the list:

function SPready(SP){
//you should submit one of the parameters that identifies he client^ phone or email or origin_user_id
SP.tags({action: 'list', phone: '7XXXXXXXXXX', callback: function(data) { console.log(data); } });
}

Deleting a tag:

You can only delete the tags created with JS SDK via JS. 

function SPready(SP){
//you should submit one of the parameters that identifies he client^ phone or email or origin_user_id
SP.tags({action: 'delete', tags: ['jstag'], phone: '7XXXXXXXXXX'}); }