Overview

Introduction to Rewardful's JavaScript API

Note: our JavaScript API is currently in beta. If something isn't working as you'd expect, please drop us a line and let us know! hello@getrewardful.com

Rewardful's remote script loads asynchronously to make it as performant and reliable as possible. In order to use Rewardful's JavaScript API you'll need to slightly modify Step #1 of our setup to ensure your JavaScript code executes as expected.

You can use our asynchronous JavaScript API to perform client-side conversion tracking as well as execute functions when Rewardful has initialized.

Add the JavaScript tag + snippet

To add support for our asynchronous JavaScript API, place this code snippet onto every page of your website, ideally in the <head> tag:

<script>(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');</script>

This code will add a rewardful function to the page, which can be immediately called and passed instructions that Rewardful will execute once loaded. The general format of these method calls is rewardful(methodName, arg1, arg2, arg3, ...)

It's important for this snippet to appear in your HTML before any calls to the rewardful function. To make it simple, we recommend adding it immediately before the script tag that loads the remote Rewardful script from Step #1 in the setup instructions. Your final Step #1 snippet should look something like this:

<script>(function(w,r){w._rwq=r;w[r]=w[r]||function(){(w[r].q=w[r].q||[]).push(arguments)}})(window,'rewardful');</script>
<script async src='https://r.wdfl.co/rw.js' data-rewardful='YOUR-API-KEY'></script>

Remember to replace YOUR-API-KEY with your Rewardful API Key, which can be found on the Company settings page in your Rewardful dashboard.

Client-Side Conversion Tracking

Rewardful's JavaScript API allows you to track conversions with frontend code only — no backend code is required. This can make integrating Rewardful much simpler, and enables you to use Rewardful in scenarios where you're unable to modify backend/server code, such as when using a hosted platform to sell your products.

To track a conversion client-side, use the "convert" function, and pass the customer's email address using the email parameter. This code should appear on your thank-you or receipt page (or whatever page your customers are taken to immediately after purchase).

For example:

<script>
rewardful('convert', { email: 'joe@example.com' })
</script>

This code will search for the most recently created customer with the email address "joe@example.com" in your Stripe account. If the customer exists and the Rewardful cookie is present (i.e. this visitor is a referral), Rewardful with associate the customer with the affiliate.

Note: this code only performs network requests if the current website visitor is a referral. If the visitor arrived on your website through another channel, the convert function does nothing.

Requirements

In order to use Client-Side Conversion Tracking there are a few prerequisites:

  1. Your Stripe account must be connected to Rewardful with read-write permission.

  2. Your platform creates Stripe Customers within your Stripe account when a purchase is made.

  3. You are able to add client-side code snippets to your website & receipt/thank-you page, and access the customer's email address on these pages.

The Stripe customer must have been created within the last 24 hours in order to be tracked with client-side conversion tracking.

Executing code when Rewardful loads

In some cases you might want to execute code once Rewardful has fully loaded and performed any tracking/network requests.

Pass a callback function to the ready handler to have it executed when Rewardful has fully loaded. This function always executes, whether the current visitor is a referral or not. For example:

<script>
rewardful('ready', function() {
console.log('Rewardful Ready!')
});
</script>

If you only want code to run if the current visitor is a referral, you can check the Rewardful.referral property:

<script>
rewardful('ready', function() {
if(Rewardful.referral) {
// The current website visitor is a referral from an affiliate.
}
});
</script>

Calls to rewardful are queued and executed in order once Rewardful has loaded. This means you can queue up multiple functions, and even call rewardful if Rewardful is loaded (which effectively calls the underlying function immediately). For example:

<script>
rewardful('ready', function() {
console.log('This will fire first.')
});
rewardful('ready', function() {
console.log('This will fire second.')
});
rewardful('ready', function() {
console.log('This will fire third.')
});
</script>

Attributes

Because Rewardful loads asynchronously, we recommend accessing these attributes within the rewardful('ready')handler. See Executing code when Rewardful loads for details.

Referral

Rewardful.referral will return the Referral ID of the current visitor if they were referred, for example: "98288128-0d5f-45a9-88b3-ef95b229f798"

If the current visitor was not referred by a Rewardful affiliate, Rewardful.referral will return an empty string: ""

<script>
rewardful('ready', function() {
if(Rewardful.referral) {
console.log('Current referral ID: ', Rewardful.referral);
} else {
console.log('No referral present.');
}
});
</script>

Affiliate

Rewardful.affiliate will return some information about who sent you a referral, for example:

{
id: "b533bfca-7c70-4dec-9691-e136a8d9a26c",
name: "James Bond",
first_name: "James",
last_name: "Bond",
token: "james007"
}

You might want to use this for personalizing your website based on who the affiliate was:

<script>
rewardful('ready', function() {
if(Rewardful.affiliate) {
$('.affiliate-banner').text(
`Hi there, friend of ${Rewardful.affiliate.first_name}!`
).show();
}
});
</script>

Rewardful.affiliate returns false if there is no affiliate, i.e. the current visitor was not referred.

Coupon Details

If you've attached a coupon to your campaign, the coupon object will be available through Rewardful.coupon. The attributes correspond directly to the coupon object in Stripe.

For example, a 25% discount that repeats for 12 months might look like:

{
id: "bf-2019",
name: "Black Friday 2019",
duration: "repeating",
duration_in_months: 12,
percent_off: 25,
amount_off: null,
currency: null
}

And a one-time $25 USD discount might look like:

{
id: "save-25",
name: "One-time $25 credit",
duration: "once",
duration_in_months: null,
percent_off: null,
amount_off: 2500,
currency: "usd"
}

We recommend checking for the coupon's existence before attempting to access it's attributes, for example:

<script>
rewardful('ready', function() {
if(Rewardful.coupon) {
showCouponBanner(Rewardful.coupon);
}
});
</script>

Methods

Attaching to forms

On page load Rewardful will automatically inject a hidden input into forms with a data-rewardful attribute. This makes it simple to get the referral ID sent to your server along with the rest of the data from your signup or payment form.

For example, your signup form might look something like this:

<form action="/signup" method="post" data-rewardful="true">
<input type="text" name="name">
<input type="email" name="email">
<button>Sign Up</button>
</form>

If the current visitor came to your site through an affiliate link, Rewardful will detect the data-rewardful attribute and automatically insert a hidden input named referral with the unique click ID (UUID) as the value. For example:

<form action="/signup" method="post" data-rewardful="true">
<input type="text" name="name">
<input type="email" name="email">
<button>Sign Up</button>
<!-- Inserted automatically by Rewardful: -->
<input type="hidden" name="referral" value="78476c40-0137-11eb">
</form>

When the form is submitted, the POST data sent to your server will include the referral parameter, along with the rest of the customer data. You can extract this value ($_POST['referral'] in PHP, params[:referral] in Rails, etc) and add it to the Stripe customer's metadata or save it in your own database for future use.

Manually attaching to forms

If your form is dynamically added to the page (Turbolinks, a single-page app or a modal) you'll need to manually tell Rewardful to attach to these forms after they have been added to the DOM.

To attach to all forms present in the DOM with the data-rewardful attribute, you can call Rewardful.Forms.attach()

document.addEventListener("turbolinks:load", function() {
Rewardful.Forms.attach();
});

If your form appears inside a Bootstrap Modal:

$('#signup-modal').on('shown.bs.modal', function (e) {
Rewardful.Forms.attach();
});

Attaching to specific forms

If you'd like to manually attach the hidden referral input into a specific form, you can do so with Rewardful.Forms.add(formElement), for example:

const signupForm = document.getElementById('signup-form');
Rewardful.Forms.add(signupForm);

This can be useful in circumstances where you cannot easily modify the source code of the form tag (for example, using a CMS or hosted service) and are unable to add the data-rewardful attribute.