실제 적용 흐름이 궁금하신가요?

이용 시나리오 / 기기 등록하기

기기 등록

이해하기

기기 등록은 이용자가 직접 지정한 모바일 기기에서만 게임 접속을 허용하거나, 특정 PC를 지정/관리하여 로그인 시 접근을 제한하는 보안 기능이에요.

적용 방식

모바일의 경우, 게임별 정책에 따라 기기 등록의 적용 강도를 선택할 수 있어요. 기기 등록 화면은 플랫폼 공통 UI로 제공돼요.
PC의 경우, 플랫폼 기본 기능으로 제공돼요. (별도 연동 작업은 하지 않아도 돼요.)

연동 가이드

사전 준비

기본 연동 구조

기기 등록 기능은 스토브 Mobile SDK가 제공하는 플랫폼 공통 UI로 동작해요. CP사는 아래 영역을 구현해야 해요.

기기 등록 팝업·다이얼로그 문구는 아래 예시를 참고해 주세요.

개발하기

모바일 SDK

기기 등록 팝업 노출과 인게임 기기 관리 UI는 모두 Auth/AuthUI 모듈이 자동으로 처리해요. 게임 클라이언트는 두 가지 진입점(AuthUI.Login, AuthUI.ManageDevices)만 호출하면 되고, 이용자 응답에 따른 후속 동선을 결과 콜백에서 처리해요.

사전 준비

• 모듈: Auth, AuthUI 모듈을 적용해야 해요. SDK 설치는 SDK 다운로드 및 설치·개발 환경 설정 참고.
• 선행 조건: Auth.Initialize 완료 후 AuthUI.Login 흐름을 사용 중이어야 해요. 기기 등록 화면이 AuthUI.Login 내부에서 자동 노출돼요. 로그인 흐름은 로그인 가이드 참고.
• 권한·설정 값: 별도 단말 권한은 필요 없어요. 기기 등록 정책(필수/선택, device_setup_exemption)은 SDK Config에서 기술 담당자가 설정해요. (위 연동 가이드 → 사전 준비 참고)
• 의존 기능: 통합 로그인 UI(AuthUI.Login) + 인게임 설정 화면 (기기 관리/등록 버튼 배치 위치)

개발 흐름

MobileSDK가 자동 처리하는 두 가지 진입점이에요. 게임에서는 각 진입점의 호출 시점과 결과 분기만 처리하면 돼요.

1. 가입/로그인 시 — AuthUI.Login에서 자동 노출
   • 게임이 AuthUI.Login()을 호출 (평소 로그인 흐름과 동일)
   • SDK가 이용자의 기기 등록 상태를 확인하고, 필요 시 기기 등록 화면을 자동으로 노출
     • 필수 설정 정책 + 미등록 이용자 → 강제 노출
     • 선택 설정 정책 → 등록 이력이 있는 계정이 미등록 기기로 접근할 때만 노출
   • 이용자가 등록을 완료하면 콜백이 result.IsSuccessful로 반환 → 평소 로그인 후속 처리 진행
   • 이용자가 등록을 완료하지 않고 화면을 닫으면 콜백이 result.IsCanceled로 반환 → 게임 정책에 따른 후속 동선 처리
     • 권장: 안내 UI 노출 후 AuthUI.Login 재호출 (재호출하면 SDK가 기기 등록 화면을 다시 노출)
     • 로그아웃 처리는 이용자 이탈 위험이 있어 비권장
2. 인게임에서 — AuthUI.ManageDevices 호출
   • 인게임 설정 화면 등 적절한 위치에 기기 관리 / 기기 등록 버튼 배치
   • 버튼 노출 여부는 Auth.AccessToken.User의 두 값으로 판단 (아래 표 참고)
   • 버튼 클릭 시 AuthUI.ManageDevices() 호출 → SDK가 기기 등록·관리 화면을 자동으로 노출
   • 콜백 결과는 Auth.AccessToken.User.VerifiedDevice 값으로 분기
     • true: 등록된 기기 → 게임 유지
     • false: 미등록 기기 → 초기 화면 이동 후 재로그인 등 정책에 따른 후속 동선

트러블슈팅

샘플 코드

AuthUI.Login과 AuthUI.ManageDevices 두 가지 진입점의 호출/콜백 처리 예시예요. 플랫폼별로 제공해요.

1. AuthUI.Login — 기기 등록 화면 자동 노출 처리

AuthUI.Login은 평소 로그인 호출과 동일해요. 콜백에서 result.IsCanceled 분기를 추가해 기기 등록 미완료 시 후속 동선만 처리하면 돼요.

public void Login()
{
    AuthUI.Login((Result result, AccessToken accessToken) =>
    {
        if (result.IsSuccessful)
        {
            /** 로그인 성공 처리 ... (중략) **/
        }
        else if (result.IsCanceled)
        {
            /** 기기 등록 화면을 닫음(등록 미완료) → 게임 정책에 따라 처리 **/
            /** 권장: 안내 UI 노출 후 Login() 재호출 → 기기 등록 화면 재노출 **/
        }
        else
        {
            /** 기타 오류 처리 ... (중략) **/
        }
    });
}

2. AuthUI.ManageDevices — 인게임 버튼 클릭 시 호출

인게임 설정 화면 등에서 "기기 관리/등록" 버튼 클릭 시 호출해요. 호출 후 Auth.AccessToken.User.VerifiedDevice 값으로 후속 동선을 분기해요.

public void ManageDevices()
{
    if (Auth.AccessToken == null) return;

    AuthUI.ManageDevices((Result result) =>
    {
        if (Auth.AccessToken.User.VerifiedDevice)
        {
            /** 등록된 기기 → 게임 유지 **/
        }
        else
        {
            /** 미등록 기기 → 기기 등록 유도 (예: 초기 화면 이동 후 로그인 재시도) **/
        }
    });
}

서버

POST /auth-secure/v1.0/my-device/{game_id}/check를 호출해 이용자의 기기 등록 여부와 보조 인증 수단(보조 이메일 인증·휴대폰 점유인증) 등록 여부를 조회하는 영역이에요. 인게임 혜택 지급 분기, 보조 인증 수단 확인 등의 용도로 사용해요.

사전 준비

• API Access Token 발급이 선행돼야 해요. Authorization 헤더에 Bearer {API Access Token} 형태로 사용해요. 발급 절차는 인증 메뉴 → Server 가이드를 참고하세요.
• 클라이언트로부터 User Access Token을 매 요청마다 전달받는 구조여야 해요. 게임 서버에 캐싱하지 않아요.

개발 흐름

1. 클라이언트가 게임 서버에 User Access Token을 전달해요.
2. 게임 서버는 보유 중인 API Access Token의 잔여 유효기간을 확인하고, 필요 시 갱신해요.
3. POST /auth-secure/v1.0/my-device/{game_id}/check를 호출해요.
   • Path: {game_id}에 게임 ID를 채워요.
   • Headers: Authorization: Bearer {API Access Token}, caller-id: {service_id}_SERVER, Content-Type: application/json
   • Body: { "access_token": "{User Access Token}" }
4. 응답 code에 따라 분기해요.
   • code == 0 → value.device_registered로 기기 등록 여부를 판단해요.
     • true: 등록 완료 → 정상 진입 또는 인게임 혜택 지급
     • false: 미등록 → 클라이언트의 기기 등록 동선 안내 (Mobile SDK가 자동 처리)
   • code != 0 → 트러블슈팅 표 참고

트러블슈팅

응답 code 별 처리 방안이에요. 상세 응답 코드·메시지 스펙은 API & SDK 레퍼런스 메뉴를 참고하세요.

샘플 코드

기기 등록 및 인증 정보 조회(POST /auth-secure/v1.0/my-device/{game_id}/check) 호출 예제예요.

// Java 25 LTS — java.net.http.HttpClient + Jackson(ObjectMapper)
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;

ObjectMapper mapper = new ObjectMapper();
String baseUrl = "https://api.onstove.com";
String serviceId = "STOVE_GAME";
String callerId = serviceId + "_SERVER";

try (HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))
        .build()) {

    String body = mapper.writeValueAsString(Map.of(
            "access_token", userAccessToken));

    HttpRequest req = HttpRequest.newBuilder(
            URI.create(baseUrl + "/auth-secure/v1.0/my-device/" + serviceId + "/check"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiAccessToken)
            .header("caller-id", callerId)
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    JsonNode data = mapper.readTree(res.body());
    if (data.path("code").asInt() != 0) {
        // 트러블슈팅 표 참고 (40000 / 40101 / 40103 / 41002 등)
        throw new IllegalStateException("device check failed: " + data.path("code"));
    }
    JsonNode value = data.path("value");
    boolean deviceRegistered = value.path("device_registered").asBoolean();
    if (deviceRegistered) {
        // 기기 등록 완료 — 정상 진입 / 혜택 지급
    } else {
        // 기기 미등록 — 클라이언트의 기기 등록 동선 안내
    }
}

자주 묻는 질문