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

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

Обзор нативного SDK

Play Core Native SDK является частью семейства Play Core SDK . Native SDK включает в себя заголовочный файл на языке C, app_update.h , который является оберткой AppUpdateManager из библиотеки Java Play In-App Update Library. Этот заголовочный файл позволяет вашему приложению вызывать 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.16.0.zip

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

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

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

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

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

Сбор данных

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

  • Название пакета приложения
  • Версия пакета приложения
  • Играйте в версию 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 Store. Это поможет вам решить, следует ли инициировать гибкое обновление или немедленное. Например, вы можете подождать несколько дней, прежде чем уведомить пользователя о гибком обновлении, и еще несколько дней после этого, прежде чем требовать немедленного обновления.

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

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

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

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

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

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

Установите приоритет, используя Google Play Developer API, как описано в документации Play Developer API . Укажите приоритет обновления приложения в ресурсе 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 не являются нулевыми и имеют правильный формат.
  • Код ошибки -5, APP_UPDATE_UNAVAILABLE указывает на отсутствие доступных обновлений. Убедитесь, что целевая версия имеет то же имя пакета , идентификатор приложения и ключ подписи . Если обновление доступно, очистите кэш приложения и снова вызовите AppUpdateManager_requestAppUpdateInfo() для обновления AppUpdateInfo .
  • Код ошибки -6, APP_UPDATE_NOT_ALLOWED указывает на то, что тип обновления, указанный объектом AppUpdateOption не разрешен. Перед запуском процесса обновления проверьте, указывает ли объект AppUpdateInfo , что данный тип обновления разрешен.

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

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