Obsługa aktualizacji w aplikacji (natywne)

Z tego przewodnika dowiesz się, jak obsługiwać aktualizacje w aplikacji za pomocą kodu natywnego (C lub C++). Osobne przewodniki dotyczą przypadków, gdy implementacja korzysta z języka programowania Kotlin lub Java, oraz przypadków, gdy implementacja korzysta z Unity lub Unreal Engine.

Omówienie natywnego pakietu SDK

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych należy do rodziny pakietów SDK podstawowej biblioteki Play. Pakiet Native SDK zawiera plik nagłówka C app_update.h, który opakowuje AppUpdateManager z biblioteki aktualizacji aplikacji w Google Play w języku Java. Ten plik nagłówka umożliwia aplikacji wywoływanie interfejsu API aktualizacji w aplikacji bezpośrednio z kodu natywnego.

Konfigurowanie środowiska programistycznego

1. Wykonaj jedną z tych czynności:

   • Zainstaluj Android Studio w wersji 4.0 lub nowszej. Użyj interfejsu SDK Managera, aby zainstalować platformę Android SDK w wersji 10.0 (poziom interfejsu API 29).
   • Zainstaluj narzędzia wiersza poleceń Android SDK i użyj sdkmanager, aby zainstalować platformę Android SDK w wersji 10.0 (interfejs API na poziomie 29).

2. Przygotuj Android Studio do tworzenia aplikacji natywnych, używając SDK Managera do zainstalowania najnowszej wersji CMake i pakietu Android Native Development Kit (NDK). Więcej informacji o tworzeniu i importowaniu projektów natywnych znajdziesz w artykule Pierwsze kroki z NDK.

3. Pobierz plik ZIP i rozpakuj go w projekcie.

   Link pobierania	Rozmiar	Suma kontrolna SHA-256
   play-core-native-sdk-1.16.0.zip	54,8 MiB	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

4. Zaktualizuj plik build.gradle aplikacji w sposób pokazany poniżej:

   Dynamiczny

       // 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.1.0'
           implementation 'com.google.android.play:asset-delivery:2.3.0'
           implementation 'com.google.android.play:integrity:1.6.0'
           implementation 'com.google.android.play:review:2.0.2'
   
           // 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.1.0")
       implementation("com.google.android.play:asset-delivery:2.3.0")
       implementation("com.google.android.play:integrity:1.6.0")
       implementation("com.google.android.play:review:2.0.2")
   
       // Import these common dependencies.
       implementation("com.google.android.gms:play-services-tasks:18.0.2")
       implementation(files("$playcoreDir/playcore-native-metadata.jar"))
       ...
   }

5. Zaktualizuj pliki CMakeLists.txt aplikacji w sposób pokazany poniżej:

   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
           ...)
   

Zbieranie danych

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych może zbierać dane związane z wersją, aby umożliwić Google ulepszanie usługi. Dotyczy to m.in.:

• Nazwa pakietu aplikacji
• Wersja pakietu aplikacji
• Wersja pakietu SDK podstawowej biblioteki Play do aplikacji natywnych

Te dane będą zbierane, gdy prześlesz pakiet aplikacji do Konsoli Play. Aby zrezygnować z tego procesu zbierania danych, usuń import $playcoreDir/playcore-native-metadata.jar w pliku build.gradle.

Pamiętaj, że zbieranie danych związanych z korzystaniem z pakietu Play Core Native SDK i wykorzystywanie ich przez Google jest niezależne od zbierania przez Google zależności bibliotek zadeklarowanych w Gradle podczas przesyłania pakietu aplikacji do Konsoli Play.

Po zintegrowaniu pakietu SDK podstawowej biblioteki Play do aplikacji natywnych z projektem dodaj ten wiersz w plikach zawierających wywołania interfejsu API:

#include "play/app_update.h"

Inicjowanie interfejsu In-App Update API

Za każdym razem, gdy używasz interfejsu API aktualizacji w aplikacji, najpierw zainicjuj go, wywołując funkcję AppUpdateManager_init(), jak w tym przykładzie utworzonym za pomocą android_native_app_glue.h:

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.
  }
}

Sprawdzanie dostępności aktualizacji

Zanim poprosisz o aktualizację, sprawdź, czy jest dostępna aktualizacja aplikacji. AppUpdateManager_requestInfo() uruchamia żądanie asynchroniczne, które zbiera informacje wymagane do późniejszego uruchomienia procesu aktualizacji w aplikacji. Jeśli żądanie zostanie pomyślnie uruchomione, funkcja zwraca APP_UPDATE_NO_ERROR.

AppUpdateErrorCode error_code = AppUpdateManager_requestInfo()

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

Możesz śledzić proces i wynik żądania za pomocą AppUpdateManager_getInfo(). Oprócz kodu błędu ta funkcja zwraca nieprzezroczystą strukturę AppUpdateInfo, której możesz użyć do pobrania informacji o żądaniu aktualizacji. Możesz na przykład wywoływać tę funkcję w każdej pętli gry, dopóki nie zwróci wyniku innego niż null dla info:

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
   }
...
}

Sprawdzanie aktualności aktualizacji

Oprócz sprawdzenia, czy aktualizacja jest dostępna, możesz też sprawdzić, ile czasu minęło od ostatniego powiadomienia użytkownika o aktualizacji w Sklepie Play. Pomoże Ci to zdecydować, czy zainicjować aktualizację elastyczną czy natychmiastową. Możesz na przykład odczekać kilka dni, zanim powiadomisz użytkownika o aktualizacji elastycznej, i kolejne kilka dni, zanim zażądasz natychmiastowej aktualizacji.

Użyj AppUpdateInfo_getClientVersionStalenessDays(), aby sprawdzić liczbę dni, które upłynęły od udostępnienia aktualizacji w Sklepie Play:

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

Sprawdzanie priorytetu aktualizacji

Interfejs Google Play Developer API umożliwia ustawienie priorytetu każdej aktualizacji. Dzięki temu aplikacja może określić, jak bardzo zalecać użytkownikowi aktualizację. Rozważmy na przykład taką strategię ustawiania priorytetu aktualizacji:

• Drobne ulepszenia interfejsu: aktualizacja o niskim priorytecie; nie proś o aktualizację elastyczną ani natychmiastową. Aktualizuj tylko wtedy, gdy użytkownik nie korzysta z aplikacji.
• Ulepszenia wydajności: aktualizacja o średnim priorytecie; poproś o aktualizację elastyczną.
• Krytyczna aktualizacja zabezpieczeń: aktualizacja o wysokim priorytecie; prośba o natychmiastową aktualizację.

Do określenia priorytetu Google Play używa liczby całkowitej z zakresu od 0 do 5, gdzie 0 to wartość domyślna, a 5 to najwyższy priorytet. Aby ustawić priorytet aktualizacji, użyj pola inAppUpdatePriority w sekcji Edits.tracks.releases w interfejsie Google Play Developer API. Wszystkie nowo dodane wersje w wersji są traktowane jako mające ten sam priorytet co wersja. Priorytet można ustawić tylko podczas wdrażania nowej wersji i nie można go później zmienić.

Ustaw priorytet za pomocą interfejsu Google Play Developer API zgodnie z opisem w dokumentacji interfejsu Play Developer API. Określ priorytet aktualizacji w aplikacji w zasobie Edit.tracks przekazanym w metodzie Edit.tracks: update. Poniższy przykład pokazuje, jak opublikować aplikację z kodem wersji 88 i inAppUpdatePriority 5:

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

W kodzie aplikacji możesz sprawdzić poziom priorytetu danej aktualizacji, używając AppUpdateInfo_getPriority():

int32_t priority = AppUpdateInfo_getPriority(info);

Rozpoczynanie aktualizacji

Po potwierdzeniu, że aktualizacja jest dostępna, możesz poprosić o jej zainstalowanie za pomocą AppUpdateManager_requestStartUpdate(). Zanim poprosisz o aktualizację, pobierz aktualny obiekt AppUpdateInfo i utwórz obiekt AppUpdateOptions, aby skonfigurować proces aktualizacji. Obiekt AppUpdateOptions definiuje opcje procesu aktualizacji aplikacji, w tym to, czy aktualizacja powinna być elastyczna czy natychmiastowa.

Ten przykład tworzy obiekt AppUpdateOptions dla elastycznego procesu aktualizacji:

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

Ten przykład tworzy obiekt AppUpdateOptions dla procesu natychmiastowej aktualizacji:

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

Obiekt AppUpdateOptions zawiera też pole AllowAssetPackDeletion, które określa, czy aktualizacja może wyczyścić pakiety zasobów w przypadku ograniczonej pamięci urządzenia. To pole jest domyślnie ustawione na false, ale możesz użyć metody AppUpdateOptions_setAssetPackDeletionAllowed(), aby ustawić je na true:

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

Gdy masz już aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, wywołaj AppUpdateManager_requestStartUpdate(), aby asynchronicznie poprosić o proces aktualizacji, przekazując aktywność Androida jobject jako ostatni parametr.

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

Aby zwolnić zasoby, wywołaj metody AppUpdateInfo_destroy() i AppUpdateOptions_destroy(), które zwolnią niepotrzebne już instancje AppUpdateInfo i AppUpdateOptions.

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

W przypadku natychmiastowej aktualizacji Google Play wyświetla stronę potwierdzenia użytkownika. Gdy użytkownik zaakceptuje prośbę, Google Play automatycznie pobierze i zainstaluje aktualizację na pierwszym planie, a następnie uruchomi ponownie aplikację w zaktualizowanej wersji, jeśli instalacja się powiedzie.

W przypadku elastycznego procesu aktualizacji możesz nadal prosić o aktualne obiekty AppUpdateInfo, aby śledzić bieżący stan aktualizacji, gdy użytkownik nadal korzysta z aplikacji. Po zakończeniu pobierania musisz wywołać zakończenie aktualizacji, wywołując metodę AppUpdateManager_requestCompleteUpdate(), jak w tym przykładzie:

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.
    }
}

Zwolnij zasoby, wywołując funkcję AppUpdateManager_destroy(), gdy aplikacja zakończy korzystanie z interfejsu API.

Obsługa błędów

W tej sekcji opisujemy rozwiązania typowych błędów wskazywanych przez określone wartości AppUpdateErrorCode:

• Kod błędu -110, APP_UPDATE_INITIALIZATION_NEEDED oznacza, że interfejs API nie został zainicjowany. Wywołaj AppUpdateManager_init(), aby zainicjować interfejs API.
• Kod błędu -4, APP_UPDATE_INVALID_REQUEST oznacza, że niektóre parametry żądania procesu aktualizacji są nieprawidłowe. Sprawdź, czy obiekty AppUpdateInfo i AppUpdateOptions nie są puste i są prawidłowo sformatowane.
• Kod błędu -5, APP_UPDATE_UNAVAILABLE oznacza, że nie ma dostępnej odpowiedniej aktualizacji. Upewnij się, że wersja docelowa ma tę samą nazwę pakietu, identyfikator aplikacji i klucz podpisywania. Jeśli aktualizacja jest dostępna, wyczyść pamięć podręczną aplikacji i ponownie zadzwoń do AppUpdateManager_requestAppUpdateInfo(), aby odświeżyć AppUpdateInfo.
• Kod błędu -6, APP_UPDATE_NOT_ALLOWED oznacza, że typ aktualizacji wskazany przez obiekt AppUpdateOption jest niedozwolony. Przed rozpoczęciem procesu aktualizacji sprawdź, czy obiekt AppUpdateInfo wskazuje, że typ aktualizacji jest dozwolony.

Dalsze kroki

Przetestuj aktualizacje w aplikacji, aby sprawdzić, czy integracja działa prawidłowo.