Obsługa aktualizacji w aplikacji (natywne)

W tym przewodniku opisano, jak obsługiwać aktualizacje w aplikacji za pomocą kodu natywnego (C lub C++). Istnieją osobne przewodniki na wypadek, gdy implementacja używa języka programowania Kotlin lub Javy, oraz na wypadek, gdy implementacja używa Unity lub Unreal Engine.

Uwaga: interfejs API natywnych funkcji do aktualizacji w aplikacji wymaga, aby aplikacja korzystała z biblioteki Play Core w wersji 1.10.0 lub nowszej.

Omówienie natywnego pakietu SDK

Natywny pakiet SDK Play Core należy do rodziny pakietów SDK Play Core. Pakiet SDK natywny zawiera plik nagłówka C, app_update.h, który zawiera AppUpdateManagerz biblioteki aktualizacji w aplikacji w Google Play. Ten plik nagłówka umożliwia aplikacji wywoływanie interfejsu API w celu aktualizacji w aplikacji bezpośrednio z użyciem kodu natywnego.

Konfigurowanie środowiska programistycznego

Pobierz Play Core Native SDK

Przed pobraniem musisz zaakceptować poniższe warunki.

Warunki korzystania z usługi

Last modified: September 24, 2020

1. By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
2. For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
3. “Redistributable Code” means Google-provided object code or header files that call the APIs.
4. Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
5. Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.

Znam i akceptuję powyższe warunki

Pobierz Play Core Native SDK Pobierz Play Core Native SDK

play-core-native-sdk-1.15.3.zip

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 najnowszą wersję CMake i pakietu Native Development Kit (NDK) na Androida za pomocą Menedżera pakietu SDK. 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.3.0'
           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.3.0")
       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 go zainicjuj, wywołując funkcję AppUpdateManager_init(), jak pokazano w tym przykładzie 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 można było uruchomić proces aktualizacji w aplikacji. Jeśli żądanie zostanie zrealizowane, funkcja zwróci wartość 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ć postępy i wynik zgłoszenia za pomocą AppUpdateManager_getInfo(). Oprócz kodu błędu funkcja zwraca niejawną 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, aż zwróci ona niezerową wartość 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 potem jeszcze kilka dni, zanim poprosisz o natychmiastową aktualizację.

Aby sprawdzić, ile dni minęło od udostępnienia aktualizacji w Sklepie Play, użyj AppUpdateInfo_getClientVersionStalenessDays():

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

Sprawdzanie priorytetu aktualizacji

Interfejs Google Play Developer API umożliwia ustawienie priorytetu każdej aktualizacji. Pozwala to aplikacji określić, jak mocno zalecić użytkownikowi zaktualizowanie aplikacji. Rozważ na przykład tę strategię ustawiania priorytetu aktualizacji:

• Niewielkie ulepszenia interfejsu: aktualizacja o niskim priorytecie; prośba o nieelastyczne ani natychmiastowe wdrożenie. 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 to domyślny priorytet, a 5 – 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 ramach danej wersji mają ten sam priorytet. 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 ramach metody Edit.tracks: update. Ten 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 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 usuwać pakiety zasobów w przypadku ograniczonej ilości miejsca na urządzeniu. 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);

Uwaga: używaj opcji interfejsu API AllowAssetPackDeletion ostrożnie, aby nie usunąć przypadkowo zasobów. Zanim ustawisz tę opcję na true, sprawdź, czy aktualizacja jest dozwolona, gdy ta opcja jest ustawiona na false.

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 funkcje 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 potem 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ę zwalniaj zasoby, wywołując funkcję AppUpdateManager_destroy().

Obsługa błędów

W tej sekcji znajdziesz rozwiązania typowych błędów wskazywanych przez określone 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

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