인앱 업데이트 지원 (Unreal Engine)

이 가이드에서는 Unreal Engine을 사용하여 앱에서 인앱 업데이트를 지원하는 방법을 설명합니다. Kotlin 프로그래밍 언어나 Java 프로그래밍 언어를 사용하는 구현의 경우와 네이티브 코드 (C/C++) 또는 Unity를 사용하는 구현의 경우에 따라 가이드가 다릅니다.

Unreal Engine SDK 개요

Play In-App Updates API는 Play Core SDK 제품군의 일부입니다. Unreal Engine용 API는 앱과 Play API 간의 통신을 처리하는 UInAppUpdatesManager 클래스를 제공합니다. 요청이 이루어지면 앱은 EAppUpdateErrorCode를 사용하여 요청 상태를 확인할 수 있습니다.

지원되는 Unreal Engine 버전

이 플러그인은 Unreal Engine 5.0 및 이후 모든 버전을 지원합니다.

개발 환경 설정

  1. GitHub 저장소에서 Play Unreal Engine 플러그인을 다운로드합니다.

  2. Unreal Engine 프로젝트의 Plugins 폴더 내에 있는 GooglePlay 폴더를 복사합니다.

  3. Unreal Engine 프로젝트를 열고 수정 → 플러그인을 클릭합니다.

  4. Google Play를 검색하고 사용 설정됨 체크박스를 선택합니다.

  5. 게임 프로젝트를 다시 시작하고 빌드를 트리거합니다.

  6. 프로젝트의 Build.cs 파일을 열고 PublicDependencyModuleNames에 PlayInAppUpdates 모듈을 추가합니다.

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayInAppUpdates");

    // ...
  }
}

업데이트 사용 가능 여부 확인

업데이트를 요청하기 전에 앱에 사용 가능한 업데이트가 있는지 확인합니다. UInAppUpdatesManager::RequestInfo를 사용하여 업데이트를 확인합니다.

MyClass.h

void MyClass::OnRequestInfoOperationCompleted(
  EAppUpdateErrorCode ErrorCode,
  UAppUpdateInfo* UpdateInfo)
{
  // Check the resulting error code.
  if (ErrorCode == EAppUpdateErrorCode::AppUpdate_NO_ERROR)
  {
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), ... and decide whether to ask the user
    // to start an in-app update.
  }
}

MyClass.cpp

void MyClass::CheckForUpdateAvailability()
{
  // Create a delegate to bind the callback function.
  FRequestInfoOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestInfoOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestInfoOperationCompleted);

  // Initiate the request info operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->RequestInfo(Delegate);
}

반환된 UAppUpdateInfo 인스턴스에 업데이트 사용 가능 상태가 포함되어 있습니다. 인앱 업데이트가 이미 진행 중이면 인스턴스는 진행 중인 업데이트의 상태도 보고합니다.

업데이트 비활성화 확인

업데이트 사용 가능 여부를 확인하는 것 외에 Play 스토어를 통해 사용자에게 업데이트 알림이 전송된 후 얼마나 시간이 지났는지 확인하는 것도 좋습니다. 그렇게 하면 유연한 업데이트를 시작할지 아니면 즉시 업데이트를 시작할지 판단하는 데 도움이 될 수 있습니다. 예를 들어 며칠을 기다렸다가 사용자에게 유연한 업데이트를 알린 다음 며칠 후 즉시 업데이트를 요청할 수도 있습니다.

UAppUpdateInfo:GetClientVersionStalenessDays를 사용하여 Play 스토어를 통해 업데이트를 사용할 수 있게 된 후 경과한 일 수를 확인합니다.

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

업데이트 우선순위 확인

Google Play Developer API를 사용하면 각 업데이트의 우선순위를 설정할 수 있습니다. 이렇게 하면 앱에서 사용자에게 업데이트를 얼마나 적극적으로 권장할지 결정할 수 있습니다. 업데이트 우선순위를 설정하는 다음 전략을 예로 들어 보겠습니다.

  • 사소한 UI 개선: 낮은 우선순위 업데이트. 유연한 업데이트와 즉시 업데이트를 둘 다 요청하지 않습니다.
  • 성능 개선: 중간 우선순위 업데이트. 유연한 업데이트를 요청합니다.
  • 중요 보안 업데이트: 높은 우선순위 업데이트. 즉시 업데이트를 요청합니다.

우선순위를 결정하기 위해 Google Play는 0에서 5 사이의 정숫값을 사용하며 0은 기본값, 5는 가장 높은 우선순위를 나타냅니다. 업데이트 우선순위를 설정하려면 Google Play Developer API의 Edits.tracks.releases 아래에 있는 inAppUpdatePriority 필드를 사용하세요. 출시에 새로 추가된 모든 버전은 출시와 동일한 우선순위로 간주됩니다. 우선순위는 새 버전을 출시할 때만 설정할 수 있으며 나중에 변경할 수 없습니다.

Play Developer API 문서에 설명된 대로 Google Play Developer API를 사용하여 우선순위를 설정합니다. 인앱 업데이트 우선순위는 Edit.tracks: update 메서드에 전달된 Edit.tracks 리소스에 지정해야 합니다. 다음 예는 버전 코드가 88이고 inAppUpdatePriority가 5인 앱 출시를 보여줍니다.

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

앱 코드에서 UAppUpdateInfo::UpdatePriority를 사용하여 특정 업데이트의 우선순위 수준을 확인할 수 있습니다.

int32 Priority = UpdateInfo->GetPriority();

업데이트 시작

업데이트가 제공되는지 확인한 후 UInAppUpdatesManager::StartUpdate를 사용하여 업데이트를 요청할 수 있습니다. 업데이트를 요청하기 전에 최신 UAppUpdateInfo 객체가 있는지 확인합니다. UAppUpdateOptions 객체도 만들어 업데이트 흐름을 구성해야 합니다.

다음은 즉시 업데이트 흐름을 위한 UAppUpdateOptions 객체 생성의 예입니다.

// Creates an UAppUpdateOptions defining an immediate in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_IMMEDIATE);

다음은 유연한 업데이트 흐름을 위한 UAppUpdateOptions 객체 생성의 예입니다.

// Creates an UAppUpdateOptions defining a flexible in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_FLEXIBLE);

UAppUpdateOptions 객체에는 기기 저장용량이 제한된 경우 업데이트가 애셋 팩을 지울 수 있는지 반환하는 IsAssetPackDeletionAllowed 함수도 포함되어 있습니다. 이 필드는 기본적으로 false로 설정되지만 UAppUpdateOptions::SetAssetPackDeletionAllowed를 사용하여 필드를 설정하여 true로 대신 설정할 수 있습니다.

// Sets the AssetPackDeletionAllowed field to true.
Options->SetAssetPackDeletionAllowed(true);

다음 단계는 유연한 업데이트와 즉시 업데이트 중 무엇을 요청하는지에 따라 다릅니다.

유연한 업데이트 처리

최신 UAppUpdateInfo 객체와 올바르게 구성된 UAppUpdateOptions 객체를 확보한 후 UInAppUpdatesManager::StartUpdate를 호출하여 업데이트 흐름을 요청할 수 있습니다.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

// .cpp
void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

유연한 업데이트 흐름의 경우에는 다운로드가 성공적으로 완료된 후 앱 업데이트 설치를 트리거해야 합니다. 이렇게 하려면 다음 예와 같이 InAppUpdatesManager::CompleteUpdate를 호출합니다.

MyClass.h

void MyClass::OnCompleteUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::CompleteFlexibleUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnCompleteUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnCompleteUpdateOperationCompleted);

  // Initiate the complete update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->CompleteUpdate(UpdateInfo, UpdateOptions, Delegate);
}

즉시 업데이트 처리

최신 UAppUpdateInfo 객체와 올바르게 구성된 UAppUpdateOptions 객체를 확보한 후 InAppUpdatesManager::StartUpdate를 호출하여 업데이트 흐름을 요청할 수 있습니다.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

즉시 업데이트 흐름의 경우에는 Google Play에 사용자 확인 대화상자가 표시됩니다. 사용자가 요청을 수락하면 Google Play에서 업데이트를 자동으로 다운로드하고 설치한 다음 설치가 완료되면 앱을 업데이트된 버전으로 다시 시작합니다.

오류 처리

이 섹션에서는 일반적인 오류 해결 방법을 설명합니다.

  • UInAppUpdatesManager::StartUpdate가 AppUpdate_INVALID_REQUEST 오류를 반환하면 UAppUpdateInfo가 잘못된 것입니다. 업데이트 흐름을 시작하기 전에 UInAppUpdatesManager::RequestInfo에서 반환된 UAppUpdateInfo 객체가 null이 아닌지 확인합니다.
  • UInAppUpdatesManager::StartUpdate이 AppUpdate_NOT_ALLOWED 오류를 반환하면 UAppUpdateOptions 객체가 사용 가능한 업데이트에 허용되지 않는 업데이트 유형을 나타냄을 의미합니다. 업데이트 흐름을 시작하기 전에 UAppUpdateInfo 객체가 선택한 업데이트 유형이 허용됨을 나타내는지 확인합니다.

다음 단계

앱의 인앱 업데이트 테스트를 통해 통합이 제대로 작동하는지 확인합니다.