In diesem Leitfaden wird beschrieben, wie Sie In-App-Updates in Ihrer App mit nativem Code (C oder C++) unterstützen. Für den Fall, dass Sie in Ihrer Implementierung die Programmiersprache Kotlin oder die Programmiersprache Java verwenden, und für den Fall, dass Sie in Ihrer Implementierung Unity verwenden, gibt es separate Leitfäden.
Natives SDK – Übersicht
Das Play Core Native SDK ist Teil der Play Core SDK-Familie. Das native SDK enthält eine C-Headerdatei namens app_update.h, die AppUpdateManager aus der Java Play In-App Update Library umschließt. Über diese Headerdatei kann Ihre App die API für In-App-Updates direkt über Ihren nativen Code aufrufen.
Entwicklungsumgebung einrichten
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.
Sie haben folgende Möglichkeiten:
- Installieren Sie Android Studio Version 4.0 oder höher. Verwenden Sie die Benutzeroberfläche des SDK-Managers, um die Android SDK-Plattformversion 10.0 (API-Level 29) zu installieren.
- Installieren Sie die Android SDK-Befehlszeilentools und verwenden Sie
sdkmanager, um die Android SDK-Plattformversion 10.0 (API-Level 29) zu installieren.
Bereiten Sie Android Studio für die native Entwicklung vor, indem Sie mit dem SDK Manager die neueste Version von CMake und das Android Native Development Kit (NDK) installieren. Weitere Informationen zum Erstellen oder Importieren nativer Projekte finden Sie unter Erste Schritte mit dem NDK.
Laden Sie die ZIP-Datei herunter und entpacken Sie sie neben Ihrem Projekt.
Downloadlink Größe SHA-256-Prüfsumme 37,8 MiB 9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7 Aktualisieren Sie die
build.gradle-Datei Ihrer App wie unten beschrieben: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")) ... }
Aktualisieren Sie die
CMakeLists.txt-Dateien Ihrer App wie unten beschrieben: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 ...)
Datenerhebung
Das Play Core Native SDK kann versionenbezogene Daten erheben, damit Google das Produkt verbessern kann. Dazu gehören:
- Paketname der App
- Paketversion der App
- Version des Play Core Native SDK
Diese Daten werden erfasst, wenn Sie Ihr App-Paket in die Play Console hochladen. Wenn Sie diese Datenerhebung deaktivieren möchten, entfernen Sie den Import von $playcoreDir/playcore-native-metadata.jar in der Datei „build.gradle“.
Hinweis: Diese Datenerhebung im Zusammenhang mit Ihrer Nutzung des Play Core Native SDK und die Verwendung der erhobenen Daten durch Google sind getrennt und unabhängig von der Erhebung von Bibliotheksabhängigkeiten durch Google, die in Gradle deklariert werden, wenn Sie Ihr App-Paket in die Play Console hochladen.
Nachdem Sie das Play Core Native SDK in Ihr Projekt eingebunden haben, fügen Sie Dateien, die API-Aufrufe enthalten, die folgende Zeile hinzu:
#include "play/app_update.h"
In-App-Update API initialisieren
Wenn Sie die In-App-Update API verwenden, müssen Sie sie zuerst initialisieren, indem Sie die Funktion AppUpdateManager_init() aufrufen. Das ist im folgenden Beispiel mit android_native_app_glue.h zu sehen:
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.
}
}
Verfügbarkeit von Updates prüfen
Bevor Sie ein Update anfordern, prüfen Sie, ob ein Update für Ihre App verfügbar ist. Mit AppUpdateManager_requestInfo() wird ein asynchroner Request gestartet, über den die erforderlichen Informationen zum Starten des In-App-Update-Vorgangs erfasst werden. Die Funktion gibt APP_UPDATE_NO_ERROR zurück, wenn die Anfrage erfolgreich gestartet wird.
AppUpdateErrorCode error_code = AppUpdateManager_requestInfo()
if (error_code == APP_UPDATE_NO_ERROR) {
// The request has successfully started, check the result using
// AppUpdateManager_getInfo.
}
Sie können den laufenden Vorgang und das Ergebnis der Anfrage mit AppUpdateManager_getInfo() verfolgen.
Neben dem Fehlercode gibt diese Funktion eine opake Struktur vom Typ AppUpdateInfo zurück, mit der Sie Informationen zur Aktualisierungsanfrage abrufen können. Sie können diese Funktion beispielsweise in jedem Gameloop aufrufen, bis sie für info ein Ergebnis ungleich „null“ zurückgibt:
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
}
...
}
Aktualität von Updates prüfen
Sie sollten nicht nur prüfen, ob ein Update verfügbar ist, sondern auch, wie viel Zeit vergangen ist, seit der Nutzer zuletzt über den Play Store über ein Update informiert wurde. So können Sie leichter entscheiden, ob Sie ein flexibles Update oder ein sofortiges Update starten sollten. Sie können beispielsweise einige Tage warten, bevor Sie den Nutzer über ein flexibles Update informieren, und einige Tage danach, bevor Sie ein sofortiges Update verlangen.
Mit AppUpdateInfo_getClientVersionStalenessDays() können Sie die Anzahl der Tage seit der Verfügbarkeit des Updates im Play Store prüfen:
int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);
Updatepriorität prüfen
Mit der Google Play Developer API können Sie die Priorität jeder Aktualisierung festlegen. So kann Ihre App entscheiden, wie dringend ein Update für den Nutzer empfohlen werden soll. Betrachten Sie beispielsweise die folgende Strategie zum Festlegen der Updatepriorität:
- Kleinere Verbesserungen an der Benutzeroberfläche: Update mit niedriger Priorität; weder ein flexibles noch ein sofortiges Update anfordern. Aktualisieren Sie die Daten nur, wenn der Nutzer nicht mit Ihrer App interagiert.
- Leistungsverbesserungen: Aktualisierung mit mittlerer Priorität; flexible Aktualisierung anfordern.
- Kritisches Sicherheitsupdate: Update mit hoher Priorität; sofortiges Update anfordern.
Google Play verwendet zur Bestimmung der Priorität einen Ganzzahlwert zwischen 0 und 5. Dabei ist 0 der Standardwert und 5 die höchste Priorität. Verwenden Sie das Feld inAppUpdatePriority unter Edits.tracks.releases in der Google Play Developer API, um die Priorität für ein Update festzulegen. Alle neu hinzugefügten Versionen im Release haben dieselbe Priorität wie der Release. Die Priorität kann nur beim Roll-out eines neuen Release festgelegt werden und kann später nicht mehr geändert werden.
Legen Sie die Priorität mit der Google Play Developer API fest, wie in der Google Play Developer API-Dokumentation beschrieben.
Geben Sie die Priorität des In-App-Updates in der Ressource Edit.tracks an, die in der Methode Edit.tracks: update übergeben wird. Im folgenden Beispiel wird das Veröffentlichen einer App mit dem Versionscode 88 und inAppUpdatePriority 5 veranschaulicht:
{ "releases": [{ "versionCodes": ["88"], "inAppUpdatePriority": 5, "status": "completed" }] }
Im Code Ihrer App können Sie die Prioritätsstufe für ein bestimmtes Update mithilfe von AppUpdateInfo_getPriority() prüfen:
int32_t priority = AppUpdateInfo_getPriority(info);
Update starten
Wenn Sie festgestellt haben, dass ein Update verfügbar ist, können Sie es mit AppUpdateManager_requestStartUpdate() anfordern.
Bevor du ein Update anforderst, lade ein aktuelles AppUpdateInfo-Objekt herunter und erstelle ein AppUpdateOptions-Objekt, um den Updatevorgang zu konfigurieren. Mit einem AppUpdateOptions-Objekt werden Optionen für einen In-App-Aktualisierungsablauf definiert, z. B. ob die Aktualisierung flexibel oder sofort erfolgen soll.
Im folgenden Beispiel wird ein AppUpdateOptions-Objekt für einen flexiblen Aktualisierungsablauf erstellt:
// Creates an AppUpdateOptions configuring a flexible in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_FLEXIBLE, &options);
Im folgenden Beispiel wird ein AppUpdateOptions-Objekt für einen sofortigen Aktualisierungsablauf erstellt:
// Creates an AppUpdateOptions configuring an immediate in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_IMMEDIATE, &options);
Das AppUpdateOptions-Objekt enthält außerdem ein AllowAssetPackDeletion-Feld, das festlegt, ob beim Update Asset-Pakete gelöscht werden dürfen, wenn der Gerätespeicher begrenzt ist. Dieses Feld ist standardmäßig auf false festgelegt. Mit der Methode AppUpdateOptions_setAssetPackDeletionAllowed() können Sie es jedoch stattdessen auf true festlegen:
bool allow = true;
AppUpdateErrorCode error_code = AppUpdateOptions_setAssetPackDeletionAllowed(options, allow);
Wenn Sie ein aktuelles AppUpdateInfo-Objekt und ein richtig konfiguriertes AppUpdateOptions-Objekt haben, rufen Sie AppUpdateManager_requestStartUpdate() auf, um asynchron einen Updatevorgang anzufordern. Geben Sie dabei eine Android-Aktivität jobject als letzten Parameter an.
AppUpdateErrorCode request_error_code =
AppUpdateManager_requestStartUpdate(info, options, app->activity->clazz);
Wenn Sie Ressourcen freigeben möchten, geben Sie Instanzen von AppUpdateInfo und AppUpdateOptions kostenlos, die Sie nicht mehr benötigen. Rufen Sie dazu AppUpdateInfo_destroy() bzw. AppUpdateOptions_destroy() auf.
AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);
Bei einem sofortigen Update wird in Google Play eine Bestätigungsseite für Nutzer angezeigt. Wenn der Nutzer die Anfrage akzeptiert, lädt Google Play das Update automatisch im Vordergrund herunter und installiert es. Anschließend wird die App mit der aktualisierten Version neu gestartet, wenn die Installation erfolgreich war.
Für einen flexiblen Aktualisierungsablauf kannst du fortlaufend aktuelle AppUpdateInfo-Objekte anfordern, um den aktuellen Aktualisierungsstatus im Blick zu behalten, während der Nutzer weiterhin mit der App interagiert. Nach Abschluss des Downloads musst du den Abschluss der Aktualisierung durch Aufrufen von AppUpdateManager_requestCompleteUpdate() auslösen, wie im folgenden Beispiel gezeigt:
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.
}
}
Sie können Ressourcen freigeben, indem Sie die Funktion AppUpdateManager_destroy() aufrufen, nachdem Ihre App die API nicht mehr verwendet.
Fehlerbehandlung
In diesem Abschnitt werden Lösungen für häufige Fehler beschrieben, die durch bestimmte AppUpdateErrorCode-Werte angezeigt werden:
- Ein Fehlercode von
-110, APP_UPDATE_INITIALIZATION_NEEDEDgibt an, dass die API nicht erfolgreich initialisiert wurde. RufeAppUpdateManager_init()auf, um die API zu initialisieren. - Ein Fehlercode von
-4, APP_UPDATE_INVALID_REQUESTgibt an, dass einige Parameter der Aktualisierungsanfrage fehlerhaft sind. Prüfen Sie, ob dieAppUpdateInfo- undAppUpdateOptions-Objekte nicht null sind und richtig formatiert sind. - Ein Fehlercode
-5, APP_UPDATE_UNAVAILABLEgibt an, dass kein entsprechendes Update verfügbar ist. Die Zielversion muss denselben Paketnamen, dieselbe Anwendungs-ID und denselben Signaturschlüssel haben. Wenn ein Update verfügbar ist, leeren Sie den Cache der App und rufen SieAppUpdateManager_requestAppUpdateInfo()noch einmal auf, umAppUpdateInfozu aktualisieren. - Ein Fehlercode von
-6, APP_UPDATE_NOT_ALLOWEDgibt an, dass der vomAppUpdateOption-Objekt angegebene Aktualisierungstyp nicht zulässig ist. Prüfe, ob dasAppUpdateInfo-Objekt angibt, dass der Updatetyp zulässig ist, bevor du den Updatevorgang startest.
Nächste Schritte
Testen Sie die In-App-Updates Ihrer App, um zu prüfen, ob die Integration ordnungsgemäß funktioniert.