Function reference

Everything the HGSDK object offers. The SDK creates it as soon as it loads, before your game's code runs.

Lifecycle of a game

• If your game has a pause menu or goes back to a menu: gameplayStop() when gameplay stops and gameplayStart() when it continues.
• If your game has a score, send it whenever you want with sendScore(score): when losing, completing a level… It doesn't stop gameplay.

Gameplay

Ads

Your game never loads ads by itself: it asks the website with HGSDK.showAd({ type }) and the website shows the ad on top of the game, frozen and muted meanwhile. reward returns a promise with { rewarded }. If you don't use promises, pass a function as second argument: it's called when the ad ends and receives that same { rewarded }. break returns nothing: your game continues on its own when the ad ends.

// one revive per run, only if the player asks for it
// option 1: with a promise
async function offerRevive() {
  const { rewarded } = await HGSDK.showAd({ type: 'reward', name: 'revive' });
  if (rewarded) revive(); else gameOver();
}

// option 2: with a function as second argument
function offerRevive() {
  HGSDK.showAd({ type: 'reward', name: 'revive' }, function (r) {
    if (r.rewarded) revive(); else gameOver();
  });
}

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

• Your game must work without ads. rewarded can be false at any moment: no ad available, ads switched off or the player closed it early. Never leave the player waiting.
• Don't call gameplayStop() or gameplayStart() because of an ad: the SDK freezes and resumes your game on its own. Call them only when the run really stops (losing, pause, menu) and when it continues. If your game does it, it's rejected until you fix it.
• The website decides how often. It shares a single counter between the feed and all the games, so breaks never come one after another. Ask whenever it makes sense in your game: if it's too soon, simply no ad is shown. This only applies to break: a reward is shown whenever the player asks for it.
• A reward never gives score or anything that ends up in the rankings directly. Revives, continues, extra lives or skins are fine.
• Ask for break ads at natural moments — losing or finishing a level — never in the middle of the action, and not in the player's first run (the website doesn't know which run it is: that part is up to your game).
• name is optional: a short label (up to 40 characters). In JavaScript you don't need it, each call gets its own answer; in GameMaker it comes back in the result to tell your rewards apart.
• One ad at a time. If you ask for a reward while another ad is on screen, it answers rewarded: false straight away.

Several rewards

Your game can have as many rewards as it needs (revive, double the coins, a skin…). Give each one its own name: a short label (up to 40 characters) that says which reward it is. In JavaScript, each showAd call receives its own answer, so each reward handles its own result:

// when they ask to revive
async function offerRevive() {
  const { rewarded } = await HGSDK.showAd({ type: 'reward', name: 'revive' });
  if (rewarded) revive(); else gameOver();
}

// at another moment: to double their coins
async function offerDoubleCoins() {
  const { rewarded } = await HGSDK.showAd({ type: 'reward', name: 'double_coins' });
  if (rewarded) coins *= 2;
}

Version

HGSDK.version is the version of the SDK that's loaded, for example "1.8.7" (read only). You don't need it to integrate your game.