---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/sdk-player.md
  - https://yandex.com/dev/games/doc/hi/sdk/sdk-player.md
  - https://yandex.com/dev/games/doc/ko/sdk/sdk-player.md
  - https://yandex.com/dev/games/doc/ru/sdk/sdk-player.md
  - https://yandex.com/dev/games/doc/tr/sdk/sdk-player.md
  - https://yandex.com/dev/games/doc/vi/sdk/sdk-player.md
  - https://yandex.com/dev/games/doc/zh/sdk/sdk-player.md
  - href: ko/sdk/sdk-player.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/ko/llms.txt

# 플레이어 데이터

게임 상태 데이터(완료한 레벨, 경험치, 게임 내 구매 포함)를 Yandex 서버에 저장하거나 내 서버로 전송할 수 있습니다. 사용자의 이름과 같은 Yandex 프로필의 데이터를 사용하여 게임을 개인화할 수도 있습니다.

`Player` 객체는 사용자 데이터 작업에 사용됩니다.



## 초기화 {#getplayer}

`Player` 객체를 초기화하려면 `ysdk.getPlayer()` 메서드를 사용합니다.

```javascript
var player;

ysdk.getPlayer().then(_player => {
        player = _player;
    }).catch(err => {
        // 플레이어 객체를 초기화하는 동안 오류가 발생했습니다.
    });
```

`Player` 객체를 초기화할 때 다음과 같은 정보가 전달됩니다:

- 모든 사용자에게 — 사용자 ID
- 인증된 플레이어에게 — 아바타와 이름
- 러시아 연방의 플레이어이며 [인앱 구매](https://yandex.com/dev/games/doc/ko/console/purchases.md)가 있는 게임의 경우 — 플랫폼에서의 구매 내역

사용자 데이터 접근 권한은 [프로필](https://yandex.com/games/user) 설정에 따라 달라집니다. 사용자가 개인 데이터 접근을 차단한 경우 응답에는 ID만 포함됩니다.

선택적 `signed: true` 파라미터와 `fetch` 메서드를 사용하여 사용자를 로그인하고 게임 상태 데이터를 서버에 저장할 수 있습니다. 이렇게 하면 서명을 사용하여 플레이어를 인증하고 사기 가능성을 방지할 수 있습니다.

```javascript
var player;

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

        // 서버에서 인증을 위해 player.signature를 사용하세요.
        fetch('https://your.game.server?auth', {
            method: 'POST',
            headers: { 'Content-Type': 'text/plain' },
            body: player.signature
        });
    }).catch(err => {
        // 플레이어 객체를 초기화하는 동안 오류가 발생했습니다.
    });
```

서버로 전송되는 요청의 `signature` 파라미터에는 Yandex 프로필의 사용자 데이터와 서명이 포함됩니다. 두 개의 Base64로 인코딩된 문자열로 구성됩니다:

```text
<signature>.<profile data>
```

자세한 내용은 [사기 방지](https://yandex.com/dev/games/doc/ko/sdk/sdk-purchases.md#signature)를 참조하세요.

{% note info "참고" %}

요청은 5분에 20번을 초과하여 보낼 수 없으며, 그렇지 않으면 오류와 함께 거부됩니다.

{% endnote %}



## 사용자 로그인 {#auth}

### 사용자 로그인 여부 확인하기 {#auth-check}

플레이어가 Yandex Games에 로그인했는지 확인하려면 `Player` 객체의 메서드인 `player.isAuthorized()`를 사용하세요. 이 메서드는 `true` 또는 `false`를 반환합니다.

{% note alert "제한" %}

`player.getMode(): 'lite' | ''` 메서드는 더 이상 사용되지 않으며 향후 인터페이스에서 제거될 예정입니다.

{% endnote %}


### 로그인 대화 상자 호출 {#open-auth-dialog}

플레이어가 로그인하지 않은 경우 `ysdk.auth.openAuthDialog()` 메서드를 사용하여 로그인 대화 상자를 열 수 있습니다.


{% note tip "팁" %}

사용자에게 로그인 시 얻을 수 있는 혜택에 대해 알려주세요. 혜택을 모르는 사용자는 로그인을 건너뛰고 게임을 종료할 가능성이 높습니다.

{% endnote %}

```javascript
var player;

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

            return player;
        });
}

initPlayer().then(_player => {
        if (_player.isAuthorized() === false) {
            // 플레이어가 로그인하지 않았습니다.
            ysdk.auth.openAuthDialog().then(() => {
                    // 플레이어가 로그인했습니다
                    initPlayer().catch(err => {
                        // 플레이어 객체를 초기화하는 동안 오류가 발생했습니다.
                    });
                }).catch(() => {
                    // 플레이어가 로그인하지 않았습니다.
                });
        }
    }).catch(err => {
        // 플레이어 객체를 초기화하는 동안 오류가 발생했습니다.
    });

```



## 게임 내 데이터 {#ingame-data}

사용자의 게임 내 데이터로 작업하려면 `Player` 객체 메서드를 사용합니다.


* `player.setData(data, flush)`: 사용자 데이터를 저장합니다. 최대 데이터 크기는 200KB를 넘지 않아야 합니다. {#setdata}

   - `data`: 객체, 키-값 쌍을 포함하는 객체.
   - `flush`: 부울, 주문 데이터가 전송되는 시점을 지정합니다. 값이 "true"이면 데이터가 즉시 서버로 전송됩니다. 값이 "false"(기본값)이면 데이터 전송 요청이 큐에 대기합니다.

   이 메서드는 데이터가 저장되었는지 여부를 나타내는 `Promise`를 반환합니다.

   파라미터 값이 `flush: false`인 경우, 반환된 결과에는 데이터 유효성만 표시됩니다(데이터는 나중에 전송하기 위해 대기열에 대기 중). 하지만 지금 `player.getData()`를 사용하면 현재 데이터가 아직 전송되지 않았더라도 `player.setData()`가 설정한 최신 데이터를 반환합니다.

   ```javascript
   player.setData({
           achievements: ['trophy1', 'trophy2', 'trophy3'],
       }).then(() => {
           console.log('data is set');
       });

   ```


- `player.getData(keys)`: Yandex 데이터베이스에 저장된 게임 내 사용자 데이터를 비동기적으로 반환합니다. {#getdata}

   - `keys`: array<string>, 반환할 키 목록입니다. `keys` 파라미터가 누락된 경우, 메서드는 모든 게임 내 사용자 데이터를 반환합니다.

   메서드는 키-값 쌍을 포함하는 객체와 함께 `Promise<Object>`를 반환합니다.

- `player.setStats(stats)`: 사용자의 숫자 데이터를 저장합니다. 최대 데이터 크기는 10KB를 넘지 않아야 합니다. {#setstats}

   - `stats`: 객체, 각 값이 숫자인 키-값 쌍을 포함하는 객체입니다.

   이 메서드는 데이터가 저장되었는지 여부를 나타내는 `Promise`를 반환합니다.


   {% note tip "팁" %}

   포인트, 경험치, 게임 내 화폐 등 자주 변경되는 숫자 값의 경우 [player.setData()](#ingame-data) 대신 이 메서드를 사용하세요.

   {% endnote %}



- `player.incrementStats(increments)`: 게임 내 사용자 데이터 변경. 최대 데이터 크기는 10KB를 넘지 않아야 합니다. {#incrementstats}

   - `increments`: 객체, 각 값이 숫자인 키-값 쌍을 포함하는 객체입니다.

   이 메서드는 변경 및 추가된 키-값 쌍이 포함된 객체와 함께 `Promise<Object>`를 반환합니다.


- `player.getStats(keys)`: 사용자의 숫자 데이터를 비동기적으로 반환합니다. {#getstats}

   - `keys`: array<string>, 반환할 키 목록입니다. `keys` 파라미터가 누락된 경우, 메서드는 모든 게임 내 사용자 데이터를 반환합니다.

   메서드는 키-값 쌍을 포함하는 객체와 함께 `Promise<Object>`를 반환합니다.

{% note info "참고" %}

요청 빈도에는 제한이 있습니다. [제한](#limits)을 초과하는 경우 요청은 오류와 함께 거부됩니다.

{% endnote %}



## 사용자 프로필 데이터 {#profile-data}

Yandex 사용자 프로필에서 데이터를 가져오려면 `Player` 객체 메서드를 사용합니다.

- `player.getUniqueID()`: 사용자의 고유 영구 ID를 반환합니다(유형: 문자열).

   {% note info "참고" %}

   이전에 사용되던 `player.getID()` 메서드는 이제 더 이상 사용되지 않지만 오류 콘솔에 경고를 표시하면서 잠시 동안 계속 작동합니다.

   `player.getID()`와 `player.getUniqueID()`의 값은 일반적으로 주어진 `Player` 객체에 대해 동일하지 않지만, 일부 사용자에게는 동일할 수 있습니다. 값이 다르고 게임 자체에서 이미 일부 데이터를 `player.getID()` 값에 링크한 경우, 이 데이터를 마이그레이션하여 `player.getUniqueID()` 값에 링크해야 합니다. 모든 사용자의 데이터를 한 번에 마이그레이션하려면 [지원팀에 문의](https://yandex.com/dev/games/doc/ko/concepts/troubleshooting.md#fos)하세요.

   {% endnote %}

- `player.getIDsPerGame()`: 사용자가 개인 데이터 전송에 명시적으로 동의한 모든 개발자 게임에서 사용자 ID가 지정된 `Promise<Array>`를 반환합니다. 예시:

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

   {% note alert "알림" %}

   이 요청은 로그인한 사용자만 사용할 수 있습니다. 필요한 경우 [인증](#auth)을 사용합니다.

   사용자가 메서드를 사용할 수 있는지 확인하려면 `ysdk.isAvailableMethod('player.getIDsPerGame')` 메서드를 사용할 수 있습니다. 이 메서드는 `Promise<Boolean>`을 반환하며, 여기서 부울 값은 메서드의 사용 가능 여부를 나타냅니다.

   {% endnote %}

- `player.getName()`: 사용자의 이름을 반환합니다(유형: 문자열).


- `player.getPhoto(size)`: 사용자 아바타의 URL을 반환합니다(유형: 문자열).

   - `size`: 문자열, 필요한 크기. 가능한 값은 다음과 같습니다. `small`, `medium`, `large`.



## 메소드 제한 {#limits}

#|
|| **메소드** | **설명** | **제한** ||
|| `ysdk.getPlayer()` | [`Player` 객체를 초기화합니다](#getplayer) |::{align="center"} 5분 동안 20번의 요청 ||
|| `player.setData()` | [사용자 데이터를 저장합니다](#setdata) |::{align="center"} 5분 동안 100번의 요청 ||
|| `player.getData()` | [사용자의 게임 내 데이터를 비동기적으로 반환합니다](#getdata) | ^ ||
|| `player.setStats()` | [사용자의 숫자 데이터를 저장합니다](#setstats) |::{align="center"} 1분 동안 60번의 요청 ||
|| `player.getStats()` | [사용자의 숫자 데이터를 비동기적으로 반환합니다](#getstats) | ^ ||
|| `player.incrementStats()` | [게임 내 사용자 데이터 변경](#incrementstats) | ^ ||
|#



## iOS에서 진행률 손실 {#progress-loss}

게임이 `iframe`을 통해 통합된 경우, 새 iOS 버전에서 `localStorage`가 초기화되어 플레이어의 진행 상황이 손실될 수 있습니다. 이를 방지하려면 `localStorage`와 동일한 인터페이스를 가진 `safeStorage`를 사용하세요.

```javascript
ysdk.getStorage().then(safeStorage => {
        safeStorage.setItem('key', 'safe storage is working');
        console.log(safeStorage.getItem('key'))
    })
```

코드를 수동으로 변경하지 않으려면 `localStorage`를 전역적으로 재정의하세요.


{% note alert "알림" %}

재정의하기 전에 `localStorage`가 사용되지 않는지 확인하세요.

{% endnote %}


```javascript
ysdk.getStorage().then(safeStorage => Object.defineProperty(window, 'localStorage', { get: () => safeStorage }))
    .then(() => {
        localStorage.setItem('key', 'safe storage is working');
        console.log(localStorage.getItem('key'))
    })
```

소스 코드를 아카이브로 다운로드하면 SDK의 특수 래퍼가 자동으로 `localStorage`를 안정적으로 만들므로 아무 작업도 할 필요가 없습니다.


---

<!-- source: ko/_includes/concepts/troubleshooting/id-troubleshooting/support.md -->
{% note info "참고" %}

지원팀은 완성된 게임을 Yandex Games에 게시하는 데 도움을 드릴 수 있습니다. 개발이나 테스트에 대해 궁금한 점이 있다면, [Discord 채널](https://discord.com/invite/wU4p3whr4T)에서 질문해 주세요.

{% endnote %}


지원 서비스는 얀덱스 게임에서 완성 된 게임을 게시 할 수 있습니다. 개발 또는 테스트에 대한 질문이 있는 경우
<!-- endsource: ko/_includes/concepts/troubleshooting/id-troubleshooting/support.md -->

<!-- source: ko/_includes/button-fos.md -->
Yandex Games SDK 사용과 관련하여 문제가 발생하거나 질문이 있는 경우 다음 방법으로 지원팀에 문의하세요.


<a href="https://yandex.com/chat/#/user/a4fa5c06-75db-9b38-6eea-b1673785f7d5">
  <span class="button">채팅 상담</span>
</a>
<!-- endsource: ko/_includes/button-fos.md -->