Sự kiện

Sự kiện tạm dừng và tiếp tục trò chơi

Thông qua sự kiện game_api_pause và game_api_resume, nền tảng thông báo cho trò chơi rằng cần phải tạm dừng hoặc tiếp tục quá trình chơi. Chúng giúp đơn giản hóa quá trình tích hợp với nền tảng của chúng tôi và giúp tuân thủ các yêu cầu về kiểm duyệt (mục 1.3 và 4.7).

Các trò chơi hỗ trợ sự kiện tạm dừng và tiếp tục có thể được phân phối thêm trên các nền tảng bên ngoài.

Sự kiện game_api_pause và game_api_resume

Các sự kiện sẽ giúp bạn theo dõi:

• hiển thị và đóng quảng cáo toàn màn hình hoặc quảng cáo có thưởng;
• mở và đóng cửa sổ mua sắm;
• chuyển đổi giữa các tab trình duyệt;
• thu nhỏ và phóng to cửa sổ trình duyệt.

Chúng được tích hợp với phương thức đánh dấu gameplay. Khi sự kiện game_api_pause được kích hoạt, phương thức GameplayAPI.stop() sẽ được gọi, và khi sự kiện game_api_resume được kích hoạt, GameplayAPI.start() sẽ được gọi.

Nếu trò chơi đã được dừng bằng phương thức GameplayAPI.stop() (ví dụ, khi người chơi mở menu), và sau đó sự kiện game_api_pause xảy ra, thì tại sự kiện game_api_resume tiếp theo, phương thức GameplayAPI.start() sẽ không được gọi. Điều này cho phép giữ lại trạng thái hiện tại của trò chơi mà không làm gián đoạn logic đánh dấu gameplay.

Sử dụng phương thức on() và off() từ SDK Yandex Games để đăng ký và hủy đăng ký các sự kiện tương ứng.

Ví dụ

const pauseCallback = () => {
    pauseGame(); // Hàm của bạn, kháng lại vòng lặp game và âm nhạc.
    console.log('GAME PAUSED');
};

ysdk.on('game_api_pause', pauseCallback); // Đăng ký sự kiện 'game_api_pause'.
ysdk.off('game_api_pause', pauseCallback); // Hủy đăng ký sự kiện 'game_api_pause'.

const resumeCallback = () => {
    resumeGame(); // Hàm của bạn, tiếp tục vòng lặp game và âm nhạc.
    console.log('GAME RESUMED');
};

ysdk.on('game_api_resume', resumeCallback ); // Đăng ký sự kiện 'game_api_resume'.
ysdk.off('game_api_resume', resumeCallback ); // Hủy đăng ký sự kiện 'game_api_resume'.

Quảng cáo toàn màn hình khi khởi động game

Khác với các khối quảng cáo mà game gọi thông qua ysdk.adv.showFullscreenAdv(), quảng cáo khởi động không có các hàm callback trực tiếp. Để xử lý hiển thị của nó một cách chính xác, hãy theo dõi các sự kiện game_api_pause và game_api_resume:

1. Khi nhận được game_api_pause, tắt âm thanh của game và tạm dừng gameplay.
2. Chờ sự kiện game_api_resume và tiếp tục game.

Điều này đặc biệt quan trọng đối với các game mà âm thanh và gameplay được bắt đầu ngay lập tức.

Ví dụ xử lý quảng cáo khởi động

let gameStarted = false;
let isPaused = false;

// Hàm khởi tạo game.
function initGame() {
    // Đăng ký sự kiện tạm dừng và tiếp tục.
    ysdk.on('game_api_pause', handlePause);
    ysdk.on('game_api_resume', handleResume);

    // Kiểm tra xem có đang trong trạng thái tạm dừng không.
    // Nếu có, chờ resume trước khi bắt đầu game.
    if (!isPaused) {
        startGame();
    }
}

function handlePause() {
    isPaused = true;
    // Dừng âm thanh và gameplay.
    console.log('GAME PAUSED - waiting for resume');
}

function handleResume() {
    isPaused = false;

    // Nếu game chưa được khởi động, khởi động nó.
    if (!gameStarted) {
        startGame();
    } else {
        // Tiếp tục âm thanh và gameplay.
    }

    console.log('GAME RESUMED');
}

function startGame() {
    gameStarted = true;

    // Khởi tạo âm thanh.
    // Bắt đầu vòng lặp game.
    console.log('GAME STARTED');
}

// Khởi chạy quá trình khởi tạo game.
initGame();

Các sự kiện khác

Bạn cũng có thể theo dõi các sự kiện khác phát sinh khi người dùng tương tác với ứng dụng.

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 {}
};

Sự kiện HISTORY_BACK

Để theo dõi việc nhấp chuột vào nút Quay lại, hãy sử dụng phương thức sau:

ysdk.on(ysdk.EVENTS.HISTORY_BACK, () => {
    // Hiển thị hộp thoại trò chơi tùy chỉnh cho người dùng với các tùy chọn
    // để xác nhận thoát khỏi trò chơi, chuyển đến cài đặt nội bộ, cửa hàng, v.v
});

Sự kiện EXIT

Nếu người dùng xác nhận thoát khỏi trò chơi trong hộp thoại tùy chỉnh bật lên sau khi nhấp vào Quay lại, trò chơi phải gửi sự kiện thoát. Để thực hiện việc này, hãy sử dụng phương thức sau:

ysdk.dispatchEvent(ysdk.EVENTS.EXIT);

Hộp thoại chọn tài khoản game

Nền tảng lưu trữ tiến trình game cho cả người chơi đã đăng nhập và chưa đăng nhập. Người dùng có thể chơi mà không cần đăng nhập trước, sau đó mới đăng nhập vào tài khoản. Trong trường hợp này, họ sẽ có hai tiến trình khác nhau: một dưới tài khoản đã đăng nhập và một không có đăng nhập. Nền tảng sẽ hiển thị hộp thoại cho phép người dùng so sánh các bản lưu dựa trên thời gian chơi, ngày đăng nhập cuối cùng và các thông số khác để chọn tiến trình muốn sử dụng.

Nếu bạn thường xuyên đồng bộ hóa dữ liệu người chơi hoặc lưu trữ tiến trình game trên máy chủ của mình, hãy theo dõi sự thay đổi tiến trình sau khi chọn tài khoản trong hộp thoại.

Trong SDK có hai sự kiện cho mục đích này:

• ACCOUNT_SELECTION_DIALOG_OPENED — hộp thoại được mở.
• ACCOUNT_SELECTION_DIALOG_CLOSED — hộp thoại được đóng.

Khi hộp thoại mở, bạn có thể tạm dừng quá trình đồng bộ hóa dữ liệu người chơi định kỳ. Khi đóng — quay về menu chính hoặc khởi động lại game và yêu cầu lại đối tượng người chơi.

Ví dụ

// Đăng ký sự kiện mở hộp thoại chọn tài khoản.
ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_OPENED, () => {
    // Tạm dừng đồng bộ hóa dữ liệu người chơi.
});

// Đăng ký sự kiện đóng hộp thoại chọn tài khoản.
ysdk.on(ysdk.EVENTS.ACCOUNT_SELECTION_DIALOG_CLOSED, async () => {
    // Quay về menu chính của game hoặc tải lại trang.
    // ...

    // Yêu cầu lại dữ liệu người chơi.
    const player = await ysdk.getPlayer();
    const data = await player.getData();
});

Nếu bạn đang gặp phải vấn đề hoặc có câu hỏi liên quan đến việc sử dụng Yandex Games SDK, vui lòng liên hệ với bộ phận hỗ trợ: