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

In diesem Leitfaden wird beschrieben, wie Sie In-App-Updates in Ihrer App mithilfe von 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älle, in denen Ihre Implementierung Unity verwendet.

Native SDK – Übersicht

Das Play Core Native SDK ist Teil der Play Core SDK-Familie. Das Native SDK enthält die C-Header-Datei 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 den nativen Code aufrufen.

Entwicklungsumgebung einrichten

1. Sie haben folgende Möglichkeiten:

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

2. Bereiten Sie Android Studio für die native Entwicklung vor. Verwenden Sie dazu den SDK Manager, um das neueste CMake und Android Native Development Kit (NDK) zu 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 zusammen mit Ihrem Projekt.

   Downloadlink	Größe	SHA-256-Prüfsumme
   play-core-native-sdk-1.14.0.zip	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

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

   Groovig

       // 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.0.0'
           implementation 'com.google.android.play:asset-delivery:2.0.0'
           implementation 'com.google.android.play:integrity:1.0.1'
           implementation 'com.google.android.play:review:2.0.0'
   
           // 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.0.0")
       implementation("com.google.android.play:asset-delivery:2.0.0")
       implementation("com.google.android.play:integrity:1.0.1")
       implementation("com.google.android.play:review:2.0.0")
   
       // 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 gezeigt:

   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 SDK

Diese Daten werden erhoben, wenn du dein App-Paket in die Play Console hochlädst. Wenn du diese Datenerhebung deaktivieren möchtest, entferne den $playcoreDir/playcore-native-metadata.jar-Import aus der Datei build.gradle.

Hinweis: Diese Datenerhebung im Zusammenhang mit Ihrer Nutzung des Play Core Native SDK und der Verwendung der erhobenen Daten durch Google ist unabhängig von der Sammlung von Bibliotheksabhängigkeiten, die Google beim Hochladen Ihres App-Pakets in die Play Console deklariert und in Gradle deklariert wird.

Nachdem Sie das Play Core Native SDK in Ihr Projekt integriert haben, fügen Sie die folgende Zeile in Dateien mit API-Aufrufen 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. Rufen Sie dazu die Funktion AppUpdateManager_init() auf, wie im folgenden mit android_native_app_glue.h erstellten Beispiel gezeigt:

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 für Ihre Anwendung ein Update verfügbar ist. Mit AppUpdateManager_requestInfo() wird eine asynchrone Anfrage gestartet, die die erforderlichen Informationen erfasst, um später den In-App-Updatevorgang zu starten. Wenn die Anfrage erfolgreich gestartet wird, gibt die Funktion APP_UPDATE_NO_ERROR zurück.

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 intransparente AppUpdateInfo-Struktur zurück, mit der Sie Informationen zur Aktualisierungsanfrage abrufen können. Sie können diese Funktion beispielsweise in jeder Spielschleife 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
   }
...
}

Update-Veralterung prüfen

Sie können nicht nur prüfen, ob ein Update verfügbar ist, sondern auch, wie viel Zeit vergangen ist, seit der Nutzer das letzte Mal über den Play Store über ein Update benachrichtigt wurde. Dies kann Ihnen bei der Entscheidung helfen, ob Sie ein flexibles oder ein sofortiges Update initiieren sollten. Beispielsweise können Sie einige Tage warten, bevor Sie den Nutzer mit einem flexiblen Update benachrichtigen, und einige Tage danach, bevor Sie eine sofortige Aktualisierung anfordern.

Mit AppUpdateInfo_getClientVersionStalenessDays() kannst du prüfen, wie viele Tage seit der Einführung des Updates im Play Store vergangen sind:

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

Updatepriorität prüfen

Mit der Google Play Developer API können Sie die Priorität jedes Updates festlegen. Auf diese Weise kann deine App entscheiden, wie stark sie dem Nutzer ein Update empfehlen sollte. Betrachten Sie beispielsweise die folgende Strategie zum Festlegen der Aktualisierungspriorität:

• Kleinere Verbesserungen an der Benutzeroberfläche: Update mit niedriger Priorität. Fordern Sie weder ein flexibles noch ein sofortiges Update an. Aktualisieren Sie sie nur, wenn der Nutzer nicht mit Ihrer App interagiert.
• Leistungsverbesserungen: Update mit mittlerer Priorität; fordern Sie ein flexibles Update an.
• Kritisches Sicherheitsupdate: Update mit hoher Priorität. Fordern Sie ein sofortiges Update an.

Zur Bestimmung der Priorität verwendet Google Play eine Ganzzahl zwischen 0 und 5, wobei 0 die Standardeinstellung und 5 die höchste Priorität ist. Um die Priorität für ein Update festzulegen, kannst du in der Google Play Developer API unter Edits.tracks.releases das Feld inAppUpdatePriority verwenden. 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 und später nicht mehr geändert werden.

Legen Sie die Priorität mithilfe der Google Play Developer API fest, wie in der Dokumentation zur Play Developer API 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 die Veröffentlichung einer App mit den Versionscodes 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 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 es mit AppUpdateManager_requestStartUpdate() anfordern. Bevor Sie eine Aktualisierung anfordern, rufen Sie ein aktuelles AppUpdateInfo-Objekt ab und erstellen Sie ein AppUpdateOptions-Objekt, um den Aktualisierungsablauf zu konfigurieren. Ein AppUpdateOptions-Objekt definiert Optionen für einen In-App-Updatevorgang, einschließlich der Frage, ob das Update flexibel oder sofort sein 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 definiert, ob bei der Aktualisierung Asset-Packs bei begrenztem Gerätespeicher gelöscht werden dürfen. Dieses Feld ist standardmäßig auf false gesetzt. Sie können es jedoch mit der Methode AppUpdateOptions_setAssetPackDeletionAllowed() auf true festlegen:

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

Wenn du ein aktuelles AppUpdateInfo-Objekt und ein richtig konfiguriertes AppUpdateOptions-Objekt hast, rufe AppUpdateManager_requestStartUpdate() auf, um einen Aktualisierungsvorgang asynchron anzufordern. Übergib ein Android-Aktivitäts-jobject als abschließenden Parameter.

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

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

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

Für einen sofortigen Updatevorgang zeigt Google Play eine Nutzerbestätigungsseite an. Wenn der Nutzer die Anfrage akzeptiert, lädt Google Play das Update automatisch im Vordergrund herunter und installiert es. Wenn die Installation erfolgreich war, wird die App mit der aktualisierten Version neu gestartet.

Für einen flexiblen Updateablauf können Sie weiterhin aktuelle AppUpdateInfo-Objekte anfordern, um den aktuellen Updatestatus zu verfolgen, während der Nutzer weiter mit der App interagiert. Nachdem der Download erfolgreich abgeschlossen wurde, müssen Sie den Abschluss des Updates auslösen, indem Sie AppUpdateManager_requestCompleteUpdate() aufrufen, 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 hat.

Fehlerbehandlung

In diesem Abschnitt werden Lösungen für häufige Fehler beschrieben, die durch bestimmte AppUpdateErrorCode-Werte gekennzeichnet werden:

• Der Fehlercode -110, APP_UPDATE_INITIALIZATION_NEEDED gibt an, dass die API nicht erfolgreich initialisiert wurde. Rufen Sie AppUpdateManager_init() auf, um die API zu initialisieren.
• Der Fehlercode -4, APP_UPDATE_INVALID_REQUEST gibt an, dass einige Parameter der Aktualisierungsanfrage fehlerhaft sind. Die Objekte AppUpdateInfo und AppUpdateOptions dürfen nicht null und richtig formatiert sein.
• Der Fehlercode -5, APP_UPDATE_UNAVAILABLE bedeutet, dass kein entsprechendes Update verfügbar ist. Achten Sie darauf, dass die Zielversion denselben Paketnamen, dieselbe Anwendungs-ID und denselben Signaturschlüssel hat. Wenn ein Update verfügbar ist, leeren Sie den Cache der App und rufen Sie AppUpdateManager_requestAppUpdateInfo() noch einmal auf, um AppUpdateInfo zu aktualisieren.
• Der Fehlercode -6, APP_UPDATE_NOT_ALLOWED gibt an, dass der durch das Objekt AppUpdateOption angegebene Aktualisierungstyp nicht zulässig ist. Prüfen Sie, ob das AppUpdateInfo-Objekt angibt, dass der Aktualisierungstyp zulässig ist, bevor Sie den Aktualisierungsvorgang starten.

Nächste Schritte

Teste die In-App-Updates deiner App, um zu prüfen, ob die Integration korrekt funktioniert.