Uygulama içi güncellemeleri destekleme (Unity)

Bu kılavuzda, Unity'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++) kullandığı durumlar için ayrı kılavuzlar vardır.

Geliştirme ortamınızı kurma

OpenUPM-CLI

OpenUPM CLI yüklüyse OpenUPM kayıt defterini şu komutla yükleyebilirsiniz:

openupm add com.google.play.appupdate

OpenUPM

  1. Düzenle > Proje Ayarları > Paket Yöneticisi Unity menü seçeneğini belirleyerek paket yöneticisi ayarlarını açın.

  2. OpenUPM'yi Paket Yöneticisi penceresine kapsamlı bir kayıt defteri olarak ekleyin:

    Name: package.openupm.com
URL: https://package.openupm.com
Scopes: com.google.external-dependency-manager
  com.google.play.common
  com.google.play.core
  com.google.play.appupdate

  3. Unity menü seçeneği Pencere > Paket Yöneticisi'ni seçerek paket yöneticisi menüsünü açın.

  4. Yönetici kapsamı açılır menüsünü Kayıt otoritelerim'i seçecek şekilde ayarlayın.

  5. Paket listesinden Unity için Google Play Integrity eklentisi paketini seçin ve Yükle'ye basın.

GitHub'dan içe aktarma

  1. GitHub'dan en son .unitypackage sürümünü indirin.

  2. Öğeler > Paket içe aktar > Özel Paket Unity menü seçeneğini belirleyip tüm öğeleri içe aktararak .unitypackage dosyasını içe aktarın.

Unity SDK'sına genel bakış

Play uygulama içi güncelleme API'si, Play Core SDK ailesinin bir parçasıdır. Unity eklentisi, uygulamanız ile Play API arasındaki iletişimi yönetmek için bir AppUpdateManager sınıfı sunar. Uygulama içi güncellemeleri yönetmek için bu sınıfı kullanabilmenizden önce sınıfı örneklemeniz gerekir:

AppUpdateManager appUpdateManager = new AppUpdateManager();

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

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

IEnumerator CheckForUpdate()
{
  PlayAsyncOperation<AppUpdateInfo, AppUpdateErrorCode> appUpdateInfoOperation =
    appUpdateManager.GetAppUpdateInfo();

  // Wait until the asynchronous operation completes.
  yield return appUpdateInfoOperation;

  if (appUpdateInfoOperation.IsSuccessful)
  {
    var appUpdateInfoResult = appUpdateInfoOperation.GetResult();
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), etc. and decide whether to ask the user
    // to start an in-app update.
  }
  else
  {
    // Log appUpdateInfoOperation.Error.
  }
}

Döndürülen AppUpdateInfo örneği, güncelleme kullanılabilirlik durumunu içerir. Uygulama içi güncelleme 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 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 ClientVersionStalenessDays simgesini kullanın:

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

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 anlık güncelleme isteğinde bulunmayın.
  • Performans iyileştirmeleri: Orta öncelikli güncelleme; esnek bir 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ı kullanır. 0 varsayılan, 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ümlerin önceliği, sürümle aynı kabul edilir. Öncelik yalnızca yeni bir sürüm kullanıma sunulduğunda belirlenebilir 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 metodunda 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, UpdatePriority kullanarak belirli bir güncellemenin öncelik düzeyini kontrol edebilirsiniz:

var priority = appUpdateInfoOperation.UpdatePriority;

Güncelleme başlatma

Güncelleme olduğunu doğruladıktan sonra AppUpdateManager.StartUpdate() simgesini kullanarak güncelleme isteğinde bulunabilirsiniz. Güncelleme isteğinde bulunmadan önce güncel bir AppUpdateInfo nesnenizin bulunduğundan emin olun. Güncelleme akışını yapılandırmak için bir AppUpdateOptions nesnesi de oluşturmanız gerekir.

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

// Creates an AppUpdateOptions defining an immediate in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.ImmediateAppUpdateOptions();

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

// Creates an AppUpdateOptions defining a flexible in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.FlexibleAppUpdateOptions();

AppUpdateOptions nesnesi, sınırlı cihaz depolama alanı olması durumunda güncellemenin öğe paketlerini temizlemesine izin verilip verilmeyeceğini tanımlayan bir AllowAssetPackDeletion alanı da içerir. Bu alan varsayılan olarak false olarak ayarlanır ancak allowAssetPackDeletion isteğe bağlı bağımsız değişkenini ImmediateAppUpdateOptions() veya FlexibleAppUpdateOptions() olarak ileterek true olarak ayarlayabilirsiniz:

// Creates an AppUpdateOptions for an immediate flow that allows
// asset pack deletion.
var appUpdateOptions =
  AppUpdateOptions.ImmediateAppUpdateOptions(allowAssetPackDeletion: true);

// Creates an AppUpdateOptions for a flexible flow that allows asset
// pack deletion.
var appUpdateOptions =
  AppUpdateOptions.FlexibleAppUpdateOptions(allowAssetPackDeletion: true);

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

Esnek güncellemeyi işleme

Güncel bir AppUpdateInfo nesnesi ve düzgün yapılandırılmış bir AppUpdateOptions nesnesi oluşturduktan sonra, güncelleme akışı isteğinde bulunmak için AppUpdateManager.StartUpdate() işlevini ayrıştırmalı olarak çağırabilirsiniz.

IEnumerator StartFlexibleUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);

  while (!startUpdateRequest.IsDone)
  {
  // For flexible flow,the user can continue to use the app while
  // the update downloads in the background. You can implement a
  // progress bar showing the download status during this time.
  yield return null;
  }

}

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

IEnumerator CompleteFlexibleUpdate()
{
  var result = appUpdateManager.CompleteUpdate();
  yield return result;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (e.g. by
  // logging result.Error or by displaying a message to the user).
}

Acil güncellemeyi işleme

Güncel bir AppUpdateInfo nesnesi ve düzgün yapılandırılmış bir AppUpdateOptions nesnesi oluşturduktan sonra, güncelleme akışı isteğinde bulunmak için AppUpdateManager.StartUpdate() işlevini ayrıştırmalı olarak çağırabilirsiniz.

IEnumerator StartImmediateUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);
  yield return startUpdateRequest;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (for
  // example, by logging result.Error or by displaying a message to the user).
}

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.

  • StartUpdate() bir ArgumentNullException atarsa AppUpdateInfo boş demektir. Güncelleme akışını başlatmadan önce GetAppUpdateInfo() tarafından döndürülen AppUpdateInfo nesnesinin null olmadığından emin olun.
  • PlayAsyncOperation, ErrorUpdateUnavailable hata kodunu döndürüyorsa aynı uygulama kimliğine ve imzalama anahtarına sahip güncel bir uygulama sürümünün bulunduğundan emin olun.
  • PlayAsyncOperation, ErrorUpdateNotAllowed hata kodunu döndürüyorsa AppUpdateOptions nesnesi, mevcut güncelleme için izin verilmeyen bir güncelleme türünü gösteriyor demektir. Güncelleme akışını başlatmadan önce AppUpdateInfo 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.