HTML Challenge System

Vouchrs Challenge System allows you to create your own challenges that can be used to lock Gifts and Promotions. The goal of every Challenge is to reach a specific score. That score can be configured in the Vouchr Dashboard or set via the creator of the gift.

Import

Import the VouchrGameInterface by adding this line.

<script src="https://s3.amazonaws.com/vouchrgames-dev/VouchrGameInterface/lib/VouchrGameInterface.js"></script>

Using the VouchrGameInterface

Add the VouchrGameInterface

You need to create an instance of VouchrGameInterface in your game.

this.gameInterface = new VouchrGameInterface();

Initializing

While your html and assets are loading, a loading screen will be displayed. Once you finish downloading the necessary assets required for initializing the game, you need to inform the VouchrGameInterface and optionally pass in your desired game height and width.

this.gameInterface.loadComplete(width:number?, height:number?)

Start the game

Once you have called loadComplete Voucher will display a start game overlay and eventually startGame() will be called. In whatever class has access to the native layer you need to add the following functions that the VouchrGameInterface will call:

startGame() - This should start the game
restartGame(victory: boolean) - This should restart the game. If victory is false, then the user has not yet scored enough points to win. If victory is true, then the gift can already be claimed and the user is simply playing

Update the score

Whenever a user scores you must communicate this to the VouchrGameInterface by calling:

this.gameInterface.setScore(score:number)

The VouchrGameInterface will determine when the user has won and display a popup allowing the user to leave the game and claim their gift.

If your challenge has a game over state you can call:

this.gameInterface.gameOver(score:number)

The VouchrGameInterface will display either a win or a lose popup depending on if the score passed in is greater than or equal to the score required to win, which is on a per Voucher basis.

Build Your first Challenge

We will be building “Hit or Miss”, a game where users must hit a Button labeled “HIT” and avoid clicking a Button labeled “MISS”. When a user clicks “HIT” their score will be increased by one. If a user accidentally clicks “MISS” they lose and need to try again. Users win when they successfully click “HIT” x number of times where x comes from the gameConfig and is different per Voucher.

Base HTML

Here’s some HTML, it displays the score and two buttons.

<body style="background-color: lightcoral">
    <div style="padding: 50% 0; text-align: center">
        <div id="gameContent" style="display:none">
            <div>SCORE</div>
            <div id="score">0</div>
            <br><br><br>
            <button>HIT</button>
            or
            <button>MISS</button>
        </div>
    </div>
</body>

Add the VouchrGameInterface

First lets create a VouchrGameInterface and call loadComplete() once the html body is ready.

<script src="https://s3.amazonaws.com/vouchrgames-dev/VouchrGameInterface/lib/VouchrGameInterface.js"></script>
<script>
  function onLoad() {
      this.gameInterface = new VouchrGameInterface()
      this.gameInterface.loadComplete(600, 800)
  }
</script>
<body onload="onLoad()"...

Create required functions

The VouchrGameInterface requires two methods be implemented so let’s add those to our script section. When we start the game I want the gameContent do be visible and reset the score to zero.

  function startGame() {
      document.getElementById("score").textContent = 0
      document.getElementById("gameContent").style.display = "block"
  }
  function restartGame(hasAlreadyWon) {
      startGame()
  }

Add Game Logic

The final step is to increase the score when a user clicks the HIT and end the game if they click the MISS button.

  function hit() {
      var newScore = parseInt(document.getElementById("score").textContent) + 1;
      document.getElementById("score").textContent = newScore
      this.gameInterface.setScore(newScore)
  }

  function miss() {
      var currentScore = parseInt(document.getElementById("score").textContent);
      this.gameInterface.gameOver(currentScore)
  }

<body ... >
  ...
        <button onclick="hit()">HIT</button>
        or
        <button onclick="miss()">MISS</button>
  ...
</body>

Final Code

Putting that all together we should have a working challenge:

<!DOCTYPE html>
<html>

<head>
    <title>HIT or MISS</title>
    <script src="https://s3.amazonaws.com/vouchrgames-dev/VouchrGameInterface/lib/VouchrGameInterface.js"></script>
    <script>
        // Required function
        function startGame() {
            document.getElementById("score").textContent = 0
            document.getElementById("gameContent").style.display = "block"
        }

        // Required function
        function restartGame(hasAlreadyWon) {
            startGame()
        }

        function onLoad() {
            this.gameInterface = new VouchrGameInterface()
            this.gameInterface.loadComplete(600, 800)
        }

        function hit() {
            var newScore = parseInt(document.getElementById("score").textContent) + 1;
            document.getElementById("score").textContent = newScore
            this.gameInterface.setScore(newScore)
        }

        function miss() {
            var currentScore = parseInt(document.getElementById("score").textContent);
            this.gameInterface.gameOver(currentScore)
        }
    </script>
</head>

<body onload="onLoad()" style="background-color: lightcoral">
    <div style="padding: 50% 0; text-align: center">
        <div id="gameContent" style="display:none">
            <div>SCORE</div>
            <div id="score">0</div>
            <br><br><br>
            <button onclick="hit()">HIT</button>
            or
            <button onclick="miss()">MISS</button>
        </div>
    </div>
</body>

</html>

Next Steps

Get the score Optional

In your challenges you can request more information related to the gift and the claiming user. For example, to get the score needed to win:

this.gameInterface.requestGameConfig()
  .then(function (gameConfig) {
    gameConfig.scoreToWin // The score the user needs to win
  }

There’s more info you can use, see GameConfig Specs

API Reference

VouchrGameInterface Specs

requestGameConfig() : Promise<GameConfig> - This returns the configuration of the game. See GameConfig for format of configuration.
loadComplete(width:number?, height:number?) - You must call this when the game is finished loading all assets. Width and Height are optional.
setScore(score:number) - This updates the client with the latest score.
gameOver(score:number) - This should be called when the game is over. The vouchr client will show a win or lose popup, allowing the user to retry the game or claim their gift.

GameConfig Specs

class GameConfig {
    mode:GAME_MODE; // CLAIM, CHALLENGE, CLAIMED
    scoreToWin:number; // the score required to win the game
    friendImageUrl:string; // an image url of friend, optional
    gameScale:number = 1; // scale of game
    friendName:string = "Boxy"; //username of your friend
    rewardNoun:string = "gift"; //noun used to define the reward
}