Dữ liệu người chơi

Bạn có thể lưu dữ liệu trạng thái trò chơi của người chơi (chẳng hạn như cấp độ đã hoàn thành, kinh nghiệm hoặc mua hàng trong trò chơi) trên máy chủ Yandex hoặc gửi dữ liệu này đến máy chủ của bạn. Bạn cũng có thể tạo ra trải nghiệm tùy chỉnh theo cá nhân hơn thông qua dữ liệu từ hồ sơ Yandex của người dùng, ví dụ: tên của người dùng.

Để làm việc với dữ liệu người dùng, hãy sử dụng đối tượng Player.

Khởi tạo

Để khởi tạo đối tượng Player, hãy sử dụng phương thức ysdk.getPlayer().

var player;

ysdk.getPlayer().then(_player => {
        player = _player;
    }).catch(err => {
         // Lỗi khởi tạo đối tượng Player.
    });

Khi khởi tạo đối tượng Player, các thông tin sau sẽ được truyền vào:

• ID người dùng — cho tất cả người chơi.
• Avatar và tên — cho người chơi đã xác thực.
• Dữ liệu mua hàng trên nền tảng (chỉ áp dụng cho trò chơi có mua hàng trong ứng dụng) — cho người chơi từ Nga.

Quyền truy cập vào dữ liệu người dùng phụ thuộc vào cài đặt trong hồ sơ của họ. Nếu người chơi từ chối quyền truy cập vào dữ liệu cá nhân, phản hồi sẽ chỉ bao gồm ID.

Bạn có thể sử dụng tham số tùy chọn signed: true và phương thức fetch() để đăng nhập người dùng và lưu dữ liệu trạng thái trò chơi của họ trên máy chủ của bạn. Cách này cho phép bạn sử dụng chữ ký để xác thực người dùng và ngăn chặn gian lận.

var player;

ysdk.getPlayer({ signed: true }).then(_player => {
        player = _player;

        // Sử dụng player.signature để cho phép trên máy chủ của bạn.
        fetch('https://your.game.server?auth', {
            method: 'POST',
            headers: { 'Content-Type': 'text/plain' },
            body: player.signature
        });
    }).catch(err => {
        // Lỗi khởi tạo đối tượng Player.
    });

Tham số chữ ký của yêu cầu được gửi đến máy chủ chứa dữ liệu người dùng từ hồ sơ Yandex và chữ ký. Tham số bao gồm hai chuỗi mã hóa theo chuẩn Base64:

<signature>.<profile data>

Để biết thêm thông tin, hãy xem Phòng chống gian lận.

Đăng nhập người dùng

Xác minh sự cho phép

Để kiểm tra xem người chơi đã đăng nhập vào Yandex hay chưa, hãy sử dụng phương thức của đối tượng Player — player.isAuthorized(). Phương thức này trả về true | false.

Gọi hộp thoại đăng nhập

Nếu người chơi chưa đăng nhập, bạn có thể sử dụng phương thức ysdk.auth.openAuthDialog() để gọi cửa sổ cho phép.

var player;

function initPlayer() {
    return ysdk.getPlayer().then(_player => {
            player = _player;

            return player;
        });
}

initPlayer().then(_player => {
        if (_player.isAuthorized() === false) {
            // Người chơi chưa đăng nhập.
            ysdk.auth.openAuthDialog().then(() => {
                    // Người chơi đã đăng nhập.
                    initPlayer().catch(err => {
                        // Lỗi khởi tạo đối tượng Player.
                    });
                }).catch(() => {
                    // Người chơi chưa đăng nhập.
                });
        }
    }).catch(err => {
        // Lỗi khởi tạo đối tượng Player.
    });

Dữ liệu trong trò chơi

Để làm việc với dữ liệu trong trò chơi của người dùng, hãy sử dụng các phương thức của đối tượng Player:

• player.setData(data, flush): Lưu dữ liệu người dùng. Kích thước dữ liệu tối đa không được vượt quá 200 KB.

  • data (object): Một đối tượng chứa các cặp khóa-giá trị.
  • flush (boolean): Xác định thứ tự gửi dữ liệu. Nếu giá trị là "true", dữ liệu ngay lập tức được gửi đến máy chủ. Nếu đó là "false" (mặc định), yêu cầu gửi dữ liệu sẽ được xếp hàng đợi.

  Phương thức trả về Promise cho biết dữ liệu đã được lưu hay chưa.

  Với flush: false, kết quả trả về chỉ hiển thị tính hợp lệ của dữ liệu (dữ liệu đã được xếp hàng đợi và sẽ được gửi sau). Đồng thời, phương thức player.getData() sẽ trả về tập dữ liệu bằng lệnh gọi player.setData() cuối cùng, ngay cả khi nó chưa được gửi.

  player.setData({
          achievements: [`trophy1`, `trophy2`, `trophy3`],
      }).then(() => {
          console.log('dữ liệu được thiết lập');
      });
  

• player.getData(keys): Trả về không đồng bộ dữ liệu người dùng trong trò chơi được lưu trữ trong cơ sở dữ liệu Yandex.

  • keys (array<string>): Danh sách các khóa cần trả lại. Nếu tham số key bị thiếu, phương thức này sẽ trả về tất cả dữ liệu người dùng trong trò chơi.

  Phương thức trả về Promise<Object>, trong đó object chứa các cặp khóa-giá trị.

• player.setStats(stats): Lưu dữ liệu số của người dùng. Kích thước dữ liệu tối đa không được vượt quá 10 KB.

  • stats (object): Một đối tượng chứa các cặp khóa-giá trị, trong đó mỗi giá trị phải là một số.

  Phương thức trả về Promise cho biết dữ liệu đã được lưu hay chưa.

  Lời khuyên

  Với các giá trị số thường xuyên thay đổi (điểm, kinh nghiệm, tiền trong trò chơi), hãy sử dụng phương pháp này thay vì player.setData().

• player.incrementStats(increments): Thay đổi dữ liệu người dùng trong trò chơi. Kích thước dữ liệu tối đa không được vượt quá 10 KB.

  • increments (object): Một đối tượng chứa các cặp khóa-giá trị, trong đó mỗi giá trị phải là một số.

  Phương thức trả về Promise<Object>, trong đó object chứa các cặp khóa-giá trị đã sửa đổi và được thêm vào.

• player.getStats(keys): Trả về không đồng bộ dữ liệu số của người dùng.

  • keys (array<string>): Danh sách các khóa cần trả lại. Nếu tham số key bị thiếu, phương thức này sẽ trả về tất cả dữ liệu người dùng trong trò chơi.

  Phương thức trả về Promise<Object>, trong đó object chứa các cặp khóa-giá trị.

Dữ liệu hồ sơ người dùng

Để lấy dữ liệu từ hồ sơ người dùng Yandex, hãy sử dụng các phương thức của đối tượng Player:

• player.getUniqueID() (string): Trả về ID duy nhất vĩnh viễn của người dùng.

  Ghi chú

  Phương thức player.getID() được sử dụng trước đây đã không còn được dùng nữa nhưng hiện vẫn được hỗ trợ, trả về cảnh báo trong bảng điều khiển lỗi.

  Các giá trị của player.getID() và player.getUniqueID() thường không giống nhau đối với một đối tượng Player nhất định, nhưng chúng có thể giống nhau với một số người dùng. Nếu các giá trị khác nhau và bản thân trò chơi đã liên kết một số dữ liệu với giá trị player.getID(), bạn cần di chuyển dữ liệu này và liên kết với giá trị player.getUniqueID(). Để di chuyển dữ liệu cho tất cả người dùng cùng một lúc, hãy liên hệ bộ phận hỗ trợ.

• player.getIDsPerGame(): Trả về Promise<Array> cùng với các ID người dùng cho tất cả các trò chơi của nhà phát triển mà họ đã cấp quyền truy cập rõ ràng vào dữ liệu cá nhân của mình. Ví dụ:

  [
      { appID: 103915, userID: "tOpLpSh7i8QG8Voh/SuPbeS4NKTj1OxATCTKQF92H4c=" },
      { appID: 103993, userID: "bviQCIAAuVmNMP66bZzC4x+4oSFzRKpteZ/euP/Jwv4=" }
  ]
  

  Chú ý

  Yêu cầu chỉ dành cho người dùng được cho phép. Nếu cần, hãy yêu cầu sự cho phép.

  Để kiểm tra xem phương thức có dùng được cho người dùng hay không, bạn có thể sử dụng phương thức ysdk.isAvailableMethod('player.getIDsPerGame'). Phương thức này trả về Promise<Boolean>, trong đó giá trị boolean cho biết tính khả dụng của phương thức.

• player.getName() (string): Trả về tên người dùng.

• player.getPhoto(size) (string): Trả về URL ảnh hồ sơ của người dùng.

  • size (string): Kích thước được yêu cầu. Các giá trị được hỗ trợ bao gồm: small, medium, large.

• player.getPayingStatus() (string): Trả về bốn giá trị có thể tùy thuộc vào tần suất và số lượng mua hàng của người dùng:

  • paying: Người dùng đã mua tiền của cổng thông tin với giá hơn ₽500 trong tháng trước.
  • partially_paying: Người dùng đã mua tiền của cổng thông tin bằng tiền thật ít nhất một lần trong năm ngoái.
  • not_paying: Người dùng đã không mua tiền của cổng thông tin bằng tiền thật trong năm ngoái.
  • unknown: Người dùng không đến từ Liên bang Nga hoặc không đồng ý chia sẻ thông tin này với nhà phát triển.

  Mẫu sử dụng:

  const ysdk = await YaGames.init(); // Khởi tạo SDK.
  const player = await ysdk.getPlayer(); // Truy xuất dữ liệu người chơi.
  const payingStatus = player.getPayingStatus(); // Lấy thông tin trạng thái hoạt động thanh toán của người dùng trên nền tảng.
  
  if (payingStatus === 'paying' || payingStatus === 'partially_paying') {
      // Cung cấp hàng hóa trong ứng dụng khi khởi động hoặc thay vì quảng cáo.
  }
  

Giới hạn của phương thức

Mất tiến độ trên iOS

Nếu trò chơi được tích hợp thông qua iframe, localStorage thường có thể bị đặt lại trên các phiên bản iOS mới, khiến người chơi mất thông tin tiến trình. Để tránh điều này, hãy sử dụng safeStorage, có giao diện tương tự như localStorage:

ysdk.getStorage().then(safeStorage => {
        safeStorage.setItem('key', 'bộ lưu trữ an toàn đang hoạt động');
        console.log(safeStorage.getItem('key'))
    })

Để tránh thay đổi mã theo cách thủ công, hãy ghi đè localStorage ở phạm vi toàn cục.

ysdk.getStorage().then(safeStorage => Object.defineProperty(window, 'localStorage', { get: () => safeStorage }))
    .then(() => {
        localStorage.setItem('key', 'bộ lưu trữ an toàn đang hoạt động');
        console.log(localStorage.getItem('key'))
    })

Nếu bạn đang tải lên mã nguồn dưới dạng tệp lưu trữ, bạn không cần phải làm gì cả: một trình bọc wrapper đặc biệt trong SDK sẽ tự động tạo sự tin cậy cho localStorage.

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ợ: