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

Obsługa aktualizacji w aplikacji (natywna)

Z tego przewodnika dowiesz się, jak obsługiwać aktualizacje w aplikacji za pomocą kodu natywnego (C lub C++). Poniżej znajdziesz instrukcje dotyczące sytuacji, w których implementacja używa języka programowania Kotlin lub języka programowania Java, oraz przypadków, w których Twoja implementacja korzysta z języka Unity.

Omówienie natywnego pakietu SDK

Pakiet Play Core Native SDK należy do Play Core SDK. Natywny pakiet SDK zawiera plik nagłówka C (app_update.h), który opakowuje AppUpdateManager z biblioteki aktualizacji w aplikacji Java Play. Umożliwia on aplikacji wywoływanie interfejsu API w celu aktualizacji bezpośrednio z kodu natywnego.

Konfigurowanie środowiska programistycznego

下载 Play Core Native SDK

您必须先接受以下条款及条件才能下载。

条款及条件

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.

我已阅读并同意上述条款及条件

下载 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 Menedżera pakietów SDK, aby zainstalować Android SDK Platform w wersji 10.0 (poziom API 29).
- Zainstaluj narzędzia wiersza poleceń pakietu Android SDK i użyj sdkmanager, aby zainstalować Android SDK Platform w wersji 10.0 (poziom API 29).
Przygotuj Android Studio do tworzenia aplikacji natywnych, korzystając z Menedżera SDK, aby zainstalować najnowszy pakiet NDK (CMake i Android Native Development Kit). Więcej informacji o tworzeniu i importowaniu projektów natywnych znajdziesz w artykule Wprowadzenie do pakietu NDK.

Pobierz plik ZIP i rozpakuj go wraz ze swoim projektem.

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

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

Odlotowy

    // 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 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

Podstawowy pakiet SDK w Google Play może gromadzić dane związane z wersją, aby umożliwić Google ulepszanie tej usługi. Obejmuje to:

Nazwa pakietu aplikacji
Wersja pakietu aplikacji
Wersja pakietu SDK podstawowego natywnego pakietu SDK

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

Pamiętaj, że zbieranie danych związanych z korzystaniem przez Ciebie z podstawowego pakietu SDK Play oraz przez Google jest niezależne od zbioru zależności bibliotek zadeklarowanych przez Google w Gradle podczas przesyłania pakietu aplikacji do Konsoli Play.

Gdy zintegrujesz pakiet Play Core Native SDK z projektem, umieść ten wiersz w plikach zawierających wywołania interfejsu API:

#include "play/app_update.h"

Inicjowanie interfejsu In-app Update API

Jeśli używasz interfejsu in-app update API, zainicjuj go najpierw przez wywołanie funkcji AppUpdateManager_init(), jak pokazano 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 dostępna jest aktualizacja dla Twojej aplikacji. AppUpdateManager_requestInfo() uruchamia asynchroniczne żądanie, które zbiera informacje wymagane do późniejszego uruchomienia procesu aktualizacji w aplikacji. Jeśli żądanie się rozpoczęło, 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.
}

Toczący się proces i wynik żądania możesz śledzić w AppUpdateManager_getInfo(). Oprócz kodu błędu funkcja zwraca nieprzejrzystą strukturę AppUpdateInfo, której możesz używać do pobierania informacji o żądaniu aktualizacji. Możesz na przykład wywoływać tę funkcję w każdej pętli gry, aż zwróci ona niepusty wynik dla funkcji 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 braku aktualizacji aktualizacji

Oprócz sprawdzenia, czy jest dostępna aktualizacja, możesz też sprawdzić, ile czasu upłynęło od ostatniego powiadomienia użytkownika o niej w Sklepie Play. Pomoże Ci to zdecydować, czy należy przeprowadzić aktualizację elastyczną czy natychmiastową. Możesz na przykład odczekać kilka dni, zanim powiadomimy użytkownika o elastycznej aktualizacji, a potem kilka dni później.

Na stronie AppUpdateInfo_getClientVersionStalenessDays() możesz sprawdzić, ile dni upłynęło od udostępnienia aktualizacji w Sklepie Play:

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

Sprawdź priorytet aktualizacji

Interfejs Google Play Developer API umożliwia określenie priorytetu każdej aktualizacji. Dzięki temu aplikacja może zdecydować, jak mocno zarekomendować użytkownikowi aktualizację. Oto przykładowa strategia ustawiania priorytetu aktualizacji:

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

Google Play określa priorytet przy użyciu liczby całkowitej z zakresu od 0 do 5, gdzie 0 to wartość domyślna, a 5 – najwyższy. Aby ustawić priorytet aktualizacji, użyj pola inAppUpdatePriority w sekcji Edits.tracks.releases w interfejsie Google Play Developer API. Wszystkie nowo dodane wersje w danej wersji mają ten sam priorytet. Priorytetu można ustawić tylko podczas wdrażania nowej wersji. Nie można go później zmienić.

Ustaw priorytet, korzystając z interfejsu Google Play Developer API, zgodnie z opisem w dokumentacji interfejsu Play Developer API. Określ priorytet aktualizacji w aplikacji w zasobie Edit.tracks przekazywanym w metodzie Edit.tracks: update. Ten przykład przedstawia publikowanie aplikacji z kodami wersji 88 i inAppUpdatePriority 5:

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

W kodzie aplikacji możesz sprawdzić priorytet danej aktualizacji za pomocą funkcji AppUpdateInfo_getPriority():

int32_t priority = AppUpdateInfo_getPriority(info);

Rozpocznij aktualizację

Po potwierdzeniu, że aktualizacja jest dostępna, możesz poprosić o jej aktualizację, używając 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 przepływu aktualizacji w aplikacji, w tym to, czy aktualizacja powinna być elastyczna lub natychmiastowa.

Ten przykład tworzy obiekt AppUpdateOptions na potrzeby elastycznego przepływu 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 na potrzeby 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 usuwać 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ć tę wartość na 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 zażądać przepływu aktualizacji, przekazując w przypadku końcowego parametru wartość jobject związaną z aktywnością na Androidzie.

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 je odpowiednio do AppUpdateInfo_destroy() i AppUpdateOptions_destroy().

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

Aby przeprowadzić natychmiastową aktualizację, Google Play wyświetli 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 przypadku elastycznego przepływu aktualizacji możesz nadal prosić o aktualne obiekty AppUpdateInfo, aby śledzić bieżący stan aktualizacji, podczas gdy użytkownik nadal korzysta z aplikacji. Po zakończeniu pobierania musisz wywołać dokończenie aktualizacji, wywołując metodę AppUpdateManager_requestCompleteUpdate(), jak pokazano 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 przestanie korzystać 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 interfejs API nie został zainicjowany. Wywołaj AppUpdateManager_init(), aby zainicjować interfejs API.
Kod błędu -4, APP_UPDATE_INVALID_REQUEST wskazuje, że niektóre parametry żądania przepływu 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. 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 polecenie AppUpdateManager_requestAppUpdateInfo(), aby odświeżyć AppUpdateInfo.
Kod błędu -6, APP_UPDATE_NOT_ALLOWED oznacza, że typ aktualizacji określony przez obiekt AppUpdateOption jest niedozwolony. Przed rozpoczęciem przepływu aktualizacji sprawdź, czy obiekt AppUpdateInfo wskazuje, że dany typ aktualizacji jest dozwolony.

Dalsze kroki

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