Hive를 적용하는 방법은 여러분이 사용하는 게임 엔진이나 게임 앱이 구동되는 플랫폼이 무엇인지에 따라 다릅니다. 그렇지만 Hive에 대한 설정값은 공통적으로 hive_config.xml이라는 파일에 정의합니다. 이 파일은 여러분의 게임 프로젝트에 반드시 포함되어야 합니다. hive_config.xml을 이용하여 설정값을 쉽게 저장/변경할 수 있으며 게임이 실행된 이후에는 Hive가 제공하는 Configuration 클래스의 여러 메서드를 이용해 런타임의 설정값을 수정할 수도 있습니다.

설정 조회 및 변경

파일에 설정하기

Hive SDK의 설정 파일은 xml 기반으로 구성되어 있으며, Hive 클라이언트는 hive_config.xml 파일에 있는 값으로 초기화합니다. 앱 실행 중 변경되지 않는 정적인 항목은 모두 파일에서 설정하기를 권장합니다. 설정 파일 이름은 반드시 hive_config.xml이어야 하며 아래에 위치해야 합니다.

파일 저장 경로
  • iOS: <프로젝트_루트>/Assets/Plugins/iOS/
  • Android
         –   Unity 2021 이상: <프로젝트_루트>/Assets/HiveSDK/hive.androidlib/src/main/res/raw
         –   Unity 2021 미만: <프로젝트_루트>/Assets/Plugins/Android/res/raw/

  • 설정 가능 항목에서 요소별 설명과 권한을 확인할 수 있습니다.

    게임 실행 중 조회 및 변경하기

    파일을 이용한 설정 외에도 게임 실행 중 Hive 설정값을 조회하거나 변경할 수 있습니다. 이를 위해 Configuration 클래스에서는 Hive 설정값의 각 요소 이름 앞에 get이나 set을 붙인 메서드를 제공합니다. 예를 들어 게임 서버 값을 조회할 때는 getServerId() 메서드를, 변경할 때는 setServerId() 메서드를 이용할 수 있습니다. 게임 언어 값처럼 setGameLanguage() 메서드를 이용해 변경할 수는 있지만 조회할 메서드가 제공되지 않는 경우도 있습니다. 자세한 내용은 설정 가능 항목에서 요소별 get/set 권한을 확인하세요.

    게임 실행 중 Hive 설정을 변경해야 하는 경우는 다음과 같습니다.

    • Hive SDK 초기화 전
      Hive SDK를 초기화하기 전 게임 서버나 게임 언어를 Configuration 클래스의 API 설정에 반영합니다.
    • Hive SDK 초기화 후 서버 점검 팝업을 띄우기 전, 유저가 게임 서버를 선택하는 경우
      Hive SDK를 초기화한 뒤 게임 서버 선택 UI를 노출하고, 유저가 고른 게임 서버를 Hive 설정에 반영합니다. 이 과정을 실행한 후 서버 점검 팝업을 띄웁니다.
    • 게임 진입 후, 게임 설정에서 유저가 게임 언어 또는 게임 서버를 변경하는 경우
      게임을 플레이하는 도중에 게임 설정이나 다른 메뉴에서 게임 서버 또는 게임 언어 변경 UI를 구성할 수 있습니다. 유저가 해당 UI를 이용해 서버나 언어를 변경했다면 이 내용을 Configuration 클래스의 API 설정에도 반영해 주세요.

      • 게임 서버 선택 UI
      • 게임 언어 선택 UI
    • 그 외 게임 기획에 따라 게임 정보가 변경되는 경우
      위에 언급한 상황 외에도 Hive 설정값과 매칭하는 게임 정보가 변경되는 경우라면 Configuration 클래스의 API 설정에 항상 반영해야 합니다.

    예를 들어 파일에서 zone 필드 값을 sandbox로 설정했더라도, Configuration 클래스를 이용해 이 값을 real로 변경하고 SDK를 초기화하면 Hive는 real을 기준으로 동작합니다. hive_config.xml 파일의 zone 필드 값은 여전히 sandbox를 유지합니다.

    setZone 함수는 setup 함수를 호출하기 전에 호출해야 정상 작동합니다.

    다음은 유저의 zone 설정을 변경하는 예제 코드입니다.

    Unity®

    API Reference: hive.Configuration.setZone

    C++

    API Reference: hive::Configuration::setZone

    Kotlin

    API Reference: Configuration.setZone

    Java

    API Reference: Configuration.setZone

    Swift

    API Reference: ConfigurationInterface.setZone

    Objective-C

    API Reference: HIVEConfiguration:setZone

     

    Hive 테마 설정

    hiveDark를 사용하여 어두운 테마를 노출 할 수 있습니다. 기본값은 hiveLight입니다.

    Unity®

    API Reference: hive.Configuration.setHiveTheme

    C++

    API Reference: hive::Configuration::setHiveTheme

    Kotlin

    API Reference: Configuration.setHiveTheme

    Java

    API Reference: Configuration.setHiveTheme

    Swift

    API Reference: HIVEConfiguration:setHiveTheme

    Objective-C

    API Reference: HIVEConfiguration:setHiveTheme

    로그 타입 설정

    Logger.setLogFilter API를 사용하여 Hive 로그 타입을 설정할 수 있습니다. 아래 6가지 유형 중 LogType.Verbose이 기본 설정값입니다.

    • LogType.Verbose: 개발 단계 출력 로그
    • LogType.Debug: 전체 단계 상세 로그
    • LogType.Info: Hive SDK 진행 단계 및 결과 콜백 (권장)
    • LogType.Warning: 예기치 않은 상황이 발생했으나, 게임 실행에 영향이 없는 에러
    • LogType.Error: 설정 정보 누락 및 게임 실행에 영향을 주는 에러
    • LogType.None: 어떠한 로그도 출력하지 않음
    • 로그 타입 순서는 다음과 같이 높은 수준에서 낮은 수준으로 구분되며, 설정한 로그 타입보다 낮은 수준만 출력됩니다.
      • Verbose > Debug > Info > Waring > Error > None
    • Configuration 클래스의 useLogtrue로 설정하는 경우에만 해당 설정이 유효합니다.
    Unity®

    C++

    Java

    Kotlin

    Objective-C

    Swift

     

    조회 가능 항목

    Configuration 클래스 메서드로로 값 조회만 가능한 항목들은 아래와 같습니다.

    항목 설명
    hiveSDKVersion Hive SDK 버전입니다.
    referenceSDKVersion Hive SDK가 참조하는 SDK 버전입니다.
    hiveCountry Hive SDK 서버에서 판단한 국가 코드입니다.

    설정 가능 항목

    hive_config.xml 파일

    hive_config.xml 파일로만 설정 가능한 항목들은 다음과 같습니다.

    항목 설명
    providers 서드 파티 라이브러리에 대한 속성값을 지정합니다.
    facebook

    providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 Facebook 관련 설정을 정의합니다.

    Facebook SDK를 사용할 때 Hive SDK에서 기본으로 설정하는 email 권한(Facebook 계정 이메일 주소 접근)과 public_profile(Facebook 공개 프로필 접근) 권한 외에 추가 권한이 필요하다면, Facebook 콘솔에서 해당 권한을 요청한 후 hive_config.xml에 요소로 추가해야 합니다.

    Hive SDK v4 Unity Windows 사용 시 Facebook 로그인을 구현하려면, 이 요소 내에 id 속성을 추가하고 속성값으로 앱 ID를 입력해야 합니다. 앱 ID는 앱을 만든 후에 Meta 앱 대시보드에서 확인할 수 있습니다.

    google

    providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 Google 관련 설정을 추가합니다.

    데스크톱에서 Google 로그인을 구현하려면, 이 요소 내에 clientId 속성을 추가하고 속성값으로 Google Cloud Console에서 발급받은 Client ID를 입력해야 합니다.

    Steam Deck에서 Google 로그인을 구현하려면(Hive SDK v4 Unity Windows 22.0.0 이상), 이 요소 내에 deviceFlowClientId 속성을 추가하고 속성값으로 Google Cloud Console에서 발급받은 Client ID를 입력해야 합니다.

    wechat providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 WeChat 관련 설정을 추가합니다.
    qq providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 QQ 관련 설정을 추가합니다.
    vk providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 VK 관련 설정을 추가합니다.
    line providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 LINE 관련 설정을 추가합니다.
    weverse providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 Weverse 관련 설정을 추가합니다.
    signinwithapple

    providers 요소에 속하는 요소로, 인증 v4로 인증할 때 사용하는 Sign-in-with-Apple 관련 설정을 추가합니다. (Android, Windows에서 Apple 계정으로 로그인할 때 사용합니다.) (+4.15.6)

    Android, Windows에서 Sign-in-with-Apple 로그인을 구현하려면, 이 요소 내에 serviceid 속성을 추가하고 속성값으로 Apple 개발자 센터에서 발급받은 Services ID를 입력해야 합니다.

    Adjust providers 요소에 속하는 요소로, 마켓 성과 측정 도구 Adjust를 사용하기 위한 관련 설정을 추가합니다.
    Singular providers 요소에 속하는 요소로, 마켓 성과 측정 도구 Singular를 사용하기 위한 관련 설정을 추가합니다.
    AppsFlyer providers 요소에 속하는 요소로, 마켓 성과 측정 도구 AppsFlyer를 사용하기 위한 관련 설정을 추가합니다.
    Firebase providers 요소에 속하는 요소로, 마켓 성과 측정 도구 Firebase Analytics를 사용하기 위한 관련 설정을 추가합니다. (+4.16.1)
    unsupportedUAShareType 게임 초대 메세지와 초대 링크를 소셜 미디어로 공유 시, 사용하지 않을 SNS를 지정합니다. Android 플랫폼만 해당합니다.
    saveAnalyticsLogBeforeCrash

    iOS 전용 기능으로, 앱이 NSException 타입 에러 또는 Unix singal 타입 에러 때문에 강제 종료되기 직전 상황을 감지하여 서버에 전송하지 않고 대기중인 Hive 애널리틱스 로그를 파일로 저장합니다. 외부 서드 파티 크래시 리포터를 이용할 경우 충돌 방지를 위해 false로 설정하여 비활성화 해야 합니다. 4.16.3 미만에서 사용되었던 useCrashReport 값은 saveAnalyticsLogBeforeCrash 값으로 사용됩니다. (+v4.16.3)

    기본 설정 값이 true에서 false로 변경되었습니다(+v4.24.2.0).

    hive_config.xml 예제

    hive_config.xml 파일과 Configuration 클래스 메서드

    Configuration 클래스와 hive_config.xml 파일로 설정 가능한 항목들은 아래와 같습니다.

     

    항목 설명
    appId 게임 빌드 식별자입니다. 이 항목이 없으면 Android에서는 앱의 기본 패키지명을, iOS에서는 번들 ID를 사용합니다.
    serverId 게임에서 서버를 지역별로 분리 운영할 때 확인할 수 있는 각 게임 서버 식별자입니다. Hive 식별자 정책에 따라 작성되어야 합니다.
    zone Hive 클라이언트가 접속할 서버입니다.

    • real: 운영 서버
    • sandbox: 테스트 서버
    useLog Hive 클라이언트의 내부 동작에 대한 로그 활성화 여부입니다. 로그를 활성화하면 개발 도구 화면에 로그를 출력합니다.

    • true: 로그 활성화
    • false: 로그 비활성화
    company 게임 퍼블리싱 업체입니다.

    • C2S: 컴투스 게임
    • GVI: 컴투스홀딩스 게임
    channel 게임 앱에서 사용하는 로그인 서비스 플랫폼입니다. C2S: Hive 플랫폼 (기본값)
    market 인앱 구매를 결제할 마켓입니다.

    • GO: Google Play Store
    • LE: Com2uS Lebi
    • AP: Apple App Store
    httpConnectTimeout Hive 클라이언트 내부에서 사용하는 HTTP Connect의 타임아웃 시간(초)입니다. 기본 값은 8초로 설정되어 있으며 특수한 상황이 아닌 이상 값 변경을 금지합니다.
    httpReadTimeout Hive 클라이언트 내부에서 사용하는 HTTP Read 타임아웃 시간(초)입니다. 기본값은 8초로 설정되어 있으며 특수한 상황이 아닌 이상 값 변경을 금지합니다.
    maxGameLogSize 비정형 데이터 파일로 저장하는 게임 로그의 최대 저장 개수입니다. Hive 애널리틱스 v2에서 이 값을 수집합니다. 기본 값은 50개로 설정되어 있으며 특수한 상황이 아닌 이상 값 변경을 금지합니다.
    gameLanguage Hive SDK에 설정하는 게임 언어입니다.
    ageGateU13 COPPA ageGateU13 적용 여부입니다. Hive SDK에 COPPA ageGateU13을 적용하려면, Hive 콘솔에 COPPA 약관을 등록한 후 Hive SDK를 초기화하기 전에 이 값을 true로 설정해야 합니다. COPPA ageGateU13을 적용하지 않으려면, Hive 콘솔에 COPPA 약관이 아닌 다른 약관을 등록한 상태에서 Hive SDK를 초기화하기 전에 이 값을 false로 설정해야 합니다.

    • true: Hive SDK에 COPPA ageGateU13을 적용
    • false: Hive SDK에 COPPA ageGateU13을 적용하지 않음
    agreementDetermineBase 약관 동의를 받는 기준을 결정합니다. device 또는 account를 선택할 수 있으며 기본값은 device입니다.

    • device 선택 시 약관 동의 팝업을 초기화 단계인 AuthV4.setup() 실행중에 노출하며 기기 기반으로 한번만 동의를 받습니다. 기기 기반으로 일단 동의를 받으면, 같은 기기에서 유저가 다른 계정으로 로그인해도 약관 동의를 받지 않습니다. resetAgreement()로 약관 동의 기록을 지울 수 있습니다.
    • account 선택 시 약관 동의 팝업을 로그인중에 노출하며 PlayerId 별로 한번만 동의를 받습니다. COPPA ageGateU13을 적용하지 않을 때에만 사용할 수 있습니다. resetAgreement()로 약관 동의 기록을 지울 수 없습니다. 마케팅 추적 도구들은 약관 동의 이후부터 동작합니다.

    Configuration 클래스 메서드

    Configuration 클래스 메서드로만 설정 가능한 항목들은 아래와 같습니다.

     

    항목 설명
    analyticsSendLimit 로그 전송 주기마다 전송할 로그의 최대치입니다. 기본 값은 5로 설정되어 있습니다.
    analyticsQueueLimit 쌓을 수 있는 로그의 최대치입니다. 기본 값은 50으로 설정되어 있습니다.
    analyticsSendCycle 로그 전송 주기입니다. 초로 설정 가능하며 설정한 주기마다 애널리틱스 로그를 전송합니다. 기본 값 1초입니다.

    지원하지 않는 항목

    hive_config.xml 파일 항목들 중 더는 지원하지 않는 항목들은 다음과 같습니다.

    항목 설명 비고
    exitEventEnabled exitEvent란 Hive SDK가 아니라 게임에서 앱을 직접 종료해야 하는 상황임을 알리는 이벤트입니다. 이 값이 True이면 이 이벤트룰 수신하며 이 때 Hive SDK는 게임 앱을 직접 종료하지 않습니다. 이 값이 False이면 Hive SDK가 게임 앱을 직접 종료할 수 있습니다.(+v4.9.0). v4.16.4부터 deprecated
    useCrashReport iOS 전용 기능으로 앱이 에러로 인하여 강제 종료(크래시) 발생하기 직전의 상황을 감지하여 서버 미전송 대기중인 Hive 애널리틱스 로그를 파일로 저장합니다. 비슷한 기능을 하는 외부 서드 파티 크래시 리포터를 이용할 경우 충돌 방지를 위해 false로 설정하여 비활성화 해야 합니다.(+v4.16.0) v4.16.3 부터 derpecated

     

    Configuration 클래스 메서드들 중 더는 지원하지 않는 메서드들은 다음과 같습니다.

    항목 설명 비고
    permissions 권한 종류별로 설정하는 권한 요청 여부입니다. Android 전용 기능입니다.

    • 외장 메모리 권한
      • true: 권한 요청 창 표시
      • false : 권한 요청 창 표시하지 않음
    • 태그명: sdwrite
    v4.16.3부터 derpecated
    hivePermissionViewOn Hive SDK 권한고지 팝업 노출 여부입니다.

    • true: 노출
    • false: 노출 안 함
    v4.16.2 부터 derpecated