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

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

Примечание. Для использования собственного API для обновлений в приложении требуется, чтобы ваше приложение использовало библиотеку Play Core версии 1.10.0 или выше.

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

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

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

Download Play Core Native SDK

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

Terms and Conditions

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.

I have read and agree with the above terms and conditions

Download Play Core Native SDK Download Play Core Native SDK

play-core-native-sdk-1.15.3.zip

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

   • Установите Android Studio версии 4.0 или выше. Используйте пользовательский интерфейс SDK Manager для установки платформы Android SDK версии 10.0 (уровень API 29).
   • Установите инструменты командной строки Android SDK и используйте sdkmanager для установки платформы Android SDK версии 10.0 (уровень API 29).

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

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

   Ссылка для скачивания	Размер	Контрольная сумма SHA-256
   play-core-native-sdk-1.15.3.zip	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.2.2'
           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.2.2")
       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 мог улучшить продукт, в том числе:

• Имя пакета приложения
• Версия пакета приложения
• Воспроизведение версии 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 в API разработчика Google Play. Все новые версии, добавленные в выпуск, имеют тот же приоритет, что и сам выпуск. Приоритет можно установить только при выпуске новой версии и нельзя изменить позже.

Установите приоритет с помощью 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);

Внимание. Используйте параметр API AllowAssetPackDeletion осторожно, чтобы избежать случайного удаления ресурсов. Прежде чем установить для этого параметра значение true , вам следует проверить, разрешено ли обновление, если для этого параметра установлено значение false .

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

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

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

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