GS2-Account 마스터 데이터 레퍼런스

마스터 데이터 포맷과 임포트할 각종 모델의 레퍼런스

마스터 데이터 포맷

{
  "version": "2024-07-30",
  "takeOverTypeModels": [
    {
      "type": "[int]슬롯 번호",
      "metadata": "[string?]메타데이터",
      "takeOverMethod": "[문자열 열거형]인계 방식",
      "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에서 획득하는 추가 반환값"
        ]
      },
      "issuedCodeSetting": {
        "expiresDays": "[int]유효 기간(일)",
        "maxFailedAttempts": "[int?]실패 상한 횟수",
        "deleteOnUse": "[bool]사용하면 코드를 만료시킬지 여부"
      }
    }
  ]
}
타입활성화 조건필수기본값값 제한설명
versionstring
✓
2024-07-30마스터 데이터 포맷 버전
takeOverTypeModelsList<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 계정 정보를 저장하는 등의 방식이 상정되어 있습니다.
어디까지나 이 인계 정보는 데이터 홀더이며, 소셜 계정과의 인증 메커니즘은 별도로 준비해야 합니다.

타입활성화 조건필수기본값값 제한설명
takeOverTypeModelIdstring
※
~ 1024자인계 정보 타입 모델 GRN
※ 서버가 자동으로 설정
typeint
✓
0 ~ 1024슬롯 번호
0부터 1024까지의 범위로 지정되며, 서로 다른 인계 정보를 구분합니다.
metadatastring~ 2048자메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
takeOverMethod문자열 열거형
enum {
  “openIdConnect”,
  “issuedCode”
}
“openIdConnect”인계 방식
이 슬롯의 인계 정보를 어떻게 등록하고 대조할지를 나타냅니다.
openIdConnect 는 OpenID Connect 준수 Identity Provider(IdP)가 발행한 ID 토큰으로 인계합니다.
issuedCode 는 GS2가 발행한 사용자 ID와 비밀번호(IssueTakeOverCode)로 인계합니다.
정의설명
openIdConnectOpenID Connect
issuedCode발행한 코드
openIdConnectSettingOpenIdConnectSetting{takeOverMethod} == “openIdConnect”
✓※
OpenID Connect 설정
OpenID Connect 준수 Identity Provider(IdP)와 연동하기 위한 설정입니다. 디스커버리 URL, 클라이언트 인증 정보, Apple Sign In 파라미터 등 플랫폼별 설정이 포함됩니다.
※ takeOverMethod이(가) “openIdConnect” 이면 필수
issuedCodeSettingIssuedCodeSetting{takeOverMethod} == “issuedCode”
✓※
발행하는 인계 코드 설정
IssueTakeOverCode로 발행하는 코드의 유효 기간, 만료될 때까지 허용하는 실패 횟수, 사용하면 만료시킬지 여부의 설정입니다.
※ takeOverMethod이(가) “issuedCode” 이면 필수

OpenIdConnectSetting

OpenID Connect 설정

OpenID Connect 준수 IdP의 설정을 등록함으로써 계정의 인계 정보로 IdP 연동을 이용할 수 있게 됩니다.

타입활성화 조건필수기본값값 제한설명
configurationPathstring
✓
~ 1024자OpenID Connect 설정 URL
OpenID Connect 제공자의 디스커버리 엔드포인트 URL입니다. well-known 형식(예: https://example.com/.well-known/openid-configuration)을 따라야 합니다.
clientIdstring
✓
~ 1024자클라이언트 ID
IdP에 등록된 애플리케이션의 클라이언트 ID입니다.
clientSecretstring{configurationPath} != “https://appleid.apple.com/.well-known/openid-configuration”
✓※
~ 1024자클라이언트 시크릿
※ configurationPath가 “https://appleid.apple.com/.well-known/openid-configuration” 이외의 다른 IdP 연동인 경우 필수
appleTeamIdstring{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” 이면 필수
appleKeyIdstring{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” 이면 필수
applePrivateKeyPemstring{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” 이면 필수
doneEndpointUrlstring~ 1024자인증 완료 시 이동하는 URL
지정하지 않으면 /authorization/done으로 이동합니다.
쿼리 스트링에 id_token이 부여됩니다.
additionalScopeValuesList<ScopeValue>[]0 ~ 10 itemsOpenID Connect에서 획득하는 추가 스코프
기본 OpenID Connect 스코프 외에 IdP에 요청하는 추가 OAuth 스코프입니다. 인증 시 추가 사용자 정보를 취득할 수 있습니다.
additionalReturnValuesList<string>[]0 ~ 10 itemsOpenID Connect에서 획득하는 추가 반환값
ID 토큰 또는 UserInfo 응답에서 반환값에 포함할 추가 클레임 이름입니다. 지정된 클레임이 추출되어 표준 인증 결과와 함께 반환됩니다.

IssuedCodeSetting

발행하는 인계 코드 설정

인계용 사용자 ID와 비밀번호를 플레이어가 정하는 것이 아니라 GS2가 발행하는 인계 정보의 설정입니다.
발행한 코드는 지정한 일수가 지나면 만료됩니다. 사용했을 때나 비밀번호를 정해진 횟수만큼 틀렸을 때 만료시킬 수도 있습니다.

타입활성화 조건필수기본값값 제한설명
expiresDaysint
✓
1 ~ 365유효 기간(일)
코드를 발행한 후 만료될 때까지의 일수입니다.
만료된 코드로는 인계를 실행할 수 없습니다.
maxFailedAttemptsint1 ~ 100실패 상한 횟수
비밀번호를 이 횟수만큼 틀리면 발행한 코드는 만료됩니다.
코드로 인계에 성공하면 횟수는 0으로 돌아갑니다.
생략한 경우에는 몇 번을 틀려도 만료되지 않습니다.
deleteOnUsebooltrue사용하면 코드를 만료시킬지 여부
활성화하면 발행한 코드는 인계에 한 번 성공한 시점에 만료됩니다.
비활성화하면 유효 기간이 끝날 때까지 몇 번이든 사용할 수 있습니다.

ScopeValue

스코프 값

OpenID Connect 인증 시 취득되는 추가 OAuth 스코프 값을 나타내는 키-값 쌍입니다. 표준 OpenID Connect 클레임 외에 IdP로부터 취득한 추가 데이터를 저장하는 데 사용됩니다.

타입활성화 조건필수기본값값 제한설명
keystring
✓
~ 64자이름
인증 시 IdP에 요청한 스코프 이름입니다.
valuestring~ 51200자값
해당 스코프에 대해 IdP로부터 반환된 값입니다.