Integracja opinii w aplikacji (natywna)

Ten przewodnik zawiera informacje o integrowaniu opinii w aplikacji za pomocą kodu natywnego (C lub C++). Jeśli używasz Kotlin lub Java albo Unity, znajdziesz osobne przewodniki integracji.

Omówienie natywnego pakietu SDK

Pakiet SDK podstawowej biblioteki Play jest częścią rodziny podstawowych bibliotek Google Play. Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych zawiera plik nagłówka C review.h, który zawiera review.hz bibliotek Java Play do sprawdzania aplikacji.ReviewManager Ten plik nagłówka umożliwia aplikacji wywoływanie interfejsu API bezpośrednio z kodu natywnego. Informacje o dostępnych publicznych funkcjach znajdziesz w dokumentacji Modułu natywnego Play Review.

ReviewManager_requestReviewFlow uruchamia żądanie, które gromadzi informacje potrzebne do uruchomienia późniejszego procesu sprawdzania w aplikacji. Wynik żądania możesz śledzić za pomocą ReviewManager_getReviewStatus. Więcej informacji o wszystkich stanach, które może zwrócić funkcja ReviewManager_getReviewStatus, znajdziesz w artykule ReviewErrorCode.

Jeśli funkcja zakończy się powodzeniem, zarówno funkcja request, jak i launch zwracają wartość REVIEW_NO_ERROR.

Konfigurowanie środowiska programistycznego

1. Wykonaj jedną z tych czynności:

   • Zainstaluj Android Studio w wersji 4.0 lub nowszej. Za pomocą interfejsu menedżera pakietu SDK zainstaluj pakiet Android SDK w wersji 10.0 (poziom interfejsu API 29).
   • Zainstaluj narzędzia wiersza poleceń pakietu Android SDK i użyj polecenia sdkmanager, aby zainstalować platformę pakietu Android SDK w wersji 10.0 (poziom interfejsu API 29).

2. Przygotuj Android Studio do tworzenia aplikacji natywnych, instalując za pomocą Menedżera pakietu SDK najnowszą wersję CMake i pakietu Native Development Kit (NDK) na Androida. Więcej informacji o tworzeniu i importowaniu projektów natywnych znajdziesz w artykule Pierwsze kroki z NDK.

3. Pobierz plik ZIP i rozpakuj go obok projektu.

   Link do pobrania	Rozmiar	Suma kontrolna SHA-256
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. Zaktualizuj plik build.gradle aplikacji w ten sposób:

   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. Zaktualizuj pliki CMakeLists.txt aplikacji w ten sposób:

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

Zbieranie danych

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych może zbierać dane związane z wersją, aby umożliwić Google ulepszanie usługi. Te dane obejmują:

• Nazwa pakietu aplikacji
• Wersja pakietu aplikacji
• Wersja pakietu SDK podstawowej biblioteki Play do aplikacji natywnych

Te dane zostaną zebrane, gdy prześlesz pakiet aplikacji do Konsoli Play. Aby zrezygnować z zbierania danych, usuń import $playcoreDir/playcore-native-metadata.jar z pliku build.gradle.

Pamiętaj, że zbieranie danych związanych z użyciem przez Ciebie natywnego pakietu SDK Play Core i wykorzystywaniem przez Google zebranych danych jest odrębne i niezależne od zbierania przez Google zależności bibliotek zadeklarowanych w Gradle podczas przesyłania pakietu aplikacji do Konsoli Play.

Po zintegrowaniu pakietu SDK podstawowej biblioteki Play do aplikacji natywnych z projektem dodaj ten wiersz do plików zawierających wywołania interfejsu API:

Dołącz plik review.h.

Po zintegrowaniu pakietu SDK podstawowej biblioteki Play z projektem dodaj ten wiersz do plików, które będą zawierać wywołania interfejsu API:

#include "play/review.h"

Inicjowanie interfejsu Review API

Przed użyciem interfejsu API musisz go zainicjować, wywołując funkcję ReviewManager_init, jak w tym przykładzie zbudowanym za pomocą funkcji android_native_app_glue.h:

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

Prośba o przesłanie procesu sprawdzania w aplikacji

Aby określić odpowiednie momenty w przebiegu użytkownika aplikacji, w których należy poprosić o opinię, postępuj zgodnie z wytycznymi dotyczącymi proszenia o opinię w aplikacji (np. gdy użytkownik zamknie ekran podsumowania na końcu poziomu w grze). Gdy aplikacja zbliży się do jednego z tych punktów, wywołaj funkcję ReviewManager_requestReviewFlow, aby asynchronicznie poprosić o informacje potrzebne do uruchomienia procesu weryfikacji w aplikacji. Sprawdzanie postępu operacji ReviewManager_requestReviewFlow przez wywołanie funkcji ReviewManager_getReviewStatus, na przykład raz na każdą klatkę. Może to potrwać kilka sekund, dlatego proces ten należy rozpocząć przed osiągnięciem przez aplikację punktu, w którym chcesz wyświetlić proces weryfikacji w aplikacji.

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

Obsługa stanów i uruchamianie procesu sprawdzania w aplikacji

Gdy tylko rozpocznie się proces weryfikacji lub przetwarzanie prośby, możesz sprawdzić jego stan, korzystając z ReviewManager_getReviewStatus. Umożliwia to zdefiniowanie logiki w zależności od stanu interfejsu API. Jednym ze sposobów jest pozostawienie stanu jako zmiennej globalnej i sprawdzenie, czy stan jest REVIEW_REQUEST_FLOW_COMPLETED, gdy użytkownik wykona określone działanie (np. kliknie przycisk „Następny poziom” w grze), jak w tym przykładzie:

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

Gdy stan jest REVIEW_REQUEST_FLOW_COMPLETED, a aplikacja jest gotowa, uruchom proces sprawdzania w aplikacji:

// 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;
}

Po uruchomieniu procesu weryfikacji w aplikacji sprawdzaj stan jego ukończenia i kontynuuj proces w aplikacji. Typowym sposobem na to jest stosowanie wzorca pętli gry.

Bezpłatne materiały

Pamiętaj, aby po zakończeniu korzystania z interfejsu API (np. po zakończeniu procesu weryfikacji w aplikacji) zwalniać zasoby, wywołując funkcję ReviewManager_destroy.

void ReviewManager_destroy();

Dalsze kroki

Sprawdź proces weryfikacji w aplikacji, aby upewnić się, że integracja działa prawidłowo.