Ce guide explique comment prendre en charge les mises à jour dans l'application à l'aide de code natif (C ou C++). Il existe des guides distincts pour les cas où votre implémentation utilise le langage de programmation Kotlin ou Java, et pour les cas où votre implémentation utilise Unity.
Présentation du SDK natif
Le SDK natif Play Core fait partie de la famille du SDK Play Core. Le SDK natif inclut un fichier d'en-tête C, app_update.h, qui encapsule AppUpdateManager à partir de la bibliothèque Play In-App Update de Java. Ce fichier d'en-tête permet à votre application d'appeler l'API pour obtenir des mises à jour directement depuis votre code natif.
Configurer l'environnement de développement
Download Play Core Native SDK
Before downloading, you must agree to the following terms and conditions.
Terms and Conditions
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.
Effectuez l'une des opérations suivantes :
- Installez Android Studio version 4.0 ou ultérieure. À l'aide de l'interface utilisateur SDK Manager, installez la version 10.0 d'Android SDK Platform (niveau d'API 29).
- Installez les outils de ligne de commande du SDK Android et utilisez
sdkmanagerpour installer la version 10.0 d'Android SDK Platform (niveau d'API 29).
Préparez Android Studio pour le développement natif en installant la dernière version de CMake et du kit de développement natif Android (NDK) à l'aide de SDK Manager. Pour en savoir plus sur la création ou l'importation de projets natifs, consultez Premiers pas avec le kit NDK.
Téléchargez le fichier ZIP et extrayez-le avec votre projet.
Lien de téléchargement Taille Somme de contrôle SHA256 37,8 Mo 9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7 Mettez à jour le fichier
build.gradlede votre application comme indiqué ci-dessous :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.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") ... }
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.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")) ... }
Mettez à jour les fichiers
CMakeLists.txtde votre application comme indiqué ci-dessous :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 ...)
Collecte des données
Le SDK natif Play Core peut collecter des données liées à la version pour permettre à Google d'améliorer le produit, y compris :
- Nom du package de l'application
- Version du package de l'application
- Version du SDK natif Play Core
Ces données seront collectées lorsque vous importerez votre package d'application dans la Play Console. Pour désactiver ce processus de collecte des données, supprimez l'importation $playcoreDir/playcore-native-metadata.jar dans le fichier build.gradle.
Notez que cette collecte de données liée à votre utilisation du SDK natif Play Core et l'utilisation par Google des données collectées sont des opérations distinctes et indépendantes de la collecte de dépendances de bibliothèque que Google déclare dans Gradle lorsque vous importez votre package d'application dans la Play Console.
Une fois le SDK natif Play Core intégré dans votre projet, incluez la ligne suivante dans les fichiers contenant des appels d'API :
#include "play/app_update.h"
Initialiser l'API de mise à jour intégrée à l'application
Chaque fois que vous utilisez l'API de mise à jour intégrée à l'application, initialisez-la en appelant la fonction AppUpdateManager_init(), comme indiqué dans l'exemple suivant, créé avec 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.
}
}
Vérifier si une mise à jour est disponible
Avant de demander une mise à jour, vérifiez si une mise à jour est disponible pour votre application.
AppUpdateManager_requestInfo() démarre une requête asynchrone qui rassemble les informations requises pour lancer ultérieurement le flux de mise à jour dans l'application. La fonction renvoie APP_UPDATE_NO_ERROR si la requête démarre correctement.
AppUpdateErrorCode error_code = AppUpdateManager_requestInfo()
if (error_code == APP_UPDATE_NO_ERROR) {
// The request has successfully started, check the result using
// AppUpdateManager_getInfo.
}
Vous pouvez suivre le processus et le résultat en cours de la requête à l'aide de AppUpdateManager_getInfo().
En plus du code d'erreur, cette fonction renvoie une structure opaque AppUpdateInfo, que vous pouvez utiliser pour récupérer des informations sur la requête de mise à jour. Par exemple, vous pouvez appeler cette fonction dans chaque boucle de jeu jusqu'à ce qu'elle renvoie un résultat non nul pour 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
}
...
}
Vérifier l'obsolescence des mises à jour
En plus de vérifier si une mise à jour est disponible, vous pouvez aussi consulter le temps écoulé depuis la dernière notification de mise à jour reçue par l'utilisateur via le Play Store. Cela peut vous aider à décider si vous devez lancer une mise à jour flexible ou immédiate. Par exemple, vous pouvez attendre quelques jours avant d'informer l'utilisateur d'une mise à jour flexible, puis quelques jours encore avant de demander une mise à jour immédiate.
Utilisez AppUpdateInfo_getClientVersionStalenessDays() pour vérifier le nombre de jours écoulés depuis la mise à jour via le Play Store :
int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);
Vérifier la priorité des mises à jour
L'API Google Play Developer vous permet de définir la priorité de chaque mise à jour. Votre application peut ainsi déterminer le degré de recommandation d'une mise à jour auprès de l'utilisateur. Prenons la stratégie suivante pour exemple :
- Améliorations mineures de l'interface utilisateur : mise à jour de faible priorité ; ne demandez ni une mise à jour flexible, ni une mise à jour immédiate. Effectuez la mise à jour uniquement lorsque l'utilisateur n'est pas en train d'interagir avec votre application.
- Améliorations des performances : mise à jour de priorité moyenne ; demandez une mise à jour flexible.
- Mise à jour de sécurité critique : mise à jour de priorité élevée ; demandez une mise à jour immédiate.
Pour déterminer la priorité, Google Play utilise un nombre entier compris entre 0 et 5, 0 étant la valeur par défaut et 5 étant la priorité la plus élevée. Pour définir la priorité d'une mise à jour, utilisez le champ inAppUpdatePriority sous Edits.tracks.releases dans l'API Google Play Developer. Toutes les nouvelles versions ajoutées sont considérées comme ayant la même priorité que la release. La priorité ne peut être définie que lors du déploiement d'une nouvelle release. Elle ne peut pas être modifiée ultérieurement.
Définissez la priorité à l'aide de l'API Google Play Developer, comme décrit dans la documentation de l'API Play Developer.
Spécifiez la priorité de mise à jour dans l'application dans la ressource Edit.tracks transmise dans la méthode Edit.tracks: update. L'exemple suivant montre comment publier une application avec le code de version 88 et une inAppUpdatePriority de 5 :
{ "releases": [{ "versionCodes": ["88"], "inAppUpdatePriority": 5, "status": "completed" }] }
Dans le code de votre application, vous pouvez vérifier le niveau de priorité d'une mise à jour donnée à l'aide de AppUpdateInfo_getPriority() :
int32_t priority = AppUpdateInfo_getPriority(info);
Commencer une mise à jour
Une fois que vous avez vérifié qu'une mise à jour est disponible, vous pouvez demander une mise à jour à l'aide de AppUpdateManager_requestStartUpdate().
Avant de demander une mise à jour, obtenez un objet AppUpdateInfo à jour et créez un objet AppUpdateOptions pour configurer le flux de mise à jour. Un objet AppUpdateOptions définit les options d'un flux de mise à jour dans l'application, indiquant si la mise à jour doit être flexible ou immédiate.
L'exemple suivant crée un objet AppUpdateOptions pour un flux de mise à jour flexible :
// Creates an AppUpdateOptions configuring a flexible in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_FLEXIBLE, &options);
L'exemple suivant crée un objet AppUpdateOptions pour un flux de mise à jour immédiat :
// Creates an AppUpdateOptions configuring an immediate in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_IMMEDIATE, &options);
L'objet AppUpdateOptions contient également un champ AllowAssetPackDeletion qui définit si la mise à jour est autorisée à effacer les packs d'éléments en cas d'espace de stockage limité sur l'appareil. Ce champ est défini sur false par défaut, mais vous pouvez utiliser la méthode AppUpdateOptions_setAssetPackDeletionAllowed() pour le définir à la place sur true :
bool allow = true;
AppUpdateErrorCode error_code = AppUpdateOptions_setAssetPackDeletionAllowed(options, allow);
Une fois que vous disposez d'un objet AppUpdateInfo à jour et d'un objet AppUpdateOptions correctement configuré, appelez AppUpdateManager_requestStartUpdate() pour demander un flux de mise à jour de manière asynchrone, en transmettant une activité Android jobject pour le paramètre final.
AppUpdateErrorCode request_error_code =
AppUpdateManager_requestStartUpdate(info, options, app->activity->clazz);
Pour libérer des ressources, libérez les instances de AppUpdateInfo et AppUpdateOptions dont vous n'avez plus besoin en appelant AppUpdateInfo_destroy() et AppUpdateOptions_destroy(), respectivement.
AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);
Pour afficher immédiatement le flux de mise à jour, Google Play affiche une page de confirmation à l'utilisateur. Lorsque l'utilisateur accepte la requête, Google Play télécharge et installe automatiquement la mise à jour au premier plan, puis redémarre l'application vers la version mise à jour si l'installation réussit.
Pour un flux de mise à jour flexible, vous pouvez continuer à demander des objets AppUpdateInfo à jour pour suivre l'état de la mise à jour actuelle pendant que l'utilisateur continue d'interagir avec l'application. Une fois le téléchargement terminé, vous devez déclencher la mise à jour en appelant AppUpdateManager_requestCompleteUpdate(), comme illustré dans l'exemple suivant :
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.
}
}
Libérez des ressources en appelant la fonction AppUpdateManager_destroy() une fois que l'application aura terminé d'utiliser l'API.
Gestion des exceptions
Cette section décrit les solutions aux erreurs courantes signalées par des valeurs AppUpdateErrorCode spécifiques :
- Un code d'erreur
-110, APP_UPDATE_INITIALIZATION_NEEDEDindique que l'API n'a pas été initialisée correctement. AppelezAppUpdateManager_init()pour initialiser l'API. - Un code d'erreur
-4, APP_UPDATE_INVALID_REQUESTindique que certains paramètres de la requête de flux de mise à jour sont incorrects. Assurez-vous que les objetsAppUpdateInfoetAppUpdateOptionsne sont pas nuls et sont correctement formatés. - Le code d'erreur
-5, APP_UPDATE_UNAVAILABLEindique qu'aucune mise à jour applicable n'est disponible. Assurez-vous que la version cible possède les mêmes nom de package, ID d'application et clé de signature. Si une mise à jour est disponible, videz le cache de l'application et appelez de nouveauAppUpdateManager_requestAppUpdateInfo()pour actualiserAppUpdateInfo. - Un code d'erreur
-6, APP_UPDATE_NOT_ALLOWEDindique que le type de mise à jour signalé par l'objetAppUpdateOptionn'est pas autorisé. Vérifiez si l'objetAppUpdateInfoindique que le type de mise à jour est autorisé avant de lancer le flux de mise à jour.
Étapes suivantes
Testez les mises à jour de votre application pour vérifier que votre intégration fonctionne correctement.