Unreal Engine을 이용하여 개발할 때 Hive SDK를 포팅하는 방법과 Android, iOS, Windows 앱으로 빌드하는 방법을 안내합니다.

개발 환경

본 가이드는 다음의 환경을 기준으로 안내합니다.

Android

  • Hive SDK v4 UE4 Android+iOS 24.1.0
  • Unreal Engine 4.27 Plus
    • commit hash: 0db0b74ff0822a57a5ce49a4cd10c8672fc57a4b
  • JDK 8
  • AndroidStudio 4.1
  • Android NDK r21
  • Android SDK min version 21
  • Android SDK target version 34

iOS

  • Hive SDK v4 UE4 Android+iOS 24.1.0
  • Unreal Engine 4.27 Plus
    • commit hash: 0db0b74ff0822a57a5ce49a4cd10c8672fc57a4b
  • Xcode 15.1+
  • iOS Version 12.0+
  • macOS Ventura 14+

Windows

  • Windows 10+
  • Unreal Engine 4.27

포팅하기

Unreal Engine을 이용한다면 Hive SDK를 플러그인의 형태로 Unreal Engine에 포팅해 주세요. 다음의 안내대로 Hive SDK를 개발 환경에 추가하고 필요한 설정 작업과 코드 작업을 수행하세요:

  1. Unreal Engine 빌드하기
  2. Unreal Editor에 Hive SDK를 플러그인 형태로 추가하기
  3. Unreal Engine 파일 수정하기
  4. 일반 설정하기
  5. Hive 설정하기

Unreal Engine 빌드하기

개발 환경을 참고해 Unreal Engine 소스코드를 받아 빌드합니다.

macOS 환경을 위한 Rosetta 에뮬레이터 활성화

Unreal Engine 4 사용 시 Apple Silicon CPU가 탑재된 macOS 개발 환경에서는 Rosetta 에뮬레이터를 사용해야 합니다. Xcode에서 Product > Destination > Destination Architectures > Show Rosetta Destinations를 체크하세요.

Unreal Editor에 Hive SDK 추가하기

Hive SDK를 Unreal Editor에 플러그인 형태로 추가하세요. 아직 Unreal Engine용 Hive SDK가 없다면, SDK 다운로드 페이지에서 Unreal Engine용 Hive SDK를 다운로드 받으세요.
이미 Unreal Engine용 Hive SDK를 다운로드 받았다면 다음의 안내를 따라 Hive SDK를 Unreal Engine Editor에 플러그인 형태로 추가하세요.

  1. 개발자 사이트에서 다운로드 받은 Unreal Engine 용 Hive SDK의 압축을 풀고, 압축 해제된 파일 중 Plugin 폴더 내 모든 항목을 Unreal 게임 프로젝트의 루트 디렉토리 아래 Plugins 디렉토리로 복사하세요.
  2. 다음의 코드와 같이 "HIVESDK"를 <프로젝트_루트>/Source/<프로젝트_루트>/<프로젝트_이름>build.cs 파일 내에서 호출하는 PublicDependencyModuleNames.AddRange() 함수의 파라미터에 추가하세요. <프로젝트_이름>은 실제 여러분의 프로젝트 이름으로 대체하세요.

Unreal Engine 파일 수정하기

Unreal Engine 4.25.4 이상을 사용하고 있다면 다음 안내에 따라 Unreal Engine 파일을 제거 및 수정하세요.

Android

게임 빌드에서 화면 방향을 양방향(가로와 세로 방향 모두)으로 설정 시, 화면 자동 회전 기능이 정상 동작하려면 아래 코드 수정이 필요합니다.

  • /Engine/Build/Android/Java/src/com/epicgames/ue4/GameActivity.java.template로
    이동하세요.

  • HiveActivity.onConfigurationChaged() API를 추가하세요.

Hive SDK에서 사용하는 Google Billing Library 5 버전과 언리얼 엔진에 내포된 Google Billing 기능 사이에 호환성 문제가 존재하여 빌드가 실패합니다. 정상 빌드를 위해 아래 코드를 수정하세요.

  • /Engine/Plugins/Online/Android/OnlineSubsystemGooglePlay/Source/OnlineSubsystemGooglePlay.Build.cs
    로 이동하세요.

  • 다음 코드를 주석처리 합니다.

Hive SDK에 포함된 Singular 외부 라이브러리를 정상적으로 사용하려면 아래 코드 수정이 필요합니다.

  • /Engine/Build/Android/Java/src/com/android/vending/licensing 로 이동하세요.

  • 다음 파일을 삭제합니다.

    • ILicensingService.aidl
    • ILicenseResultListener.aidl
iOS

iOS용 Hive SDK는 Swift로 개발되어 있기 때문에 Unreal Engine과 Swift 호환을 위한 수정이 필요하며, Hive SDK에서 제공하는 Notification 기능을 사용하기 위해서도 Unreal Engine 수정이 필요합니다.

아래 파일들에서 'Add' 주석으로 표시한 라인을 추가하세요.
 

Engine/Source/Runtime/ApplicationCore/Public/IOS/IOSAppDelegate.h

 

Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp

    Hive SDK v4.15.2.2 이상 버전을 적용할 때 iOS에서 양방향 설정 추가 기능이 정상 동작하려면 Unreal Engine의 IOSAppDelegate.cpp 파일 내 화면 회전 관련 메서드인 application(_:supportedInterfaceOrientationsFor:)를 구현해야 합니다. 이 메서드의 return은 게임에 적용시킬 UIInterfaceOrientationMask 값으로 반환합니다. 가로 전용 게임은 landscape, 세로 전용 게임은 portrait을 반환하며, 가로와 세로 화면을 동시 지원하는 게임은 landscapeportrait를 모두 반환합니다.

    • /Engine/Source/Runtime/ApplicationCore/Private/IOS/IOSAppDelegate.cpp에 아래의 코드를 추가하세요.

 

Unreal Engine 4.27 Plus와 Hive SDK v4.16.3(최소 지원 도구 Xcode 14.1) 버전을 사용하는 경우, 아래 파일들에서 'Add' 주석으로 표시한 라인을 추가하세요.
 

Engine/Source/Programs/UnrealBuildTool/ProjectFiles/Xcode/XcodeProject.cs

 

Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSToolChain.cs

 

Universal Link 설정하기
  • Hive SDK v4.15.8 이상 버전부터 URL Scheme 방식이 아닌 Universal Link를 사용하여 초대 페이지를 통한 앱 최초 설치 및 실행, 초대자 보상이 이루어 집니다.
  • Universal Link 기반의 초대자 링크 생성을 위한 추가 콘솔 설정은 개발자 사이트의 프로모션 운영가이드를 참고 하세요.

아래 파일들에서 'Add' 주석으로 표시한 라인을 추가하세요.
 

Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExport.cs

일반 설정하기

Android
  1. Unreal Editor에서 편집 > 프로젝트 세팅 메뉴를 클릭하세요. 프로젝트 설정 창이 화면에 나타납니다.
  2. 프로젝트 설정 창의 좌측 패널에서 플랫폼 제목 아래의 안드로이드 SDK 메뉴를 클릭하세요. 안드로이드 SDK 설정 화면이 나타나면, 다음의 안내대로 Android 버전을 설정하세요.
    • SDK API Level 필드를 android-30(Hive SDK v4.15.1+)이상으로 설정하세요.
    • NDK API Level 필드를 android-21로 설정하세요.

  3. 프로젝트 설정 창의 좌측 패널에서 플랫폼 제목 아래의 안드로이드 메뉴를 클릭하세요. 안드로이드 화면이 나타나면 APKPackaging 섹션에서 다음의 필드를 안내된 대로 설정하세요.
    • Android Package Name 필드에 게임의 AppID를 입력하세요.
    • Store Version 필드에 Google Play Store에 명시하는 앱의 버전을 입력하세요. 앱 버전에 대해 자세히 보기
    • Minimum SDK Version 필드를 21 이상으로 설정하세요. 21 미만으로 지정된 값은 Unreal Engine 동작에 따라 자동으로 21로 설정됩니다.
    • Target SDK Version 필드를 30(Hive SDK v4.15.1+) 이상으로 설정하세요.

Google과 Google Play Games 인증 지원

Hive SDK는 일반 구글 인증(iOS, Android)과 Google Play Games 인증(Android)을 모두 지원합니다. Google Play Games 인증을 사용하려면 먼저 아래와 같이 언리얼 엔진 코드를 수정해야 합니다.

  1. ./Engine/Build/Android/Java/src/com/epicgames/ue4/GameActivity.java.template를 엽니다.
  2. 아래 라인을 제거합니다.

Google 또는 Google Play Games 인증을 사용하려면 “GOOGLE” 또는 “GOOGLE_PLAY_GAMES” ProviderType를 선택해 AuthV4.SignIn()을 호출합니다.

 

iOS
  1. Unreal Editor의 메뉴에서 편집 > 프로젝트 세팅 메뉴를 클릭하세요. 프로젝트 설정 창이 화면에 나타납니다.
  2. 프로젝트 설정 창의 좌측 패널에서 플랫폼 제목 아래의 iOS 메뉴를 선택하세요. iOS 설정 화면이 나타나면, 그룹 별로 안내된 항목을 설정하세요.
    • Bundle Information 그룹: 번들 식별자(Bundle Identifier) 필드에 게임의 AppID를 입력하세요.
    • OS Info 그룹: Unreal Engine 4.25부터 지원하는 OS 버전이 11.0 이상으로 변경되었습니다. Minimum OSVersion 필드 값을 11.0으로 설정하세요.
    • Build 그룹: Additional Non-Shipping Linker Flags 필드와 Additional Shipping Linker Flags 필드에 -ObjC를 입력하세요.
    • Extra PList Data 그룹: Additional PList Data 필드에 다음의 코드를 입력하세요.
    • 접근 권한 요청 설정하기
    • Facebook, QQ, VK, WeChat, Line을 이용할 경우, 서버 Whitelist를 설정하기 위해 다음 코드를 추가하세요.
    • Facebook 이용 시 다음의 코드를 이용하여 Facebook AppID와 ClientToken을 추가하세요.
      반드시 여러분 게임에 대한 Facebook AppID와 ClientToken 값을 입력하세요.
    • URL Scheme을 설정하세요.
    • 다음은 위 안내의 모든 값을 Additional PList Data 필드에 넣은 값의 예제입니다.
  3. Apple SignIn 지원을 위해 프로젝트 폴더 > Config > DefaultEngine.ini 파일 내 아래 코드를 추가하세요.
Firebase Analytics 추가하기
  • Firebase 콘솔(https://firebase.google.com/)에서 앱등록 후, 발급받은 GoogleService-Info.plist 파일을 다음 경로에 넣어주세요.

    /Plugins/HIVESDK/Source/HIVESDK/ThirdParty/iOS/resource

  • 다국어 설정파일 적용하기
  • 다국어를 적용하기 위해서는 다국어 설정파일의 추가가 필요합니다.
    • 다국어 설정 파일 > localize 폴더 하위의 폴더들을 다음 경로에 넣어주세요.

      /Plugins/HIVESDK/Source/HIVESDK/ThirdParty/iOS/resource

  • HIVEAppDelegate 적용하기
  • iOS 빌드의 경우 AppDelegate 메서드 수정이 필요합니다. Unreal Engine의 경우 Swizzling을 이용하여 AppDelegate에 접근합니다.
    게임시작시 초기화하는 단계에서 아래 코드를 추가해주세요.
  •  

    iOS FMallocAnsi 설정하기

    Unreal Engine iOS 환경과 C++ 표준 템플릿 라이브러리가 정상적으로 호환되려면 아래와 같이 FMallocAnsi 설정이 필요합니다.

    게임 프로젝트의 {YourProject}.Target.cs 파일에 다음 코드를 추가합니다.

    Windows
    플러그인 설정

    기존 Hive SDK의 언리얼 엔진 플러그인 적용 프로젝트에서 Plugin/HIVESDK 내용을 덮어쓰기 하세요.

     

    C++ 인터페이스 변경 적용

    SDK Plugin API 호출

    • STL이 적용된 플러그인 인터페이스 호출 시 크래시 발생으로 인하여 일부 API는 대체 API로 호출해야 합니다.
    • 클래스는 JSON 객체 형식의 문자열(string)이며, 배열(std::vector 등)은 JSON 배열 형식의 문자열(string)로 반환됩니다.
    • 다음은 AuthV4::getPlayerInfo() 호출 예시입니다.
    • 추가된 API 목록은 다음과 같습니다.
    • HIVESDKSampleUtility.cpp를 참고하여 Promotion.h에 포함된 클래스의 toString() 호출 시 크래시 발생에 대한 우회용 예제 코드를 알아보세요.

     

    변경된 클래스

    1. AppInvitationCampaign 클래스에서
      위 변경점에 대해 아래와 같이 사용합니다.
    2. hive::IAPV4TypeHiveStore = 15가 추가되었습니다.
    3. Result API에 ErroCode:IAPSUCCESS = 90Code:IAPV4HiveStoreSuccess = -6110000가 추가되었습니다.
    4. ConflictSingleViewInfo 클래스에서
    5. ConflictViewInfo 클래스에서

     

    Windows 빌드 전용 API

    • 예제 프로젝트 PlayerTestView.cpp를 참고하여 AuthV4::showInquiry, AuthV4::showMyInquiry, AuthV4::showDeviceManagement, AuthV4ShowChatbotInquiry, AuthV4::showProfile API(windows용) 호출 시 위의 API 호출 IME(외국어 입력기) 활성화/비활성화를 알아보세요.
      • SDK API 호출 전과 호출 이후에 추가해야 합니다.

      • HIVESDKIMEEnable, HIVESDKIMEDisable은 엔진 수정(TSF 입력 방식 비활성화)이 적용된 경우 동작합니다.
      • Hive SDK 4.15.7부터 HIVESDKCEFImeEnable, HIVESDKCEFImeDisable은 엔진 수정없이 동작합니다.

     

    Result API Error Code 추가 (Hive SDK v4.15.7+)
    아래의 내용이 새로 추가되었습니다.

    • HIVE_ResultAPI.h 파일 ResultAPI class의 Code enum

     

    빌드 전 설정
    1. 다음 링크의 내용을 참고하여 중복 실행을 방지할 수 있도록 준비하세요. 프로젝트에 맞는 다른 방법을 적용해도 상관 없습니다.
    2. SDK의 기능이 정상적으로 동작할 수 있도록 엔진을 수정해야 합니다. (bootstrappakage 수정)
      언리얼 엔진 소스 코드를 수정 하고 빌드합니다. /Engine/Source/Programs/Windows/BootstrapPackagedGame/Private/BootstrapPackagedGame.cpp

      • 패키지 완료된 bootstrappakage 실행 파일에서 binaries 위치한 실행 파일을 실행 했을 때 게임명 파라미터가 제거됩니다.
        • 수정 전
          swprintf(ChildCmdLine, ChildCmdLineLength, L”\”%s\\%s\” %s %s”, BaseDirectory, ExecFile, BaseArgs, CmdLine);
        • 수정 후
          swprintf(ChildCmdLine, ChildCmdLineLength, L”\”%s\\%s\” %s”, BaseDirectory, ExecFile, CmdLine);
      • 수정 후 UE4 솔루션에서 BootstrapPackagedGame 프로젝트 빌드
    3. Plugins/HIVESDK/Source/HIVESDK/ThirdParty/windows/config/에 위치한 hive_config.xml 파일에서 프로젝트에 맞게 appidzone, provider id를 수정하세요.

    Hive 설정하기

    다음의 안내에 따라 Hive 사용을 위한 설정 항목을 설정하세요. 여러분이 설정 값을 변경하면 Unreal Editor의 값은 자동으로 저장되며, 설정 값을 저장하는 파일(hive_config.xml, etc_string.xml, GooglePlayAppID.xml)의 값 역시 변경 사항을 반영해 자동 저장됩니다. 설정 값 파일이 없으면 Hive SDK가 자동으로 생성하며, 파일은 다음 위치에서 찾을 수 있습니다:

    • Android:
      <프로젝트_루트>/Plugins/HIVESDK/Source/HIVESDK/ThirdParty/android/resource/res/raw
    • iOS:
      <프로젝트_루트>/Plugins/HIVESDK/Source/HIVESDK/ThirdParty/iOS/resource/

    Hive에서 필요한 값을 설정하기 위해 다음의 안내를 따르세요:

    1. Unreal Editor의 메뉴에서 편집 > 프로젝트 세팅을 클릭하세요. 프로젝트 설정 창이 화면에 나타납니다.
    2. 프로젝트 설정 창의 좌측 패널에서 플러그인 제목 아래의 HIVEConfig XML 메뉴를 클릭하세요. HIVEConfig XML 설정 화면이 나타납니다.
    3. HIVEConfig XML 화면에서 다음의 안내대로 설정 항목을 변경하세요:
      • Facebook Settings 그룹의 Facebook App ID 필드에 게임에 대한 Facebook AppID를 입력하세요. 게임에 대한 Facebook AppID 값을 모른다면 선행 작업 섹션을 읽어 보세요.
      • Google Play Settings 그룹의 Google Play App ID 필드에 게임빌이나 컴투스로부터 전달 받은 Google Play Game Service AppID를 입력하세요.
      • HiveConfig Settings 그룹: hive_config.xml 파일에서 설정하는 값 중 다음 값을 설정할 수 있습니다.
      • HiveConfig Mobile App Tracking Settings: 이용할 마케팅 어트리뷰션에 대한 설정 값을 입력하세요. 이용할 마케팅 어트리뷰션 대시보드에서 발급 받은 AppID, 키 혹은 토큰 값을 입력하세요.
        마케팅 어트리뷰션 설정 가이드 보기
      • WriteExternalStoragePermission: Android에서 필요한 값으로, 외부 저장소 사용 권한을 유저에게 요청할 지 여부를 설정합니다. 체크하면 Hive 클라이언트가 단말기에서 초기화 될 때, 유저에게 외부 저장소 권한을 요청합니다.

    Hive 기능 선택 적용하기 (Android, iOS)

    인증, 애널리틱스 등에서 사용할 Hive 기능만 선택하여 적용하려면, 다음 안내를 따르세요.

    1. Unreal Editor의 메뉴에서 Edit > Project Settings을 클릭하세요. Project Settings 창이 나타납니다.
    2. Project Settings 창의 좌측 패널에서 Hive SDK 하위의 Dependency – Android / Dependency – iOS를 각 클릭하세요.

    3. 우측의 Hive SDK Dependency – Android / Dependency – iOS 각 화면에서 사용할 기능에 대한 라이브러리 의존성을 선택하세요.

    빌드하기

    Unreal Engine을 이용한다면 OS별로 다음 안내에 따라 빌드해주세요.

    Android 빌드하기

    빌드 설정하기

    Unreal Engine 4.0 이상 버전을 이용한다면, Google Play Store에 앱을 배포하기 위한 항목을 다음의 안내대로 설정하세요:

    • Signing Key 설정하기:
        1. Unreal Editor의 메뉴에서 편집 > 프로젝트 세팅을 클릭하세요. 프로젝트 설정 창이 화면에 나타납니다.
        2. 프로젝트 설정 창의 좌측 패널에서 플랫폼 제목 아래의 안드로이드 메뉴를 클릭하세요. 안드로이드 설정 화면이 나타납니다.
        3. 안드로이드 설정 화면에서 Distribution Signing 그룹의 필드에 Signing Key 정보를 입력하세요.

    • 패키징 설정하기:
        1. 프로젝트 설정 창의 좌측 패널에서 프로젝트 제목 아래의 패키징 메뉴를 클릭하세요. 패키징 설정 창이 나타납니다.
        2. 패키징 설정 화면의 Project 그룹의 For Distribution 필드를 체크하세요.

    빌드하기

    Hive가 포팅된 Android 용 게임을 빌드하는 방법은 Unreal Editor에서 일반 Android 앱을 빌드하는 방법과 동일합니다. Unreal Editor에서 파일 > 프로젝트 패키징 > 안드로이드 메뉴를 이용하세요.

    빌드 방법에 대한 자세한 내용은 Unreal에서 제공하는 가이드를 참고하세요.

    iOS 빌드하기

    Hive가 포팅된 iOS 용 게임을 빌드하는 방법은 Unreal Editor에서 일반 iOS 앱을 빌드하는 방법과 동일합니다. Unreal Editor에서 파일 > 프로젝트 패키징 > iOS 메뉴를 이용하세요.

    빌드 방법에 대한 자세한 내용은 Unreal에서 제공하는 가이드를 참고하세요.

    Windows 빌드하기

    • 언리얼 엔진 에디터에서 패키지 시 Windows (64-bit)로 선택하세요.
    • 최초 빌드 시 다음과 같은 에러가 발생하더라도 이후에 재시도하면 정상적으로 빌드가 진행됩니다.
      UATHelper: 패키징 (Windows (64-bit)): Exception: ‘\Binaries\Win64\OpenImageIO_Util.dll’ 경로에 대한 액세스가 거부되었습니다.
      UATHelper: 패키징 (Windows (64-bit)): ERROR: Exhausted all retries!

    Windows 빌드 완료 후, Plugins/HIVESDK/Source/HIVESDK/ThirdParty/windows/util/rcedit.exe를 이용하거나 그 외의 방법으로 실행 파일의 제품 버전파일 버전을 수정해야 합니다.
    아래의 버전 변경이 반영된 스트립트 파일 예시 이미지를 확인해보세요.

     

    개발자 PC 이외의 환경에서는 재배포 가능 패키지가 필요합니다.
    (관련 가이드: 지원되는 최신 Visual C++ 재배포 가능 패키지 다운로드)