Getting started

Integrate the SDK into an HTML5 game made with JavaScript. Steps 1 to 3 are required; the rest is optional. If you use an engine, see its page under Engines in the menu.

1. Load the SDK

In your index.html, before your game's code:

<script src="/sdk/v1/hg-sdk.js"></script>
<script src="game.js"></script>

2. Report when gameplay starts

HGSDK.gameplayStart();

From that moment on, touches and gestures belong to your game. Before that (in your menu), a swipe goes to another game.

Call it on the player's first tap, not when the game loads: calling it removes the cover.

3. Report when gameplay stops

HGSDK.gameplayStop();

Call it whenever gameplay stops: when the player loses, pauses or goes back to the menu. When they continue or play again, call gameplayStart() again. The time between the two is the real play time.

4. Send the score (optional)

HGSDK.sendScore(score);

If your game has a score, send it whenever you want: when the player loses, completes a level… If the player is signed in, the website keeps it as their high score when it beats the previous one, and shows it in your game's rankings. It doesn't stop gameplay. The score is a whole number from 0 to 10,000,000 (decimals are rounded down).

If your game has no score, don't call it: in the tester, tick “This game has no score”.

5. Ads (optional)

Your game never loads ads by itself: it asks the website with showAd, the website shows the ad on top and freezes your game meanwhile. Don't call gameplayStop() or gameplayStart() because of the ad, and don't stop its music: the website freezes and resumes your game on its own. reward returns a promise with { rewarded }; break returns nothing: your game continues on its own when the ad ends.

// between runs, never before the first one
if (runs > 0) HGSDK.showAd({ type: 'break' });
runs++;
startRun();

// the player chooses to watch one to revive
async function offerRevive() {
  const { rewarded } = await HGSDK.showAd({ type: 'reward' });
  if (rewarded) revive(); else gameOver();
}

Your game must work the same when no ad is shown, and a reward never gives score. A reward must always be optional: the player has to be able to keep playing and progress without watching any. All the rules are in the reference.

Full example

index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <style>html,body{margin:0;height:100%;overflow:hidden;background:#000}</style>
</head>
<body>
  <canvas id="c"></canvas>
  <script src="/sdk/v1/hg-sdk.js"></script>
  <script src="game.js"></script>
</body>
</html>

game.js: a tapping game that adds one point per tap for 10 seconds. Between runs it asks for a break, and when time runs out the player can choose to watch a reward to continue for 5 more seconds, once per run.

const canvas = document.getElementById('c');
const ctx = canvas.getContext('2d');
let state = 'menu', points = 0, timeLeft = 0, last = 0, runs = 0, continued = false;

function resize() { canvas.width = innerWidth; canvas.height = innerHeight; }
addEventListener('resize', resize);
resize();

canvas.addEventListener('pointerdown', (e) => {
  if (state === 'menu') startRun();
  else if (state === 'playing') points++;
  else if (state === 'offer') {
    // the player chooses: the top half watches the ad, the bottom half finishes
    if (e.clientY < canvas.height / 2) watchAdToContinue(); else endRun();
  }
});

function startRun() {
  if (runs > 0) HGSDK.showAd({ type: 'break' });   // between runs, never before the first one
  runs++;
  state = 'playing'; points = 0; timeLeft = 10; continued = false;
  HGSDK.gameplayStart();          // gameplay starts
}

async function watchAdToContinue() {
  state = 'ad';
  const { rewarded } = await HGSDK.showAd({ type: 'reward' });
  if (rewarded) { state = 'playing'; timeLeft = 5; continued = true; }
  else endRun();
}

function endRun() {
  state = 'menu';
  HGSDK.sendScore(points);        // optional: this game has a score
  HGSDK.gameplayStop();           // gameplay stops
}

function frame(t) {
  const dt = Math.min(0.05, (t - last) / 1000); last = t;
  if (state === 'playing') {
    timeLeft -= dt;
    if (timeLeft <= 0) {
      if (continued) endRun(); else state = 'offer';   // the ad to continue is offered only once per run
    }
  }
  ctx.fillStyle = '#111'; ctx.fillRect(0, 0, canvas.width, canvas.height);
  ctx.fillStyle = '#fff'; ctx.font = '32px sans-serif'; ctx.textAlign = 'center';
  if (state === 'playing') {
    ctx.fillText(`${points} · ${Math.ceil(timeLeft)}s`, canvas.width / 2, canvas.height / 2);
  } else if (state === 'offer' || state === 'ad') {
    ctx.fillText('▶ Watch an ad: +5 s', canvas.width / 2, canvas.height / 4);
    ctx.fillText('Finish', canvas.width / 2, canvas.height * 3 / 4);
  } else {
    // while waiting, keep something moving: it's the cover's background
    ctx.fillStyle = '#ffd23f'; ctx.beginPath();
    ctx.arc(canvas.width / 2, canvas.height / 2, 40 + Math.sin(t / 300) * 10, 0, Math.PI * 2); ctx.fill();
  }
  // no "TAP TO PLAY" of your own: the website shows the cover
  requestAnimationFrame(frame);     // the SDK freezes it on its own when pausing
}
requestAnimationFrame(frame);

Test it

Upload the game folder (or its .zip) in Upload game and tap 🧪 Test before submitting. More details in Test and publish.