Ta strona została przetłumaczona przez Cloud Translation API.

Obsługa aktualizacji w aplikacji (natywna)

W tym przewodniku opisujemy, jak obsługiwać aktualizacje w aplikacji przy użyciu kodu natywnego (C lub C++). Istnieją osobne przewodniki dla przypadków, w których implementacja jest oparta na języku programowania Kotlin lub Java, oraz w sytuacjach, gdy używa ona Unity.

Omówienie natywnego pakietu SDK

Podstawowy pakiet SDK Google Play należy do rodziny pakietów SDK Play Core. Natywny pakiet SDK zawiera plik nagłówka C (app_update.h), który otacza AppUpdateManager z biblioteki aktualizacji Javy Play w aplikacji. Ten plik nagłówka pozwala aplikacji bezpośrednio z Twojego kodu natywnego wywoływać interfejs API na potrzeby aktualizacji w aplikacji.

Konfigurowanie środowiska programistycznego

Download Play Core Native SDK

Before downloading, you must agree to the following terms and conditions.

Terms and Conditions

Last modified: September 24, 2020

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.
For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
“Redistributable Code” means Google-provided object code or header files that call the APIs.
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.
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.

I have read and agree with the above terms and conditions

Download Play Core Native SDK

play-core-native-sdk-1.14.0.zip

Wykonaj jedną z tych czynności:
- Zainstaluj Android Studio w wersji 4.0 lub nowszej. Użyj interfejsu SDK Managera, aby zainstalować pakiet Android SDK Platform w wersji 10.0 (poziom interfejsu API 29).
- Zainstaluj narzędzia wiersza poleceń pakietu Android SDK i użyj narzędzia sdkmanager, aby zainstalować pakiet Android SDK Platform w wersji 10.0 (poziom interfejsu API 29).
Przygotuj Androida Studio do tworzenia aplikacji natywnych, korzystając z Menedżera SDK do zainstalowania najnowszych wersji CMake i Android Native Development Kit (NDK). Więcej informacji o tworzeniu i importowaniu projektów natywnych znajdziesz w artykule wprowadzającym do NDK.

Pobierz plik ZIP i rozpakuj go razem z projektem.

Link do pobierania	Rozmiar	Suma kontrolna SHA-256
	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

Zaktualizuj plik build.gradle aplikacji, jak pokazano poniżej:

Odlotowe

    // 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"))
    ...
}

Zaktualizuj pliki CMakeLists.txt aplikacji, jak pokazano 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

Aby umożliwić Google ulepszanie usługi, pakiet Play Core Native SDK może gromadzić dane dotyczące wersji, w tym:

Nazwa pakietu aplikacji
Wersja pakietu aplikacji
Wersja Core Native SDK w Google Play

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 z pliku build.gradle.

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

Po zintegrowaniu z projektem natywnego pakietu Play Core umieść ten wiersz w plikach 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, zainicjuj go najpierw, wywołując funkcję AppUpdateManager_init() w sposób podany 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.
  }
}

Sprawdź dostępność aktualizacji

Zanim poprosisz o aktualizację, sprawdź, czy jest dostępna aktualizacja Twojej aplikacji. AppUpdateManager_requestInfo() uruchamia asynchroniczne żądanie, które zbiera informacje wymagane do późniejszego uruchomienia procesu aktualizacji w aplikacji. Jeśli żądanie zostanie 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.
}

Trwający proces oraz wynik żądania możesz śledzić za pomocą narzędzia AppUpdateManager_getInfo(). Oprócz kodu błędu ta funkcja zwraca nieprzejrzystą strukturę AppUpdateInfo, której można 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 ona wyniku info, który nie jest pusty:

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

Sprawdź aktualność aktualizacji

Oprócz sprawdzenia, czy jest dostępna aktualizacja, możesz też sprawdzić, ile czasu upłynęło od ostatniego powiadomienia użytkownika o aktualizacji w Sklepie Play. Pomoże Ci to podjąć decyzję, czy aktualizacja jest elastyczna czy natychmiastowa. Możesz np. odczekać kilka dni przed powiadomieniem użytkownika o elastycznej aktualizacji i kilka dni później, zanim zażądasz natychmiastowej aktualizacji.

Użyj narzędzia AppUpdateInfo_getClientVersionStalenessDays(), aby sprawdzić, ile dni minęło od udostępnienia aktualizacji w Sklepie Play:

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

Sprawdź priorytet aktualizacji

Interfejs Google Play Developer API pozwala określić priorytet każdej aktualizacji. Dzięki temu aplikacja może zdecydować, jak zdecydowanie zalecić aktualizację użytkownikowi. Rozważ na przykład tę strategię ustalania priorytetu aktualizacji:

Drobne ulepszenia interfejsu użytkownika: aktualizacja o niskim priorytecie; nie wymaga elastycznych aktualizacji ani natychmiastowej aktualizacji. Aktualizuj tylko wtedy, gdy użytkownik nie wchodzi w interakcję z aplikacją.
Ulepszenia wydajności: aktualizacja o średnim priorytecie; prośba o elastyczną aktualizację.
Krytyczna aktualizacja zabezpieczeń: aktualizacja o wysokim priorytecie – prośba o natychmiastową aktualizację.

Aby określić priorytet, Google Play używa wartości całkowitej z zakresu od 0 do 5, gdzie 0 oznacza wartość domyślną, a 5 – najwyższy priorytet. Priorytet aktualizacji możesz ustawić w polu inAppUpdatePriority w sekcji Edits.tracks.releases w interfejsie Google Play Developer API. Wszystkie nowo dodane wersje w danej wersji są traktowane jako mające ten sam priorytet co wersja. Priorytet można ustawić tylko podczas wdrażania nowej wersji. 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 publikowanie aplikacji z kodem wersji 88 i inAppUpdatePriority 5:

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

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

int32_t priority = AppUpdateInfo_getPriority(info);

Rozpocznij aktualizację

Po potwierdzeniu, że aktualizacja jest dostępna, możesz poprosić o jej udostępnienie na stronie AppUpdateManager_requestStartUpdate(). Zanim poprosisz o aktualizację, pobierz aktualny obiekt AppUpdateInfo i utwórz obiekt AppUpdateOptions, aby skonfigurować przepływ aktualizacji. Obiekt AppUpdateOptions określa opcje procesu aktualizacji w aplikacji, w tym czy aktualizacja powinna być elastyczna czy natychmiastowa.

Poniższy przykład pokazuje obiekt AppUpdateOptions na potrzeby 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, aby umożliwić natychmiastową aktualizację:

// 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 czyścić pakiety zasobów w przypadku ograniczonej pamięci urządzenia. To pole jest domyślnie ustawione na false, ale możesz zamiast tego ustawić wartość true za pomocą metody AppUpdateOptions_setAssetPackDeletionAllowed():

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

Gdy będziesz już mieć aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, wywołaj AppUpdateManager_requestStartUpdate(), aby asynchronicznie zażądać procesu aktualizacji, przesyłając jobject aktywność na Androidzie jako parametr końcowy.

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

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

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

Aby natychmiast przeprowadzić aktualizację, Google Play wyświetla stronę potwierdzenia użytkownika. Gdy użytkownik zaakceptuje żądanie, Google Play automatycznie pobierze i zainstaluje aktualizację na pierwszym planie. Jeśli instalacja się powiedzie, aplikacja uruchomi się ponownie w zaktualizowanej wersji.

Jeśli chcesz użyć elastycznego procesu aktualizacji, możesz wysyłać żądania o aktualne obiekty AppUpdateInfo, aby śledzić bieżący stan aktualizacji, gdy użytkownik nadal korzysta z aplikacji. Po zakończeniu pobierania musisz wywołać funkcję AppUpdateManager_requestCompleteUpdate(), jak widać 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() po zakończeniu korzystania przez aplikację z interfejsu API.

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 oznacza, że nie udało się zainicjować interfejsu API. Wywołaj AppUpdateManager_init(), aby zainicjować interfejs API.
Kod błędu -4, APP_UPDATE_INVALID_REQUEST oznacza, że niektóre parametry żądania aktualizacji są uszkodzone. Sprawdź, czy obiekty AppUpdateInfo i AppUpdateOptions nie mają wartości null i są prawidłowo sformatowane.
Kod błędu -5, APP_UPDATE_UNAVAILABLE oznacza, że nie ma odpowiedniej aktualizacji. Sprawdź, czy wersja docelowa ma taką samą nazwę pakietu, identyfikator aplikacji i klucz podpisywania. Jeśli dostępna jest aktualizacja, wyczyść pamięć podręczną aplikacji i ponownie wywołaj AppUpdateManager_requestAppUpdateInfo(), by 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 ten typ aktualizacji jest dozwolony.

Dalsze kroki

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