> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Account 마스터 데이터 레퍼런스
마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스
## 마스터 데이터 포맷
**JSON**
```json
{
"version": "2024-07-30",
"takeOverTypeModels": [
{
"type": "[int]슬롯 번호",
"metadata": "[string?]메타데이터",
"openIdConnectSetting": {
"configurationPath": "[string]OpenID Connect 설정 URL",
"clientId": "[string]클라이언트 ID",
"clientSecret": "[string]클라이언트 시크릿",
"appleTeamId": "[string]Apple Developer 팀 ID",
"appleKeyId": "[string]Apple에 등록된 키 ID",
"applePrivateKeyPem": "[string]Apple로부터 받은 비밀 키",
"doneEndpointUrl": "[string?]인증 완료 시 이동하는 URL",
"additionalScopeValues": [
{
"key": "[string]이름",
"value": "[string?]값"
}
],
"additionalReturnValues": [
"[string]OpenID Connect에서 획득하는 추가 반환값"
]
}
}
]
}
```
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| version | string | | ✓ | 2024-07-30 | | 마스터 데이터 포맷 버전 |
| takeOverTypeModels | [List<TakeOverTypeModel>](#takeovertypemodel) | | | | ~ 1000 items | 인계 정보 타입 모델
인계 정보를 정의하는 모델입니다.
인계 정보란 디바이스 기종 변경이나 플랫폼 간 계정 이동·공유 시에 사용하는 정보입니다.
개인을 식별하는 고유한 문자열과 비밀번호로 구성되며, 그 올바른 조합을 입력함으로써 Account(익명 계정)를 취득할 수 있습니다.
하나의 Account에 대해 여러 개의 인계 정보를 설정할 수 있습니다.
여러 개의 인계 정보를 설정하려면 각각 다른 슬롯을 지정해야 합니다.
슬롯은 0~1024를 지정할 수 있으므로 최대 1,025종류의 인계 정보를 설정할 수 있습니다.
구체적인 예로는 0에는 Sign in with Apple의 계정 정보를, 1에는 Google 계정 정보를 저장하는 등의 방식이 상정되어 있습니다.
어디까지나 이 인계 정보는 데이터 홀더이며, 소셜 계정과의 인증 메커니즘은 별도로 준비해야 합니다. |
## 모델
### TakeOverTypeModel
인계 정보 타입 모델
인계 정보를 정의하는 모델입니다.
인계 정보란 디바이스 기종 변경이나 플랫폼 간 계정 이동·공유 시에 사용하는 정보입니다.
개인을 식별하는 고유한 문자열과 비밀번호로 구성되며, 그 올바른 조합을 입력함으로써 Account(익명 계정)를 취득할 수 있습니다.
하나의 Account에 대해 여러 개의 인계 정보를 설정할 수 있습니다.
여러 개의 인계 정보를 설정하려면 각각 다른 슬롯을 지정해야 합니다.
슬롯은 0~1024를 지정할 수 있으므로 최대 1,025종류의 인계 정보를 설정할 수 있습니다.
구체적인 예로는 0에는 Sign in with Apple의 계정 정보를, 1에는 Google 계정 정보를 저장하는 등의 방식이 상정되어 있습니다.
어디까지나 이 인계 정보는 데이터 홀더이며, 소셜 계정과의 인증 메커니즘은 별도로 준비해야 합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| takeOverTypeModelId | string | | ※ | | ~ 1024자 | 인계 정보 타입 모델 GRN
※ 서버가 자동으로 설정 |
| type | int | | ✓ | | 0 ~ 1024 | 슬롯 번호
0부터 1024까지의 범위로 지정되며, 서로 다른 인계 정보를 구분합니다. |
| metadata | string | | | | ~ 2048자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| openIdConnectSetting | [OpenIdConnectSetting](#openidconnectsetting) | | ✓ | | | OpenID Connect 설정
OpenID Connect 준수 Identity Provider(IdP)와 연동하기 위한 설정입니다. 디스커버리 URL, 클라이언트 인증 정보, Apple Sign In 파라미터 등 플랫폼별 설정이 포함됩니다. |
---
### OpenIdConnectSetting
OpenID Connect 설정
OpenID Connect 준수 IdP의 설정을 등록함으로써 계정의 인계 정보로 IdP 연동을 이용할 수 있게 됩니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| configurationPath | string | | ✓ | | ~ 1024자 | OpenID Connect 설정 URL
OpenID Connect 제공자의 디스커버리 엔드포인트 URL입니다. well-known 형식(예: https\://example.com/.well-known/openid-configuration)을 따라야 합니다. |
| clientId | string | | ✓ | | ~ 1024자 | 클라이언트 ID
IdP에 등록된 애플리케이션의 클라이언트 ID입니다. |
| clientSecret | string | {configurationPath} != "https\://appleid.apple.com/.well-known/openid-configuration" | ✓※ | | ~ 1024자 | 클라이언트 시크릿
※ configurationPath가 "https\://appleid.apple.com/.well-known/openid-configuration" 이외의 다른 IdP 연동인 경우 필수 |
| appleTeamId | string | {configurationPath} == "https\://appleid.apple.com/.well-known/openid-configuration" | ✓※ | | ~ 1024자 | Apple Developer 팀 ID
Apple Developer 계정의 팀 ID입니다. Sign in with Apple 인증에 필요합니다.
※ configurationPath이(가) "https\://appleid.apple.com/.well-known/openid-configuration" 이면 필수 |
| appleKeyId | string | {configurationPath} == "https\://appleid.apple.com/.well-known/openid-configuration" | ✓※ | | ~ 1024자 | Apple에 등록된 키 ID
Sign in with Apple용으로 Apple Developer 계정에 등록된 키 ID입니다.
※ configurationPath이(가) "https\://appleid.apple.com/.well-known/openid-configuration" 이면 필수 |
| applePrivateKeyPem | string | {configurationPath} == "https\://appleid.apple.com/.well-known/openid-configuration" | ✓※ | | ~ 10240자 | Apple로부터 받은 비밀 키
Apple Developer 포털에서 다운로드한 PEM 형식의 비밀 키입니다. Sign in with Apple 인증에 필요합니다.
※ configurationPath이(가) "https\://appleid.apple.com/.well-known/openid-configuration" 이면 필수 |
| doneEndpointUrl | string | | | | ~ 1024자 | 인증 완료 시 이동하는 URL
지정하지 않으면 /authorization/done으로 이동합니다.
쿼리 스트링에 id_token이 부여됩니다. |
| additionalScopeValues | [List<ScopeValue>](#scopevalue) | | | [] | 0 ~ 10 items | OpenID Connect에서 획득하는 추가 스코프
기본 OpenID Connect 스코프 외에 IdP에 요청하는 추가 OAuth 스코프입니다. 인증 시 추가 사용자 정보를 취득할 수 있습니다. |
| additionalReturnValues | List<string> | | | [] | 0 ~ 10 items | OpenID Connect에서 획득하는 추가 반환값
ID 토큰 또는 UserInfo 응답에서 반환값에 포함할 추가 클레임 이름입니다. 지정된 클레임이 추출되어 표준 인증 결과와 함께 반환됩니다. |
---
### ScopeValue
스코프 값
OpenID Connect 인증 시 취득되는 추가 OAuth 스코프 값을 나타내는 키-값 쌍입니다. 표준 OpenID Connect 클레임 외에 IdP로부터 취득한 추가 데이터를 저장하는 데 사용됩니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string | | ✓ | | ~ 64자 | 이름
인증 시 IdP에 요청한 스코프 이름입니다. |
| value | string | | | | ~ 51200자 | 값
해당 스코프에 대해 IdP로부터 반환된 값입니다. |
---