Skip to content

Introduction

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 technical, gameplay, ads and account integration requirements.

Our HTML5 and Unity SDKs support all the scenarios. Other SDKs miss certain functionalities for which you can usually manage at least basic integration through the HTML5 version. Most game engines that support WebGL also have a way of interacting with JavaScript when running in browser.

The SDK has the following modules:

ad display video ads & detect adblockers 🟩 Fully supported
banner display banners 🟩 Fully supported
game various game events and integration 🟩 Fully supported
user interact with logged in user 🟩 Fully supported
data store user data that persists across devices 🟩 Fully supported
In-game Purchases handle in-game purchases (not a separate module) 🟩 Fully supported

ad display video ads & detect adblockers 🟩 Fully supported
banner display banners 🟩 Fully supported
game various game events and integration 🟩 Fully supported
user interact with logged in user 🟩 Fully supported
data store user data that persists across devices 🟩 Fully supported
In-game Purchases handle in-game purchases (not a separate module) 🟩 Fully supported

ad display video ads & detect adblockers 🟩 Fully supported
banner display banners 🟩 Fully supported
game various game events and integration 🟧 Basic support
user interact with logged in user 🟥 Not supported
data store user data that persists across devices 🟥 Not supported
In-game Purchases handle in-game purchases (not a separate module) 🟥 Not supported

ad display video ads & detect adblockers 🟩 Fully supported
banner display banners 🟩 Fully supported
game various game events and integration 🟩 Fully supported
user interact with logged in user 🟩 Fully supported
data store user data that persists across devices 🟩 Fully supported
In-game Purchases handle in-game purchases (not a separate module) 🟩 Fully supported

ad display video ads & detect adblockers 🟩 Fully supported
banner display banners 🟩 Fully supported
game various game events and integration 🟧 Basic support
user interact with logged in user 🟥 Not supported
data store user data that persists across devices 🟥 Not supported
In-game Purchases handle in-game purchases (not a separate module) 🟥 Not supported

ad display video ads & detect adblockers 🟩 Fully supported
banner display banners 🟥 Not supported
game various game events and integration 🟩 Fully supported
user interact with logged in user 🟩 Fully supported
data store user data that persists across devices 🟩 Fully supported
In-game Purchases handle in-game purchases (not a separate module) 🟩 Fully supported

Getting started

This section explains how to get the CrazyGames SDK up and running in your engine.

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 SDK relies on promises and doesn't accept a callback parameter. 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 HTML5 SDK docs will contain only examples using await.

Start by downloading the Unity SDK

Info

Before importing the SDK, we recommend that you delete the folders CrazySDK and CrazyOptimizer (if present).

The SDK is found in the CrazyGames namespace, which you will have to import at the start of your files:

using CrazyGames;

Before calling any SDK related functionality, please ensure that CrazySDK.IsAvailable is true. The CrazySDK is available on CrazyGames, when running in Editor, and when running on localhost.

The SDK will not be available when your game runs on any other platform (Android, iOS, etc). It will also not be available when running on a whitelisted domain (see Sitelock).

Initialization

Manual initialization

The SDK needs to be manually initialized like this:

CrazySDK.Init(() => { /** initialization finished callback */ });

Since the initialization is done asynchronously, please don't call any methods from the SDK until the callback provided to the Init is called.

To help you, we have created a demo loading scene, that you can modify or use as it is. When the game is running on CrazyGames the scene will init the SDK and wait for initialization and then continue to another scene. If your game is running on a whitelisted domain (see Sitelock), the initialization will be skipped, as the SDK is disabled there.

You can find the demo loading scene here:

Loading scene

Don't forget to drag it into the included scenes in the build as the first scene, and set the nextSceneName in CrazySDKLoadingScene object.

To get started, download the sample project. To avoid weird browser behaviour, right click the link, select Save link as.

Install the SDK by inserting a <script> tag into your game's index.html file. The easiest way to do this is to copy the HTML file that Game Maker outputs, modify it, and then include that copy as a custom HTML file.

  1. In Game Maker Studio 2, Compile your HTML build.
  2. Unzip the zip file that Game Maker creates for you.
  3. In the unzipped files, find index.html. It should be in the root.
  4. Make a copy of the index.html and move the copy to PROJECT_FOLDER/datafiles/ (where PROJECT_FOLDER is the root directory of your project). If your project does not have a /datafiles/ folder create it first.
  5. Open your newly copied /datafiles/index.html in a text editor.
  6. Insert the following somewhere in the <head>...</head> container: 
    <!-- CrazyGames -->
<script src="https://sdk.crazygames.com/crazygames-sdk-v1.js"></script>
  7. Save the changes you've made to PROJECT_FOLDER/datafiles/index.html.
  8. In Game Maker Studio 2, from the Asset Browser panel, open Quick Access > Game Options > HTML5. HTML5 Options
  9. Under General > Advanced where it says "Included file as index.html", change the dropdown selection from Use Default to index.html. If index.html does not appear in the list, close and reopen the Game Options > HTML5 dialog.
  10. Now your game will be using your custom index.html that contains the modifications.

Setting up banner containers

You can further customize index.html if you wish to display banner ads. You would create a <div> container for each banner ad, describe its size and placement using CSS, then show and hide them through GML code. Here is a basic example of having two banners in your game:

  1. Insert the following just before the closing </body> tag: 
    <div class="crazy_banner hidden" id="crazy_banner_1"></div>
<div class="crazy_banner hidden" id="crazy_banner_2"></div>
  2. The crazy_banner class is required. (Later on, we will import a JS extension that depends on this class name for querying all banner containers.)
  3. Insert the following, just before the closing </style> tag: 
    .crazy_banner {
    display: block;
    position: absolute;
    background: #00f; /* remove this line when you are done testing size and placement */
}
#crazy_banner_1 {
    top: 0;
    left: 0;
    width: 300px;
    height: 250px;
}
#crazy_banner_2 {
    top: 0;
    right: 0;
    width: 300px;
    height: 250px;
}
.crazy_banner.hidden {
    display: none;
}
  4. To preview their size and placement, remove the hidden class from the <div class="crazy_banner hidden"> containers (remember to add them back after). You can customize their size and placement by modifying the CSS as you wish.
  5. The IDs and their corresponding selectors can be renamed as you wish, but this guide will refer to them as crazy_banner_1 and crazy_banner_2.
  6. When you are done previewing size and placement, remove the background: #00F; declaration from the .crazy_banner selector, and add the hidden class back to your <div class="crazy_banner"> containers.
  7. Now that you've set up your containers, you can fill them with ads during gameplay using GML (covered later on).

Import the JS extension

Next, you'll need to import a JS extension so that you can call JS functions directly in your GML code.

  1. Download this sample project (right click the link, select Save link as) and double-click to open it. It should open automatically in Game Maker Studio 2.
  2. A save dialog will open. Select a temporary location, such as the root folder where you keep your game projects.
  3. In Game Maker Studio, in the Asset Browser panel:
    1. Right-click on any folder or asset.
    2. Click Add Existing. HTML5 Options
    3. Navigate to where you unzipped the sample project and find the /extensions/crazygames/ folder.
    4. Select (open) the yy file.
    5. The extension should now be installed in your game.

Receive and handle events

To respond to browser events directly in your game, you can use a callback function. Create a script resource, named, for example functions, to contain the following function template:

function gmcallback_crazy_callback( _event ){
    if ( _event == "crazy.break.started" ) {
    } else if ( _event == "crazy.break.error" ) {
    } else if ( _event == "crazy.break.finished" ) {
    } else if ( _event == "crazy.banner.rendered" ) {
    } else if ( _event == "crazy.banner.error" ) {
    } else if ( _event == "crazy.adblock.detected" ) {
    } else if ( _event == "crazy.sdk.initialized" ) {
    }
}

You would write your code to execute in the case of each event. Here is a full GameMaker example.

Note: The function name must be exactly gmcallback_crazy_callback for it to work.

All the functionality of our SDK is showcased in this demo project. To avoid weird browser behavior, right-click the link, and select Save link as.

Warning

The CrazyGames SDK is not working with Construct "Worker mode". "Worker mode" can be disabled by selecting your project in the "Project" panel, going to "Advanced", and setting "Use worker" to "No"

You will need to create a separate layout for loading and initializing the SDK. Our demo project contains an example layout called CrazySDKLoadingDemo. That layout should contain a System > On start of layout script with these contents:

// don't forget to set the name of the next layout
// that should be loaded after initialization
const nextLayoutName = "CrazySDKDemo";
const sdkElem = document.createElement("script");
sdkElem.type = "text/javascript";
sdkElem.src = "https://sdk.crazygames.com/Construct3CrazySDK-v3.js";
document.body.appendChild(sdkElem);
sdkElem.onload = function () {
    window.ConstructCrazySDK.init()
        .then(() => {
            runtime.goToLayout(nextLayoutName);
        })
        .catch((e) => console.log("Failed to init CrazySDK", e));
};
sdkElem.onerror = function () {
    console.error("Failed to load Construct3CrazySDK script.");
};

The script will load our SDK, initialize it, and continue to nextLayoutName.

The SDK functionality is implemented in JavaScript, so to call various features from the SDK, you will need to add scripts to your event sheets. When right-clicking on your events, you will get an "Add script" option, which will add a small text editor where you can write the code.

  1. Create a new project, or add the SDK to your existing project.
  2. Under Project/Export, add a new HTML5 export preset, and rename it to CrazyGames.
  3. On the Options tab, add the following in the Head Include field: 
    <script src="https://sdk.crazygames.com/crazygames-sdk-v2.js"></script>
    Export preset
  4. On the Features tab, add a custom feature "crazygames". This allows you to check in your code whether the build is running in the CrazyGames export. Custom feature
  5. Create a new script "CrazySDK.gd" extending the Node class for wrapping the SDK. Go to Project/Project Settings and open the Autoload tab. Add the new script here. It is now registered as an Autoload singleton that is instantiated when booting up the game. Autoload
  6. Within CrazySDK.gd, define a global scope variable to store the SDK: 
    var SDK = null
  7. In the _ready function, check whether the game is running in the dedicated preset, and return if this is not the case: 
    func _ready() -> void:
    if not OS.has_feature("crazygames"): return
  8. Via the JavaScript singleton, access the window, and from it, the SDK. 
    var window = JavaScript.get_interface("window")
SDK = window.CrazyGames.SDK

Download the Cocos SDK.

Right-click on the assets folder in the Assets panel and select Import Asset Package.

Import step 1

Be sure all the files are selected and click Import.

Import step 2

You can now open the CrazySDK/CrazySDKDemo scene to view the functionality of the SDK.

Demo scene

To use the SDK, import it into your files:

import CrazySDK from "./CrazySDK";

Before using the SDK, please ensure the current platform is supported:

CrazySDK.isSupportedPlatform;

The supported platforms are the mobile and desktop browsers.

Initialization

Manual initialization

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

await CrazySDK.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.

To help you, we also created a demo loading scene, called CrazySDKDemoLoadScene. Ensure this is the first scene loaded in your game, and also provide a next scene name to the script. It will wait for the SDK initialization, and then redirect to the next scene.

Demo load scene

Important information

Don't miss this section with important information regarding your engine

Major changes when migrating from v2 to v3

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

  • The SDK requires to be manually initialized now.
  • Some async get methods are now simple variables:
    • window.CrazyGames.SDK.environment
    • window.CrazyGames.SDK.user.isUserAccountAvailable
    • window.CrazyGames.SDK.user.systemInfo

  • 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'}

Optimization

Optimization is important for launching succesful games on the web:

  • We suggest that you read the following Unity WebGL export tips. They may help you to reduce the final build size and increase the performance of your game, thus increasing your revenue.
  • Furthermore, you can also have a look at the WebGL Optimizer utility that the CrazySDK provides by default.
  • CrazyGames supports only compressed builds (either Brotli or Gzip). This means that the development builds won't run on CrazyGames or our QA Tool, since they are not compressed.

Sitelock

Sitelocking is done automatically on game start. It allows your game to run only on CrazyGames.com and our affiliated sites. This ensures that your game cannot be stolen and hosted on other domains, so you do not lose any revenue. By default, the sitelock will also block the game on your domain. To avoid this, you should add your domain to the list of whitelisted domains in the CrazySDK settings. You can find the settings in CrazySDK/Resources/CrazyGamesSettings.

Info

When reimporting the SDK, Unity resets these settings.

Whitelist domain

A sitelock is a mechanism that deters third parties from stealing and reuploading your game to other websites and monetizing it without your permission. We currently do not have a sitelock for GML games, but what you can do is write some code that prevents your game from loading if it detects that it is hosted on a domain that is not approved.

Include the following code as early as possible in your game.

domain = url_get_domain();
if (
    !debug_mode &&
    string_pos( ".crazygames.", domain ) == 0 &&
    string_pos( ".1001juegos.com", domain ) == 0
){
    game_end();
}

When testing your game, remember to use debug mode to bypass your sitelock.

Note: string_pos() returns the position where a substring is found. It treats the first position as 1 and returns 0 if the string is not found.

Alternatively, instead of simply calling game_end(), if you like, you can display some instructions to the player to help them find your game. But that is up to you.

User Info

The extension will return a userInfo object via the "crazy.sdk.initialized" event. Game Maker Studio will convert it into a struct, and you can access its variables to customize your game. Here is a sample of its contents:

userInfo: {
    countryCode: "FR", // ISO 3166-1 alpha-2 country code

    // For browser and os, format is the same as https://github.com/faisalman/ua-parser-js
    browser: {
        name: "Chrome",
        version: "87.0.4280.141"
    },
    os: {
        name: "Windows",
        version: "10"
    },
    device: {
        type: "desktop" // possible values: "desktop", "tablet", "mobile"
    }
}

Refer to the gmcallback_crazy_callback() function in the GameMaker example, in particular, the code that runs if _event == "crazy.sdk.initialized". In the example, it is stored in a variable global.user_info. So for example, you could access the browser value by referencing global.user_info.browser.

Looking for the old Construct 3 SDKs?

Godot 4

Godot 4 can be used if you build a single threaded version of your game. Be careful as you might encounter audio issues and callbacks are slightly different.

#godot 3
var adStartedCallback = JavaScript.create_callback(self, "adStarted")
var adErrorCallback = JavaScript.create_callback(self, "adError")
var adFinishedCallback = JavaScript.create_callback(self, "adFinished")

#godot 4
var adStartedCallback = JavaScript.create_callback(adStarted)
var adErrorCallback = JavaScript.create_callback(adError)
var adFinishedCallback = JavaScript.create_callback(adFinished)

No important information for Cocos.

Development & Testing

During the development, you will be running your game on different domains/environments:

  • localhost - our SDKs work fine on localhost domains, where they display demo ads/banners and try to simulate other behaviour.
  • editors - this applies to Unity, Construct, Cocos, etc. In editors our SDKs will also display demo ads/banners and try to simulate other behaviour.
  • QA Tool - our QA tool offers the most realistic version of CrazyGames.com. After you've finished integrating the SDK, create a new game on Developer Portal, upload your files, and you will be able to access the QA tool. Obtaining a working Xsolla token is possible only here.
  • 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 test the SDK in the editor and by building and running your game on localhost. When testing the project locally, please ensure that it runs on localhost or 127.0.0.1, otherwise the sitelock will block it.

You can test your game at any time in Game Maker's debug mode.

You can test the SDK with Construct preview, or by building and running the game locally.

To test the SDK, export your project using the CrazyGames preset under Project/Export/Export Project. Rename the HTML file to index.html, and then use the QA Tool.

Alternatively, you can test locally using the HTML5 debug button in the top right of the editor. You may need to temporalily modify the head include to:

<script crossorigin="anonymous" src="https://sdk.crazygames.com/crazygames-sdk-v2.js"></script>

On localhost or 127.0.0.1 the SDK starts into local mode. This will do the following things:

  • The calls to request rewarded and midgame videos will display an overlay text.
  • SDK console logging will be enabled.
  • Requesting user data will return some demo date.
  • Only demo banners will be displayed.

If you want to enforce the local mode on other domain/ip, you can do it by appending the ?useLocalSdk=true query parameter to the URL in your browser.

On CrazyGames domains, the SDK will work as expected.

On any other domains the SDK is disabled. This means all the method calls to the SDK will throw errors about the SDK beeing disabled. To prevent this, we recommend that you check if the SDK environment is not disabled before calling any functionality:

CrazySDK.environment;