In-App-Überprüfungen einbinden (nativ)

In dieser Anleitung wird beschrieben, wie Sie In-App-Rezensionen mit nativem Code (C oder C++) in Ihre App einbinden. Für Kotlin oder Java oder Unity gibt es separate Integrationsanleitungen.

Natives SDK – Übersicht

Das Play Core Native SDK gehört zur Familie der Google Play Core-Bibliotheken. Das Play Core Native SDK enthält eine C-Headerdatei namens review.h, die ReviewManager aus den Java-Bibliotheken für Play In-App-Rezensionen umschließt. Über diese Headerdatei kann Ihre App die API direkt aus Ihrem nativen Code aufrufen. Eine Übersicht über die verfügbaren öffentlichen Funktionen finden Sie in der Play Review-Dokumentation für das native Modul.

ReviewManager_requestReviewFlow startet eine Anfrage, über die die Informationen erfasst werden, die später für die In-App-Überprüfung erforderlich sind. Sie können das Ergebnis der Anfrage mit ReviewManager_getReviewStatus verfolgen. Weitere Informationen zu allen Status, die ReviewManager_getReviewStatus zurückgeben kann, findest du unter ReviewErrorCode.

Sowohl die Funktion „request“ als auch die Funktion „launch“ geben REVIEW_NO_ERROR zurück, wenn die Funktion erfolgreich war.

Entwicklungsumgebung einrichten

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

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

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

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 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:

review.h einschließen

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/review.h"

Review API initialisieren

Wenn Sie die API verwenden möchten, müssen Sie sie zuerst initialisieren, indem Sie die Funktion ReviewManager_init aufrufen, wie im folgenden Beispiel mit android_native_app_glue.h gezeigt:

void android_main(android_app* app) {
  app->onInputEvent = HandleInputEvent;

  ReviewErrorCode error_code = ReviewManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == REVIEW_NO_ERROR) {
    // You can use the API.
  }
}

In-App-Überprüfung beantragen

Folgen Sie der Anleitung unter Wann Sie In-App-Rezensionen anfordern sollten, um geeignete Stellen im Nutzerfluss Ihrer App zu ermitteln, an denen Sie Nutzer zu einer Rezension auffordern können (z. B. nachdem ein Nutzer den Zusammenfassungsbildschirm am Ende eines Levels in einem Spiel geschlossen hat). Wenn Ihre App sich einem dieser Punkte nähert, rufen Sie ReviewManager_requestReviewFlow auf, um asynchron die Informationen anzufordern, die Ihre App zum Starten eines In-App-Überprüfungsvorgangs benötigt. Sie können den Fortschritt des Vorgangs ReviewManager_requestReviewFlow überwachen, indem Sie ReviewManager_getReviewStatus aufrufen, z. B. einmal pro Frame. Das kann einige Sekunden dauern. Sie sollten diesen Vorgang also starten, bevor Ihre App den Punkt erreicht, an dem Sie den In-App-Überprüfungsvorgang anzeigen möchten.

ReviewErrorCode error_code = ReviewManager_requestReviewFlow();
if (error_code == REVIEW_NO_ERROR) {
    // The request has successfully started, check the status using
    // ReviewManager_getReviewStatus.
} else {
    // Error such as REVIEW_PLAY_STORE_NOT_FOUND indicating that the in-app
    // review isn't currently possible.
}

Status verarbeiten und den In-App-Überprüfungsvorgang starten

Sobald eine Anfrage gestartet wurde oder der In-App-Überprüfungsvorgang gestartet wird, können Sie den Status mit ReviewManager_getReviewStatus prüfen. So können Sie die Logik je nach API-Status definieren. Eine Möglichkeit besteht darin, den Status als globale Variable zu belassen und zu prüfen, ob der Status REVIEW_REQUEST_FLOW_COMPLETED ist, wenn der Nutzer eine bestimmte Aktion ausführt, z. B. in einem Spiel auf die Schaltfläche „Nächste Stufe“ tippt, wie im folgenden Beispiel gezeigt:

ReviewStatus status;
ReviewErrorCode error_code = ReviewManager_getReviewStatus(&status);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error with the most recent operation.
    return;
}

switch (status) {
    case REVIEW_REQUEST_FLOW_PENDING:
        // Request is ongoing. The flow can't be launched yet.
        break;
    case REVIEW_REQUEST_FLOW_COMPLETED:
        // Request completed. The flow can be launched now.
        break;
    case REVIEW_LAUNCH_FLOW_PENDING:
        // The review flow is ongoing, meaning the dialog might be displayed.
        break;
    case REVIEW_LAUNCH_FLOW_COMPLETED:
        // The review flow has finished. Continue with your app flow (for
        // example, move to the next screen).
        break;
    default:
        // Unknown status.
        break;
}

Wenn der Status REVIEW_REQUEST_FLOW_COMPLETED lautet und Ihre App bereit ist, starten Sie die In-App-Überprüfung:

// This call uses android_native_app_glue.h.
ReviewErrorCode error_code = ReviewManager_launchReviewFlow(app->activity->clazz);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error while launching the flow.
    return;
}

Prüfen Sie nach dem Starten des In-App-Überprüfungsvorgangs den Status, bis er abgeschlossen ist, und fahren Sie dann mit dem App-Vorgang fort. Eine gängige Methode ist das Game-Loop-Muster.

Kostenlose Ressourcen

Denken Sie daran, Ressourcen freizugeben, indem Sie die Funktion ReviewManager_destroy aufrufen, sobald Ihre App die API nicht mehr verwendet (z. B. nachdem der In-App-Überprüfungsvorgang abgeschlossen ist).

void ReviewManager_destroy();

Nächste Schritte

Testen Sie den In-App-Überprüfungsablauf Ihrer App, um zu prüfen, ob die Integration ordnungsgemäß funktioniert.