In-App-Rezensionen einbinden (native App)

In diesem Leitfaden wird beschrieben, wie Sie In-App-Rezensionen mithilfe von nativem Code (C oder C++) in Ihre App einbinden. Wenn Sie Kotlin oder Java, Unity oder Unreal Engine verwenden, finden Sie separate Integrationsleitfäden.

Native 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-Header-Datei, review.h, die ReviewManager aus den Java Play In-App Review-Bibliotheken umschließt. Mit dieser Header-Datei kann Ihre App die API direkt aus Ihrem nativen Code aufrufen. Eine Übersicht über die verfügbaren öffentlichen Funktionen finden Sie in der Dokumentation zum nativen Play Review-Modul.

ReviewManager_requestReviewFlow startet eine Anfrage, mit der die Informationen erfasst werden, die später zum Starten des Ablaufs für In-App-Rezensionen erforderlich sind. Sie können das Ergebnis der Anfrage mit ReviewManager_getReviewStatus verfolgen. Weitere Informationen zu allen Status, die ReviewManager_getReviewStatus zurückgeben kann, finden Sie unter ReviewErrorCode.

Sowohl die Anfrage- als auch die Startfunktion geben REVIEW_NO_ERROR zurück, wenn die Funktion erfolgreich ist.

Entwicklungsumgebung einrichten

1. Führen Sie eine der folgenden Aktionen aus:

   • Installieren Sie Android Studio Version 4.0 oder höher. Installieren Sie über die Benutzeroberfläche des SDK-Managers die Android SDK-Plattformversion 10.0 (API-Level 29).
   • 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 neuesten Versionen von CMake und dem 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 extrahieren Sie sie in Ihr Projekt.

   Downloadlink	Größe	SHA-256-Prüfsumme
   play-core-native-sdk-1.16.0.zip	54,8 MiB	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

4. Aktualisieren Sie die Datei build.gradle 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.6.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.6.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 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
           ...)
   

Datenerfassung

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 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 aus der Datei „build.gradle“.

Diese Datenerhebung im Zusammenhang mit Ihrer Nutzung des Play Core Native SDK und die Verwendung der erhobenen Daten durch Google erfolgen 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 die folgende Zeile in Dateien ein, die API-Aufrufe enthalten:

review.h einbeziehen

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

#include "play/review.h"

Review API initialisieren

Wenn Sie die API verwenden möchten, müssen Sie sie zuerst durch Aufrufen der Funktion ReviewManager_init initialisieren, 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-Rezensionsablauf anfordern

Folge den Hinweisen dazu, wann In-App-Rezensionen angefordert werden sollten, um geeignete Stellen im Nutzerfluss deiner App zu finden, an denen du den Nutzer um eine Rezension bitten kannst (z. B. nachdem ein Nutzer den Zusammenfassungsbildschirm am Ende eines Levels in einem Spiel geschlossen hat). Wenn deine App einen dieser Punkte erreicht, rufe ReviewManager_requestReviewFlow auf, um asynchron die Informationen anzufordern, die deine App benötigt, um einen In-App-Rezensionsablauf zu starten. Überwachen Sie den Fortschritt des ReviewManager_requestReviewFlow-Vorgangs, indem Sie ReviewManager_getReviewStatus aufrufen, z. B. einmal pro Frame. Dies kann einige Sekunden dauern. Sie sollten diesen Vorgang also starten, bevor Ihre App den Punkt erreicht, an dem Sie den In-App-Überprüfungsablauf 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 In-App-Rezensionsprozess starten

Wenn eine Anfrage gestartet oder der In-App-Überprüfungsablauf gestartet wurde, 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 beizubehalten und zu prüfen, ob der Status REVIEW_REQUEST_FLOW_COMPLETED ist, wenn der Nutzer eine bestimmte Aktion ausführt (z. B. auf die Schaltfläche „Nächstes Level“ in einem Spiel 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 den In-App-Überprüfungsablauf:

// 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 Start des In-App-Überprüfungsablaufs immer wieder den Status, um zu sehen, ob er abgeschlossen ist, und fahren Sie mit dem App-Ablauf fort. Eine gängige Methode, um dies zu erreichen, ist das Spielschleifen-Muster.

Kostenlose Ressourcen

Vergiss nicht, Ressourcen freizugeben, indem du die Funktion ReviewManager_destroy aufrufst, sobald deine App die API nicht mehr verwendet (z. B. nach Abschluss des Ablaufs für In-App-Rezensionen).

void ReviewManager_destroy();

Nächste Schritte

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