Unreal Engine 4

Hive SDK 설치 후 수행할 작업을 안내합니다.

화면 자동 회전 기능 설정¶

화면 방향을 양방향(가로와 세로 방향 모두)으로 설정할 때는 아래 설정이 필요합니다.

Android¶

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

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

HiveActivity.onConfigurationChanged() API를 추가하세요.

@Override
public void onConfigurationChanged(Configuration newConfig)
{
HiveActivity.onConfigurationChanged(this, newConfig); // Add
super.onConfigurationChanged(newConfig);


// forward the orientation
boolean bPortrait = newConfig.orientation == Configuration.ORIENTATION_PORTRAIT;
nativeOnConfigurationChanged(bPortrait);
}

iOS¶

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

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

- (UIInterfaceOrientationMask)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window
{
  // TODO: 가로 전용 게임
  return UIInterfaceOrientationMaskLandscape;
  // TODO: 세로 전용 게임
  return UIInterfaceOrientationMaskPortrait;
  // TODO: 가로와 세로 모두 지원하는 게임
  return UIInterfaceOrientationMaskAll;
}

Swift 호환성 설정 (iOS)¶

iOS 개발 환경에서는 Unreal Engine 4와 Swift 언어의 호환성을 위해 아래 파일들에서 'Add' 주석으로 표시한 줄 또는 여러 줄(Add부터 Add End)을 추가하세요.

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

    {
       Content.Append("\t\t\t\t\"PRODUCT_BUNDLE_IDENTIFIER[sdk=iphoneos*]\" = " + IOS_BUNDLE + ";" + ProjectFileGenerator.NewLine);
    }
    // Add
    if (ProjectFile != null)
    {
        Content.Append("\t\t\t\tSWIFT_VERSION = 5.0;" + ProjectFileGenerator.NewLine);
        Content.Append("\t\t\t\tSWIFT_OBJC_BRIDGING_HEADER = \"" + GamePath + "/dummy-Bridging-Header.h\";" + ProjectFileGenerator.NewLine);
    }
   // Add End
}
if (TVOSRunTimeVersion != null)
{

if (XcodeProjectFileGenerator.bGeneratingRunIOSProject)
{
   Content.Append("\t\t\t\tALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES;"+ ProjectFileGenerator.NewLine); // Add
   Content.Append("\t\t\t\tINFOPLIST_FILE = \"" + IOSInfoPlistPath + "\";" + ProjectFileGenerator.NewLine);
   Content.Append("\t\t\t\tCODE_SIGN_ENTITLEMENTS = \"" + IOSEntitlementPath + "\";" + ProjectFileGenerator.NewLine);
}

Content.Append("\t\t\t\t\"INFOPLIST_FILE[sdk=macosx*]\" = \"" + MacInfoPlistPath + "\";" + ProjectFileGenerator.NewLine);
if (IOSRunTimeVersion != null)
{
   Content.Append("\t\t\t\tALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES;"+ ProjectFileGenerator.NewLine); // Add
   Content.Append("\t\t\t\t\"INFOPLIST_FILE[sdk=iphoneos*]\" = \"" + IOSInfoPlistPath + "\";" + ProjectFileGenerator.NewLine);
   Content.Append("\t\t\t\t\"CODE_SIGN_ENTITLEMENTS[sdk=iphoneos*]\" = \"" + IOSEntitlementPath + "\";" + ProjectFileGenerator.NewLine);
}

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

    Result += " -Xlinker \\\"" + Path.GetDirectoryName(OutputFile.AbsolutePath) + "\\\"";
}
Result += " -Xlinker -rpath -Xlinker /usr/lib/swift";  // Add
Result += " -dead_strip";
Result += " -m" + GetXcodeMinVersionParam() + "=" + ProjectSettings.RuntimeVersion;
Result += " -Wl";

Entitlements 설정 (iOS)¶

Unreal Engine은 빌드 타임에 UnrealBuildTool을 통해 서명용 entitlements 파일을 동적으로 생성합니다. 필요한 권한 항목을 추가하는 방법은 아래와 같습니다.

프로젝트 설정을 통한 추가: 일부 공통 권한 항목은 Unreal Engine 에디터의 프로젝트 설정(Project Settings) 메뉴에서 직접 활성화하여 추가할 수 있습니다.
엔진 소스 수정을 통한 추가: 프로젝트 설정에서 지원하지 않는 그 외의 항목들은 아래 UnrealBuildTool 엔진 소스 파일 내의 entitlements 생성부 코드를 직접 수정하여 추가해야 합니다
- 수정 대상 파일: Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExport.cs

Hive SDK 기능별로 필요한 entitlement 항목과 추가 방법은 아래와 같습니다. 앱에서 사용하는 기능(프로비저닝 프로파일에 활성화된 capability)에 해당하는 항목만 추가하세요. 각 항목의 상세 설명은 Apple 공식 문서를 참고하세요.

사용 기능	필요한 entitlement	추가 방법
리모트 푸시	`aps-environment`	프로젝트 세팅 > 플랫폼 > iOS의 Online 항목에서 Enable Remote Notifications Support 체크
Apple 로그인 (IdP)	`com.apple.developer.applesignin`	Config/DefaultEngine.ini의 `[/Script/IOSRuntimeSettings.IOSRuntimeSettings]` 섹션에 `bEnableSignInWithAppleSupport=True` 추가
유니버설 링크 (딥링크·초대 링크)	`com.apple.developer.associated-domains`	IOSExport.cs 수정 — 도메인 구성은 유니버설 링크 설정하기 참고
Game Center 로그인 (IdP)	`com.apple.developer.game-center`	IOSExport.cs 수정
연령 고지 (AgeRange 모듈)	`com.apple.developer.declared-age-range`	IOSExport.cs 수정 — 상세는 App Store 규정 준수 참고

IOSExport.cs를 수정하는 경우, 아래 위치의 'Add'와 'Add End' 사이에 필요한 항목을 추가하세요.

Text.AppendLine( "<dict>");
Text.AppendLine( "\t<key>get-task-allow</key>");
Text.AppendLine(string.Format( "\t<{0}/>", bForDistribution ? "false": "true"));

// Add — 필요한 entitlement 항목을 추가하세요. 아래는 Game Center 예시입니다.
Text.AppendLine("\t<key>com.apple.developer.game-center</key>");
Text.AppendLine("\t<true/>");
// Add End

if (bCloudKitSupported) {
    if (iCloudContainerIdentifiersXML != "")

Note

IOSExport.cs 파일 수정은 UnrealBuildTool(UBT)의 소스 코드 변경에 해당합니다. 따라서 엔진 전체를 다시 빌드할 필요가 없으며, 다음 프로젝트 빌드 시 UBT가 자동으로 컴파일되면서 변경 사항이 즉시 반영됩니다.

빌드 후 앱에 entitlements가 적용되었는지 아래와 같이 확인하세요.

codesign -d --entitlements :- {빌드된 .app 경로}

HIVEAppDelegate 적용 (iOS)¶

Hive SDK v4 26.4.1부터 HIVEAppDelegate Swizzling이 Hive SDK 플러그인 내부에서 자동으로 수행됩니다. 앱 실행 시 플러그인이 이를 자동 처리하므로, 앱 코드 내 별도의 추가 작업이 필요하지 않습니다.

기존 연동 코드 제거(v4 26.4.1 미만 버전 대상)

Hive SDK v4 26.4.1 미만 버전을 사용 중인 경우, 업데이트할 때 이전 수정 사항을 제거하세요.

HIVEAppDelegate 수동 호출 코드 제거: 이전 가이드의 "HIVEAppDelegate 적용 (iOS)" 단계를 참고하여 앱 초기화 단계에 추가한 아래 형태의 코드 블록을 프로젝트에서 제거하세요.

#if PLATFORM_IOS
UIApplication * dummyApplication = [UIApplication sharedApplication];

Class clzHIVEAppDelegate = NSClassFromString(@"HIVEAppDelegate");
SEL selApplicationDidFinishLaunchingWithOptions = NSSelectorFromString(@"application:didFinishLaunchingWithOptions:");
if( clzHIVEAppDelegate != nil && [clzHIVEAppDelegate respondsToSelector:selApplicationDidFinishLaunchingWithOptions] ) {
        NSMethodSignature *method = [clzHIVEAppDelegate methodSignatureForSelector:selApplicationDidFinishLaunchingWithOptions];
        if (method != nil) {
                NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:method];
                [invocation setSelector:selApplicationDidFinishLaunchingWithOptions];
                [invocation setTarget:clzHIVEAppDelegate];
                [invocation setArgument:(void*)&dummyApplication atIndex:2];
                NSDictionary *localLaunchOptions = [IOSAppDelegate GetDelegate].launchOptions;
                if( localLaunchOptions != nil ) {
                        [invocation setArgument:(void*)&localLaunchOptions atIndex:3];
                }
                [invocation invoke];
        }
}
#endif

딥링크 델리게이트 구독 코드 제거: 이전 가이드의 "딥링크 설정을 위한 프로모션 코드 추가 (iOS)" 단계를 참고하여 GameInstance 등에 추가한 아래 형태의 구독 및 대응 핸들러 코드를 제거하세요.
- 핸들러 내부 로직은 사용 중인 인터페이스에 따라 Promotion::processURI(...) 또는 FHivePromotion::ProcessURI(...) 형태로 구현되어 있을 수 있습니다.
```
// 구독 코드 (GameInstance::Init 등) — 제거
FIOSCoreDelegates::OnOpenURLwithOptions.AddUObject(this, &UMyGameInstance::ApplicationOpenURL);

// 대응 핸들러 — 제거 (헤더의 선언 포함)
void UMyGameInstance::ApplicationOpenURL(UIApplication* application, NSURL* url, NSDictionary* options)
{
        Promotion::processURI(std::string([[url absoluteString] UTF8String]));
}
```
Blueprint의 부트스트랩 트리거 호출 제거: 앱에서 자체 정의하여 블루프린트(Blueprint) 내에서 호출하던 트리거 함수(예: RemoveOpenURLDelegate())와 해당 호출 노드를 프로젝트에서 모두 제거하세요.

기존에 커스텀 엔진에 직접 적용했던 openURL 관련 수정 코드(IOSAppDelegate.h, IOSAppDelegate.cpp)는 앞서 진행한 앱 코드 내 델리게이트 구독이 정상적으로 제거되었다면 엔진 동작에 영향을 주지 않습니다. 따라서 해당 코드는 굳이 제거하거나 롤백하지 않고 그대로 유지하셔도 무방합니다.