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

Bu kılavuzda, Unreal Engine'i kullanarak uygulamanızda uygulama içi güncellemeleri nasıl destekleyeceğiniz açıklanmaktadır. Uygulamanızın Kotlin programlama dilini veya Java programlama dilini kullandığı durumlar ve uygulamanızın yerel kod (C/C++) veya Unity kullandığı durumlar için ayrı kılavuzlar vardır.

Unreal Engine SDK'sına genel bakış

Play Uygulama İçi Güncellemeler API'si, Play Core SDK ailesinin bir parçasıdır. Unreal Engine API'si, uygulamanız ile Play API arasındaki iletişimi yönetmek için bir UInAppUpdatesManager sınıfı sunar. Bir istek yapıldıktan 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ı kurma

Not: Unreal Engine'da uygulama içi yorumlar veya uygulama içi güncellemeler eklentilerini daha önce kullandıysanız son adıma atlayabilirsiniz.

1. GitHub deposundan Play Unreal Engine eklentisini indirin.

2. Unreal Engine projenizdeki Plugins klasörüne GooglePlay klasörünü kopyalayın.

3. Unreal Engine projenizi açıp Düzenle → Eklentiler'i tıklayın.

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

5. Oyun projesini yeniden başlatın ve derleme işlemini tetikleyin.

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

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

Güncelleme kullanılabilirliğini 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 içi güncelleme zaten devam ediyorsa örnek, devam eden güncellemenin durumunu da bildirir.

Güncellemenin güncel olup olmadığını kontrol etme

Kullanıcıya Play Store üzerinden en son güncelleme bildirimi gönderildikten bu yana ne kadar süre geçtiğini de kontrol edebilirsiniz. Bu, esnek bir güncelleme mi yoksa anında güncelleme mi başlatacağınıza karar vermenize yardımcı olabilir. Örneğin, kullanıcıyı esnek bir güncellemeyle bilgilendirmeden önce birkaç gün bekleyebilir ve hemen güncelleme yapmadan önce birkaç gün daha bekleyebilirsiniz.

Güncellemenin 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 güncellemeyi ne kadar güçlü bir şekilde önereceğine karar verebilir. Örneğin, güncelleme önceliğini belirlemek için aşağıdaki stratejiyi kullanabilirsiniz:

• Kullanıcı arayüzünde küçük iyileştirmeler: Düşük öncelikli güncelleme; esnek güncelleme veya anında güncelleme isteğinde bulunmayın.
• Performans iyileştirmeleri: Orta öncelikli güncelleme; esnek güncelleme isteyin.
• Kritik güvenlik güncellemesi: Yüksek öncelikli güncellemedir. 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, 5 ise en yüksek önceliktir. Bir güncellemenin önceliğini ayarlamak için Google Play Developer API'sinde Edits.tracks.releases altındaki inAppUpdatePriority alanını kullanın. Sürüme yeni eklenen tüm sürümlerin önceliği, sürümle aynı kabul edilir. Öncelik yalnızca yeni bir sürüm kullanıma sunulduğunda ayarlanabilir ve daha sonra değiştirilemez.

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

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

Uygulamanızın kodunda, belirli bir güncellemenin öncelik düzeyini UAppUpdateInfo::UpdatePriority kullanarak kontrol edebilirsiniz:

int32 Priority = UpdateInfo->GetPriority();

Güncelleme başlatma

Güncellemenin kullanıma sunulduğunu onayladıktan sonra UInAppUpdatesManager::StartUpdate simgesini kullanarak güncelleme isteğinde bulunabilirsiniz. Güncelleme isteğinde bulunmadan önce güncel bir UAppUpdateInfo nesnenizin bulunduğ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 bir 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, sınırlı cihaz depolama alanı 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 olarak ayarlanmıştır ancak UAppUpdateOptions::SetAssetPackDeletionAllowed kullanarak alanı true olarak 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, AllowAssetPackDeletion seçeneği false olarak ayarlanmışken UAppUpdateInfo::IsUpdateTypeAllowed'ü işaretlemeniz gerekir.

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

Esnek güncellemeyi işleme

Güncel bir UAppUpdateInfo nesnesi ve düzgün yapılandırılmış bir UAppUpdateOptions nesnesi oluşturduktan sonra güncelleme akışı isteğinde bulunmak için UInAppUpdatesManager::StartUpdate'yi ç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 bir güncelleme akışı için, indirme işlemi başarıyla tamamlandıktan sonra uygulama güncellemesinin yüklenmesini tetiklemeniz gerekir. Bunu yapmak için aşağıdaki örnekte gösterildiği gibi InAppUpdatesManager::CompleteUpdate işlevini ç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üncelleme yapma

Güncel bir UAppUpdateInfo nesnesi ve düzgün yapılandırılmış bir UAppUpdateOptions nesnesi oluşturduktan sonra güncelleme akışı isteğinde bulunmak için InAppUpdatesManager::StartUpdate'yi ç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);
}

Google Play, anında güncelleme akışında kullanıcı onayı iletişim kutusu gösterir. Kullanıcı isteği kabul ettiğinde Google Play güncellemeyi otomatik olarak indirip yükler, ardından yükleme başarılı olursa uygulamayı güncellenmiş sürüme 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çersizdir. Güncelleme akışını başlatmadan önce UInAppUpdatesManager::RequestInfo kaynağından döndürülen UAppUpdateInfo nesnesinin null olmadığından emin olun.
• UInAppUpdatesManager::StartUpdate, AppUpdate_NOT_ALLOWED hatası döndürüyorsa UAppUpdateOptions nesnesi, mevcut güncelleme için izin verilmeyen bir güncelleme türünü belirtiyor demektir. Güncelleme akışını başlatmadan önce UAppUpdateInfo nesnesinin, seçilen güncelleme türüne izin verildiğini belirtip belirtmediğini kontrol edin.

Sonraki adımlar

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