Uygulama içi güncellemeleri destekleme (Unreal Engine)

Bu kılavuzda, Unreal Engine kullanarak uygulamanızda uygulama güncellemelerini nasıl destekleyeceğiniz açıklanmaktadır. Uygulamanızda Kotlin programlama dili veya Java programlama dili kullanıldığı durumlar ve uygulamanızda yerel kod (C/C++) ya da Unity kullanıldığı durumlar için ayrı kılavuzlar vardır.

Unreal Engine SDK'sına genel bakış

Google Play Uygulama İçi Güncelleme API'si, Google Play Core SDK ailesinin bir parçasıdır. Unreal Engine için API, uygulamanız ile Play API arasındaki iletişimi yönetmek için bir UInAppUpdatesManager sınıfı sunar. İstek gönderildikten sonra uygulamanız, EAppUpdateErrorCode kullanarak isteğin durumunu kontrol edebilir.

Desteklenen Unreal Engine sürümleri

Eklenti, Unreal Engine 5.0 ve sonraki tüm sürümleri destekler.

Geliştirme ortamınızı ayarlama

Not: Unreal Engine'de Uygulama İçi Yorumlar veya Uygulama İçi Güncellemeler eklentilerini daha önce kullandıysanız son adıma geçebilirsiniz.

1. GitHub deposundan Play Unreal Engine eklentisini indirin.

2. Unreal Engine projenizdeki Plugins klasörünün içinde bulunan GooglePlay klasörünü kopyalayın.

3. Unreal Engine projenizi açın ve Edit → Plugins'i (Düzenle > Eklentiler) tıklayın.

4. Google Play'i arayın ve Etkin onay kutusunu işaretleyin.

5. Oyun projesini yeniden başlatın ve derlemeyi tetikleyin.

6. Projenizin Build.cs dosyasını açın ve PlayInAppUpdates modülünü PublicDependencyModuleNames dosyasına ekleyin:

   using UnrealBuildTool;
   
   public class MyGame : ModuleRules
   {
     public MyGame(ReadOnlyTargetRules Target) : base(Target)
     {
       // ...
   
       PublicDependencyModuleNames.Add("PlayInAppUpdates");
   
       // ...
     }
   }
   

Güncelleme olup olmadığını kontrol etme

Güncelleme isteğinde bulunmadan önce uygulamanız için güncelleme olup olmadığını kontrol edin. Güncelleme olup olmadığını kontrol etmek için UInAppUpdatesManager::RequestInfo kullanın:

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);
}

Döndürülen UAppUpdateInfo örneği, güncelleme kullanılabilirlik durumunu içerir. Uygulama güncellemesi devam ediyorsa örnek, devam eden güncellemenin durumunu da bildirir.

Güncellemenin güncelliğini kontrol etme

Güncelleme olup olmadığını kontrol etmenin yanı sıra, kullanıcının Play Store üzerinden bir güncelleme hakkında en son ne zaman bilgilendirildiğini de kontrol etmek isteyebilirsiniz. Bu sayede, esnek güncelleme mi yoksa hemen güncelleme mi başlatmanız gerektiğine karar verebilirsiniz. Örneğin, kullanıcıya esnek bir güncellemeyle bildirim göndermeden önce birkaç gün, hemen güncelleme yapmasını istemeden önce de birkaç gün bekleyebilirsiniz.

Güncellemenin Google Play Store'da kullanıma sunulmasından bu yana geçen gün sayısını kontrol etmek için UAppUpdateInfo:GetClientVersionStalenessDays kullanın:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Güncelleme önceliğini kontrol etme

Google Play Developer API, her güncellemenin önceliğini ayarlamanıza olanak tanır. Bu sayede uygulamanız, kullanıcıya bir güncellemeyi ne kadar güçlü bir şekilde önereceğine karar verebilir. Örneğin, güncelleme önceliğini ayarlamak için aşağıdaki stratejiyi göz önünde bulundurun:

• Kullanıcı arayüzüyle ilgili küçük iyileştirmeler: Düşük öncelikli güncelleme; esnek güncelleme veya hemen güncelleme istemeyin.
• Performans iyileştirmeleri: Orta öncelikli güncelleme; esnek güncelleme isteyin.
• Kritik güvenlik güncellemesi: Yüksek öncelikli güncelleme; hemen güncelleme isteyin.

Google Play, önceliği belirlemek için 0 ile 5 arasında bir tam sayı değeri kullanır. 0 varsayılan değer, 5 ise en yüksek önceliktir. Bir güncellemenin önceliğini ayarlamak için Google Play Developer API'de Edits.tracks.releases altındaki inAppUpdatePriority alanını kullanın. Sürüme yeni eklenen tüm sürümler, sürümle aynı önceliğe sahip olarak kabul edilir. Öncelik yalnızca yeni bir sürüm kullanıma sunulurken ayarlanabilir ve daha sonra değiştirilemez.

Play Developer API belgelerinde açıklandığı şekilde Google Play Developer API'yi kullanarak önceliği ayarlayın. Uygulama güncellemesi önceliği, Edit.tracks: update yönteminde iletilen Edit.tracks kaynağında belirtilmelidir. Aşağıdaki örnekte, sürüm kodu 88 ve 5 olan bir uygulamanın yayınlanması gösterilmektedir: inAppUpdatePriority

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

Uygulamanızın kodunda, belirli bir güncellemenin öncelik düzeyini kontrol etmek için UAppUpdateInfo::UpdatePriority kullanabilirsiniz:

int32 Priority = UpdateInfo->GetPriority();

Güncelleme başlatma

Güncelleme olduğunu onayladıktan sonra UInAppUpdatesManager::StartUpdate kullanarak güncelleme isteğinde bulunabilirsiniz. Güncelleme isteğinde bulunmadan önce güncel bir UAppUpdateInfo nesneniz olduğundan emin olun. Güncelleme akışını yapılandırmak için bir UAppUpdateOptions nesnesi de oluşturmanız gerekir.

Aşağıdaki örnekte, anında güncelleme akışı için bir UAppUpdateOptions nesnesi oluşturulmaktadır:

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

Aşağıdaki örnekte, esnek bir güncelleme akışı için UAppUpdateOptions nesnesi oluşturulmaktadır:

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

UAppUpdateOptions nesnesi, cihaz depolama alanının sınırlı olması durumunda güncellemenin öğe paketlerini temizlemesine izin verilip verilmediğini döndüren bir IsAssetPackDeletionAllowed işlevi de içerir. Bu alan varsayılan olarak false şeklinde ayarlanmıştır ancak UAppUpdateOptions::SetAssetPackDeletionAllowed kullanarak alanı true şeklinde ayarlayabilirsiniz:

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

Not: Öğeleri yanlışlıkla silmemek için AllowAssetPackDeletion API seçeneğini dikkatli kullanın. Bu seçeneği true olarak ayarlamadan önce UAppUpdateInfo::IsUpdateTypeAllowed politikasını AllowAssetPackDeletion seçeneği false olarak ayarlanmış şekilde kontrol etmeniz gerekir.

Sonraki adımlar, esnek güncelleme mi yoksa hemen güncelleme mi istediğinize bağlıdır.

Esnek güncellemeleri işleme

Güncel bir UAppUpdateInfo nesnesi ve doğru şekilde yapılandırılmış bir UAppUpdateOptions nesnesi oluşturduktan sonra güncelleme akışı istemek için UInAppUpdatesManager::StartUpdate yöntemini çağırabilirsiniz.

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);
}

Esnek güncelleme akışı için uygulama güncellemesinin yüklenmesini, indirme işlemi başarıyla tamamlandıktan sonra tetiklemeniz gerekir. Bunun için aşağıdaki örnekte gösterildiği gibi InAppUpdatesManager::CompleteUpdate yöntemini çağırın:

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);
}

Anında güncellemeyi işleme

Güncel bir UAppUpdateInfo nesnesi ve doğru şekilde yapılandırılmış bir UAppUpdateOptions nesnesi oluşturduktan sonra güncelleme akışı istemek için InAppUpdatesManager::StartUpdate yöntemini çağırabilirsiniz.

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);
}

Anında güncelleme akışı için Google Play, kullanıcı onayı iletişim kutusu gösterir. Kullanıcı isteği kabul ettiğinde Google Play, güncellemeyi otomatik olarak indirip yükler ve yükleme başarılı olursa uygulamayı güncellenmiş sürümle yeniden başlatır.

Hata işleme

Bu bölümde, sık karşılaşılan hataların çözümleri açıklanmaktadır.

• UInAppUpdatesManager::StartUpdate bir AppUpdate_INVALID_REQUEST hatası döndürürse UAppUpdateInfo geçersiz demektir. Güncelleme akışını başlatmadan önce UInAppUpdatesManager::RequestInfo tarafından döndürülen UAppUpdateInfo nesnesinin boş olmadığından emin olun.
• UInAppUpdatesManager::StartUpdate, AppUpdate_NOT_ALLOWED hatasını döndürürse UAppUpdateOptions nesnesi, mevcut güncelleme için izin verilmeyen bir güncelleme türünü gösteriyor demektir. Güncelleme akışını başlatmadan önce UAppUpdateInfo nesnesinin, seçilen güncelleme türüne izin verildiğini gösterip göstermediğini kontrol edin.

Sonraki adımlar

Entegrasyonunuzun doğru şekilde çalıştığını doğrulamak için uygulamanızın uygulama içi güncellemelerini test edin.