Events

Pause and Resume Events

Using the game_api_pause and game_api_resume events, the platform informs the game to pause or resume the gameplay process. These events simplify the integration process with our platform and help comply with moderation requirements (points 1.3 and 4.7).

Games that support pause and resume events can be additionally distributed on external platforms.

game_api_pause and game_api_resume events

These events will help you track:

• displaying and closing of full-screen or rewarded ads;
• opening and closing of purchase windows;
• switching browser tabs;
• minimizing and maximizing the browser window.

They are aligned with the gameplay markup methods. When game_api_pause is triggered, the GameplayAPI.stop() method is called, and when game_api_resume is triggered, GameplayAPI.start() is executed.

If the game has already been stopped using the GameplayAPI.stop() method (for example, when the player opens a menu) and then the game_api_pause event occurs, the GameplayAPI.start() method will not be called upon the subsequent game_api_resume event. This allows preserving the current game state without disrupting the gameplay logic.

Use the on() and off() methods from the Yandex Games SDK to subscribe and unsubscribe from events accordingly.

Example

const pauseCallback = () => {
    pauseGame(); // Your function that stops the game loop and music.
    console.log('GAME PAUSED');
};

ysdk.on('game_api_pause', pauseCallback); // Subscribing to 'game_api_pause' events.
ysdk.off('game_api_pause', pauseCallback); // Unsubscribing from 'game_api_pause' events.

const resumeCallback = () => {
    resumeGame(); // Your function that resumes the game loop and music.
    console.log('GAME RESUMED');
};

ysdk.on('game_api_resume', resumeCallback ); // Subscribing to 'game_api_resume' events.
ysdk.off('game_api_resume', resumeCallback ); // Unsubscribing from 'game_api_resume' events.

Fullscreen ad on game startup

Unlike ad units triggered via ysdk.adv.showFullscreenAdv(), startup ads don't have direct callbacks. To handle them properly, track the game_api_pause and game_api_resume events:

1. When receiving game_api_pause, mute game audio and pause gameplay.
2. Wait for game_api_resume before resuming the game.

This is particularly important for games where audio and gameplay start immediately.

Startup ad handling example

let gameStarted = false;
let isPaused = false;

// Game initialization function.
function initGame() {
    // Subscribe to pause/resume events.
    ysdk.on('game_api_pause', handlePause);
    ysdk.on('game_api_resume', handleResume);

    // Check if we're not already paused.
    // If not, start the game immediately.
    if (!isPaused) {
        startGame();
    }
}

function handlePause() {
    isPaused = true;
    // Stop audio and gameplay.
    console.log('GAME PAUSED - waiting for resume');
}

function handleResume() {
    isPaused = false;

    // Start game if it wasn't launched yet.
    if (!gameStarted) {
        startGame();
    } else {
        // Resume audio and gameplay.
    }

    console.log('GAME RESUMED');
}

function startGame() {
    gameStarted = true;

    // Initialize audio.
    // Start game loop.
    console.log('GAME STARTED');
}

// Launch game initialization.
initGame();

Other events

You can also track additional events triggered by user interactions with the application.

enum ESdkEventName {
    EXIT = 'EXIT',
    HISTORY_BACK = 'HISTORY_BACK',
    ACCOUNT_SELECTION_DIALOG_OPENED = 'ACCOUNT_SELECTION_DIALOG_OPENED',
    ACCOUNT_SELECTION_DIALOG_CLOSED = 'ACCOUNT_SELECTION_DIALOG_CLOSED',
}

ysdk = {
    EVENTS: {
        EXIT: ESdkEventName.EXIT,
        HISTORY_BACK: ESdkEventName.HISTORY_BACK,
        ACCOUNT_SELECTION_DIALOG_OPENED: ESdkEventName.ACCOUNT_SELECTION_DIALOG_OPENED,
        ACCOUNT_SELECTION_DIALOG_CLOSED: ESdkEventName.ACCOUNT_SELECTION_DIALOG_CLOSED,
    },

    dispatchEvent(eventName: ESdkEventName, detail?: object): Promise<unknown> {},

    on(eventName: ESdkEventName, listener: Function): () => void {}
};

HISTORY_BACK event

To track clicks on the Back button, use the following method:

ysdk.on(ysdk.EVENTS.HISTORY_BACK, () => {
    // Showing the custom game dialog to the user with the options
    // to confirm exiting the game, going to the internal settings, store, and so on
});

EXIT event

If the user confirms exiting the game in the custom dialog box that pops up after clicking Back, the game must send an exit event. To do this, use the following method:

ysdk.dispatchEvent(ysdk.EVENTS.EXIT);

Game account selection dialog

The platform saves game progress for both authorized and unauthorized players. A user might start playing without authorization and later sign in to an account. In this case, they'll have two separate progress tracks — one linked to their account and another anonymous one. The platform will show a dialog where users can compare saves by playtime, last login date, and other parameters to choose which progress to keep.

If you frequently sync player data or store game progress on your own server, monitor progress changes after account selection in this dialog.

The SDK provides two events for this:

• ACCOUNT_SELECTION_DIALOG_OPENED — dialog opening.
• ACCOUNT_SELECTION_DIALOG_CLOSED — dialog closing.

When the dialog opens, you may pause regular player data sync. When it closes — return to the main menu or restart the game and re-fetch the player object.

Example

// Subscribe to account selection dialog opening.
ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_OPENED, () => {
    // Pause player data synchronization.
});

// Subscribe to account selection dialog closing.
ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_CLOSED, async () => {
    // Return to main menu or reload the page.
    // ...

    // Re-fetch player data.
    const player = await ysdk.getPlayer();
    const data = await player.getData();
});

If you are facing an issue or have a question regarding the use of Yandex Games SDK, please contact support: