Unterstützung von In-App-Updates (nativ)

In diesem Leitfaden wird beschrieben, wie Sie In-App-Updates in Ihrer App mit nativem Code (C oder C++) unterstützen. Es gibt separate Leitfäden für Fälle, in denen Ihre Implementierung die Programmiersprache Kotlin oder die Programmiersprache Java verwendet, und für Fälle, in denen Ihre Implementierung Unity oder Unreal Engine verwendet.

Native SDKs – Übersicht

Das Play Core Native SDK ist Teil der Play Core SDK-Familie. Das Native SDK enthält eine C-Headerdatei, app_update.h, die AppUpdateManager aus der Java Play In-App Update Library umschließt. Mit dieser Headerdatei kann Ihre App die API für In-App-Updates direkt über Ihren nativen Code aufrufen.

Entwicklungsumgebung einrichten

1. Sie haben folgende Möglichkeiten:

   • Installieren Sie Android Studio 4.0 oder höher. Installieren Sie die Android SDK-Plattformversion 10.0 (API-Level 29) über die SDK Manager-Benutzeroberfläche.
   • Installieren Sie die Android SDK-Befehlszeilentools und verwenden Sie sdkmanager, um die Android SDK-Plattformversion 10.0 (API-Level 29) zu installieren.

2. Bereiten Sie Android Studio für die native Entwicklung vor, indem Sie mit dem SDK Manager die aktuelle Version von CMake und des Android Native Development Kit (NDK) installieren. Weitere Informationen zum Erstellen oder Importieren nativer Projekte finden Sie unter Erste Schritte mit dem NDK.

3. Laden Sie die ZIP-Datei herunter und entpacken Sie sie neben Ihrem Projekt.

   Downloadlink	Größe	SHA-256-Prüfsumme
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. Aktualisieren Sie die build.gradle-Datei Ihrer App wie unten gezeigt:

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

   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.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. 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 versionsbezogene Daten erheben, damit Google das Produkt verbessern kann. Dazu gehören:

• Paketname der App
• Paketversion der App
• Version des Play Core Native SDKs

Diese Daten werden erhoben, wenn Sie Ihr App-Paket in die Play Console hochladen. Wenn Sie diese Datenerhebung deaktivieren möchten, entfernen Sie den $playcoreDir/playcore-native-metadata.jar-Import in der Datei „build.gradle“.

Die Datenerhebung im Zusammenhang mit Ihrer Nutzung des Play Core Native SDK und die Verwendung der erhobenen Daten durch Google sind unabhängig von der Erhebung von Bibliotheksabhängigkeiten, die in Gradle deklariert sind, 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 in Dateien, die API-Aufrufe enthalten, die folgende Zeile ein:

#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 folgende Beispiel wurde mit android_native_app_glue.h erstellt:

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

Prüfen, ob ein Update verfügbar ist

Bevor Sie ein Update anfordern, prüfen Sie, ob ein Update für Ihre App verfügbar ist. Mit AppUpdateManager_requestInfo() wird eine asynchrone Anfrage gestartet, mit der die erforderlichen Informationen für den späteren Start des In-App-Updatevorgangs 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 Prozess und das Ergebnis der Anfrage mit AppUpdateManager_getInfo() verfolgen. Zusätzlich zum Fehlercode gibt diese Funktion eine undurchsichtige AppUpdateInfo-Struktur zurück, mit der Sie Informationen zur Aktualisierungsanfrage abrufen können. Sie können diese Funktion beispielsweise in jedem Game-Loop aufrufen, bis sie ein Ergebnis ungleich null für info 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 seit der letzten Benachrichtigung des Nutzers über ein Update im Play Store vergangen ist. So können Sie besser entscheiden, ob Sie ein flexibles oder ein sofortiges Update starten sollten. Sie können beispielsweise einige Tage warten, bevor Sie den Nutzer mit einem flexiblen Update benachrichtigen, 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);

Priorität von Updates prüfen

Mit der Google Play Developer API können Sie die Priorität jeder Aktualisierung festlegen. So kann Ihre App entscheiden, wie dringend sie dem Nutzer ein Update empfiehlt. Betrachten Sie beispielsweise die folgende Strategie zum Festlegen der Updatepriorität:

• Kleinere Verbesserungen an der Benutzeroberfläche: Update mit niedriger Priorität; es ist weder ein flexibles noch ein sofortiges Update erforderlich. Aktualisieren Sie 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 erforderlich.

Google Play verwendet zur Bestimmung der Priorität einen ganzzahligen Wert zwischen 0 und 5. Der Standardwert ist 0 und 5 ist die höchste Priorität. Wenn Sie die Priorität für ein Update festlegen möchten, verwenden Sie das Feld inAppUpdatePriority unter Edits.tracks.releases in der Google Play Developer API. Alle neu hinzugefügten Versionen im Release haben dieselbe Priorität wie das Release. Die Priorität kann nur beim Einführen einer neuen Version festgelegt und später nicht mehr geändert werden.

Legen Sie die Priorität mit der Google Play Developer API fest, wie in der Play Developer API-Dokumentation beschrieben. Geben Sie die Priorität für In-App-Updates in der Ressource Edit.tracks an, die in der Methode Edit.tracks: update übergeben wird. Im folgenden Beispiel wird gezeigt, wie eine App mit dem Versionscode 88 und inAppUpdatePriority 5 veröffentlicht wird:

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

Im Code Ihrer App können Sie die Prioritätsstufe für ein bestimmtes Update mit AppUpdateInfo_getPriority() prüfen:

int32_t priority = AppUpdateInfo_getPriority(info);

Update starten

Nachdem Sie bestätigt haben, dass ein Update verfügbar ist, können Sie mit AppUpdateManager_requestStartUpdate() ein Update anfordern. Bevor Sie ein Update anfordern, müssen Sie ein aktuelles AppUpdateInfo-Objekt abrufen und ein AppUpdateOptions-Objekt erstellen, um den Updatevorgang zu konfigurieren. Ein AppUpdateOptions-Objekt definiert Optionen für einen In-App-Aktualisierungsablauf, einschließlich der Frage, ob die Aktualisierung flexibel oder sofort erfolgen soll.

Im folgenden Beispiel wird ein AppUpdateOptions-Objekt für einen flexiblen Updateablauf 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 auch das Feld AllowAssetPackDeletion, das angibt, ob das Update Asset-Packs löschen darf, wenn der Gerätespeicher begrenzt ist. Dieses Feld ist standardmäßig auf false gesetzt. Sie können es jedoch mit der Methode AppUpdateOptions_setAssetPackDeletionAllowed() auf true setzen:

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

Nachdem Sie ein aktuelles AppUpdateInfo-Objekt und ein korrekt konfiguriertes AppUpdateOptions-Objekt haben, rufen Sie AppUpdateManager_requestStartUpdate() auf, um asynchron einen Aktualisierungsvorgang anzufordern. Übergeben Sie dazu eine Android-Aktivität jobject für den letzten Parameter.

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

Um Ressourcen freizugeben, geben Sie Instanzen von AppUpdateInfo und AppUpdateOptions kostenlos, die Sie nicht mehr benötigen, indem Sie AppUpdateInfo_destroy() bzw. AppUpdateOptions_destroy() aufrufen.

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

Bei einem sofortigen Update-Ablauf wird im Google Play Store 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 in der aktualisierten Version neu gestartet, sofern die Installation erfolgreich war.

Bei einem flexiblen Update-Ablauf können Sie weiterhin aktuelle AppUpdateInfo-Objekte anfordern, um den aktuellen Updatestatus im Blick zu behalten, während der Nutzer weiterhin mit der App interagiert. Nachdem der Download erfolgreich abgeschlossen wurde, müssen Sie den Abschluss des Updates 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.
    }
}

Geben Sie Ressourcen kostenlos, 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 angegeben werden:

• Ein Fehlercode von -110, APP_UPDATE_INITIALIZATION_NEEDED gibt an, dass die API nicht erfolgreich initialisiert wurde. Rufen Sie AppUpdateManager_init() auf, um die API zu initialisieren.
• Ein Fehlercode von -4, APP_UPDATE_INVALID_REQUEST weist darauf hin, dass einige Parameter der Anfrage für den Aktualisierungsablauf falsch formatiert sind. Prüfen Sie, ob die Objekte AppUpdateInfo und AppUpdateOptions nicht null und richtig formatiert sind.
• Ein Fehlercode -5, APP_UPDATE_UNAVAILABLE gibt an, dass kein anwendbares Update verfügbar ist. Die Zielversion muss denselben Paketnamen, dieselbe Anwendungs-ID und denselben Signaturschlüssel haben. Wenn ein Update verfügbar ist, löschen Sie den Cache der App und rufen Sie AppUpdateManager_requestAppUpdateInfo() noch einmal auf, um AppUpdateInfo zu aktualisieren.
• Ein Fehlercode von -6, APP_UPDATE_NOT_ALLOWED gibt an, dass der vom AppUpdateOption-Objekt angegebene Aktualisierungstyp nicht zulässig ist. Prüfen Sie, ob das AppUpdateInfo-Objekt angibt, dass der Updatetyp zulässig ist, bevor Sie den Updatevorgang starten.

Nächste Schritte

Testen Sie die In-App-Updates Ihrer App, um zu prüfen, ob Ihre Integration ordnungsgemäß funktioniert.