Skip to content

HTML5 v3 SDK

Requirements

When integrating the CrazyGames SDK, make sure to follow our requirements. They will help you use the SDK in the best way possible and guide you in terms of ad placements and account integration.

Installation

You can install the SDK by including the following script in the head of your game's index.html:

<script src="https://sdk.crazygames.com/crazygames-sdk-v3.js"></script>

Manual initialization

The v3 SDK requires initialization before being used. This can be done by calling the init method:

await window.CrazyGames.SDK.init();

It is important to await for the initialization since it happens asynchronously, and the SDK is unusable until initialized. We recommend that you do this before the game starts, for example on the loading screen.

Promises

The new SDK relies on promises and doesn't accept a callback parameter anymore. If you don't have the possibility to use await, you can call the async methods with .then(...).catch(...), like in the example below:

// await example
try {
    const user = await window.CrazyGames.SDK.user.getUser();
    console.log(user);
} catch (e) {
    console.log("Get user error: ", e);
}

// .then .catch example
window.CrazyGames.SDK.user
    .getUser()
    .then((user) => console.log(user))
    .catch((e) => console.log("Get user error: ", e));

The docs will contain only examples using await.

Development

Your game runs on different domains during development/release, which the SDK considers to be different environments.

  • The localhost and 127.0.0.1 domains are considered local environments. Advertisements are not available. Instead, an overlay text will be displayed. For other events such as happy time, gameplay start, etc. the console output can be consulted. If you are using a different domain/ip for local development, you can always enforce the local environment by appending the ?useLocalSdk=true query parameter to the URL in your browser.
  • On CrazyGames domains the SDK has the crazygames environment, where it functions properly.
  • On any other domains (including your domain on which you may host your game) the SDK has the disabled environment. All the calls to the SDK methods will throw an error. To prevent this, we recommend checking on which environment the SDK is running and avoiding making use of it outside local or crazygames environments.

The environment can be retrieved like this:

window.CrazyGames.SDK.environment;

You can check if the game is running in QA Tool like this:

window.CrazyGames.SDK.isQaTool;

Modules

The SDK has the following modules:

  • ad - display video ads, detect adblockers
  • banner - display banners
  • game - various game events
  • user - for interacting with the currently logged in user
  • data - new module in v3, that allows you to store user data that persists across devices

Each one of these modules can be accessed as follows:

window.CrazyGames.SDK.[moduleName], for example, window.CrazyGames.SDK.ad.

Other

Disable unwanted page scroll

By default, browsers scroll the page when a user presses the spacebar or the arrow keys. Your game should prevent this behavior. You might not notice it in development because your game is taking on the full height of the window. But when your game is embedded on CrazyGames, you’ll need to prevent scroll. You can do so by adding the following code to your game:

window.addEventListener("wheel", (event) => event.preventDefault(), {
    passive: false,
});

window.addEventListener("keydown", (event) => {
    if (["ArrowUp", "ArrowDown", " "].includes(event.key)) {
        event.preventDefault();
    }
});

Sitelock

We currently do not have a sitelock for plain Javascript games but do recommend building in some protections to avoid your game files getting stolen. Check the sitelock page for more info.

Migration from HTML5 v2 SDK

You can find the docs for the old HTML5 v2 SDK here.

Init

The SDK requires to be manually initialized now.

Some methods are now variables

Some async get methods are now simple variables:

  • window.CrazyGames.SDK.environment
  • window.CrazyGames.SDK.user.isUserAccountAvailable
  • window.CrazyGames.SDK.user.systemInfo

Better error handling

The v2 SDK was throwing inconsistent errors (strings or objects). The v3 SDK has now the following error format:

// there is always a "code" and a "message" containing more information
{code: 'userAlreadySignedIn', message: 'The user is already signed in'}

These errors can be caught by using try/catch with await, or .catch()