Unreal Engine 5

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

화면 자동 회전 기능 설정¶

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

Android¶

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

/Engine/Build/Android/Java/src/com/epicgames/unreal/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¶

Hive SDK Unreal Engine 5 iOS에서는 화면 자동 회전 관련 별도 설정이 필요하지 않습니다.

Entitlements 설정 (iOS)¶

앱 서명에 사용할 entitlements 파일은 앱 프로젝트에서 직접 관리하고, Unreal Engine의 PremadeIOSEntitlements 설정으로 지정합니다.

원격 푸시 알림, Apple 로그인, 유니버설 링크 등 Hive SDK의 주요 기능이 정상적으로 동작하려면, 해당 entitlements 파일에 아래 기능들을 위한 권한 항목이 반드시 포함되어 있어야 합니다.

앱 프로젝트에 entitlements 파일을 생성하세요. (예: Build/IOS/YourGame.entitlements) 아래는 Hive SDK 기능 기준의 구성 예시입니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>application-identifier</key>
    <string>{Team ID}.{Bundle ID}</string>
    <key>com.apple.developer.team-identifier</key>
    <string>{Team ID}</string>
    <!-- 개발 빌드는 true, 배포 빌드는 false -->
    <key>get-task-allow</key>
    <false/>
    <key>aps-environment</key>
    <string>production</string>
    <key>com.apple.developer.applesignin</key>
    <array>
        <string>Default</string>
    </array>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:{게임에서 사용하는 도메인}</string>
    </array>
    <key>com.apple.developer.game-center</key>
    <true/>
</dict>
</plist>

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

사용 기능	필요한 entitlement
공통 (앱 서명)	`application-identifier`, `com.apple.developer.team-identifier` — `{Team ID}`, `{Bundle ID}`를 게임 값으로 교체
리모트 푸시	`aps-environment` — 개발 `development`, 배포 `production`
Apple 로그인 (IdP)	`com.apple.developer.applesignin`
유니버설 링크 (딥링크·초대 링크)	`com.apple.developer.associated-domains` — 도메인 구성은 유니버설 링크 설정하기 참고
Game Center 로그인 (IdP)	`com.apple.developer.game-center`
연령 고지 (AgeRange 모듈)	`com.apple.developer.declared-age-range` — 상세는 App Store 규정 준수 참고

Unreal 에디터 메뉴에서 편집 > 프로젝트 세팅을 클릭하고, 좌측 패널에서 플랫폼 > Xcode 프로젝트를 선택하세요. 권한 항목에서 작성한 entitlements 파일을 지정합니다.

항목	설명
iOS: 권한	앱 서명에 사용할 entitlements 파일
iOS: 권한(출시 환경설정 오버라이드)	배포(Shipping) 빌드에 다른 파일을 사용하려는 경우 지정

설정은 Config/DefaultEngine.ini에 아래와 같이 저장되며, 파일을 직접 편집해 지정할 수도 있습니다.

[/Script/MacTargetPlatform.XcodeProjectSettings]
PremadeIOSEntitlements=(FilePath="{entitlements 파일 경로}")
ShippingSpecificIOSEntitlements=(FilePath="{배포용 entitlements 파일 경로}")

빌드 후 앱에 entitlements가 적용되었는지 확인하세요.
```
codesign -d --entitlements :- {빌드된 .app 경로}
```

Note

PremadeIOSEntitlements로 지정한 파일은 지정하면 iOS 서명 단계에 원본 그대로 반영됩니다.
- 필수 항목 누락 시: 관련 기능(푸시, Apple 로그인 등)이 정상적으로 동작하지 않습니다.
- 미지원 항목 포함 시: 프로비저닝 프로파일(Provisioning Profile)에 등록되지 않은 권한이 entitlements 파일에 포함되어 있으면, 앱 설치 및 서명 검증(Code Signing) 단계에서 실패합니다.
Hive SDK 플러그인의 Plugins/HIVESDK/Source/HiveSDKiOS/template/ 경로에 샘플 entitlements 파일이 참고용으로 포함되어 있습니다.

Warning

샘플 entitlements 파일은 테스트 목적으로 거의 모든 권한 항목을 활성화해 둔 것이므로 절대로 프로젝트에 그대로 복사하여 사용하지 마세요. 반드시 게임 서비스에 필요한 유효 항목만 선별하여 발췌해 사용하시기 바랍니다.

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)는 앞서 진행한 앱 코드 내 델리게이트 구독이 정상적으로 제거되었다면 엔진 동작에 영향을 주지 않습니다. 따라서 해당 코드는 굳이 제거하거나 롤백하지 않고 그대로 유지하셔도 무방합니다.