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 Anleitungen für Fälle, in denen Ihre Implementierung die Programmiersprache Java oder die Programmiersprache Java verwendet, und für Fälle, in denen Ihre Implementierung Unity verwendet.

Hinweis :Für die Native API für In-App-Updates muss in deiner App die Play Core-Bibliothek Version 1.10.0 oder höher verwendet werden.

Native SDK – Übersicht

Das Play Core Native SDK ist Teil der Play Core SDK-Familie. Das native SDK enthält die C-Headerdatei app_update.h, die AppUpdateManager aus der Java Play In-App-Update-Bibliothek umschließt. Mithilfe dieser 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

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.14.0.zip

1. Sie haben folgende Möglichkeiten:

   • Installieren Sie Android Studio Version 4.0 oder höher. Verwende die SDK Manager-UI, um Version 10.0 der Android SDK Platform (API-Level 29) zu installieren.
   • Installieren Sie die Android SDK-Befehlszeilentools und verwenden Sie sdkmanager, um Version 10.0 (API-Level 29) der Android SDK Platform zu installieren.

2. Bereiten Sie Android Studio für die native Entwicklung vor. Installieren Sie dazu mit dem SDK Manager das neueste CMake- und Android Native Development Kit (NDK). Weitere Informationen zum Erstellen oder Importieren von nativen Projekten findest du unter Erste Schritte mit dem NDK.

3. Lade die ZIP-Datei herunter und entpacke sie zusammen mit deinem 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:

   Cool

       // 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 Core Native SDK

Diese Daten werden erhoben, wenn du dein App-Paket in die Play Console hochlädst. Wenn Sie diesen Datenerfassungsprozess deaktivieren möchten, entfernen Sie den Import $playcoreDir/playcore-native-metadata.jar in der Datei build.gradle.

Hinweis: Die Datenerhebung im Zusammenhang mit deiner Nutzung des Play Core Native SDK und der Nutzung der erhobenen Daten durch Google erfolgt separat und unabhängig von der Sammlung der Bibliotheksabhängigkeiten, die Google beim Hochladen deines App-Pakets in die Play Console in Gradle deklariert hat.

Nachdem du das Play Core Native SDK in dein Projekt eingebunden hast, füge die folgende Zeile in die Dateien ein, die API-Aufrufe enthalten:

#include "play/app_update.h"

In-App Update API initialisieren

Wenn Sie die In-App Update API verwenden, initialisieren Sie sie zuerst, indem Sie die Funktion AppUpdateManager_init() aufrufen, wie im folgenden Beispiel gezeigt, das mit android_native_app_glue.h erstellt wurde:

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 Anwendung verfügbar ist. Mit AppUpdateManager_requestInfo() wird eine asynchrone Anfrage gestartet, mit der die erforderlichen Informationen erfasst werden, um den Vorgang für die In-App-Aktualisierung später zu starten. 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.
}

Mit AppUpdateManager_getInfo() können Sie den laufenden Prozess und das Ergebnis der Anfrage 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 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
   }
...
}

Veraltete Updates prüfen

Neben der Prüfung, ob ein Update verfügbar ist, kannst du auch prüfen, wie viel Zeit vergangen ist, seit der Nutzer das letzte Mal über ein Update über den Play Store benachrichtigt wurde. Dies kann Ihnen bei der Entscheidung helfen, ob Sie ein flexibles oder ein sofortiges Update vornehmen sollten. Sie können beispielsweise einige Tage warten, bevor Sie den Nutzer über ein flexibles Update benachrichtigen, und einige Tage danach, bevor ein sofortiges Update erforderlich ist.

Mit AppUpdateInfo_getClientVersionStalenessDays() kannst du prüfen, wie viele Tage seit dem Update im Play Store verfügbar 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. So kann Ihre App entscheiden, wie dringend ein Update dem Nutzer empfohlen wird. Betrachten Sie beispielsweise die folgende Strategie zum Festlegen der Aktualisierungspriorität:

• Kleinere Verbesserungen der Benutzeroberfläche: Aktualisierung mit niedriger Priorität; weder ein flexibles noch eine sofortige Aktualisierung anfordern. Du solltest nur aktualisieren, wenn der Nutzer nicht mit deiner App interagiert.
• Leistungsverbesserungen: Aktualisierung mit mittlerer Priorität; flexible Aktualisierung anfordern.
• Kritisches Sicherheitsupdate: Update mit hoher Priorität. Fordern Sie ein sofortiges Update an.

Zur Bestimmung der Priorität verwendet Google Play einen ganzzahligen Wert zwischen 0 und 5, wobei 0 die Standardeinstellung und 5 die höchste Priorität ist. Verwende das Feld inAppUpdatePriority unter Edits.tracks.releases in der Google Play Developer API, um die Priorität für eine Aktualisierung festzulegen. Alle neu hinzugefügten Versionen im Release haben dieselbe Priorität wie der Release. Die Priorität kann nur bei der Einführung 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 mit der Methode Edit.tracks: update übergeben wird. Das folgende Beispiel zeigt die Veröffentlichung einer App mit dem Versionscode 88 und inAppUpdatePriority 5:

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

Mit AppUpdateInfo_getPriority() können Sie die Prioritätsstufe für ein bestimmtes Update im Code Ihrer App 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-Update-Ablauf, 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 Aktualisierungsvorgang 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 das Update bei begrenztem Speicherplatz auf dem Gerät Asset-Packs löschen darf. Dieses Feld ist standardmäßig auf false gesetzt, aber Sie können stattdessen auch die Methode AppUpdateOptions_setAssetPackDeletionAllowed() verwenden, um es auf true festzulegen:

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

Achtung :Verwenden Sie die API-Option AllowAssetPackDeletion mit Vorsicht, um zu vermeiden, dass Assets versehentlich gelöscht werden. Bevor Sie diese Option auf true setzen, sollten Sie prüfen, ob die Aktualisierung zulässig ist, wenn diese Option auf false gesetzt ist.

Wenn Sie ein aktuelles AppUpdateInfo-Objekt und ein ordnungsgemäß konfiguriertes AppUpdateOptions-Objekt haben, rufen Sie AppUpdateManager_requestStartUpdate() auf, um asynchron einen Aktualisierungsablauf anzufordern und eine Android-Aktivitäts-jobject für den letzten Parameter zu übergeben.

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

Geben Sie zum Freigeben von Ressourcen 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);

Damit ein Update sofort durchgeführt werden kann, wird in Google Play eine Bestätigungsseite des Nutzers angezeigt. Wenn der Nutzer die Anfrage annimmt, lädt Google Play das Update automatisch im Vordergrund herunter und installiert es. Ist die Installation erfolgreich, wird die App dann mit der aktualisierten Version neu gestartet.

Für einen flexiblen Aktualisierungsablauf kannst du weiterhin aktuelle AppUpdateInfo-Objekte anfordern, um den aktuellen Aktualisierungsstatus zu verfolgen, während der Nutzer weiterhin mit der App interagiert. Nachdem der Download erfolgreich abgeschlossen wurde, 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 Anwendung die API nicht mehr verwendet hat.

Fehlerbehandlung

In diesem Abschnitt werden Lösungen für häufige Fehler beschrieben, die durch bestimmte AppUpdateErrorCode-Werte angezeigt 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 Anfrage für den Aktualisierungsvorgang fehlerhaft sind. Die Objekte AppUpdateInfo und AppUpdateOptions dürfen nicht null und richtig formatiert sein.
• Der Fehlercode -5, APP_UPDATE_UNAVAILABLE gibt an, 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 Anwendung 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 Objekt AppUpdateInfo 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.