Steam 로그인 활용 가이드
Steam 로그인은 사용자가 자신의 Steam 계정으로 앱에 로그인하도록 하는 기능입니다. Steam은 사용자를 대신 인증해 주는 외부 인증 제공자이며, 앱은 그 인증 결과로 Hive Axyl 로그인 세션을 얻습니다. 세션은 로그인을 마쳐 Hive Axyl SDK가 사용자를 식별하고 있는 상태를 뜻합니다.
구현하려면 Steamworks 설정, Hive 콘솔 설정, Hive Axyl SDK 호출, 레시피 코드 호출, 앱 코드를 조합해야 합니다. 레시피 코드를 사용하면 자격 증명 획득부터 세션 활성화까지 필요한 호출이 메서드 하나로 줄어듭니다.
구현 범위
Steam 로그인을 구현하는 데 필요한 작업은 Steamworks에서 인증 정보를 준비하는 것에서 시작해, 로그인 결과에 맞는 화면을 띄우는 것으로 끝납니다.
각 단계의 작업은 아래 여섯 가지 구분 중 하나에 해당합니다.
| 구분 | 담당 | 내용 |
|---|---|---|
| 외부 콘솔 | 앱 운영자 | Steamworks에서 수행하는 설정입니다. |
| Hive 콘솔 | 앱 운영자 | Hive 콘솔에서 수행하는 설정입니다. |
| Hive Axyl SDK | 앱 개발자 | 앱에서 호출하는 Hive Axyl SDK 메서드입니다. |
| Add-on | 앱 개발자 | Steam 인증을 담당하는 Hive Axyl SDK 확장 패키지의 메서드를 앱이 직접 호출합니다. |
| 레시피 코드 | 앱 개발자 | 앱에서 호출하는 레시피 메서드입니다. |
| 앱 코드 | 앱 개발자 | Hive Axyl을 거치지 않고 앱이 직접 구현하는 부분입니다. |
Steam 로그인에는 Hive Axyl 서버 API 호출이 없습니다. Add-on은 대부분 레시피가 대신 호출하지만, Windows와 macOS에서는 앱이 Add-on을 직접 호출하는 단계가 하나 있습니다. 로그인이 끝난 뒤 인증 티켓을 반납하는 작업입니다. 파라미터의 의미와 응답 필드는 각 단계에서 연결한 상세 절차를 참조하세요.
레시피
Hive Axyl SDK는 로그인 기능을 세분화된 메서드로 제공합니다. Steam에서 자격 증명을 받는 Add-on 호출, 그 자격 증명으로 로그인하는 메서드, 토큰을 발급하는 메서드, 세션을 활성화하는 메서드가 각각 따로 있습니다. 사용자 한 명을 로그인시키는 데에도 호출 순서와 중간 실패 처리를 앱이 직접 조합해야 합니다.
레시피는 그 조합을 미리 완성해 둔 소스 코드입니다. 패키지가 아니라 프로젝트에 복사해서 사용합니다.
| 구분 | 위치 | 성격 |
|---|---|---|
| Hive Axyl SDK | Unity 패키지 com.com2usplatform.hiveaxyl.* | 설치해서 사용합니다. 인증 기능을 세분화된 메서드로 제공합니다. |
| 레시피 | Assets/Recipes/ProviderLogin/, Assets/Recipes/ProviderLogin.Steam/, Assets/Recipes/ProviderLogin.WebAuth/ | 복사해서 사용합니다. SDK 호출을 목적 단위로 묶은 순수 C# 코드입니다. |
| 사용 예제 | Assets/RecipeExamples/Authentication/ProviderLoginExample.cs | 읽고 참고하는 코드입니다. 모든 외부 인증 제공자에 공통인 로그인 흐름과 결과별로 앱이 구현해야 할 부분을 주석으로 설명합니다. |
레시피는 복사해서 사용하는 코드입니다
레시피는 앱에 복사되어 앱의 코드가 됩니다. 그대로 사용해도 되고 앱 정책에 맞게 수정해서 사용해도 됩니다.
로그인 레시피는 외부 인증 제공자 하나에 종속되지 않습니다. Steam 자격 증명을 받아 오는 부분만 ProviderLogin.Steam/과 ProviderLogin.WebAuth/가 담당하고, 그 뒤 과정은 Apple이나 Google Play Games 로그인과 같은 코드를 사용합니다.
레시피 지원 OS
Steam 로그인은 OS에 따라 자격 증명을 얻는 방법이 다르므로 레시피도 자격 증명 소스를 두 가지로 제공합니다. 자격 증명 소스는 Steam에서 사용자 식별자와 인증 결과를 받아오는 객체입니다. 앱은 실행 중인 OS에 맞는 소스를 골라 레시피에 전달합니다.
| 방식 | OS | 자격 증명 소스 | 인증 방법 |
|---|---|---|---|
| Steam 클라이언트 방식 | Windows, macOS | SteamCredentialSource | Steam 클라이언트에서 인증 티켓을 받습니다. 사용자는 이미 Steam 클라이언트에 로그인한 상태이므로 로그인 화면이 따로 뜨지 않습니다. |
| 브라우저 방식 | Android, iOS | SteamOpenIdCredentialSource | 브라우저에서 Steam 로그인 페이지를 엽니다. 사용자는 Steam 계정으로 직접 로그인하며, 로그인 결과는 Hive Axyl이 운영하는 중계 주소를 거쳐 앱으로 돌아옵니다. |
이 가이드는 두 방식을 위 이름으로 구분해 설명합니다. 두 소스는 받아 오는 값만 다르고 그 뒤 과정은 같습니다. 어느 쪽을 쓰든 레시피 호출 방법과 결과 처리 방법은 동일합니다.
각 소스는 필요한 Add-on이 등록된 환경에서만 동작합니다. Add-on이 등록되지 않은 환경에서 호출하면 Unavailable 오류를 반환하며, 이는 로그인이 거절된 것이 아니라 그 환경에서 Steam 로그인을 실행하지 못한다는 뜻입니다. Unity 에디터에서는 두 Add-on 모두 등록되지 않습니다.
앱이 직접 구현하는 부분
레시피는 자격 증명 획득부터 세션 활성화까지만 대신합니다. 아래 항목은 레시피 밖에서 앱이 구현합니다.
- 로그인 화면과 로그인 후 화면 전환
- 실행 중인 OS에 맞는 자격 증명 소스를 고르는 분기
- Steam 클라이언트 방식의 Steamworks 초기화와 콜백 처리, Steam ID64 읽기, 인증 티켓 반납
- 브라우저 방식에서 Steam이 돌려보낼 주소의 구성과 Android의 앱 콜백 스킴 등록
DeviceKey의 생성과 보관- 로그인으로 받은 세션 토큰의 보관
- 실패했을 때의 재시도 정책과 사용자 안내 메시지
공통 사전 준비
구현을 시작하기 전에 아래 항목을 먼저 준비하세요.
| 준비 항목 | 필수 여부 | 구분 | 확인할 곳 |
|---|---|---|---|
| Steam App ID 확인 | 필수 | 외부 콘솔 | 스토어 App ID 등록 |
| 프로젝트 생성 | 필수 | Hive 콘솔 | 프로젝트 생성 |
| App ID 생성 | 필수 | Hive 콘솔 | App ID 생성 |
| Store App ID 등록 | 필수 | Hive 콘솔 | Store App ID 등록 |
| Client ID 확인 | 필수 | Hive 콘솔 | 보안 키 획득 |
| Unity 프로젝트에 SDK 연결 | 필수 | Hive Axyl SDK | Unity 프로젝트에 SDK 연결 |
App ID는 실행 환경과 스토어의 조합으로 만듭니다. Steam으로 배포하는 Windows나 macOS 빌드는 스토어로 Steam을 고르고, Store App ID에는 Steamworks에서 확인한 Steam App ID를 입력하세요. Android와 iOS 빌드도 함께 서비스한다면 그 조합의 App ID를 따로 만드세요. App ID는 SDK를 초기화할 때 입력하고 Client ID는 로그인할 때 입력하므로 둘 다 먼저 확인해야 합니다. SDK를 연결해 두어야 이어지는 단계에서 인증 모듈과 Add-on을 설치합니다.
다음 단계
사전 준비를 마쳤다면 Steam 로그인 구현하기를 시작하세요.