Obsługa aktualizacji w aplikacji (natywne)

Ten przewodnik zawiera opis obsługi aktualizacji w aplikacji za pomocą kodu natywnego (C lub C++). Istnieją osobne przewodniki dla przypadków, w których implementacja korzysta z języka programowania Kotlin lub Java, oraz dla przypadków, w których implementacja korzysta z Unity lub Unreal Engine.

Omówienie natywnego pakietu SDK

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych jest częścią rodziny pakietów SDK podstawowej biblioteki Play. Pakiet SDK Native zawiera plik nagłówkowy C, app_update.h, który opakowuje AppUpdateManager z biblioteki Java Play In-App Update. Ten plik nagłówkowy umożliwia aplikacji wywoływanie interfejsu API do aktualizacji w aplikacji bezpośrednio z 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.
Pobierz Play Core Native SDK

play-core-native-sdk-1.15.3.zip

  1. Wykonaj jedną z tych czynności:

  2. Przygotuj Android Studio do tworzenia aplikacji natywnych, używając Menedżera SDK do zainstalowania najnowszych 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 tym samym folderze co projekt.

    Link do pobrania Rozmiar Suma kontrolna SHA-256
    37,8 MiB 9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

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

    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 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. Dane te mogą obejmować:

  • 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 w pliku build.gradle.$playcoreDir/playcore-native-metadata.jar

Pamiętaj, że zbieranie danych związanych z korzystaniem przez Ciebie z natywnego pakietu SDK Play Core i wykorzystywanie tych danych przez Google to proces odrębny i niezależny 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 do plików 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 pokazano w poniższym 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 ona dostępna dla Twojej aplikacji. Funkcja AppUpdateManager_requestInfo() rozpoczyna asynchroniczne żądanie, które zbiera wymagane informacje, aby później uruchomić proces aktualizacji w aplikacji. Jeśli żądanie zostanie rozpoczęte, 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 wyniki zgłoszenia za pomocą AppUpdateManager_getInfo(). Oprócz kodu błędu ta funkcja zwraca nieprzejrzystą 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 ona niepustego wyniku 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 sprawdzania, 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ć elastyczną aktualizację czy aktualizację natychmiastową. Na przykład możesz odczekać kilka dni, zanim powiadomisz użytkownika o elastycznej aktualizacji, a potem kilka dni, zanim zażądasz natychmiastowej aktualizacji.

Użyj funkcji 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 mocno zalecać użytkownikowi aktualizację. Rozważ na przykład tę strategię ustawiania priorytetu aktualizacji:

  • Drobne ulepszenia interfejsu: aktualizacja o niskim priorytecie, która nie wymaga elastycznej ani natychmiastowej aktualizacji. Aktualizuj tylko wtedy, gdy użytkownik nie wchodzi w interakcję z aplikacją.
  • Poprawa wydajności: aktualizacja o średnim priorytecie; poproś o elastyczną aktualizację.
  • Krytyczna aktualizacja zabezpieczeń: aktualizacja o wysokim priorytecie; natychmiast poproś o aktualizację.

Aby określić priorytet, Google Play używa liczby całkowitej z zakresu od 0 do 5, przy czym 0 to wartość domyślna, 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 wersji są traktowane jako mające taki sam priorytet jak 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 przekazywanym w metodzie Edit.tracks: update. Poniższy przykład pokazuje wydanie aplikacji 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ą tego kodu:AppUpdateInfo_getPriority()

int32_t priority = AppUpdateInfo_getPriority(info);

Rozpoczęcie aktualizacji

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

Ten przykład pokazuje, jak utworzyć 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 pokazuje, jak utworzyć obiekt AppUpdateOptions w przypadku przepływu 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. Domyślnie to pole jest 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 aktualny obiekt AppUpdateInfo i prawidłowo skonfigurowany obiekt AppUpdateOptions, wywołaj AppUpdateManager_requestStartUpdate(), aby asynchronicznie poprosić o proces aktualizacji, przekazując jako ostatni parametr obiekt Activity 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, wywołując odpowiednio AppUpdateInfo_destroy() i AppUpdateOptions_destroy().

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

W przypadku przepływu 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 ponownie uruchomi aplikację w zaktualizowanej wersji, jeśli instalacja się powiedzie.

W przypadku elastycznego procesu aktualizacji możesz w dalszym ciągu wysyłać prośby o aktualne obiekty AppUpdateInfo, aby śledzić bieżący stan aktualizacji, podczas gdy użytkownik nadal korzysta z aplikacji. Po pomyślnym zakończeniu pobierania musisz wywołać zakończenie aktualizacji, wywołując 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() po zakończeniu korzystania z interfejsu API przez aplikację.

Obsługa błędów

W tej sekcji opisujemy rozwiązania typowych błędów sygnalizowanych 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 przepływu aktualizacji są nieprawidłowe. Sprawdź, czy obiekty AppUpdateInfo i AppUpdateOptions nie mają wartości null i są poprawnie sformatowane.
  • Kod błędu -5, APP_UPDATE_UNAVAILABLE oznacza, że nie ma dostępnej odpowiedniej aktualizacji. Upewnij się, że wersja docelowa ma taką samą nazwę pakietu, identyfikator aplikacji i klucz podpisu. Jeśli dostępna jest aktualizacja, wyczyść pamięć podręczną aplikacji i ponownie zadzwoń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.