Smile.io

# Introduction

Welcome to Smile! Get familiar with the ways you can extend and integrate Smile.

### Questions

We're always happy to help with code or other questions you might have! Search our documentation at the top of the page, visit our [knowledge base](https://help.smile.io), or contact support through [support@smile.io](mailto:support@smile.io).


Introduction

Fundamentals

Use cases

Add Smile to any website

Landing/explainer page

# Rewarding for any action

{% hint style="info" %}
Only available on Enterprise plans.
{% endhint %}

Smile.io lets you reward for virtually any action your customers do while engaging with your brand. Our platform supports the ability to reward for a variety of standard actions, but sometimes you want to reward for additional custom actions that may be specific to your brand. Good news is, if your system is able to detect when the action occurs, then Smile can reward for it!

Here are some common custom actions we think are great candidates for rewarding:

* Newsletter subscription
* Blog post visit
* Watching a video
* Filling out a survey
* Voting on new product ideas

## How To: Reward for a newsletter subscriptions

### 1. Navigate to Settings > Developer Tools

![](../.gitbook/assets/developer-tools.png)

### 2. Click "Build my first custom activity"

![](<../.gitbook/assets/new-custom-activity (2).png>)

### 3. Fill out the name fields for the custom activity and save

![](../.gitbook/assets/name-custom-activity.png)

### 4. Notify Smile that the activity has occurred

After creating a new type of custom activity, you need to setup your system to notify us when the activity has occurred. You can do this via Javascript on the frontend, or server-side using an API call.

**Using Javascript**\
Copy the provided Javascript snippet into your frontend. We recommend inserting it as a callback (i.e. something that runs after submitting your newsletter subscription form or once the desired action has been completed).

![](../.gitbook/assets/js\_activity\_snippet.png)

{% hint style="warning" %}
**Be careful when using Javascript to send custom activities!**

Since Javascript source code is available in the web browser, users of your website can manipulate data via the Developer Console to send you multiple activities, or even activities that they have not actually performed. To eliminate this concern, consider [adding rate limits to your earning rules](https://help.smile.io/article/2449-limit-points-earning-for-certain-actions) (so that you only reward once for a given type of activity) or sending custom activities via a backend API call instead.
{% endhint %}

**Using a backend API call**\
You can use the Activities endpoint to notify Smile that a given activity has been performed by a customer. To do so, you'll need to extract the activity's token/type from the provided code sample:

![](../.gitbook/assets/code\_snippet.png)

The token/type will always start with `activity_`, followed by a series of letters and numbers. You will then use this value along with the customer's Smile ID to send an [API call to the activities endpoint](https://api-reference.smile.io/#create-an-activity) which lets us know the activity has taken place.

{% code title="POST https://api.smile.io/v1/activities" %}
```javascript
{
  "activity": {
    "customer_id": 1,
    "token": "activity_dDPUD2R6I9czhXcm037w6SWj"
  }
}
```
{% endcode %}

### **5. Setup an earning rule in your program to reward the custom activity**

By default, Smile does not issue rewards for new custom activities, so you need to [create a new earning rule](https://help.smile.io/article/2360-add-an-earning-action) that specifies how you would like to reward. When selecting what activity you would like to reward for, scroll to the bottom and choose the custom activity you just created.

![](../.gitbook/assets/choose\_earning\_action.png)

Once selected, you'll simply configure the earning rule as you would any other, and it will become available as part of your normal program!

{% hint style="info" %}
If you're notifying us that the activity has occurred using Javascript on the frontend, it's a good idea to make sure your earning rule has a [rate limit](https://help.smile.io/article/2449-limit-points-earning-for-certain-actions). This helps prevent abuse and spam from users playing around in their web browser's developer console.
{% endhint %}

## You have now created a custom activity!

That's it, you're done! Smile will now automatically issue rewards any time a customer performs the activity you've just setup.


Reward for any action

# Points spending at checkout

Allowing customers to redeem points at checkout is a great way to promote points spending and boost engagement with your reward program. Adding a points slider or dropdown to your checkout page makes spending points quick, easy, and seamless.‌

We've curated guides for each of our supported platforms with instructions on how to modify your checkout page.

## Shopify

* [Points dropdown at checkout](../install-smile/shopify/points-dropdown-at-checkout.md)
* [Points slider at checkout](../install-smile/shopify/points-slider-at-checkout.md)

## BigCommerce

* [Points dropdown at checkout](../install-smile/bigcommerce/points-dropdown-at-checkout.md)
* [Points slider at checkout](../install-smile/bigcommerce/points-slider-at-checkout.md)

## Custom platform

* [Points dropdown at checkout](../install-smile/custom-platform/frontend-integration/points-dropdown-at-checkout.md)


Points at checkout

Build an app

# Activities

Activities represent actions a customer may perform while interacting with an app. Using the activities API, an app is able to reward customers for any action.

### Creating a new activity type

Activity types can be created in the app settings page of the Partner Dashboard. Once an activity type has been created, you can use the provided token to create activities for customers in Smile.

Activity types map to actions that customers perform. For example, an activity type could be "Complete a survey". Then, whenever a customer completes a survey in your app, an activity could be sent to Smile.

### Creating an activity

In order to report actions that customers perform, you will need to create an activity in Smile via an API request. Take a look at our API reference for details on how to [create an activity](https://api-reference.smile.io/#create-an-activity).



Activities

Authorization

Supported endpoints

# Webhooks

Instead of polling the Smile API for updates, your app can subscribe to webhook topics in order to receive events as they occur within Smile.

{% hint style="info" %}
**Webhooks must be used with HTTPS**. Webhooks are insecure if they are delivered without TLS. Only use HTTPS for your webhook URLs.&#x20;
{% endhint %}

### Creating a webhook

Webhooks can be created via the app settings page in the Smile Partner Dashboard.

Upon the creation of a Webhook, Smile will `POST` a test webhook to the supplied URL. This webhook will have the `ping` topic. In order for the webhook to be created, the endpoint must respond with a `2xx` HTTP status code. This is a simple smoke test that shows Smile your app is capable of receiving a webhook.

### Topics

Webhook topics allow an app to subscribe to specific events that occur in Smile. Below is a list of webhook topics that an app can subscribe to.

| Topic              | Description                                                                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ping`             | This is a pseudo topic that gets sent by Smile to check if your webhook endpoint is functioning properly. The `data` portion of this webhook is an empty object. |
| `customer/updated` | Occurs when a customer is updated. This includes the initial creation of a customer.                                                                             |

### Structure

Webhooks have a consistent structure across all topics. They contain the following parameters.

| Parameter    | Description                                                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `account_id` | The ID of the account on which the event occurred.                                                                                        |
| `data`       | The specific data pertaining to the webhook topic. For example, the data in a `customer/updated` webhook will contain a `customer`object. |
| `topic`      | The webhook topic. Topics contain two components: a subject and a verb separated by a slash (e.g. `customer/updated`).                    |

Here is an example webhook body.

```javascript
{
  "account_id": 0,
  "data": {},
  "topic": "ping"
}
```

#### Customer webhooks

For webhook topics with a "customer" subject (e.g. `customer/updated`), the data attribute in the webhook body will contain the following parameters.

| Parameter  | Description                                                                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer` | An object representing the customer that was updated. See the [customer object](https://api-reference.smile.io/#the-customer-object) for the attributes that are included. |

### Verifying signatures

In order to verify that a webhook contains legitimate data, Smile signs the contents of each webhook with a `sha256` [HMAC](https://en.wikipedia.org/wiki/HMAC). Webhooks are signed using the app's client secret which can be found in the app settings page of the Smile Partner Dashboard.

The following headers must be utilized to verify the signature of a webhook.\


| Header            | Description                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `Smile-Signature` | The HMAC generated by Smile. An app will attempt to compute this signature in order to verify that the webhook is legitimate. |
| `Smile-Timestamp` | The number of seconds since the Unix epoch (UTC). This value is used to prevent replay attacks.                               |

To verify a webhook's signature, the app must perform the following steps.

1. Concatenate the `Smile-Timestamp`, followed by a period (`.`), followed by the webhook request body.
2. Generate a `sha256` HMAC using the computed string and the app's client secret.
3. Compare the computed HMAC to the value of the `Smile-Signature`.
4. Verify that the timestamp is within 5 minutes of the current time.

For a working example, see the code snippet below.

{% tabs %}
{% tab title="Ruby" %}
```ruby
require 'rubygems'
require 'base64'
require 'openssl'
require 'sinatra'


def verify_webhook_signature(body, timestamp, signature)
  client_secret = ENV['SMILE_CLIENT_SECRET']
  prepared_string = "#{timestamp}.#{body}"

  # Compute the hmac using the client secret.
  digest = OpenSSL::Digest.new('sha256')
  hmac = OpenSSL::HMAC.digest(digest, client_secret, prepared_string)
  encoded_hmac = Base64.encode64(hmac).strip

  # Verify that the webhook has been sent within the last 5 minutes.
  timestamp_plus_five_minutes = timestamp.to_i + 5 * 60
  webhook_is_fresh = timestamp_plus_five_minutes > Time.now.to_i

  # Check that the signature matches and the webhook is fresh.
  (encoded_hmac == signature) && webhook_is_fresh
end


post '/' do
  body = request.body.read
  timestamp = request.env['HTTP_SMILE_TIMESTAMP']
  signature = request.env['HTTP_SMILE_SIGNATURE']

  # Verify the webhook signature.
  verified = verify_webhook_signature(body, timestamp, signature)
  puts("Webhook verified: #{verified}")

  status 200
end
```
{% endtab %}

{% tab title="Python" %}
```python
import hmac
from base64 import b64encode
from hashlib import sha256
from os import environ
from time import gmtime
from flask import Flask, request, Response


app = Flask(__name__)


def verify_webhook_signature(body, timestamp, signature):
    client_secret = environ['SMILE_CLIENT_SECRET']
    prepared_string = '{timestamp}.{body}'.format(timestamp=timestamp, body=body)

    # Compute the hmac using the client secret.
    computed_hmac = hmac.new(client_secret, msg=prepared_string, digestmod=sha256)
    digest = computed_hmac.digest()
    encoded_digest = b64encode(digest)

    # Verify that the webhook has been sent within the last 5 minutes.
    timestamp_plus_five_minutes = int(timestamp) + 5 * 60
    webhook_is_fresh = gmtime(timestamp_plus_five_minutes) > gmtime()

    return (encoded_digest == signature) and webhook_is_fresh


@app.route('/', methods=['POST'])
def handler():
    body = request.get_data()
    timestamp = request.headers['Smile-Timestamp']
    signature = request.headers['Smile-Signature']

    # Verify the webhook signature.
    verified = verify_webhook_signature(body, timestamp, signature)
    print('Webhook verified: {verified}'.format(verified=verified))

    return Response(status=200)


app.run(port=4567)
```
{% endtab %}
{% endtabs %}

The above code snippet is functional, however in order to prevent timing attacks, a constant time string comparison function should be used when comparing signatures.

### Etiquette

Webhook processing should **not** be synchronous. When a webhook is received, it should be added to a queuing system for asynchronous processing. This frees up Smile's server resources. Apps that take a long time to respond to webhooks may have their webhooks disabled.

When responding to a webhook, the endpoint must use a `2xx` HTTP status code to indicate that the webhook was successfully received. Any status code outside of the `2xx` range will be considered a delivery failure.

### Retries

If a webhook fails to send for any reason, Smile will try to send the webhook again later. Smile uses an exponential back off algorithm when resending failed webhooks. If the webhook cannot be sent successfully within a 24 hour period, the webhook will be disabled for the entire app.

### Permissions

OAuth permissions determine if webhooks can be sent to an app for a given Smile account.

{% hint style="info" %}
**This section discusses OAuth concepts.** We suggest that you read the [Smile OAuth Reference](../oauth-reference/) before diving into this section.
{% endhint %}

Every webhook topic has corresponding OAuth permissions. For example, in order to receive `customer/updated` webhooks, the app must be granted the `customer:read` permission.

It is important to understand that app permissions are granted on a per-account basis. This means that an app is not guaranteed to have the same scope on all of the Smile accounts that it is installed on. As a result, an app will only receive webhooks for the subset of Smile accounts that have granted it one of the required permissions.

Once a webhook is created via the Smile Partner Dashboard and at least one user has authorized the app with one of the required permissions, the app will start to receive webhooks.


Webhooks

Deprecated

Custom HTML emails

Custom platform

Blank

Developer Docs

Guides and information on how to use Smile.io's developer resources and tooling.

Developer Docs | Smile.io

Production

Access scopes

BigCommerce dropdown

BigCommerce slider

BigCommerce Stencil

Backend integration

Customer deleted

Customer events

Customer object

Customer updated

Example usage

Object reference

Handlebar variables

Frontend integration

Order deleted

Order events

Order object

Order updated

OAuth errors

OAuth flow

Client secret rotation

<p class="slate-p " >In order to make reward programs simple to setup and effortless to maintain, Smile uses the basic model of “actions in, rewards out.” This means that all of the complexity of evaluating when, where, and how to issue rewards is handled internally by Smile. From a development perspective, the only thing you need to worry about is notifying Smile that the customer has performed an action.</p><div style="text-align:left"><img src="https://theneo-prod-public.s3.us-east-1.amazonaws.com/2520d761-6fbe-43c9-ab3d-cf76d1d750de.svg" style="
              width:712px;
	            height:333px;
	            aspect-ratio:712 / 333"
         /></div><h2 class="slate-h2 " >Customer actions</h2><p class="slate-p " >In technical terms, customer actions are represented as <a href="https://dev.smile.io/api/resources/activities" target="">Activities</a>, and they&apos;re created using the <a href="https://dev.smile.io/api/resources/activities/create-activity" target="_self">create an activity</a> endpoint. Smile supports a variety of native activity types (like orders, social sharing, birthdays, and more), and additional custom activity types can be defined to enable <a href="6716b71dd44c980357125cd6/66e875ec4d5db70fdbf4ee9d" target="">rewarding for any action</a>.</p><p class="slate-p " >Native activity types sync automatically into Smile, requiring no custom development. Only custom activity types require explicit definition and for you to use the create an activity endpoint.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Reward issuing</h2><p class="slate-p " >When a new activity is created in Smile, it’s processed asynchronously against the account’s configured ways to earn (a.k.a. “earning/activity rules”). These rules are setup via Smile&apos;s reward program management UI, Smile Admin. If a matching rule is found and the customer and activity meet all of the rewarding criteria, Smile will generate a <a href="https://dev.smile.io/api/resources/reward-fulfillments" target="_self">Reward Fulfillment</a>. The fulfillment represents Smile&apos;s attempt to issue a reward to the customer. At this time, the only type of reward that can be issued when a customer performs an action are points.</p><p class="slate-p " >When a customer earns points, a <a href="https://dev.smile.io/api/resources/points-transactions" target="_self">Points Transaction</a> record is created, and the points balance field on the <a href="https://dev.smile.io/api/resources/customers" target="_self">Customer</a> object is updated.</p><p class="slate-p " ></p><h2 class="slate-h2 " >Points redemption</h2><p class="slate-p " >When they have accumulated enough points, customers can exchange their points for a reward (e.g. a discount coupon for their next order). The available redeeming options are modelled as <a href="https://dev.smile.io/api/resources/points-products" target="_self">Points Products</a>, and are configured by the merchant in Smile Admin. Redemption can occur via any of Smile&apos;s native UI components (like Smile UI or Shopify Checkout Extensions), by using the <a href="https://dev.smile.io/js/smile/purchase-points-product" target="_self">JavaScript SDK</a>, or with the <a href="https://dev.smile.io/api/resources/points-products/purchase-points-product" target="_self">purchase a points product</a> endpoint. </p><p class="slate-p " ></p>

In order to make reward programs simple to setup and effortless to maintain, Smile uses the basic model of “actions in, rewards out.” This means that all of the complexity of evaluating when, where, and how to issue rewards is handled internally by Smile. From a development perspective, the only thing you need to worry about is notifying Smile that the customer has performed an action.

In technical terms, customer actions are represented as 

 endpoint. Smile supports a variety of native activity types (like orders, social sharing, birthdays, and more), and additional custom activity types can be defined to enable 

Native activity types sync automatically into Smile, requiring no custom development. Only custom activity types require explicit definition and for you to use the create an activity endpoint.

When a new activity is created in Smile, it’s processed asynchronously against the account’s configured ways to earn (a.k.a. “earning/activity rules”). These rules are setup via Smile's reward program management UI, Smile Admin. If a matching rule is found and the customer and activity meet all of the rewarding criteria, Smile will generate a 

. The fulfillment represents Smile's attempt to issue a reward to the customer. At this time, the only type of reward that can be issued when a customer performs an action are points.

 record is created, and the points balance field on the 

When they have accumulated enough points, customers can exchange their points for a reward (e.g. a discount coupon for their next order). The available redeeming options are modelled as 

, and are configured by the merchant in Smile Admin. Redemption can occur via any of Smile's native UI components (like Smile UI or Shopify Checkout Extensions), by using the 

Learn about key concepts within Smile to kick-start your custom loyalty development efforts.

Sections