Getting Started

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 Settings>Secret keys page and generate a new key. We recommend rotating your secret keys once every 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.

The secret key was generated in step 2 on your dashboard and the API_SERVER_ENDPOINT can be obtained from the URL of your admin dashboard. It will look something like "your_company_name.apps.scrimmage.co".

Use 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 does not doing anything magical, just replaces API calls with SDK calls.

npm install -s @scrimmage/rewards
yarn add @scrimmage/rewards
import Scrimmage from '@scrimmage/rewards'

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

🚧

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 for your users, instead we maintain an accurate state of a user's reward profile through an anonymous user ID that you send us for each user. We require you to authenticate a user every time the user accesses the reward widget or iframe.

**Authenticating a user is a 2 step process:

To generate login links for user authentication you will first call our API or use a typescript library to request a user TOKEN.

const TOKEN = Scrimmage.user.getUserToken(USER_ID)

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

https://<API_SERVER_ENDPOINT>?token=<TOKEN>

📘

Authenticating a user through API only

If you are only using Scrimmage's API solution and not our frontend, you will use this TOKEN in your API calls instead of passing it to the widget

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.

  1. Open Game Rules and click Create.
  1. Select data type for primary reward. betExecuted is selected on the screenshot below.
  1. Type the reward rule. For primary reward, you should only use .usdTakeIn field. On the screenshot you can see that we reward 1% of netProfit from betExecuted events.
  1. Provide name and save the 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>(
  {
    dataType: 'betExecuted',
    eventId: <string>data.id,
    userId: <string>uid,
    body: {
      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,
  	namespace: 'production'
  });

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.