События

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

С помощью событий 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 Яндекс Игр для подписки на события и отписки от них соответственно.

Пример

1const pauseCallback = () => {
2    pauseGame(); // Ваша функция, останавливающая игровой цикл и музыку.
3    console.log('GAME PAUSED');
4};
5
6ysdk.on('game_api_pause', pauseCallback); // Подписка на события 'game_api_pause'.
7ysdk.off('game_api_pause', pauseCallback); // Отписка от событий 'game_api_pause'.

1const resumeCallback = () => {
2    resumeGame(); // Ваша функция, возобновляющая игровой цикл и музыку.
3    console.log('GAME RESUMED');
4};
5
6ysdk.on('game_api_resume', resumeCallback); // Подписка на события 'game_api_resume'.
7ysdk.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 и возобновите игру.

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

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

 1let gameStarted = false;
 2let isPaused = false;
 3
 4// Функция инициализации игры.
 5function initGame() {
 6    // Подписываемся на события паузы и возобновления.
 7    ysdk.on('game_api_pause', handlePause);
 8    ysdk.on('game_api_resume', handleResume);
 9
10    // Проверяем, не находимся ли мы в состоянии паузы.
11    // Если да, то ждем resume перед началом игры.
12    if (!isPaused) {
13        startGame();
14    }
15}
16
17function handlePause() {
18    isPaused = true;
19    // Останавливаем звук и геймплей.
20    console.log('GAME PAUSED - waiting for resume');
21}
22
23function handleResume() {
24    isPaused = false;
25
26    // Если игра еще не запущена, запускаем ее.
27    if (!gameStarted) {
28        startGame();
29    } else {
30        // Возобновляем звук и геймплей.
31    }
32
33    console.log('GAME RESUMED');
34}
35
36function startGame() {
37    gameStarted = true;
38
39    // Инициализация звука.
40    // Запуск игрового цикла.
41    console.log('GAME STARTED');
42}
43
44// Запускаем инициализацию игры.
45initGame();

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

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

 1enum ESdkEventName {
 2    EXIT = 'EXIT',
 3    HISTORY_BACK = 'HISTORY_BACK',
 4    ACCOUNT_SELECTION_DIALOG_OPENED = 'ACCOUNT_SELECTION_DIALOG_OPENED',
 5    ACCOUNT_SELECTION_DIALOG_CLOSED = 'ACCOUNT_SELECTION_DIALOG_CLOSED',
 6}
 7
 8ysdk = {
 9    EVENTS: {
10        EXIT: ESdkEventName.EXIT,
11        HISTORY_BACK: ESdkEventName.HISTORY_BACK,
12        ACCOUNT_SELECTION_DIALOG_OPENED: ESdkEventName.ACCOUNT_SELECTION_DIALOG_OPENED,
13        ACCOUNT_SELECTION_DIALOG_CLOSED: ESdkEventName.ACCOUNT_SELECTION_DIALOG_CLOSED,
14    },
15
16    dispatchEvent(eventName: ESdkEventName, detail?: object): Promise<unknown> {},
17
18    on(eventName: ESdkEventName, listener: Function): () => void {}
19};

HISTORY_BACK

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

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

EXIT

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

ysdk.dispatchEvent(ysdk.EVENTS.EXIT);

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

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

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

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

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

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

Пример

 1// Подписка на событие открытия диалога выбора аккаунта.
 2ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_OPENED, () => {
 3    // Приостанавливаем синхронизацию данных игрока.
 4});
 5
 6// Подписка на событие закрытия диалога выбора аккаунта.
 7ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_CLOSED, async () => {
 8    // Выходим в главное меню игры или перезагружаем страницу.
 9    // ...
10
11    // Перезапрашиваем данные игрока.
12    const player = await ysdk.getPlayer();
13    const data = await player.getData();
14});

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