콘텐츠로 이동

공통 규약

Hive Axyl SDK 레퍼런스 페이지 구성, 표기 규칙, 모든 모듈에 공통으로 적용되는 호출 규약을 설명합니다.

페이지 구성

레퍼런스는 아래 세 종류의 페이지로 구성됩니다.

  • 런타임 레퍼런스: 모든 모듈에 공통으로 적용되는 Core 모듈의 초기화, 설정, 세션, 호출 컨텍스트, 결과와 오류 모델
  • 모듈 개요: 패키지, 지원 플랫폼, 등록 메서드, 모듈이 제공하는 인터페이스 목록, 앱 코드가 직접 사용하는 진입 클래스
  • 인터페이스 레퍼런스: 인터페이스가 제공하는 메서드, 각 메서드의 파라미터와 결과 케이스, 요청·응답 데이터 타입, 열거형

인터페이스 레퍼런스 페이지는 아래 순서로 구성됩니다.

  1. 등록과 획득: 모듈을 등록하고 인터페이스를 가져오는 코드
  2. 메서드 요약: 메서드 전체 목록과 각 메서드의 용도
  3. 메서드: 메서드별 시그니처, 파라미터, 결과 케이스
  4. 데이터 타입: 요청·응답 본문에 사용하는 타입
  5. 열거형: 필드에 사용하는 열거 값

표기 규칙

타입 표기

타입은 앱 코드에서 실제로 사용하는 C# 타입을 기준으로 표기합니다. 필드도 C# 프로퍼티 이름으로 표기합니다.

서버와 주고받는 JSON 필드명이 필요하다면 C# 프로퍼티 이름의 첫 글자를 소문자로 바꾼 형태로 계산하세요. 예를 들어 PlayerId는 playerId, CodeChallengeMethod는 codeChallengeMethod입니다. 앱 코드는 JSON을 직접 다루지 않으므로, 이 변환은 서버 로그를 확인하거나 앱 서버와 규약을 맞출 때만 필요합니다.

열거형은 C# 멤버 이름과 와이어 값이 다릅니다. 앱 코드에는 C# 멤버 이름을 입력하세요. 각 열거형 표에 두 값을 함께 싣습니다.

// C# 멤버 이름은 Guest, 직렬화되어 서버로 전달되는 값은 GUEST입니다.
ProviderId = Provider.Guest

필수 여부

필드 표의 '필수 여부' 열은 아래 두 값으로 표기합니다.

  • Required: 요청 필드라면 반드시 값을 지정해야 하고, 응답 필드라면 항상 값이 담깁니다.
  • Optional: 요청 필드라면 생략할 수 있고, 응답 필드라면 값이 없을 수 있으므로 null 여부를 확인하세요.

인증 요구

메서드 요약 표의 '인증' 열은 호출 시점에 로그인 세션이 필요한지를 나타냅니다.

  • 불필요: 세션 없이 호출할 수 있어 로그인 전에도 사용하는 메서드
  • 세션 필요: 로그인해 세션을 등록한 뒤에만 호출할 수 있는 메서드
  • 액세스 토큰 필요: 현재 세션이 아니라 ApiCallContext.WithAccessToken()으로 실어 보낸 액세스 토큰으로 인증하는 메서드

결과 모델

Hive Axyl SDK 메서드는 호출 실패를 예외가 아니라 결과 객체로 반환합니다. 결과 갈래와 분기 방법은 Core 결과 모델에, 앱 코드를 고쳐야 하는 문제에서 발생하는 예외는 예외에 정리되어 있습니다.

공통 Failure 코드

아래 세 가지는 IAuthService와 ITokenService가 반환하는 공통 Failure 코드입니다. 서버가 코드로 응답하지만 기능 관점의 결과가 아니므로 Outcome이 아닌 Failure로 분기하며, 원인 코드는 Failure.Problem.ExternalCode에 담깁니다. 공통 Failure 코드의 목록은 모듈마다 다르므로 다른 모듈의 목록은 모듈별 공통 Failure 코드를 참조하세요.

  • invalid_parameter: 요청 파라미터가 형식에 맞지 않는 경우
  • missing_field: X-App-Id 헤더를 보내지 않은 경우처럼 필수 필드나 필수 헤더 자체가 누락된 경우
  • missing_app_id: X-App-Id 헤더는 보냈지만 값이 비어 있는 경우

세 코드는 모두 앱 코드의 호출 방식을 고쳐야 해결됩니다. 사용자에게 재시도를 안내할 대상이 아닙니다.

호출 컨텍스트

Hive Axyl 서버를 호출하는 메서드는 마지막 파라미터로 ApiCallContext?를 받습니다. 네이티브 기능을 감싸는 Add-on 메서드는 대신 CancellationToken을 받습니다. 둘 다 생략할 수 있고, 생략하면 기본값이 적용됩니다.

지정할 수 있는 값과 사용 예시는 Core 호출 컨텍스트에 정리되어 있습니다.

Add-on 사용 시 주의

Add-on은 지원 플랫폼에서만 등록됩니다. Unity 에디터나 지원하지 않는 플랫폼에서는 등록되지 않으므로, HiveCore.Resolve<T>() 대신 HiveCore.TryResolve<T>()로 확인한 뒤 사용하세요.

등록되지 않은 타입을 Resolve<T>()로 요청하면 RegistrationNotFoundException이 발생합니다.