Поддержка обновлений в приложении (встроенная)

В этом руководстве описывается, как реализовать поддержку внутренних обновлений в вашем приложении с помощью нативного кода (C или C++). Существуют отдельные руководства для случаев, когда ваша реализация использует язык программирования Kotlin или Java , а также для случаев, когда ваша реализация использует Unity или Unreal Engine .

Обзор собственного SDK

Play Core Native SDK входит в семейство Play Core SDK . Native SDK включает заголовочный файл на языке C app_update.h , который представляет собой оболочку AppUpdateManager из библиотеки обновления внутри приложения Java Play. Этот заголовочный файл позволяет вашему приложению вызывать API для обновления внутри приложения непосредственно из вашего нативного кода.

Настройте среду разработки

Скачать Play Core Native SDK

Перед загрузкой вы должны согласиться со следующими условиями.

Условия и положения

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.
Скачать Play Core Native SDK

play-core-native-sdk-1.15.3.zip

  1. Выполните одно из следующих действий:

  2. Подготовьте Android Studio к разработке нативных приложений, установив последнюю версию CMake и Android Native Development Kit (NDK) с помощью SDK Manager . Подробнее о создании и импорте нативных проектов см. в разделе «Начало работы с NDK» .

  3. Загрузите zip-файл и распакуйте его вместе с вашим проектом.

    Ссылка для скачивания Размер Контрольная сумма SHA-256
    37,8 МБ 9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

  4. Обновите файл build.gradle вашего приложения, как показано ниже:

    Круто 

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

    Котлин 

    // 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. Обновите файлы CMakeLists.txt вашего приложения, как показано ниже:

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

Сбор данных

Play Core Native SDK может собирать данные, связанные с версией, чтобы позволить Google улучшить продукт, включая:

  • Имя пакета приложения
  • Версия пакета приложения
  • Версия Play Core Native SDK

Эти данные будут собираться при загрузке пакета приложения в Play Console. Чтобы отказаться от сбора данных, удалите импорт $playcoreDir/playcore-native-metadata.jar из файла build.gradle.

Обратите внимание, что сбор данных, связанный с использованием вами Play Core Native SDK и использованием собранных данных компанией Google, осуществляется отдельно и независимо от сбора Google зависимостей библиотек, объявленных в Gradle при загрузке пакета вашего приложения в Play Console.

После интеграции Play Core Native SDK в свой проект включите следующую строку в файлы, содержащие вызовы API:

#include "play/app_update.h"

Инициализируйте API обновления внутри приложения

При использовании API обновления внутри приложения сначала инициализируйте его, вызвав функцию AppUpdateManager_init() , как показано в следующем примере, созданном с помощью 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.
  }
}

Проверить наличие обновлений

Прежде чем запрашивать обновление, проверьте, доступно ли обновление для вашего приложения. AppUpdateManager_requestInfo() запускает асинхронный запрос, который собирает необходимую информацию для последующего запуска процесса обновления внутри приложения. Функция возвращает 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.
}

Вы можете отслеживать текущий процесс и результат запроса с помощью AppUpdateManager_getInfo() . Помимо кода ошибки, эта функция возвращает непрозрачную структуру AppUpdateInfo , которую можно использовать для получения информации о запросе на обновление. Например, можно вызывать эту функцию в каждом игровом цикле, пока она не вернет ненулевой результат для 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
   }
...
}

Проверить актуальность обновлений

Помимо проверки наличия обновления, вы также можете проверить, сколько времени прошло с момента последнего уведомления пользователя о нём через Play Маркет. Это поможет вам решить, следует ли инициировать гибкое или немедленное обновление. Например, вы можете подождать несколько дней, прежде чем уведомить пользователя о гибком обновлении, и ещё несколько дней после этого, прежде чем потребовать немедленное обновление.

Используйте AppUpdateInfo_getClientVersionStalenessDays() чтобы проверить количество дней с момента, когда обновление стало доступно в Play Store:

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

Проверить приоритет обновления

API разработчика Google Play позволяет вам устанавливать приоритет каждого обновления. Это позволяет вашему приложению самостоятельно определять, насколько настоятельно рекомендовать обновление пользователю. Например, рассмотрим следующую стратегию установки приоритета обновления:

  • Незначительные улучшения пользовательского интерфейса: обновление с низким приоритетом ; не запрашивается ни гибкое, ни немедленное обновление. Обновляйте только тогда, когда пользователь не взаимодействует с вашим приложением.
  • Улучшения производительности: обновление со средним приоритетом ; запросите гибкое обновление.
  • Критическое обновление безопасности: обновление высокого приоритета ; запросите немедленное обновление.

Для определения приоритета Google Play использует целое число от 0 до 5, где 0 — значение по умолчанию, а 5 — наивысший приоритет. Чтобы задать приоритет обновления, используйте поле inAppUpdatePriority в разделе Edits.tracks.releases в API разработчика Google Play. Все новые версии в релизе считаются имеющими тот же приоритет, что и сам релиз. Приоритет можно задать только при выпуске нового релиза и нельзя изменить позже.

Установите приоритет с помощью API Google Play Developer, как описано в документации API Play Developer . Укажите приоритет обновления внутри приложения в ресурсе Edit.tracks , передаваемом в методе Edit.tracks: update :. В следующем примере демонстрируется выпуск приложения с кодом версии 88 и inAppUpdatePriority 5:

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

В коде вашего приложения вы можете проверить уровень приоритета для данного обновления с помощью AppUpdateInfo_getPriority() : 

int32_t priority = AppUpdateInfo_getPriority(info);

Начать обновление

Убедившись в наличии обновления, вы можете запросить его с помощью AppUpdateManager_requestStartUpdate() . Перед запросом обновления получите актуальный объект AppUpdateInfo и создайте объект AppUpdateOptions для настройки процесса обновления. Объект AppUpdateOptions определяет параметры процесса обновления внутри приложения, включая то, должно ли обновление быть гибким или немедленным.

В следующем примере создается объект AppUpdateOptions для гибкого потока обновлений: 

// Creates an AppUpdateOptions configuring a flexible in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_FLEXIBLE, &options);

В следующем примере создается объект AppUpdateOptions для немедленного потока обновления: 

// Creates an AppUpdateOptions configuring an immediate in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_IMMEDIATE, &options);

Объект AppUpdateOptions также содержит поле AllowAssetPackDeletion , которое определяет, разрешено ли обновлению удалять пакеты ресурсов в случае ограниченного хранилища устройства. По умолчанию это поле имеет значение false , но вы можете использовать метод AppUpdateOptions_setAssetPackDeletionAllowed() , чтобы установить его в true : 

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

После того как у вас будет актуальный объект AppUpdateInfo и правильно настроенный объект AppUpdateOptions , вызовите AppUpdateManager_requestStartUpdate() , чтобы асинхронно запросить поток обновления, передав в качестве конечного параметра jobject Android Activity. 

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

Чтобы освободить ресурсы, освободите экземпляры AppUpdateInfo и AppUpdateOptions , которые вам больше не нужны, вызвав AppUpdateInfo_destroy() и AppUpdateOptions_destroy() соответственно. 

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

Для немедленного обновления Google Play отображает страницу подтверждения. Когда пользователь принимает запрос, Google Play автоматически загружает и устанавливает обновление в фоновом режиме, а затем перезапускает приложение с обновлённой версией, если установка прошла успешно.

Для гибкого процесса обновления вы можете постоянно запрашивать актуальные объекты AppUpdateInfo , чтобы отслеживать текущий статус обновления, пока пользователь продолжает взаимодействовать с приложением. После успешного завершения загрузки необходимо инициировать завершение обновления, вызвав AppUpdateManager_requestCompleteUpdate() , как показано в следующем примере: 

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

Освободите ресурсы, вызвав функцию AppUpdateManager_destroy() после того, как ваше приложение завершит использование API.

Обработка ошибок

В этом разделе описываются решения для распространенных ошибок, на которые указывают определенные значения AppUpdateErrorCode :

  • Код ошибки -110, APP_UPDATE_INITIALIZATION_NEEDED означает, что API не был успешно инициализирован. Для инициализации API вызовите AppUpdateManager_init() .
  • Код ошибки -4, APP_UPDATE_INVALID_REQUEST указывает на то, что некоторые параметры запроса на обновление некорректны. Убедитесь, что объекты AppUpdateInfo и AppUpdateOptions не равны NULL и имеют правильный формат.
  • Код ошибки -5, APP_UPDATE_UNAVAILABLE означает, что подходящего обновления нет. Убедитесь, что целевая версия имеет те же имя пакета , идентификатор приложения и ключ подписи . Если обновление доступно, очистите кэш приложения и снова вызовите AppUpdateManager_requestAppUpdateInfo() , чтобы обновить AppUpdateInfo .
  • Код ошибки -6, APP_UPDATE_NOT_ALLOWED означает, что тип обновления, указанный объектом AppUpdateOption недопустим. Перед запуском процесса обновления проверьте, указывает ли объект AppUpdateInfo , что данный тип обновления допустим.

Следующие шаги

Протестируйте внутренние обновления вашего приложения, чтобы убедиться, что интеграция работает правильно.