Smile.io

# Introduction

This reference documents the objects and methods available for use in Smile’s frontend library, Smile.js. If you're using Storefront.js, note that it is just a shim for Smile.js and all of the same methods and objects are available.

You can use Smile.js’s API to retrieve and display customer information, redeem points for rewards, and embed rewards information within your site. Currently, Smile.js is always bundled with [Smile UI](https://smile.io/smile-ui), which provides a pop-up rewards experience for your customers.

{% hint style="warning" %}
Smile.js is not currently compatible with single page applications.
{% endhint %}

{% hint style="success" %}
To make use of the objects, methods, and event listeners provided by Smile.js, you'll need to enable the [Javascript SDK setting](https://help.smile.io/en/articles/4891875-javascript-sdk) in Smile Admin.
{% endhint %}


Introduction

Including Smile.js

# Including Smile.js

{% hint style="info" %}
If you're using one of Smile's pre-built integrations (such as the Shopify, Wix, BigCommerce app) or the old `storefront.js`, then Smile.js is already included and initialized on your site.

**However,** to make use of the methods, objects, and event listeners provided by Smile.js, you'll also need to enable the [Javascript SDK setting](https://help.smile.io/en/articles/4891875-javascript-sdk) in Smile Admin.
{% endhint %}

Include the Smile.js script on each page of your site to access all of the functionality of Smile's browser-side Javascript library. The script should always be loaded directly from `https://js.smile.io` rather than included in a bundle or hosted yourself.

```markup
<script async src="https://js.smile.io/v1/smile-ui.js"></script>
```

**Note:** Currently, Smile.js is always bundled with [Smile UI](https://smile.io/smile-ui), which provides a pop-up rewards experience for your customers. Including and initializing the script on a page will automatically result in the Smile Launcher being displayed.

## Initializing Smile.js

To initialize the Smile.js library, you must add a script tag to every page where Smile.js is included. This snippet will call `SmileUI.init` which kicks off the initialization process.

```markup
<script type="text/javascript">
  SmileUI.init({
    channel_key: "pk_0987654321",
    customer_identity_jwt: "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcl9pZGVudGl0eSI6eyJkaXN0aW5jdF9pZCI6IjEwMCJ9LCJleHAiOjE1ODU1OTE1MzZ9.PGJhiM0NYRok5VGAlAOT6F-57gu7SCBaennQbt6YrqU"
  })
</script>
```

### SmileUI.init() arguments

| Argument                | Description                                                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `channel_key`           | Your Smile.io public key. This is used for identifying your store and can be made public. Found in your account settings.                                                      |
| `customer_identity_jwt` | Signed JWT for the currently logged in customer on your site. See instructions below for generating a signed JWT. This should be `null` if no customer is currently logged in. |

### Generating a signed JWT

The signed [JWT](https://en.wikipedia.org/wiki/JSON\_Web\_Token) is what's used to verify your store is the one requesting information from Smile.io on behalf of a customer. It should be generated using your platform's server side language so your Smile.io private key remains secret. It must also have an expiration, for which we recommend 5 minutes.

#### Payload of the JWT

The payload of the JWT should be a hash containing the unique identifier for the currently logged in customer in your system. We require the following format, where `100` is the customer's unique identifier.

```ruby
{
  customer_identity: {
    distinct_id: "100"
  }
}
```

_Note:_ Depending on the backend language and JWT library you're using, you may need to include the JWT's expiry directly in the payload.

#### Code sample

{% tabs %}
{% tab title="Ruby" %}
```ruby
require "jwt"

# Unique identifier of the customer in your system
customer_id = "100"

# Your Smile.io private key
private_key = "sk_1234567890"

payload = {
  customer_identity: {
    distinct_id: customer_id
  },
  exp: Time.now.to_i + 300 # Set expiry to 5 minutes
}

signed_jwt = JWT.encode(payload, private_key, "HS256")
```
{% endtab %}
{% endtabs %}


Initializing Smile.js

HTML Helpers

Smile object

# Create an activity

### Smile.createActivity

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/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, you must create a [custom activity](https://app.smile.io/settings) in the Smile Admin. Replace the sample token used in this example with the token from your new custom activity.

{% hint style="info" %}
Activities can only be created after a customer has been identified.
{% endhint %}

This method takes the following arguments.

| Argument                                          | Description                                                                                                                                                            |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>activityAttributes</p><p><em>required</em></p> | 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. |

```javascript
let activityAttributes = {
  token: 'activity_1dDdzcKNsp84b'
};

Smile.createActivity(activityAttributes).then(() => {
  // The activity was created successfully
});
```


Create an activity

Format points

# Listen to Smile events

Two types of events are supported and can be listened for by your code.

### Smile.ready

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using\_promises). 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.

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/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](../other-objects/customer-object.md). 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:

```javascript
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
});
```


Listen for events

# Load a points product

### Smile.fetchPointsProduct

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Promise/reject).

This method takes the following arguments.

| Argument                          | Description                                                   |
| --------------------------------- | ------------------------------------------------------------- |
| <p>id</p><p><em>required</em></p> | The unique identifier for the points product to be retrieved. |

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


Load a points product

# Load all points products

### Smile.fetchAllPointsProducts

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Promise) that resolves to an Array of [points products](../other-objects/points-product-object.md). 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                                                                                              |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| <p>options</p><p><em>optional</em></p> | A hash containing filters such as the `exchange_type`. The `exchange_type` can be `fixed` or `variable`. |

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


Load all points products

Load all reward fulfillments

Load all customer points products

# Purchase a points product

### Smile.purchasePointsProduct

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/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](../other-objects/points-purchase-object.md). If your points product is a [variable reward](http://help.smile.io/points/earning-and-spending/the-difference-between-fixed-and-variable-rewards) you can pass in `points_to_spend` as an option.

{% hint style="info" %}
Points products can only be purchased after a customer has been identified.
{% endhint %}

This method takes the following arguments.

| Argument                                  | Description                                                                                                                                                                                                                             |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p><em>required</em></p>         | The unique identifier of the points product to be purchased.                                                                                                                                                                            |
| <p>options</p><p><em>conditional</em></p> | 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.  |

```javascript
Smile.purchasePointsProduct(38891).then((pointsPurchase) => {
  // Handle the points purchase object
});

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


Purchase a points product

# Reload the customer

### Smile.fetchCustomer

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Promise). Used to reload the [customer object](../other-objects/customer-object.md). 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.

```javascript
Smile.fetchCustomer().then((customer) => {
  // Handle the customer object
});
```

This 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](../other-objects/vip-tier-object.md).

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

###


Reload the customer

Smile UI object

# Closing Panel

### SmileUI.closePanel

Closes the Panel immediately.

```javascript
SmileUI.closePanel();
```


Close panel

# Deep links

[Deep links](https://en.wikipedia.org/wiki/Mobile\_deep\_linking) allow you to open the Panel to specific pages programatically. This allows you to display relevant content to your customers in specific scenarios.

Here are some examples of what you can do with the deep link system:

* Show a customer how they can earn more points when they click a button on your site
* Show a customer their referral link
* Show a customer how they can spend points

## Types of deep links

Deep links provide a way to engage a customer with a specific experience within the Panel. The following table defines each deep link and its behaviour.

| Deep link                  | Description                                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| home                       | Displays the customer's rewards program status based on which programs the account has setup (points, referrals, VIP). |
| points\_activity\_rules    | Displays a list of ways that the customer can earn points.                                                             |
| points\_products           | Displays a list of items that the customer can redeem their points for.                                                |
| referral\_program\_details | Displays information about the referral program along with the customer's referral URL.                                |

## Using deep links

There are 4 different ways you can use the deep link system.

### Query parameter

```http
https://store.example.com/?smile_deep_link=points_products
```

### JavaScript

```javascript
SmileUI.openPanel({ deep_link: 'points_products' });
```

### HTML attribute

```markup
<a href="#" data-smile-deep-link="points_products">Redeem your points!</a>
```

### Anchor tag

This method differs slightly from the others. For this method, the deep links are prefixed with "smile-" and are dasherized instead of underscored. For example, the `points_products` deep link becomes `smile-points-products`. See the example below.

```
https://store.example.com/#smile-points-products
```

{% hint style="info" %}
Anchor tags should only be used when you want to open the Panel from a page that the user already has open. If you'd like to link to a different page AND open the Panel once the page has loaded, you should use the [query parameter approach](deep-links.md#query-parameter) to deep linking instead.

Links included in emails should also use the [query parameter approach](deep-links.md#query-parameter).
{% endhint %}


Deep links

# Listen to Smile UI events

## Checking if Smile UI has loaded

If you are loading Smile UI asynchronously or trying to access it before page load, you will need to check when the `SmileUI` object has been loaded. Smile UI conveniently fires a `smile-ui-loaded` DOM event when it is has been instantiated.

{% hint style="info" %}
This does not mean that Smile UI has been initialized. To check for initialization after load, see the [SmileUI.ready](../smile-object/listen-to-smile-events.md#smile-ready) method.
{% endhint %}

```javascript
if (window.SmileUI) {
  // SmileUI has loaded
} else {
  document.addEventListener('smile-ui-loaded', () => {
    // SmileUI has loaded
  });
}
```

## Supported events

Two types of events are supported and can be listened for by your code.

### SmileUI.ready

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using\_promises). This is a convenience method for determining when Smile UI and its requirements have been fully initialized. This includes identifying any logged in customers and loading up Smile UI. If Smile UI has been initialized before invoking this method the promise will resolve right away.

```javascript
SmileUI.ready().then(smileUiInstance => {
  // Smile UI has been fully intialized and is ready to be used.
  // smileUiInstance is an instance of the initialized variable, this is
  // synonymous to window.SmileUI.
}).catch(err => {
  // An error has occurred will intializing SmileUI
});
```

### SmileUI.customerReady

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using\_promises). The promise resolves once customer identification has occurred (even if there is no logged in customer) and does not wait for other dependencies. The promise will resolve with a [customer object](../other-objects/customer-object.md).

```javascript
SmileUI.customerReady().then(customer => {
  if (customer) {
    // A customer is logged in
  } else {
    // No customer was identified (user needs to log in or create an account)
  }
}).catch(err => {
  // An error has occurred will trying to identify a customer
});
```


# Opening Panel

### SmileUI.openPanel

Opens the Panel. In order to provide the best experience for customers, the Panel will not open until it has finished loading.

This method takes the following arguments.

| Argument                               | Description                                                                                                                                              |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>options</p><p><em>optional</em></p> | An object containing a `deep_link` attribute. Providing a [deep link](deep-links.md) will cause the Panel to display the page corresponding to the link. |

```javascript
SmileUI.openPanel(); // Opens the panel
SmileUI.openPanel({deep_link: 'home'}); // Opens the panel on the home page
```


Open panel

Other objects

Activity object

# Customer object

The customer object contains basic information like the customer's name and email address. It also contains rewards program information like the customer's points balance.

| Attribute       | Description                                                                                                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id              | The unique identifier of the customer.                                                                                                                                                                                                                                    |
| first\_name     | The customer's first name.                                                                                                                                                                                                                                                |
| last\_name      | The customer's last name.                                                                                                                                                                                                                                                 |
| email           | The customer's email address.                                                                                                                                                                                                                                             |
| date\_of\_birth | The customer's date of birth.                                                                                                                                                                                                                                             |
| points\_balance | The number of points the customer currently has.                                                                                                                                                                                                                          |
| referral\_url   | The customer's unique referral URL.                                                                                                                                                                                                                                       |
| state           | The customer's state within the reward program. Only members are eligible to participate in a rewards program (i.e. receive rewards, enter VIP tiers, etc). The state may be one of `member`, `candidate`, or `disabled`. Additional states could be added in the future. |
| created\_at     | The date the customer was created at in Smile.                                                                                                                                                                                                                            |
| updated\_at     | The date the customer was last updated in Smile.                                                                                                                                                                                                                          |


Customer object

Customer points product object

# Points product object

Points products are items that a customer can purchase with points that they have earned.

| Attribute                             | Description                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                                    | The unique identifier for the points product.                                                                                                                                                                                                                                                                                                                                                                           |
| exchange\_type                        | Indicates how points are exchanged for the reward. Either `fixed` or `variable`. If the customer must spend a fixed amount of points for a predetermined reward value, the exchange type is fixed. If the customer can spend a variable amount of points for a dynamic reward value, the exchange type is variable.                                                                                                     |
| exchange\_description                 | A human readable description of how a customer spends points on this reward. It includes the points branding for the program. E.g. "500 Gold Points".                                                                                                                                                                                                                                                                   |
| points\_price                         | Number of points needed to purchase this reward. Only present when `exchange_type` is `fixed`.                                                                                                                                                                                                                                                                                                                          |
| variable\_points\_step                | Imagine there's a points slider your customers can drag to spend more or less points on a reward. The `variable_points_step` represents the number of points between each notch on the slider. E.g. If this value is set to 100, it means customers can spend their points in increments of 100. They will drag the slider from 100, 200, 300, etc. Only present when `exchange_type` is `variable`.                    |
| variable\_points\_step\_reward\_value | Imagine there's a points slider your customers can drag to spend more or less points on a reward. The `variable_points_step_reward_value` represents the corresponding reward value for each step increment on the slider. E.g. if this value is set to 1, and the `variable_points_step` is set to 100, the customer will get $1 off for every 100 points they spend. Only present when `exchange_type` is `variable`. |
| variable\_points\_min                 | The minimum amount of points the customer must spend to get this reward. Normally the minimum value of the points slider. Only present when `exchange_type` is `variable`.                                                                                                                                                                                                                                              |
| variable\_points\_max                 | The maximum amount of points the customer can spend on this reward. Normally the maximum value of the points slider. Only present when `exchange_type` is `variable`.                                                                                                                                                                                                                                                   |
| reward                                | The [reward](broken-reference) given to the customer when they purchase this points product.                                                                                                                                                                                                                                                                                                                            |
| created\_at                           | Time at which the points product was created.                                                                                                                                                                                                                                                                                                                                                                           |
| updated\_at                           | Time at which the points product was updated.                                                                                                                                                                                                                                                                                                                                                                           |


Points product object

# Points purchase object

A points purchase is a record representing when a customer spends points on a reward. Much like spending money on a product results in an order, spending points on a points product results in a points purchase.

| Attribute           | Description                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| id                  | The unique identifier for the points purchase.                                                            |
| points\_product\_id | The unique identifier of the points product that was purchased.                                           |
| points\_spent       | The total points spent by the customer.                                                                   |
| reward\_fulfillment | The [reward fulfillment](reward-fulfillment-object.md) received by the customer as part of this purchase. |
| created\_at         | Time at which the points purchase was created.                                                            |
| updated\_at         | Time at which the points purchase was updated.                                                            |


Points purchase object

# Reward fulfillment object

A reward fulfillment is a reward that has been issued to a customer. It commonly contains a unique discount code for customers to apply at checkout on their next order.

| Attribute   | Description                                                                                                                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id          | The unique identifier of the reward fulfillment.                                                                                                                                                                                                  |
| name        | The reward fulfillment's name.                                                                                                                                                                                                                    |
| code        | A unique code for the customer to use. This is commonly a discount code the customer applies at checkout on their next order, but it can be a unique code they use for other purposes like accessing an exclusive page on the merchant's website. |
| image\_url  | The reward fulfillment's image.                                                                                                                                                                                                                   |
| used\_at    | Time at which the reward fulfillment was used by the customer.                                                                                                                                                                                    |
| created\_at | Time at which the reward fulfillment was created.                                                                                                                                                                                                 |
| updated\_at | Time at which the reward fulfillment was updated.                                                                                                                                                                                                 |


Reward fulfillment object

# Reward object

A reward object describes how a customer will be rewarded for completing a certain action, such as redeeming points for a points product, or completing a referral.

| Attribute   | Description                            |
| ----------- | -------------------------------------- |
| id          | The unique identifier of the reward.   |
| name        | The name of the reward.                |
| description | An optional description of the reward. |
| image\_url  | An image for the reward.               |
| created\_at | Time at which the reward was created.  |
| updated\_at | Time at which the reward was updated.  |


Reward object

# VIP tier object

A VIP tier represents a status that a customer can achieve as they move through your VIP program. Customers move through different tiers by accruing points or making purchases.

| Attribute  | Description                            |
| ---------- | -------------------------------------- |
| id         | The unique identifier of the VIP tier. |
| name       | The VIP tier's name.                   |
| image\_url | The VIP tier's image.                  |


VIP tier object

Blank

JavaScript SDK

Stable

Smile.js is a frontend JavaScript SDK that lets you build custom reward experiences directly in the browser.

JavaScript SDK | Smile.io

Production

<p class="slate-p " >This reference documents the objects and methods available for use in Smile’s frontend JavaScript SDK, Smile.js. At it&apos;s core, the library is a wrapper around Smile&apos;s REST API, so many objects and concepts are shared.</p><p class="slate-p " >You can use Smile.js to retrieve and display customer information, redeem points for rewards, and embed rewards information within your site.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=error ><div class="callout-icon"><svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M9.08366 9.9801C9.25033 9.9801 9.39269 9.92107 9.51074 9.80302C9.6288 9.68496 9.68783 9.53566 9.68783 9.3551V5.31344C9.68783 5.14677 9.62533 5.00441 9.50033 4.88635C9.37533 4.7683 9.22949 4.70927 9.06283 4.70927C8.88227 4.70927 8.73296 4.7683 8.61491 4.88635C8.49685 5.00441 8.43783 5.15371 8.43783 5.33427V9.37594C8.43783 9.5426 8.50033 9.68496 8.62533 9.80302C8.75033 9.92107 8.9031 9.9801 9.08366 9.9801ZM9.00033 13.1676C9.19477 13.1676 9.35796 13.1016 9.48991 12.9697C9.62185 12.8377 9.68783 12.6745 9.68783 12.4801C9.68783 12.2857 9.62185 12.1225 9.48991 11.9905C9.35796 11.8586 9.19477 11.7926 9.00033 11.7926C8.80588 11.7926 8.64269 11.8586 8.51074 11.9905C8.3788 12.1225 8.31283 12.2857 8.31283 12.4801C8.31283 12.6745 8.3788 12.8377 8.51074 12.9697C8.64269 13.1016 8.80588 13.1676 9.00033 13.1676ZM9.00033 17.3343C7.81977 17.3343 6.72255 17.1225 5.70866 16.6989C4.69477 16.2752 3.81283 15.6884 3.06283 14.9384C2.31283 14.1884 1.72602 13.3065 1.30241 12.2926C0.878798 11.2787 0.666992 10.1815 0.666992 9.00094C0.666992 7.83427 0.878798 6.74399 1.30241 5.7301C1.72602 4.71621 2.31283 3.83427 3.06283 3.08427C3.81283 2.33427 4.69477 1.74399 5.70866 1.31344C6.72255 0.88288 7.81977 0.667603 9.00033 0.667603C10.167 0.667603 11.2573 0.88288 12.2712 1.31344C13.285 1.74399 14.167 2.33427 14.917 3.08427C15.667 3.83427 16.2573 4.71621 16.6878 5.7301C17.1184 6.74399 17.3337 7.83427 17.3337 9.00094C17.3337 10.1815 17.1184 11.2787 16.6878 12.2926C16.2573 13.3065 15.667 14.1884 14.917 14.9384C14.167 15.6884 13.285 16.2752 12.2712 16.6989C11.2573 17.1225 10.167 17.3343 9.00033 17.3343ZM9.00033 16.0843C10.9448 16.0843 12.6114 15.3898 14.0003 14.0009C15.3892 12.612 16.0837 10.9454 16.0837 9.00094C16.0837 7.05649 15.3892 5.38982 14.0003 4.00094C12.6114 2.61205 10.9448 1.9176 9.00033 1.9176C7.05588 1.9176 5.38921 2.61205 4.00033 4.00094C2.61144 5.38982 1.91699 7.05649 1.91699 9.00094C1.91699 10.9454 2.61144 12.612 4.00033 14.0009C5.38921 15.3898 7.05588 16.0843 9.00033 16.0843Z" fill="#E90005"></path></svg></div><div ><p class="slate-p " >Smile.js is not currently compatible with single page applications.</p></div></div><p class="slate-p " ></p><p class="slate-p " ></p>

This reference documents the objects and methods available for use in Smile’s frontend JavaScript SDK, Smile.js. At it's core, the library is a wrapper around Smile's REST API, so many objects and concepts are shared.

You can use Smile.js to retrieve and display customer information, redeem points for rewards, and embed rewards information within your site.

A list of objects and methods available for use in Smile’s frontend JavaScript SDK, Smile.js.

HTML

<p class="slate-p " >If you&apos;re using one of Smile&apos;s pre-built integrations (such as the Shopify or BigCommerce app), then Smile.js is already included and initialized on your site. If you&apos;re using a custom frontend, custom checkout, or want to make use of Smile functionality elsewhere, you need to manually include the Smile.js script tag on each page where you want access to SDK functionality.</p><p class="slate-p " ><strong class="slate-bold">Good to know:</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">The script should always be loaded directly from Smile&apos;s CDN rather than included in a bundle or hosted yourself.</div></li><li class="slate-li " ><div style="position:relative">Currently, Smile.js is always bundled with <a href="https://smile.io/smile-ui" target="_self">Smile UI</a>, which provides a pop-up rewards experience for your customers. Including and initializing the script on a page will automatically result in the rewards launcher &amp; panel being displayed.</div></li><li class="slate-li " ><div style="position:relative">To make use of the objects, methods, and functionality provided by Smile.js, you&apos;ll need to enable the <a href="https://help.smile.io/en/articles/4891875-javascript-sdk" target="_self">Javascript SDK setting</a> for your account in Smile Admin.</div></li></ul><div class="slate-div"></div><p class="slate-p " ></p><p class="slate-p " ></p>

If you're using one of Smile's pre-built integrations (such as the Shopify or BigCommerce app), then Smile.js is already included and initialized on your site. If you're using a custom frontend, custom checkout, or want to make use of Smile functionality elsewhere, you need to manually include the Smile.js script tag on each page where you want access to SDK functionality.

Instructions for how to include Smile.js (Smile's JavaScript SDK) on your website or webpage.

JavaScript

<p class="slate-p " ><code class="slate-code">SmileUI.init(options)</code></p><p class="slate-p " >This method initializes Smile.js with information about the reward program to display and the currently logged in customer. This method must be called before you can interact with other methods provided by the SDK.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >If you&apos;re loading the Smile.js script asynchronously, you should wrap your initialization code within a <a href="66d9ee32a4347c9ff41d1809/66d9ee32a4347c9ff41d180f/66da024ba4347c9ff4212ede" target="">loaded event</a> to ensure it doesn&apos;t encounter an error due to the script not yet being present on the page.</p></div></div><div class="table-container" style="width:100%;min-width:100%"><table class="slate-table" style="min-width:100%"><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:261px;">Title</div><div style="width:0px;">Description</div></div><colgroup ><col style="width:261px"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Parameter</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Description</strong></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><code class="slate-code">options</code></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >A required object with the following keys:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><code class="slate-code">channel_key</code> - Your Smile.io Public Key. This is used for identifying your store and can be made public. Refer to the <a href="https://help.smile.io/en/articles/4036181-find-api-keyshttps://help.smile.io/en/articles/4036181-find-your-public-key-or-private-key" target="">help docs</a> for where to find it.</div></li><li class="slate-li " ><div style="position:relative"><code class="slate-code">customer_identity_jwt</code> - A signed JWT for the currently logged in customer on your site. See instructions below for generating a signed JWT. This should be <code class="slate-code">null</code> if no customer is currently logged in.</div></li></ul></td></div></tr></tbody></table></div><h2 class="slate-h2 " >Generating a signed JWT</h2><p class="slate-p " >The signed <a href="https://en.wikipedia.org/wiki/JSON_Web_Token" target="_self">JWT</a> is what&apos;s used to verify your store is the one requesting information from Smile.io on behalf of a customer. It should be generated using your platform&apos;s server side language so your Smile.io <a href="https://help.smile.io/en/articles/4036181-find-your-public-key-or-private-key" target="_self">Private Key</a> remains secret. It must also have an expiration, for which we recommend 5 minutes.</p><p class="slate-p " ></p><h3 class="slate-h3 " >Payload of the JWT</h3><p class="slate-p " >The payload of the JWT should be a hash containing the unique identifier in your system for the currently logged in customer. For example, if your Smile account is connected to Shopify, the unique identifier would be the Shopify Customer ID (e.g. <code class="slate-code">123456</code>, not <code class="slate-code">gid://shopify/Customer/123456</code>). This value should never be the Smile Customer ID.</p><p class="slate-p " >We require the following format, where <code class="slate-code">100</code> is the customer&apos;s unique identifier. Depending on the backend language and JWT library you&apos;re using, you may need to include the JWT&apos;s expiry directly in the payload.</p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-ruby keep-markup drop-tokens"><div class="slate-code_line">{</div><div class="slate-code_line">  customer_identity: {</div><div class="slate-code_line">    distinct_id: &quot;100&quot;</div><div class="slate-code_line">  }</div><div class="slate-code_line">}</div></code></pre></div><h3 class="slate-h3 " >Code sample</h3><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-ruby keep-markup drop-tokens"><div class="slate-code_line">require &quot;jwt&quot;</div><div class="slate-code_line"></div><div class="slate-code_line"># Unique identifier of the customer in your system (not the Smile Customer ID)</div><div class="slate-code_line"># For Shopify, use the numeric Shopify Customer ID (123456), not the fully</div><div class="slate-code_line"># qualified Shopify GraphQL ID (gid://shopify/Customer/123456)</div><div class="slate-code_line">customer_id = &quot;100&quot;</div><div class="slate-code_line"></div><div class="slate-code_line"># Your Smile.io Private Key</div><div class="slate-code_line">private_key = &quot;sk_1234567890&quot;</div><div class="slate-code_line"></div><div class="slate-code_line">payload = {</div><div class="slate-code_line">  customer_identity: {</div><div class="slate-code_line">    distinct_id: customer_id</div><div class="slate-code_line">  },</div><div class="slate-code_line">  exp: Time.now.to_i + 300 # Set expiry to 5 minutes</div><div class="slate-code_line">}</div><div class="slate-code_line"></div><div class="slate-code_line">signed_jwt = JWT.encode(payload, private_key, &quot;HS256&quot;)</div></code></pre></div><div class="slate-div"></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p>

This method initializes Smile.js with information about the reward program to display and the currently logged in customer. This method must be called before you can interact with other methods provided by the SDK.

Title

Description

 is what's used to verify your store is the one requesting information from Smile.io on behalf of a customer. It should be generated using your platform's server side language so your Smile.io 

 remains secret. It must also have an expiration, for which we recommend 5 minutes.

The payload of the JWT should be a hash containing the unique identifier in your system for the currently logged in customer. For example, if your Smile account is connected to Shopify, the unique identifier would be the Shopify Customer ID (e.g. 

). This value should never be the Smile Customer ID.

 is the customer's unique identifier. Depending on the backend language and JWT library you're using, you may need to include the JWT's expiry directly in the payload.

This method initializes Smile.js with information about the reward program to display and the currently logged in customer.

<div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=warning ><div class="callout-icon"><svg width="18" height="16" viewBox="0 0 18 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.916637 15.5009C0.791637 15.5009 0.683998 15.4732 0.59372 15.4176C0.503443 15.362 0.430526 15.2857 0.37497 15.1884C0.319415 15.0912 0.288165 14.9905 0.28122 14.8864C0.274276 14.7822 0.305526 14.6745 0.37497 14.5634L8.4583 0.605103C8.52775 0.493991 8.60761 0.41413 8.69789 0.365519C8.78816 0.316908 8.88886 0.292603 8.99997 0.292603C9.11108 0.292603 9.21178 0.316908 9.30205 0.365519C9.39233 0.41413 9.47219 0.493991 9.54164 0.605103L17.625 14.5634C17.6944 14.6745 17.7257 14.7822 17.7187 14.8864C17.7118 14.9905 17.6805 15.0912 17.625 15.1884C17.5694 15.2857 17.4965 15.362 17.4062 15.4176C17.3159 15.4732 17.2083 15.5009 17.0833 15.5009H0.916637ZM1.99997 14.2509H16L8.99997 2.1676L1.99997 14.2509ZM9.0833 13.0634C9.26386 13.0634 9.41316 13.0044 9.53122 12.8864C9.64928 12.7683 9.7083 12.619 9.7083 12.4384C9.7083 12.2579 9.64928 12.1086 9.53122 11.9905C9.41316 11.8725 9.26386 11.8134 9.0833 11.8134C8.90275 11.8134 8.75344 11.8725 8.63539 11.9905C8.51733 12.1086 8.4583 12.2579 8.4583 12.4384C8.4583 12.619 8.51733 12.7683 8.63539 12.8864C8.75344 13.0044 8.90275 13.0634 9.0833 13.0634ZM9.0833 10.7509C9.26386 10.7509 9.41316 10.6919 9.53122 10.5739C9.64928 10.4558 9.7083 10.3065 9.7083 10.1259V6.70927C9.7083 6.52871 9.64928 6.37941 9.53122 6.26135C9.41316 6.1433 9.26386 6.08427 9.0833 6.08427C8.90275 6.08427 8.75344 6.1433 8.63539 6.26135C8.51733 6.37941 8.4583 6.52871 8.4583 6.70927V10.1259C8.4583 10.3065 8.51733 10.4558 8.63539 10.5739C8.75344 10.6919 8.90275 10.7509 9.0833 10.7509Z" fill="#F1C21B"></path></svg></div><div ><p class="slate-p " >On pages where you are able to include or write custom JavaScript, we recommend using the relevant SDK methods instead of the automatic replacement behaviour of the HTML Helpers.</p></div></div><p class="slate-p " >On any page where Smile.js is loaded, the library will look for HTML elements with the following classes and replace their content with dynamic values from the rewards program. To use a helper, simply add the relevant class to an empty <code class="slate-code">span</code> tag.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Supported classes</h2><div class="table-container" style="width:98%;
  min-width:98%;"><table class="slate-table" style="min-width:100%"><div class="published-table-header" style="width:100%;min-width:100%;min-height:initial;visibility: hidden;border:initial"><div style="width:100px;">Title</div><div style="width:100px;">Description</div></div><colgroup ><col style="width:initial"><col style="width:initial"></colgroup><tbody class="slate-TableElement-tbody"><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">HTML Class</strong></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><strong class="slate-bold">Replacement Value</strong></p></td></div></tr><tr class="slate-tr " ><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " ><code class="slate-code">smile-points-balance</code></p></td></div><div class="slate-TableCellElement-content"><td class="slate-td"><p class="slate-p " >The points balance of the currently logged-in customer.</p></td></div></tr></tbody></table></div><p class="slate-p " ></p><p class="slate-p " ></p><p class="slate-p " ></p><div class="slate-div"></div><p class="slate-p " ></p><p class="slate-p " ></p>

On any page where Smile.js is loaded, the library will look for HTML elements with the following classes and replace their content with dynamic values from the rewards program. To use a helper, simply add the relevant class to an empty 

HTML helpers that can be used to augment the functionality of the JS SDK.

<p class="slate-p " >The <code class="slate-code">Smile</code> object is a reference to the instance of Smile.js that has been included &amp; initialized on the current page. It&apos;s methods can be used to interact with the core components of the reward program and do things like list available rewards or create activities. For presentational concerns, use the methods on the <a href="66d9ee32a4347c9ff41d1809" target="">Smile UI object</a>.</p><p class="slate-p " ></p>

 object is a reference to the instance of Smile.js that has been included & initialized on the current page. It's methods can be used to interact with the core components of the reward program and do things like list available rewards or create activities. For presentational concerns, use the methods on the 

Methods and information available on the Smile JavaScript object.

<p class="slate-p " >The Smile UI object is a reference to the rewards panel being shown on the current page. It's methods can be used to control how and when the panel appears. To interact directly with the reward program beyond presentational concerns, refer to the <a href="66d9ee32a4347c9ff41d17fb" target="">Smile object</a>.</p><p class="slate-p " ></p>

The Smile UI object is a reference to the rewards panel being shown on the current page. It's methods can be used to control how and when the panel appears. To interact directly with the reward program beyond presentational concerns, refer to the 

Information and methods available on the SmileUI JavaScript object.

<p class="slate-p" placeholder="Type / for widgets">When using methods that interact with Smile&apos;s API, responses are converted into JavaScript objects to make them easier to work with. The properties of these methods can be accessed using dot notation, and are exact copies of the objects returned by Smile&apos;s REST API.</p>

When using methods that interact with Smile's API, responses are converted into JavaScript objects to make them easier to work with. The properties of these methods can be accessed using dot notation, and are exact copies of the objects returned by Smile's REST API.

A list of objects available as part of the Smile JavaScript SDK.

Sections