Button for Loyalty and Rewards

Button for Loyalty and Rewards

Button helps you power a real-time loyalty & rewards platform across the mobile app ecosystem, enabling you to notify and reward your members for purchases made on their mobile devices.



Note: Want to work with companies not supported today? Just let us know and we'll work with them to make it happen!

In this guide, we'll go over:

How Button Powers Loyalty and Rewards

There are two components to a Loyalty and Rewards integration with Button:

  1. Route users to Brands through Button. Integrating with Button includes:

    • Button attribution / closed-loop tracking
    • App-to-app deeplinking
    • Embedded web checkout
    • Simple Button Links to a Brand (for mobile web Publishers)
  1. Receive transaction notifications when users install or checkout in Brand apps or mobile websites, and notify/credit your users as necessary.

What would that look like in a diagram?

It would look like this...


Setting up Loyalty and Rewards with Button in 5 steps

  1. Configure the SDK and set up user IDs
  2. Create a Button Purchase Path
  3. Send users to the Brand to purchase
  4. Configure webhooks on commissionable events
  5. Notify and reward users

1. Configure the SDK and set up user IDs

The first thing you'll need to do is add the Button SDK to your app, initialize it, and identify your users with your unique User ID. The reason you'll want to pass your user identifier is that when we notify you of transactions you drove (via webhooks or our Transactions API), we'll include the user identifier so that you can reward them accordingly.

2. Create a Button Purchase Path

You can fetch an action from Button by passing a Brand URL to Button's SDK, which Button will then enhance with a mix of tracking, native technology, and a highly optimized user experience. This simple approach allows you to add Button to virtually any purchasable item that is accessible through a URL. The SDK determines if Button supports commissioning on a particular URL, so all you have to do is pass it to the SDK and Button will take care of the rest. For more information on Button Purchase Path, check out this guide.

For mobile web publishers (i.e. integrating with Button on a mobile website), simply create Button Links.

3. Send users to the Brand to purchase

If Button can exchange the the given URL for a fully attributed action, the fetch will complete with a Purchase Path. Starting a purchasePath will pass control to the Button SDK which will open the Brand app if installed or bring the user to checkout in our embedded webview.

Note: If the user doesn't already have the Brand app installed, they can choose to seamlessly install it using our proprietary Attended Install functionality. You may receive a webhook on app download completion to inform you of any commission earned.



4. Configure webhooks on commissionable events

In order to receive notifications when your users install or checkout in Button Marketplace apps, you need to configure a webhook endpoint. Webhooks send you a notification by POSTing to an API endpoint you declare with the details of the user and transaction.

You can configure webhooks in the Dashboard Webhooks tab.

Pending, Validated, and Declined States

Your webhook will be sent Transaction: Pending, Transaction: Validated, and Transaction: Declined events from Button. These represent pending, validated, and declined transactions respectively. See here for more details.

Until a transaction is marked as validated, it can be changed and should not be redeemable / cash-out-able to a user. Pending transactions can be shown to users in a pending state (e.g. Balance vs. Available Balance.)

5. Notify and reward users

Note: You should only reward users on purchase events, so make sure you check the category field and filter out app install webhooks.

When you receive a webhook POST, you know that one of your users may be eligible for a reward.

The webhook payload will contain a few fields that are particularly useful:

  • publisher_customer_id: The User ID (your ID) for the user that transacted
  • category: The Category of transaction (Order vs Install)
  • button_order_id: The unique identifier for the transaction
  • order_total: For orders, this is the total amount of the order
  • status: The status of the transaction
  • commerce_organization: The ID of the Brand app that the purchase took place in
  • order_line_items[].publisher_commission: Each line item contains the exact commission granted to the Publisher for the line item

Click here for the full webhook documentation.

In this case, if you wanted to give a user 100 points for purchasing in App A, we would perform logic like the following:

// Get the user that made the transaction
User affectedUser = User.userByID(webhook.publisher_customer_id);

if (webhook.commerce_organization == TARGET_COMMERCE_APP_ID) {
    if (webhook.status == "validated") {
        affectedUser.addPoints(100, "Purchasing in App X");
    }
    else if (webhook.status == "pending") {
        // Optionally tell them something here
    }
}

Alternatively, you can use the publisher commission field to calculate rebates based on the specific commission generated by each item in the order. If publisher commission == 0, this item was likely subject to a Brand exclusion.

// assume `webhook` is a parsed Button webhook
const USER_COMMISSION_PERCENTAGE = .8;
const PUBLISHER_COMMISSION_EPOCH = new Date('2018-07-18T23:00:00Z'); // see webhook field documentation

const user = User.userByID(webhook.publisher_customer_id);
const attributionDate = new Date(webhook.attribution_date);

if (attributionDate < PUBLISHER_COMMISSION_EPOCH) {
  // Use your original commissioning logic
} else {
  for (const lineItem of webhook.order_line_items) {
    const publisherCommission = lineItem.publisher_commission;
    if (publisherCommission === 0) {
      continue;
    }

    // apply a commission to the user with your chosen method
    lineItemTotal = lineItem.amount * lineItem.quantity;
    user.addPoints(lineItemTotal * USER_COMMISSION_PERCENTAGE);
  }
}
# assume `webhook` is a parsed Button webhook
require 'date'

PUBLISHER_COMMISSION_EPOCH = "2018-07-18T23:00:00Z" # see webhook field documentation
USER_COMMISSION_PERCENTAGE = 0.8

user = User.user_by_id(webhook["publisher_customer_id"])
attribution_date = DateTime.iso8601(webhook["attribution_date"])

if (attribution_date < DateTime.iso8601(PUBLISHER_COMMISSION_EPOCH))
  # Use your original commissioning logic
else
  webhook["order_line_items"].each { |line_item|
    publisher_commission = line_item["publisher_commission"]
    if (publisher_commission == 0)
      next
    end

    # apply a commission to the user with your chosen method
    line_item_total = line_item["amount"] * line_item["quantity"]
    user.add_points(line_item_total * USER_COMMISSION_PERCENTAGE)
  }
end
# assume `webhook` is a parsed Button webhook
import datetime

PUBLISHER_COMMISSION_EPOCH = '2018-07-18T23:00:00Z' # see webhook field documentation
USER_COMMISSION_PERCENTAGE = .8
ISO_8601_FORMAT_STRING = "%Y-%m-%dT%H:%M:%SZ"

user = User.user_by_id(webhook['publisher_customer_id'])

attribution_date = datetime.datetime.strptime(webhook['attribution_date'], ISO_8601_FORMAT_STRING)
epoch_date = datetime.datetime.strptime(PUBLISHER_COMMISSION_EPOCH, ISO_8601_FORMAT_STRING)

if attribution_date < epoch_date:
  # Use your original commission logic
  pass
else:
  for line_item in webhook['order_line_items']:
    publisher_commission = line_item['publisher_commission']
    if publisher_commission == 0:
      # line item was not commissionable
      continue

    # apply a commission to the user with your chosen method
    line_item_total = line_item['amount'] * line_item['quantity']
    user.add_points(line_item_total * USER_COMMISSION_PERCENTAGE)

Testing your Integration

Now it's time to test that everything is working correctly.

  • Display a Button in your app
  • Tap it and go through to the Brand app
  • Make a purchase
  • Your webhook will fire
  • Confirm that the webhook fires with the correct amount & user ID.

Note: You can also use the Button Partner Test App to test out your integration, but it does not currently support userID so all webhooks will fire without a user ID.

Questions?

Have other use-cases in mind, or see something that doesn't make sense? Contact us and we'll get in touch!

What's Next

Now that you know Button for Loyalty and Rewards, see more on how to integrate:


Configure Webhooks

Button allows you to configure webhooks so you can get real-time updates to your system when users push Buttons in your app. To do so, you will need to configure the destination of the webhook and what events you want to receive. Then, Button will send you an HTTP request when any of those events are created.

View Guide