Uygulama içi güncellemeleri destekleme (Yerel)

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

Yerel SDK'ya genel bakış

Play Core Yerel SDK'sı, Play Core SDK ailesinin bir parçasıdır. Yerel SDK, Java Play Uygulama İçi Güncelleme Kitaplığı'ndan AppUpdateManager sarmalayan C başlık dosyası (app_update.h) içerir. Bu başlık dosyası, uygulamanızın doğrudan yerel kodunuzdan uygulama içi güncellemeler için API'yi çağırmasına olanak tanır.

Geliştirme ortamınızı ayarlama

1. Aşağıdakilerden birini yapın:

   • Android Studio'nun 4.0 veya sonraki bir sürümünü yükleyin. Android SDK Platformu 10.0 (API düzeyi 29) sürümünü yüklemek için SDK Yöneticisi kullanıcı arayüzünü kullanın.
   • Android SDK komut satırı araçlarını yükleyin ve Android SDK Platform 10.0 (API düzeyi 29) sürümünü yüklemek için sdkmanager aracını kullanın.

2. En yeni CMake ve Android Yerel Geliştirme Kiti'ni (NDK) yüklemek için SDK Yöneticisi'ni kullanarak Android Studio'yu yerel geliştirmeye hazırlayın. Yerel projeler oluşturma veya içe aktarma hakkında daha fazla bilgi için NDK'yı Kullanmaya Başlama bölümüne bakın.

3. ZIP dosyasını indirin ve projenizle birlikte çıkarın.

   Bağlantıyı İndir	Boyut	SHA-256 Sağlaması
   play-core-native-sdk-1.14.0.zip	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

4. Uygulamanızın build.gradle dosyasını aşağıda gösterildiği gibi güncelleyin:

   Eski

       // App build.gradle
   
       plugins {
         id 'com.android.application'
       }
   
       // Define a path to the extracted Play Core SDK files.
       // If using a relative path, wrap it with file() since CMake requires absolute paths.
       def playcoreDir = file('../path/to/playcore-native-sdk')
   
       android {
           defaultConfig {
               ...
               externalNativeBuild {
                   cmake {
                       // Define the PLAYCORE_LOCATION directive.
                       arguments "-DANDROID_STL=c++_static",
                                 "-DPLAYCORE_LOCATION=$playcoreDir"
                   }
               }
               ndk {
                   // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                   abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
               }
           }
           buildTypes {
               release {
                   // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                   proguardFile '$playcoreDir/proguard/common.pgcfg'
                   proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                   proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                   ...
               }
               debug {
                   ...
               }
           }
           externalNativeBuild {
               cmake {
                   path 'src/main/CMakeLists.txt'
               }
           }
       }
   
       dependencies {
           // Import these feature-specific AARs for each Google Play Core library.
           implementation 'com.google.android.play:app-update:2.0.0'
           implementation 'com.google.android.play:asset-delivery:2.0.0'
           implementation 'com.google.android.play:integrity:1.0.1'
           implementation 'com.google.android.play:review:2.0.0'
   
           // Import these common dependencies.
           implementation 'com.google.android.gms:play-services-tasks:18.0.2'
           implementation files("$playcoreDir/playcore-native-metadata.jar")
           ...
       }
       

   Kotlin

   // App build.gradle
   
   plugins {
       id("com.android.application")
   }
   
   // Define a path to the extracted Play Core SDK files.
   // If using a relative path, wrap it with file() since CMake requires absolute paths.
   val playcoreDir = file("../path/to/playcore-native-sdk")
   
   android {
       defaultConfig {
           ...
           externalNativeBuild {
               cmake {
                   // Define the PLAYCORE_LOCATION directive.
                   arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
               }
           }
           ndk {
               // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
               abiFilters.clear()
               abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
           }
       }
       buildTypes {
           release {
               // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
               proguardFile("$playcoreDir/proguard/common.pgcfg")
               proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
               proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
               ...
           }
           debug {
               ...
           }
       }
       externalNativeBuild {
           cmake {
               path = "src/main/CMakeLists.txt"
           }
       }
   }
   
   dependencies {
       // Import these feature-specific AARs for each Google Play Core library.
       implementation("com.google.android.play:app-update:2.0.0")
       implementation("com.google.android.play:asset-delivery:2.0.0")
       implementation("com.google.android.play:integrity:1.0.1")
       implementation("com.google.android.play:review:2.0.0")
   
       // Import these common dependencies.
       implementation("com.google.android.gms:play-services-tasks:18.0.2")
       implementation(files("$playcoreDir/playcore-native-metadata.jar"))
       ...
   }
   

5. Uygulamanızın CMakeLists.txt dosyalarını aşağıda gösterildiği gibi güncelleyin:

   cmake_minimum_required(VERSION 3.6)
   
   ...
   
   # Add a static library called “playcore” built with the c++_static STL.
   include(${PLAYCORE_LOCATION}/playcore.cmake)
   add_playcore_static_library()
   
   // In this example “main” is your native code library, i.e. libmain.so.
   add_library(main SHARED
           ...)
   
   target_include_directories(main PRIVATE
           ${PLAYCORE_LOCATION}/include
           ...)
   
   target_link_libraries(main
           android
           playcore
           ...)
   

Veri Toplama

Play Core Yerel SDK'sı, Google'ın ürünü iyileştirmesini sağlamak için sürümle ilgili verileri toplayabilir. Buna şunlar dahildir:

• Uygulamanın paket adı
• Uygulamanın paket sürümü
• Play Core Yerel SDK sürümü

Bu veriler, uygulama paketinizi Play Console'a yüklediğinizde toplanır. Bu veri toplama işlemini devre dışı bırakmak için build.gradle dosyasındaki $playcoreDir/playcore-native-metadata.jar içe aktarma işlemini kaldırın.

Play Core Yerel SDK'yı kullanımınızla ve Google'ın toplanan verileri kullanımıyla ilgili bu veri toplama işleminin, uygulama paketinizi Play Console'a yüklediğinizde Google'ın Gradle'da beyan ettiği kitaplık bağımlılıkları toplamasından ayrı ve bağımsız olduğunu unutmayın.

Play Core Yerel SDK'sını projenize entegre ettikten sonra API çağrıları içeren dosyalara aşağıdaki satırı ekleyin:

#include "play/app_update.h"

Uygulama içi güncelleme API'sini başlatma

In-App Update API'yi kullanırken öncelikle android_native_app_glue.h ile derlenen aşağıdaki örnekte gösterildiği gibi AppUpdateManager_init() işlevini çağırarak API'yi başlatın:

void android_main(android_app* app) {
  app->onInputEvent = HandleInputEvent;

  AppUpdateErrorCode error_code =
    AppUpdateManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == APP_UPDATE_NO_ERROR) {
    // You can use the API.
  }
}

Güncelleme kullanılabilirliğini kontrol etme

Güncelleme isteğinde bulunmadan önce uygulamanız için bir güncelleme olup olmadığını kontrol edin. AppUpdateManager_requestInfo(), uygulama içi güncelleme akışını daha sonra başlatmak için gerekli bilgileri toplayan eşzamansız bir istek başlatır. İstek başarıyla başlatılırsa işlev APP_UPDATE_NO_ERROR değerini döndürür.

AppUpdateErrorCode error_code = AppUpdateManager_requestInfo()

if (error_code == APP_UPDATE_NO_ERROR) {
    // The request has successfully started, check the result using
    // AppUpdateManager_getInfo.
}

AppUpdateManager_getInfo() kullanarak devam eden süreci ve isteğin sonucunu takip edebilirsiniz. Bu işlev, hata koduna ek olarak, güncelleme isteği hakkında bilgi almak için kullanabileceğiniz bir AppUpdateInfo opak struct döndürür. Örneğin, info için null olmayan bir sonuç döndürene kadar bu işlevi her oyun döngüsünde çağırmak isteyebilirsiniz:

AppUpdateInfo* info;
GameUpdate() {

   // Keep calling this in every game loop until info != nullptr
   AppUpdateErrorCode error_code = AppUpdateManager_getInfo(&info);


   if (error_code == APP_UPDATE_NO_ERROR && info != nullptr) {
       // Successfully started, check the result in the following functions
   }
...
}

Güncelleme eskiliğini kontrol etme

Bir güncellemenin mevcut olup olmadığını kontrol etmenin yanı sıra kullanıcıya Play Store üzerinden son güncelleme bildiriminden bu yana ne kadar süre geçtiğini de kontrol etmek isteyebilirsiniz. Bu, esnek bir güncelleme mi yoksa hemen bir güncelleme mi başlatmanız gerektiğine karar vermenize yardımcı olabilir. Örneğin, kullanıcıyı esnek bir güncellemeyle bilgilendirmeden önce birkaç gün ve bundan sonra, acil güncelleme gerektirmeden birkaç gün bekleyebilir.

Güncellemenin Play Store'da kullanıma sunulmasından bu yana geçen gün sayısını kontrol etmek için AppUpdateInfo_getClientVersionStalenessDays() aracını kullanın:

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

Güncelleme önceliğini kontrol edin

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

• Kullanıcı arayüzünde küçük iyileştirmeler: Düşük öncelikli güncelleme; ne esnek güncelleme ne de anında güncelleme isteğinde bulunun. Yalnızca kullanıcı, uygulamanızla etkileşim kurmadığında güncelleyin.
• Performans iyileştirmeleri: Orta öncelikli güncelleme; esnek bir güncelleme isteyin.
• Kritik güvenlik güncellemesi: Yüksek öncelikli güncelleme; anında 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'deki 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 sahiptir. Öncelik yalnızca yeni bir sürüm kullanıma sunulurken ayarlanabilir ve daha sonra değiştirilemez.

Önceliği, Play Developer API belgelerinde açıklandığı gibi Google Play Developer API'yi kullanarak ayarlayın. Uygulama içi güncelleme önceliğini Edit.tracks: update yönteminde iletilen Edit.tracks kaynağında belirtin. Aşağıdaki örnekte, 88 ve inAppUpdatePriority 5 sürüm koduyla bir uygulama yayınlanması gösterilmektedir:

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

Uygulamanızın kodunda, belirli bir güncellemenin öncelik düzeyini AppUpdateInfo_getPriority() kullanarak kontrol edebilirsiniz:

int32_t priority = AppUpdateInfo_getPriority(info);

Güncelleme başlatın

Bir güncellemenin olduğunu onayladıktan sonra AppUpdateManager_requestStartUpdate() adresini kullanarak güncelleme isteğinde bulunabilirsiniz. Güncelleme isteğinde bulunmadan önce güncel bir AppUpdateInfo nesnesi alın ve güncelleme akışını yapılandırmak için AppUpdateOptions nesnesi oluşturun. AppUpdateOptions nesnesi, uygulama içi güncelleme akışıyla ilgili seçenekleri tanımlar. Güncellemenin esnek mi yoksa hemen mi olacağı da buna dahildir.

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

// Creates an AppUpdateOptions configuring a flexible in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_FLEXIBLE, &options);

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

// Creates an AppUpdateOptions configuring an immediate in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_IMMEDIATE, &options);

AppUpdateOptions nesnesi, cihaz depolama alanının sınırlı olması durumunda güncellemenin öğe paketlerini temizlemesine izin verilip verilmediğini tanımlayan bir AllowAssetPackDeletion alanı da içerir. Bu alan varsayılan olarak false değerine ayarlıdır ancak bunun yerine AppUpdateOptions_setAssetPackDeletionAllowed() yöntemini kullanarak true olarak ayarlayabilirsiniz:

bool allow = true;
AppUpdateErrorCode error_code = AppUpdateOptions_setAssetPackDeletionAllowed(options, allow);

Güncel bir AppUpdateInfo nesneniz ve uygun şekilde yapılandırılmış bir AppUpdateOptions nesneniz olduğunda, son parametre için bir Android Etkinliği jobject ileterek eşzamansız olarak bir güncelleme akışı istemek için AppUpdateManager_requestStartUpdate() yöntemini çağırın.

AppUpdateErrorCode request_error_code =
AppUpdateManager_requestStartUpdate(info, options, app->activity->clazz);

Kaynakları serbest bırakmak için artık ihtiyaç duymadığınız AppUpdateInfo ve AppUpdateOptions örneklerini sırasıyla AppUpdateInfo_destroy() ve AppUpdateOptions_destroy() çağırarak yayınlayın.

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

Google Play, anında güncelleme akışı için bir kullanıcı onay sayfası gösterir. Kullanıcı isteği kabul ettiğinde Google Play güncellemeyi otomatik olarak indirip ön plana yükler. Yükleme işlemi başarılı olursa uygulamayı güncellenmiş sürümle yeniden başlatır.

Esnek bir güncelleme akışı için kullanıcı uygulamayla etkileşim kurmaya devam ederken mevcut güncelleme durumunu takip etmek amacıyla güncel AppUpdateInfo nesneleri istemeye devam edebilirsiniz. İndirme işlemi başarıyla tamamlandıktan sonra, aşağıdaki örnekte gösterildiği gibi AppUpdateManager_requestCompleteUpdate() çağrısı yaparak güncellemenin tamamlanmasını tetiklemeniz gerekir:

AppUpdateStatus status = AppUpdateInfo_getStatus(info);
if (status == APP_UPDATE_DOWNLOADED) {
    AppUpdateErrorCode error_code = AppUpdateManager_requestCompleteUpdate();
    if (error_code != APP_UPDATE_NO_ERROR)
    {
      // There was an error while completing the update flow.
    }
}

Uygulamanızın API kullanımı bittikten sonra AppUpdateManager_destroy() işlevini çağırarak kaynakları serbest bırakın.

Hata işleme

Bu bölümde, belirli AppUpdateErrorCode değerleriyle belirtilen yaygın hataların çözümleri açıklanmaktadır:

• -110, APP_UPDATE_INITIALIZATION_NEEDED hata kodu, API'nin başarıyla başlatılmadığını gösterir. API'yi başlatmak için AppUpdateManager_init() yöntemini çağırın.
• -4, APP_UPDATE_INVALID_REQUEST hata kodu, güncelleme akışı isteğine ait bazı parametrelerin hatalı olduğunu gösterir. AppUpdateInfo ve AppUpdateOptions nesnelerinin boş olmadığından ve doğru biçimlendirildiğinden emin olun.
• -5, APP_UPDATE_UNAVAILABLE hata kodu, geçerli bir güncelleme olmadığını gösterir. Hedef sürümün aynı paket adı, uygulama kimliği ve imzalama anahtarı olduğundan emin olun. Güncelleme varsa uygulamanın önbelleğini temizleyin ve AppUpdateInfo uygulamasını yenilemek için AppUpdateManager_requestAppUpdateInfo() yöntemini tekrar çağırın.
• -6, APP_UPDATE_NOT_ALLOWED hata kodu, AppUpdateOption nesnesi tarafından belirtilen güncelleme türüne izin verilmediğini belirtir. Güncelleme akışı başlamadan önce AppUpdateInfo nesnesinin güncelleme türüne izin verilip verilmediğini kontrol edin.

Sonraki adımlar

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