Smile.js

This is the API reference for Smile.js. Use Smile.js to identify logged in customers, embed elements of your reward program within the page, spend points on behalf of a customers, and much more. Smile.js gives you full control to create rewarding experiences for your customers.

Smile.js can only be used in conjunction with Smile UI.

This is an advanced way to use Smile. If you're just getting started with Smile, we recommend using Smile UI to start rewarding customers in just a few minutes.

The Smile object

Properties:

Methods:

smile.customer

The customer attribute is available after the customerReady promise gets resolved. Once available, the customer object can be accessed to render reward program data or to add conditions based on the customer's points balance, referral URL, and more.

smile.customer.points_balance;
// 2400

smile.ready

Returns a Promise. This is a convenience method for determining when Smile.js and its requirements have been fully initialized. Upon successful initialization, the promise will be resolved with itself - the initialized Smile.js instance. If Smile.js has been initialized before invoking this method the promise will resolve right away.

smile.ready().then(smileInstance => {
// Smile has been fully intialized and is ready to be used.
// Note that 'smile' and 'smileInstance' refer to the same object.
}).catch(err => {
// An error has occurred will initializing smile.
});

smile.customerReady

Returns a Promise. This method enables you to check if a customer is logged in or not. When a customer is identified, the promise will resolve with a customer object. If no customer is logged in, the promise will resolve with null. This provides ways to show loading spinners and render logged in or logged out data depending on whether or not a customer has been identified.

If a customer has already been identified, the promise will resolve immediately. Checking for when a customer has potentially been identified can be done as follows:

smile.customerReady().then(customer => {
if (customer) {
// A customer was identified, render a logged in state
} else {
// A customer was not identified, render a logged out state
}
}).catch(err => {
// An error occurred while identifying the customer
});

smile.fetchCustomer

Returns a Promise. Use smile.fetchCustomer to reload the customer object. This is useful when it's expected that the customer information in Smile has changed since the page loaded. A common example of this is right after a customer has spent points, since their points balance will have been updated on Smile. Reloading the customer object in the browser allows you to render the customer's new points balance.

smile.fetchCustomer().then((customer) => {
// Handle the customer object
});

The smile.fetchCustomer method can also be passed an options object. This can be used to include attributes that are not loaded with the customer by default, such as their VIP tier.

smile.fetchCustomer({ include: 'vip_tier' }).then((customer) => {
console.log(customer.vip_tier.name);
});

smile.createActivity

Returns a Promise. Send an activity to Smile for an action that a customer has performed. Smile will issue a reward for activities based on the activity rules setup in your Smile account.

Before you send an activity, create a custom activity in the Smile Admin. Replace the sample token used in this example with the token from your new custom activity.

Activities can only be created after a customer has been identified.

This method takes the following arguments.

Argument

Description

activityAttributes

required

An object containing the attributes that will be used to create the activity. This object must contain the token corresponding to the custom activity being created.

let activityAttributes = {
token: 'activity_1dDdzcKNsp84b'
};
smile.createActivity(activityAttributes).then(() => {
// The activity was created successfully
});

smile.fetchAllPointsProducts

Returns a Promise that resolves to an Array of points products. Given that you have a valid points product set up with customer spending rules, this method will return a list of the products your customers can purchase using points. If no points products exist, the returned promise will resolve with an empty Array.

This method takes the following arguments.

Argument

Description

options

optional

A hash containing filters such as the exchange_type. The exchange_type can be fixed or variable.

smile.fetchAllPointsProducts().then(pointsProducts => {
// Handle the points products collection
});

smile.fetchPointsProduct

Returns a Promise. When given a valid points product id, the promise will be resolved with the points product associated with that id. If no points product is associated with the provided id, the returned promise will be rejected.

This method takes the following arguments.

Argument

Description

id

required

The unique identifier for the points product to be retrieved.

smile.fetchPointsProduct(38891).then((pointsProduct) => {
// Handle the points product object
});

smile.purchasePointsProduct

Returns a Promise. When given a valid points product id, it purchases the points product for the customer and resolves the promise with a points purchase object. If your points product is a variable reward you can pass in points_to_spend as an option.

Points products can only be purchased after a customer has been identified.

This method takes the following arguments.

Argument

Description

id

required

The unique identifier of the points product to be purchased.

options

conditional

Required if the points product being purchased has a variable exchange type. In that case, the options object must contain the points_to_spend attribute - the number of points that the customer is spending on the points product.

smile.purchasePointsProduct(38891).then((pointsPurchase) => {
// Handle the points purchase object
});
smile.purchasePointsProduct(38892, { 'points_to_spend': 100 }).then((pointsPurchase) => {
// Handle the points purchase object
});