Obsługa aktualizacji w aplikacji (natywna)

Z tego przewodnika dowiesz się, jak obsługiwać aktualizacje w aplikacji za pomocą kodu natywnego (C lub C++). Istnieją oddzielne przewodniki na potrzeby implementacji, które używają języka programowania Kotlin lub Javy, oraz implementacji, które używają Unity.

Omówienie natywnego pakietu SDK

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych należy do rodziny pakietów SDK podstawowej biblioteki Play. Pakiet SDK natywny zawiera plik nagłówka C, app_update.h, który zawiera app_update.hz biblioteki Play In-App Update Library w języku Java.AppUpdateManager Ten plik nagłówka umożliwia aplikacji wywoływanie interfejsu API w celu aktualizacji w aplikacji bezpośrednio z użyciem kodu natywnego.

1. Wykonaj jedną z tych czynności:

   • Zainstaluj Android Studio w wersji 4.0 lub nowszej. Za pomocą interfejsu menedżera pakietu SDK zainstaluj pakiet Android SDK w wersji 10.0 (poziom interfejsu API 29).
   • Zainstaluj narzędzia wiersza poleceń pakietu Android SDK i uruchom sdkmanager, aby zainstalować platformę pakietu Android SDK w wersji 10.0 (poziom interfejsu API 29).

2. Przygotuj Android Studio do tworzenia aplikacji natywnych, instalując za pomocą Menedżera pakietu SDK najnowszą wersję CMake i pakietu Native Development Kit (NDK) na Androida. Więcej informacji o tworzeniu i importowaniu projektów natywnych znajdziesz w artykule Pierwsze kroki z NDK.

3. Pobierz plik ZIP i rozpakuj go obok projektu.

   Link do pobrania	Rozmiar	Suma kontrolna SHA-256
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. Zaktualizuj plik build.gradle aplikacji w ten sposób:

   Groovy

       // 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.2.2'
           implementation 'com.google.android.play:integrity:1.4.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.2.2")
       implementation("com.google.android.play:integrity:1.4.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 ten sposób:

   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. Te dane obejmują:

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

Te dane zostaną zebrane, gdy prześlesz pakiet aplikacji do Konsoli Play. Aby zrezygnować z zbierania danych, usuń import $playcoreDir/playcore-native-metadata.jar z pliku build.gradle.

Pamiętaj, że zbieranie danych związanych z użyciem przez Ciebie natywnego pakietu SDK Play Core i wykorzystywaniem przez Google zebranych danych jest odrębną kwestią i niezależną 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 z projektem dodaj ten wiersz do plików zawierających wywołania interfejsu API:

#include "play/app_update.h"

Inicjowanie interfejsu API aktualizacji w aplikacji

Za każdym razem, gdy używasz interfejsu API aktualizacji w aplikacji, najpierw inicjuj go, wywołując funkcję AppUpdateManager_init(), jak w poniższym przykładzie utworzonym za pomocą interfejsu 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 gromadzi wymagane informacje, aby później uruchomić proces aktualizacji w aplikacji. Funkcja zwraca APP_UPDATE_NO_ERROR, jeśli żądanie zostało uruchomione.

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ć postępy i wynik zgłoszenia za pomocą AppUpdateManager_getInfo(). Oprócz kodu błędu funkcja zwraca też 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 wartości niezerowej 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 jest dostępna aktualizacja, warto też sprawdzić, ile czasu minęło od ostatniego powiadomienia o aktualizacji w Sklepie Play. Pomoże Ci to zdecydować, czy chcesz przeprowadzić elastyczne, czy natychmiastowe wprowadzenie zmian. Możesz na przykład poczekać kilka dni, zanim powiadomisz użytkownika o możliwości aktualizacji, a po kilku kolejnych dniach poprosisz o natychmiastową aktualizację.

Użyj AppUpdateInfo_getClientVersionStalenessDays(), aby sprawdzić, ile dni minęło 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 mocno zalecić użytkownikowi aktualizację. Rozważ na przykład tę strategię ustawiania priorytetu aktualizacji:

• Niewielkie ulepszenia interfejsu: aktualizacja o niskim priorytecie; nie żądaj elastycznej aktualizacji ani natychmiastowej aktualizacji. Aktualizuj tylko wtedy, gdy użytkownik nie wchodzi w interakcję z aplikacją.
• Ulepszenia dotyczące wydajności: aktualizacja o średnim priorytecie; poproś o elastyczne aktualizacje.
• Niezbędna aktualizacja zabezpieczeń: wysoki priorytet; zalecana natychmiastowa aktualizacja.

Aby określić priorytet, Google Play używa liczby całkowitej z zakresu od 0 do 5, gdzie 0 jest domyślną wartością, a 5 – najwyższym priorytetem. Aby ustawić priorytet aktualizacji, użyj pola inAppUpdatePriority w interfejsie Google Play Developer API (Edits.tracks.releases). Wszystkie nowo dodane wersje w ramach danej wersji mają ten sam priorytet. Priorytet można ustawić tylko podczas wdrażania nowej wersji. Nie można go zmienić w późniejszym czasie.

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 ramach metody Edit.tracks: update. Ten przykład pokazuje, jak wydać 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 za pomocą AppUpdateInfo_getPriority():

int32_t priority = AppUpdateInfo_getPriority(info);

Rozpoczynanie aktualizacji

Po potwierdzeniu, że aktualizacja jest dostępna, możesz poprosić o jej zainstalowanie, korzystając z funkcji 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 w aplikacji, w tym to, czy aktualizacja ma być elastyczna, czy natychmiastowa.

W tym przykładzie tworzymy obiekt AppUpdateOptions do 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);

W tym przykładzie tworzymy obiekt AppUpdateOptions do natychmiastowego procesu 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 ilości miejsca na urządzeniu. To pole ma domyślnie wartość false, ale możesz użyć metody AppUpdateOptions_setAssetPackDeletionAllowed(), aby zamiast tego ustawić wartość true:

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

Gdy masz aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, wywołaj metodę AppUpdateManager_requestStartUpdate(), aby asynchronicznie przesłać żądanie procesu aktualizacji, przekazując jako ostatni parametr aktywność Androida jobject.

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

Aby zwolnić zasoby, zwolnij instancje AppUpdateInfo i AppUpdateOptions, których już nie potrzebujesz, odpowiednio wywołując AppUpdateInfo_destroy() i AppUpdateOptions_destroy().

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

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

Aby zapewnić elastyczność procesu aktualizacji, możesz stale 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ć metodę AppUpdateManager_requestCompleteUpdate(), aby rozpocząć proces aktualizacji. Przykład:

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

Po zakończeniu korzystania z interfejsu API przez aplikację uwolnij zasoby, wywołując funkcję AppUpdateManager_destroy().

Obsługa błędów

W tej sekcji znajdziesz rozwiązania dotyczące typowych błędów wskazywanych przez konkretne wartości AppUpdateErrorCode:

• Kod błędu -110, APP_UPDATE_INITIALIZATION_NEEDED wskazuje, że interfejs API nie został zainicjowany. Wywołaj funkcję AppUpdateManager_init(), aby zainicjować interfejs API.
• Kod błędu -4, APP_UPDATE_INVALID_REQUEST wskazuje, że niektóre parametry żądania procesu aktualizacji są nieprawidłowe. Sprawdź, czy obiekty AppUpdateInfo i AppUpdateOptions nie są puste i są poprawnie sformatowane.
• Kod błędu -5, APP_UPDATE_UNAVAILABLE oznacza, że nie ma dostępnych odpowiednich aktualizacji. Upewnij się, że wersja docelowa ma tę samą nazwę pakietu, identyfikator aplikacji i klucz podpisywania. Jeśli dostępna jest aktualizacja, wyczyść pamięć podręczną aplikacji i ponownie wywołaj funkcję AppUpdateManager_requestAppUpdateInfo(), aby odświeżyć AppUpdateInfo.
• Kod błędu -6, APP_UPDATE_NOT_ALLOWED wskazuje, ż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

Sprawdź aktualizacje w aplikacji, aby upewnić się, że integracja działa prawidłowo.