GithubNPMOfficial Website
API Reference

Getting Started

Suggest Edits

The following outlines how to get a loyalty program up and running on your app and website. Scrimmage Rewards provides both an API/TS SDK and web widget solution. If you would like an API only solution, you can stop after step 5.

Step 1. Get Access to the Admin Dashboard

Email [email protected] to request access to the admin dashboard. The admin dashboard is where you will be able to set up your secret keys, data types, and everything related to the reward program.

Step 2. Initialize Your Secret Key

Once on the admin dashboard, navigate to the "Secret keys" tab and generate a new key. We recommend rotating your secret keys once in 6 months for security reasons.

Step 3. Initialize the Scrimmage Rewards Library

Initialize the library by providing your unique server endpoint and a secret key, which you have generated in the previous step in the Admin Dashboard. We are using npm to install our library. If you are not a Node.js user please navigate to "API reference" to complete the API integration. Our library is not doing anything magical, just replacing API calls with SDK calls.

yarn add scrimmage-rewards

npm install -s scrimmage-rewards

import Scrimmage from '@scrimmage/rewards'

Scrimmage.initRewarder({  
  apiServerEndpoint: API_SERVER_ENDPOINT,  
  privateKey: SECRET_KEY,  
})

🚧

Keep your secret key safe!

The TS API is the wrapper around the Scrimmage API that allows for a quick integration.
It is very important to use this library only on the backend side of the application as it operates with secret keys.

Step 4. Initialize User Authentication

Scrimmage does not store login credentials, instead for us to store and manage a user's reward program information we rely on our clients to send us a user ID for that user.

To generate login links for user authentification you would need to call our API or use a typescript library to request a user token.

const TOKEN = Scrimmage.user.getUserToken(USER_ID)

After that, you have to pass this token to the frontend part of your application and insert it in the parameters of the widget URL.

https://<PARTNER_ID>.apps.scrimmage.co?token=<TOKEN>

To access best practices over integrating this page in your app navigate to our Github page and search for relevant examples.

Step 5. Create a Primary Reward Rule

This is the primary action you want to reward your users for. Typically this is something like wager amount or sales volume. Whatever you choose, users should always have the ability to earn rewards for completing this action. The primary reward rule is how users will understand and describe your reward program to others.

👍

An example of a good primary reward rule

  • Earn 1 coin for every $1 wagered
  • Earn 1 coin for every mile traveled
  • Earn 1 coin for every dollar spent
  • Earn 1 coin for every ADS watched

An example of a good primary reward rule: "Earn 1 coin for every$1 wagered". This is a good rule because it is simple and can always be achieved by the user. Better yet, the completion of this action directly leads to revenue for the company.

❗️

An example of a bad primary reward rule:

  • Complete the onboarding for our app
  • Make first deposit
  • Verify your account

An example of a bad primary reward rule: "Complete the onboarding for our app". This is a bad rule because it can only be completed by a user once, not allowing for ongoing rewards. Rewards like this can still be handled, but they should not be a primary rule.

Use our Default Primary Reward Rule

📘

If you are a gaming operator, we recommend using our default primary reward rule:

"Earn 1 coin for every $1 wagered and 1 coin for every $1 won"

The data structure we require for this rule is as follows:

import Scrimmage from '@scrimmage/rewards';
import {
  BetExecuted,
  BetLeague,
  BetOutcome,
  BetSport,
  BetType,
  SingleBet,
  SingleBetType
} from "@scrimmage/schemas";

await Scrimmage.reward.trackRewardable<BetExecuted>(
  {
    type: 'betExecuted',
    id: <string>data.id,
    userId: <string>uid,
    event: "asdasd",
    betType: <BetType>data.betType,
    isLive: false,
    // decimal odds
    odds: <number>data.odds,
    description: <string>data.description,
    event: "sdasdasd"
    // convert everything in dollars
    wagerAmount: <number>data.wagerAmount,
    // convert everything in dollars
    netProfit: <number>data.netProfit,
    outcome: <BetOutcome>data.outcome, // Make sure you convert
    betDate: <number>data.betDate, // UNIX
    bets: data.bets.map((bet: SingleBet) => ({
      type: <SingleBetType>bet.type,
      odds: <number>bet.odds, // decimal odds
      teamBetOn: <string>bet?.teamBetOn,
      teamBetAgainst: <string>bet?.teamBetAgainst,
      league: <BetLeague>bet?.league,
      sport: <BetSport>bet?.sport,
    })),
  });

Please insert this code wherever your bets are executed. Once this code is inserted, it will open up a one-way connection for you to send bet details to Scrimmage.

📘

Sending the same ID will prompt an update to the parameters of the reward. Sending the same bet multiple times is not an issue.

🚧

If you would like to handle the frontend interface for the reward program on your own, you may stop here, otherwise please continue

Step 6. Create the Endpoint to Send a User Authentication Token to the Frontend

This step has to be done from the backend side.

In this example, we are using our TS library to fetch the user token and send it to the frontend.

The previous user token is not getting invalidated so you can call this function multiple times.

The token will be valid for the next 24 hours

import * as functions from 'firebase-functions';
import Scrimmage from '@scrimmage/rewards';

const SCRIMMAGE_PRIVATE_KEY = 'secret'; // paste your Scrimmage private key here
const SCRIMMAGE_API_SERVER_ENDPOINT = 'https://orgurl.apps.scrimmage.co'; // paste your Organization URL here

Scrimmage.initRewarder({
    privateKey: SCRIMMAGE_PRIVATE_KEY,
    apiServerEndpoint: SCRIMMAGE_API_SERVER_ENDPOINT,
  });

export const generateIntegrationInfo =
  functions.https.onCall(async (data, context) => {
    return {
      Scrimmage.user.getUserToken(String(context.auth?.uid))
    };
  });

Step 7. Create the Endpoint to Fetch a User Authentication Token from the Frontend

In this step, you have to fetch the user token from the newly implemented backend endpoint.

For example we are not passing any user ID, but in your case you have to pass ID of your user to get a user specific token.

window.addEventListener('load', async () => {
  document.querySelector('.scrimmage-widget-container .scrimmage-widget-fab')
    .addEventListener('click', (event) => {
      event.target.closest('.scrimmage-widget-container').classList.toggle('open');
    });
  await setWidgetLink();
});

const setWidgetLink = async () => {
  const backendUrl = 'https://us-central1-bright-practice-331514.cloudfunctions.net/requestGenerateAuthInfo';
  const { token } = await fetch(backendUrl).then((response) => response.json());
  const iframe = document.querySelector('.scrimmage-widget-container iframe');
  iframe.src = `https://coinflip.apps.scrimmage.co/?token=${token}`;
}

Step 8. Display the Widget on the Frontend

In this example, we are adding our widget to an already existing website using an iframe.

The iframe needs user token to work and this token will be passed in it from the step 2.

<!-- Scrimmage Rewards integration -->
<div class="scrimmage-widget-container">
    <div class="scrimmage-widget-body">
        <div class="scrimmage-widget-frame">
            <iframe src="https://coinflip.apps.scrimmage.co"></iframe>
        </div>
    </div>
    <button class="btn btn-dark rounded-circle scrimmage-widget-fab">
        <span class="fab-stale-content">
            <img src="assets/trophy.svg" alt="open" width="40" height="40">
        </span>
        <span class="fab-active-content">
            <img src="assets/cross-icon.svg" alt="close" width="20" height="20">
        </span>
    </button>
</div>

There you go, all set! When you send us a rewardable event going forward, all you have to do is pass us the dataType, the thing to reward, and the userID, and we handle everything else.

Updated 3 months ago