> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 첫 번째 플레이테스트

> XBOX CLI와 Partner Center를 사용하여 XBOX 게임의 빌드를 업로드한 다음, 해당 빌드의 플레이테스트를 만들고, 게시하고, 공유합니다.

플레이테스트를 사용하면 선택한 플레이어 그룹이 출시 전이나 후에 인증이나 Microsoft Store 목록 없이
XBOX 본체와 PC에 게임 빌드를 설치할 수 있습니다. 이 페이지에서는 빌드 업로드부터
테스터와 플레이테스트 공유까지 안내합니다.
[Playtest 개요](https://learn.microsoft.com/gaming/game-publishing/concepts/playtest)에서
플레이테스트의 작동 방식을 설명합니다.

이 페이지의 명령은 대부분 실험적이므로 옵션과 출력이 변경될 수 있습니다.
[실험적 명령](https://docs.xbox.com/ko/tools/xbox-cli/cli-command-lifecycle.md)을 참조하세요.

## 시작하기 전에

* XBOX 게임을 개발하도록 설정되어 있고 게임이 포함된 Partner Center 계정. 플레이테스트에는 별도의
  액세스 요청이 필요하지 않습니다.
* 게임의 연령 등급. Partner Center에 있는 게임의 **Age ratings** 페이지에서 IARC(International Age Rating Coalition)
  설문지를 한 번 작성하세요. 연령 등급이 없으면 플레이테스트를
  게시할 수 없습니다.
* Partner Center에서 게임의 패키지를 관리할 수 있는 권한. 이 권한이 없으면 `package` 및
  `playtest` 명령이 403 `package_permission_denied`로 실패합니다. Partner
  Center 계정의 관리자에게 권한을 요청하거나, 게임이 다른 판매자에게 속한 경우 `--seller-id`를 전달하세요.
* [시작하기](https://docs.xbox.com/ko/tools/xbox-cli/getting-started.md)에 설명된 대로 `xbox auth login`으로 로그인하고 판매자를 선택합니다.

플레이테스트는 RETAIL 샌드박스에서 실행됩니다. 빌드가 XBOX 로그인 또는 기타 XBOX services를 사용하는 경우
먼저 [플레이테스트에서 XBOX services 사용](https://docs.xbox.com/ko/tools/xbox-cli/xbox-services-in-a-playtest.md)을 따르세요.

예에서는 Store ID `9N0000000000`을 사용합니다. 게임의 Store ID는
`xbox game list --output table`로 찾을 수 있습니다.

## 1. 패키지 업로드

CLI는 패키지를 업로드하지 않습니다. 2026년 10월 XBOX GDK(Game Development Kit) 이상의
`makepkg`로 빌드를 업로드하세요. 빌드가 `layout` 폴더에 있는 PC 게임의 경우 다음과 같습니다.

```text theme={null}
makepkg upload /d layout /msixvc2 /pc /storeid 9N0000000000 /branch Main
```

[makepkg 참조](https://learn.microsoft.com/gaming/gdk/docs/features/common/packaging/deployment/makepkg)에서
다른 패키지 형식을 다룹니다. 그런 다음 Partner Center가 패키지를 처리하며, 이 작업에는 시간이
걸릴 수 있습니다. 확인하려면 다음을 실행합니다.

```bash theme={null}
xbox package list --store-id 9N0000000000 --output table
```

`STATE`가 `Processed`이고 `PLAYTEST`가 `true`이면 패키지가 준비된 것입니다. 해당 `PACKAGE ID`를 기록해 두세요.
표에는 유효성 검사 결과가 표시되지 않으므로, JSON에서 `validationItems`에 심각도가 `Error`인
항목이 없는지 확인하세요.

```bash theme={null}
xbox package list --store-id 9N0000000000
```

`STATE`가 `ProcessFailed`이거나, `PLAYTEST`가 `false`로 유지되거나, `Error` 항목이 있는 경우
[플레이테스트의 필수 구성 요소](https://learn.microsoft.com/gaming/game-publishing/concepts/playtest-preview#prerequisites-for-a-playtest)에서 패키지 요구 사항을 확인하세요.

## 2. 대상 그룹 만들기

대상 그룹은 플레이테스트를 설치할 수 있는 사용자를 결정합니다. Partner Center에서는 이를 고객 그룹이라고 합니다.
Partner Center의 **Apps and games** 작업 영역에서 **Customer groups**를 선택한 다음
**Create new group**을 선택합니다. **Known user group**을 선택하고, 테스터를 추가하고, 저장합니다.

또는 테스터의 이메일 주소를 한 줄에 하나씩 `testers.txt`에 나열하고, 실험적
[`audience create`](https://docs.xbox.com/ko/tools/xbox-cli/commands/audience#creating-an-audience) 명령으로 대상 그룹을 만듭니다.

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt
```

플레이테스트에 추가할 때 사용할 수 있도록 대상 그룹의 `id`를 기록해 두세요.

## 3. 플레이테스트 만들기

`audience create`로 대상 그룹을 만든 경우 출력된 `id`를 사용하세요. Partner Center에서
그룹을 만든 경우 해당 `ID`를 찾습니다.

```bash theme={null}
xbox audience list --output table
```

[알려진 문제](https://docs.xbox.com/ko/tools/xbox-cli/known-issues.md#xbox-audience-list-can-time-out)로 인해 `xbox audience list`가 시간 초과되면
플레이테스트를 만들 때 `--audience-id`를 생략하세요. 그런 다음 Partner Center의 **Services** 아래에 있는
게임의 Playtest 페이지에서 플레이테스트를 열고, 2단계의 그룹을 선택한 다음, 게시하지 않고
저장합니다.

플레이테스트를 만듭니다.

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena playtest" --start 2026-12-01 --end 2026-12-15 --pc-package-id 11111111-2222-3333-4444-555555555555 --audience-id 1152921504606846976
```

* `--pc-package-id`는 1단계의 패키지 ID를 받습니다. 본체 패키지에는 `--console-package-id`를
  사용하세요.
* `--audience-id`는 대상 그룹의 ID를 받습니다. 대상 그룹을 더 추가하려면 이 옵션을 반복하세요.
* 테스터는 `--start`부터 `--end`까지 플레이테스트를 설치할 수 있습니다. 시간이 없는 날짜는
  UTC 자정을 의미합니다.

명령은 플레이테스트를 만들기 전에 확인을 요청한 다음, 플레이테스트를 JSON으로 출력합니다. `details` 아래의
`playtestId`인 플레이테스트 ID를 기록해 두세요.

명령이 `3`으로 종료되면 플레이테스트가 만들어졌는지 여부를 확인할 수 없었던 것입니다. 명령이 출력하는
명령으로 다시 시도하세요. 이 명령은 두 번째 플레이테스트를 만들지 않습니다.

## 4. 게시

3단계의 ID로 플레이테스트를 게시합니다.

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

명령은 플레이테스트가 `Live` 상태가 되거나 시작 날짜가 아직 되지 않은 경우 `Scheduled` 상태가 될 때까지
기다린 후 `0`으로 종료합니다. 다른 종료 코드는 플레이테스트가 아직 게시되지 않았음을 의미합니다.

| 종료 코드 | 의미 |
| - | - |
| 1 | 플레이테스트에 패키지, 대상 그룹 또는 연령 등급이 없는 등의 이유로 Partner Center의 검사가 실패했습니다. 아무것도 게시되지 않습니다. 명령이 나열하는 검사 항목을 수정하고 다시 게시하세요. |
| 2 | 게시가 실패했습니다. |
| 3 | 결과를 알 수 없습니다. 다시 게시하기 전에 `xbox playtest get`으로 플레이테스트를 확인하세요. |
| 4 | 5분이 지난 후에도 플레이테스트가 아직 게시 중입니다. 나중에 `xbox playtest get`으로 확인하세요. |

[플레이테스트 게시](https://docs.xbox.com/ko/tools/xbox-cli/commands/playtest.md#publishing-a-playtest)를 참조하세요.

## 5. 공유

플레이테스트가 라이브 상태가 되면 해당 대상 그룹의 테스터가 라이브러리에서 플레이테스트를 찾을 수 있습니다.

* 본체에서는 **Full Library**의 **Playtest** 필터 아래에 있습니다.
* PC에서는 XBOX 앱 **라이브러리**의 **Access** 필터 아래에 있습니다.

새로 추가된 테스터는 먼저 로그아웃했다가 다시 로그인해야 합니다.

테스터에게 링크를 보낼 수도 있습니다. Partner Center에 있는 게임의 Playtest 페이지에서 플레이테스트의
**Share**를 선택하고 `msxbox://playtest/`로 시작하는 링크를 복사합니다. CLI는 아직 이 링크를
표시할 수 없습니다. 이 링크는 플레이테스트 대상 그룹에 속한 사용자에게만 작동하며, PC에서는 XBOX 앱에서
플레이테스트를 엽니다.
[테스터와 플레이테스트 공유](https://learn.microsoft.com/gaming/game-publishing/concepts/playtest-preview#share-a-playtest-with-testers)를 참조하세요.

## 스크립트 및 연속 통합

서비스 주체를 사용하여 CI(연속 통합) 파이프라인에서 패키지를 업로드할 수 있습니다.
[패키지 업로드](https://docs.xbox.com/ko/tools/xbox-cli/commands/package.md#uploading-packages)를 참조하세요. `xbox package` 및
`xbox playtest` 명령은 아직 서비스 주체를 허용하지 않으므로 로그인한 사용자가 필요합니다.
[자동화(서비스 주체) 인증](https://docs.xbox.com/ko/tools/xbox-cli/authentication.md#automation-service-principal-authentication)을 참조하세요.

로그인한 상태에서 실행되는 스크립트에서는 `playtest create` 및 `playtest publish`에 `--confirm`을
전달하세요. 터미널이 없으면 확인을 요청할 수 없어 아무것도 변경하지 않기 때문입니다. 출력되는
JSON을 읽고 종료 코드를 확인하세요. 게시를 5분보다 오래 기다리려면
`--timeout`을 전달하세요.


## Related topics

- [Playtest 사용](https://docs.xbox.com/ko/publishing/game-publishing/concepts/playtest-preview.md)
- [시작하기](https://docs.xbox.com/ko/tools/xbox-cli/getting-started.md)
- [플레이테스트에서 XBOX services 사용](https://docs.xbox.com/ko/tools/xbox-cli/xbox-services-in-a-playtest.md)
- [Playtest](https://docs.xbox.com/ko/tools/xbox-cli/commands/playtest.md)
- [제품 변경 및 콘텐츠 업데이트](https://docs.xbox.com/ko/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-post-release-lifecycle.md)
