Player data

You can save game data (completed levels, experience, in-app purchases, etc.) on the Yandex server or send it to your server, and also personalize the game using data from the user's Yandex profile, such as their name.

To work with user data, use the Player object.

Initialization

To initialize the Player object, use the ysdk.getPlayer() method:

1const ysdk = await YaGames.init();
2
3try {
4    const player = await ysdk.getPlayer();
5} catch (e) {
6    // Error initializing the Player object.
7}

When initializing a Player object, the following data is passed:

• User ID — for all players.
• Avatar and name — for authorized players.
• Platform purchase data (only for games with in-app purchases) — for players from Russia.

For more information about these parameters, see User profile data.

Access to user data depends on settings in their profile. If a player restricts access to personal data, only the ID will be included in the response.

To authorize a user and save game state data on your server, you can use the optional signed: true parameter and the fetch() method. This allows you to use the signature to verify player authenticity and prevent potential fraud.

 1const ysdk = await YaGames.init();
 2
 3try {
 4    const player = await ysdk.getPlayer({ signed: true });
 5
 6    // Use player.signature for authorization on your server.
 7    const authData = await fetch('https://your.game.server/auth', {
 8        method: 'POST',
 9        headers: { 'Content-Type': 'text/plain' },
10        body: player.signature
11    });
12} catch (e) {
13    // Error initializing the Player object or during authorization.
14}

The signature parameter of the request sent to the server contains user data from the Yandex profile and the signature. The parameter represents two strings in base64 encoding:

<signature>.<profile data>

For more information, see Fraud prevention.

User authorization

Verifying authorization

To check if a player is authorized in Yandex, use the Player object method player.isAuthorized(). The method returns true | false.

Calling the authorization dialog box

To call the authorization window, use the ysdk.auth.openAuthDialog() method.

 1const ysdk = await YaGames.init();
 2
 3try {
 4    let player = await ysdk.getPlayer();
 5
 6    // Player is not authorized.
 7    if (!player.isAuthorized()) {
 8        try {
 9            // Opening the authorization window.
10            await ysdk.auth.openAuthDialog();
11
12            const authorizedPlayer = await ysdk.getPlayer();
13
14            player = authorizedPlayer;
15        } catch (e) {
16            // Error during player authorization or re-initialization of the Player object.
17        }
18    }
19    // Player successfully authorized.
20} catch (err) {
21    // Error initializing the Player object.
22}

In-game data

To work with the user's in-game data, use the Player object methods.

player.setData(data, flush)

Saves the user data. The maximum data size per player is 200 KB.

Method signature:

function setData(data: object, flush: boolean) => Promise<void> {}

Accepts parameters:

The method returns a Promise that indicates whether the data was saved or not.

At flush: false, the returned result only shows the data validity (the data has been queued and will be sent later). At the same time, the player.getData() method will return the data set by the last player.setData() call, even if it has not been sent yet.

Example

1const ysdk = await YaGames.init();
2
3const player = await ysdk.getPlayer();
4
5await player.setData({
6    achievements: ['trophy1', 'trophy2', 'trophy3'],
7})
8
9console.log('data is set');

player.getData(keys)

Asynchronously returns in-game user data stored in the Yandex database.

Method signature:

function getData(keys?: Array<string>) => Promise<object> {}

Accepts parameter:

The method returns Promise<object>, which contains key-value pairs.

player.setStats(stats)

Saves the user's numeric data. The maximum numeric data size per player is 10 KB.

Method signature:

function setStats(stats?: object) => Promise<void> {}

Accepts parameter:

The method returns a Promise that indicates whether the data was saved or not.

player.incrementStats(increments)

Changes the user's numeric data. The maximum numeric data size per player is 10 KB.

Method signature:

function incrementStats(increments: object) => Promise<object> {}

Accepts parameter:

The method returns Promise<object>, which contains modified and added key-value pairs.

player.getStats(keys)

Asynchronously returns the user's numeric data.

Method signature:

function getStats(keys?: Array<string>) => Promise<object> {}

Accepts parameter:

The method returns Promise<object>, which contains key-value pairs.

User profile data

To get data from the user's Yandex profile, use the Player object methods.

player.getUniqueID()

Returns the user's permanent unique ID.

Method signature:

function getUniqueID() => string {}

player.getIDsPerGame()

The method returns an array of objects with user IDs for all of the developer's games in which the user has explicitly granted access to their personal data.

Method signature:

function getIDsPerGame() => Promise<Array<{ appID: number, userID: string }>> {}

player.getName()

Returns the user's name.

Method signature:

function getName() => string {}

player.getPhoto()

Returns the URL of the user's avatar depending on the requested image size.

Method signature:

function getPhoto(size: 'small' | 'medium' | 'large') => string {}

player.getPayingStatus()

Returns a value depending on the user's purchase frequency and amount.

Method signature:

function getPayingStatus() => EPayingStatus {}

EPayingStatus takes one of the following values:

Example

1const ysdk = await YaGames.init(); // Initialize the SDK.
2const player = await ysdk.getPlayer(); // Get the player.
3const payingStatus = player.getPayingStatus(); // Get the user's payment activity status on the platform.
4
5if (payingStatus === 'paying' || payingStatus === 'partially_paying') {
6    // Offer in-app goods at startup or instead of ads.
7}

Method limitations

Progress loss on iOS

If you use your own domain for game integration, localStorage may often reset on new iOS versions, causing players to lose their progress. To avoid this, use safeStorage, which has the same interface as localStorage:

1const ysdk = await YaGames.init();
2
3const safeStorage = await ysdk.getStorage();
4
5safeStorage.setItem('key', 'safe storage is working');
6console.log(safeStorage.getItem('key'));

To avoid manually changing the code, override localStorage globally.

1const ysdk = await YaGames.init();
2
3const safeStorage = await ysdk.getStorage();
4
5Object.defineProperty(window, 'localStorage', { get: () => safeStorage });
6
7localStorage.setItem('key', 'safe storage is working');
8console.log(localStorage.getItem('key'));

If you are uploading the source code as an archive, you don't need to do anything: a special wrapper in the SDK automatically makes localStorage reliable.

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