GETTING STARTED


This API documentation is basically designed for game developers who'd like to develop web based games for Triangool. We primarily prefer HTML5/Javascript based games that is highly comptible with modern browsers.

To join the developer program, a developer must meet all of the requirements stated below:


  • Create or use an already existing user account on this platform
  • Sign Up for the Developer Program by clicking on the appropriate link
  • Each Developer is provided a unique string of characters referred to as the Developer Key . This key provides exclusive access to requests you might need to make via the API
  • Design the HTML5/Javascript Games, zip the folder where the files are located and upload via your dashboard.
  • Uploaded games will go through a verification process where the system will test and determine if the game meets the standards, terms and policy of TRIANGOOL. This process usually takes between 6-24 hours to complete.
  • If there are issues with your upload, you will be contacted via mail else your game will be approved


Staking and playing of games happens in two (2) major categories highlighted below:

One-on-One Contest: When two users are scheduled to compete against each other, the player with the highest score wins. If the outcome is a stalemate, they both split the sum of what was left after the service fee has been removed.

General Contest: This is a pool where contestants numbering from 2 and above play and contest on a game. Winners are determined by a standard chart that selects how many players will be winners based on the total number of contestants.

For every time your game is played in a competitive/contest mode , you earn 10% of the total stakes for that game.

Take for instance, if your game is competitively played between 2000 contestants who each place a stake of NGN 100. At the end of the contest period, the 10% (NGN 20,000) of the total stakes (NGN 200, 000) is credited into your developer wallet. This amount in your developer wallet can always be cashed out whenever you decide to.

This therefore implies that the more users compete on your game,the more you earn.

You are free to design your game as it seems best using industry standards. But here are some tips to enable a smooth run of your game on our platform

  1. All games are hosted on our platform. Our platform is backed up with modern ZFS storage mechanisms and high-grade SSDs instead of the regular HDDs
  2. SYNTAX — Declare your web application/game as HTML5 using the using the standard markup
                
                   <!DOCTYPE html>
                 
                
  3. GAME FILES  — Your game is expected to contain an index.html, preview.html and play.html files

    It is highly important you understand the workings and functionalities of these files.

    Fig 1:1 A typical example of a simple HTML5 game folder

    INDEX.HTML: This is the landing page for the game. When users click on your game from any section of the site, they are directed to this page. Creatively design this index page as you wish. This is usually the first point of contact users might see. You should also place detailed description of the game as well as instructions on this page

    PREVIEW.HTML: This is a demo version of your game. No scores are recorded. The users are allowed to preview and play this game as many times as they want. It could help build up interest as well as the confidence to stake their money and compete against other contestants.

    PLAY.HTML: This is the most imprtant section of your game file. Also, this is the page where you should use and make requests for the TRIANGOOL API. Only games played via this mode is recorded.

    Please Note:
    Do not place a link directly to this page from your index or preview page.
    Users who have booked and are scheduled to play this game will only be able to access and use this game from their account panel.
    Our URL routing system has been designed in such a way that it leads users to this page when they are ready to competitively play this game

  4. ON PAGE LOAD When users are directed to PLAY.HTML, it is always advisable you place an overlay banner that prevents the Player from taking any action until the api has been fully loaded and all the methods necessary to validate this user are available.
    When fully loaded, you should authenticate this user and display error messages on this overlay banner if any. If the user was fully authenticated and no issue, you can then remove this overlay and let the user play the game
  5. API LOAD We always recommend placing a link to this API at the bottom of your PLAY.HTML page just before the closing body tag.
              
                <script src="https://api.triangool.com/js/v.2.1.js"></script>
            
            
  6. API CALL The next step is to call this API by creating an instance of our triangool object. The calling of this object should come immediately after the line for the API LOAD.
              
            <script>
              var response = new triangool(TYPE_OF_REQUEST, DEVELOPER_KEY, CALLBACK_FUNCTION);
            </script>
            
            
    Calling the API accepts three (3) parameters.
    The first paramter expects a string which is to be the type of request you are making. For now, the value of this will be fixture
    The second parameter expects a string of your Developer Key. You can always find this on your Developer Panel
    The third parameter expects a call back function that should be fired up as soon as the api is done loading. This call back function could be a custom method where you use the API methods to verify the status of the user as well as other relevant information.

    It is Okay if you choose to place the code for creating the instance in an external sheet or if you rather choose to place it directly within the play.html page. No matter the pattern you choose, always ensure it comes after the API LOAD.

  7. SUBMITTING THE SCORES Definitely, while programming your game, there should be a method or class that is fired up when the user looses or is done playing a game... And yes, that is all you need.
    When that occurs, simply call back that modal overlay that prevents the user from taking any further action while you submit. To submit this score, call the submitScores() method from the API. This method accepts two parameters, the score and the element ID of the modal element. The reason for this second parameter is to ensure the API returns an error message peradventure there was an error during submission.

    If no error was encountered during submission, the API will automatically redirect the user to a special page.
              
            <script>
            /*
            ** The moment the user looses, 
            ** The submiScore API should be called
            ** Assuming the user scored 1000 points
            ** Also, assuming the element ID of my overlay banner where errors should be displayed (if any) is overlay-content
            ** Remember the handle for the object response we created initially was response
            ** As such, we keep using this handle to call all methods within the class 
            */ 
              response.submitScores(1000, "overlay-content");
            </script>
            
            

There are basically two methods that should be checked before pulling out any other information about the user. They are:

  1. devAuth() : This method checks if the developer key provided was successfully authenticated. Possible return values from this method are

    300 : No developer key was found

    301 : This developer key is invalid

    500 : Developer key is correct and accepted

  2. playerAuth() : This method checks the status of the player currently within the PLAY.HTML page. Possible return values from this method are

    400 : No session was found for the player. He needs to be logged in

    401 : There is a logged in session but the player no longer exists as a member on the platform

    402 : No pending fixture was found for this player on this game

    403 : This player has already played and completed this fixture

    404 : No permission was granted to play this game. The player needs to return to his/her account panel and re-click to play this fixture

    500 : The player is fully authenticated and permitted to play

PLEASE NOTE
The followig methods will become readily available and will contain real values ONLY IF devAuth() and playerAuth() both have a value of 500

METHODS Return
playerUsername() Provides the username of the player
fixtureKey() A string unique for each fixture either as a general-contest or as a one-on-one contest
playingAs() Either as player1 or as player2. For a general-contest, all players within that fixture will usually have the player1 tag
gameKey() A string unique for each uploaded game
fixtureType() Either a general-contest or a one-on-one contest

submitScore():
This is the special method you call to submit scores when the player looses or is done playing the contest.
This method accepts two (2) parameters, the only method that receives custom parameters.

The first parameter should be the score/points of the player, the second parameter should be the ID of an element that the API should output an error message if there is an error with submission.

If no error during submission of scores, the API will mark the fixture as played for that player and re-directs the player to a special page

So far so good, here is a practical example
       
      <!DOCTYPE > 
      <html>
      <head>
      <meta charset="UTF-8" />
      <title>My Amazing Game - Triangool </title>
      <link type="text/css" rel="stylesheet" href="style.css"/> 
      <!-- My main stylesheet  -->
      </head>
      <body>
      <!-- If you wish to inform the user he/she is in contest mode -->
      <div class="top-sticker">
      <h5> CONTEST MODE</h5>
      <p id="player-info"></p>
      </div>
      
      <!-- The canvas or div that holds your amazing game -->
      <div id="gameContainer" class="gameContainer"></div>

      <!-- 
      /* This is just a modal overlay you can style to stop the player from taking any action. 
      /* On page load, by default the user shouldnt  be able to do anything. 
      /* If there is an error during authentication, inform the user and possibly redirect 
      /* Else, clear the modal overlay and let the games begin
      -->
      <div class="overlay-banner" id="overlay-banner">
      <div class="overlay-content" id="overlay-content">
      <h4> Authenticating... </h4>
      <span>please wait </span>
      </div>
      </div>
      
      <!-- script that controls your game -->
      <script src="js/game.js"></script> 
      
      <!-- LOAD THE API -->
      <script src="https://api.triangool.com/requests/js/v2.1.js"></script>

      <!-- MY CUSTOM FUNCTION -->>
      <script src="js/custom.js"></script>

      <!-- CALL THE API -->
      <script>
      var response = new triangool("fixture", "gshgsjvkusv3373", authenticate);
      </script>
      </body>
      </html> 
      
      

Sample of PLAY.HTML


       
       <!-- 
       /** Okay, so here is my custom js script 
       /** This is where I do the actual validation and use the API methods 
      -->
      <script>
      function authenticate() {
      var devAuth = response.devAuth();
      var playerAuth = response.playerAuth();
      var elemOverlay = document.getElementById("overlay-banner");
      var elemContent = document.getElementById("overlay-content");
      if (devAuth !== 500 ) {
      elemContent.innerHTML = 'Developer Authentication failed! This process cannot continue';
      }
      else if (playerAuth !== 500) {
      if (playerAuth === 400) {
      elemContent.innerHTML = 'User Authentication failed! User needs to be logged in';
      }
      else if (playerAuth === 401) {
      elemContent.innerHTML = 'User Authentication failed! No user with this logged in details was found';
      }
      else if (playerAuth === 402) {
      elemContent.innerHTML = 'User Authentication failed!  No pending booking was found for this game';
      }
      else if (playerAuth === 403) {
      elemContent.innerHTML = 'User Authentication failed! Our record shows you have already your fixture for this game';
      }
      }
      else {
      var pDe = document.getElementById("player-info");
      var playerUsername = response.playerUsername(); 
      pDe.innerHTML = playerUsername+' ₦ '+response.fixtureStake()+')';
      elemOverlay.style.display = "none";
                        
      /*	
      /** The moment all is set and done, call the MAIN method that controls your game. 
      /** In this game, mine is called runGame
      */
          runGame(); 
      };
      </script>
      
      

Sample code for user authentication before playing a contest