События

Пауза и возобновление игры

С помощью событий game_api_pause и game_api_resume платформа сообщает игре, что нужно поставить игровой процесс на паузу или возобновить его. Они упрощают процесс интеграции с нашей платформой и помогают соответствовать требованиям модерации (пункты 1.3 и 4.7).

Игры, которые поддерживают события паузы и возобновления игры, могут быть дополнительно дистрибутированы на внешние площадки.

game_api_pause и game_api_resume

События помогут вам отследить:

• показ и закрытие полноэкранной или rewarded-рекламы;
• открытие и закрытие окна покупок;
• переключение вкладок браузера;
• сворачивание и разворачивание окна браузера.

Они согласованы с методами разметки геймплея. При срабатывании game_api_pause вызывается метод GameplayAPI.stop(), а при срабатывании game_api_resume – GameplayAPI.start().

Если игра уже была остановлена с помощью метода GameplayAPI.stop() (например, когда игрок открыл меню), и затем срабатывает game_api_pause, то при последующем событии game_api_resume метод GameplayAPI.start() не будет вызван. Это позволяет сохранить текущее состояние игры без нарушения логики разметки геймплея.

Используйте методы on() и off() из SDK Яндекс Игр для подписки на события и отписки от них соответственно.

Пример

const pauseCallback = () => {
    pauseGame(); // Ваша функция, останавливающая игровой цикл и музыку.
    console.log('GAME PAUSED');
};

ysdk.on('game_api_pause', pauseCallback); // Подписка на события 'game_api_pause'.
ysdk.off('game_api_pause', pauseCallback); // Отписка от событий 'game_api_pause'.

const resumeCallback = () => {
    resumeGame(); // Ваша функция, возобновляющая игровой цикл и музыку.
    console.log('GAME RESUMED');
};

ysdk.on('game_api_resume', resumeCallback); // Подписка на события 'game_api_resume'.
ysdk.off('game_api_resume', resumeCallback); // Отписка от событий 'game_api_resume'.

Полноэкранная реклама на старте игры

В отличие от рекламных блоков, которые игры вызывают через ysdk.adv.showFullscreenAdv(), у стартовой рекламы нет прямых callback-функций. Чтобы правильно обрабатывать ее показ, отслеживайте события game_api_pause и game_api_resume:

1. При получении game_api_pause выключите звук игры и поставьте геймплей на паузу.
2. Дождитесь события game_api_resume и возобновите игру.

Это особенно важно для игр, в которых звук и геймплей запускаются сразу.

Пример обработки стартовой рекламы

let gameStarted = false;
let isPaused = false;

// Функция инициализации игры.
function initGame() {
    // Подписываемся на события паузы и возобновления.
    ysdk.on('game_api_pause', handlePause);
    ysdk.on('game_api_resume', handleResume);

    // Проверяем, не находимся ли мы в состоянии паузы.
    // Если да, то ждем resume перед началом игры.
    if (!isPaused) {
        startGame();
    }
}

function handlePause() {
    isPaused = true;
    // Останавливаем звук и геймплей.
    console.log('GAME PAUSED - waiting for resume');
}

function handleResume() {
    isPaused = false;

    // Если игра еще не запущена, запускаем ее.
    if (!gameStarted) {
        startGame();
    } else {
        // Возобновляем звук и геймплей.
    }

    console.log('GAME RESUMED');
}

function startGame() {
    gameStarted = true;

    // Инициализация звука.
    // Запуск игрового цикла.
    console.log('GAME STARTED');
}

// Запускаем инициализацию игры.
initGame();

Прочие события

Вы также можете отслеживать другие события, возникающие при взаимодействии пользователя с приложением.

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

Чтобы отследить нажатие на кнопку Back, используйте метод:

ysdk.on(ysdk.EVENTS.HISTORY_BACK, () => {
    // Показ пользователю кастомного диалога игры с возможностью
    // подтвердить выход из игры, перейти к внутренним настройкам, магазину и т. п.
});

EXIT

Если пользователь подтвердил выход из игры в кастомном диалоге, открывшемся после нажатия Back, то игра должна отправить событие выхода. Для этого используйте метод:

ysdk.dispatchEvent(ysdk.EVENTS.EXIT);

Диалог выбора игрового аккаунта

Платформа сохраняет игровой прогресс как авторизованных, так и неавторизованных игроков. Пользователь может сначала поиграть без авторизации, а затем войти в аккаунт. В этом случае у него будет два разных прогресса: один под логином, другой — без него. Платформа покажет диалоговое окно, в котором пользователь сможет сравнить сохранения по длительности игры, дате последнего входа и другим параметрам и выбрать, какой прогресс использовать.

Если вы часто синхронизируете данные игрока или храните игровой прогресс на своем сервере, отслеживайте смену прогресса после выбора аккаунта в диалоговом окне.

В SDK для этого есть два события:

• ACCOUNT_SELECTION_DIALOG_OPENED — открытие диалога.
• ACCOUNT_SELECTION_DIALOG_CLOSED — закрытие диалога.

При открытии диалога можно приостановить регулярную синхронизацию данных игрока. При закрытии — выйти в главное меню или перезапустить игру и заново запросить объект игрока.

Пример

// Подписка на событие открытия диалога выбора аккаунта.
ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_OPENED, () => {
    // Приостанавливаем синхронизацию данных игрока.
});

// Подписка на событие закрытия диалога выбора аккаунта.
ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_CLOSED, async () => {
    // Выходим в главное меню игры или перезагружаем страницу.
    // ...

    // Перезапрашиваем данные игрока.
    const player = await ysdk.getPlayer();
    const data = await player.getData();
});

Если при использовании SDK Яндекс Игр вы столкнулись с проблемой или у вас появился вопрос, обратитесь в службу поддержки: