Integracja opinii w aplikacji (natywna)

Z tego przewodnika dowiesz się, jak zintegrować opinie w aplikacji z aplikacją za pomocą kodu natywnego (C lub C++). Jeśli używasz języka Kotlin lub Java, Unity albo Unreal Engine, zapoznaj się z odpowiednimi przewodnikami integracji.

Omówienie pakietu SDK do aplikacji natywnych

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych jest częścią rodziny podstawowych bibliotek Google Play. Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych zawiera plik nagłówkowy C, review.h, który opakowuje ReviewManager z bibliotek opinii w aplikacji w Javie. Ten plik nagłówkowy umożliwia aplikacji wywoływanie interfejsu API bezpośrednio z kodu natywnego. Omówienie dostępnych funkcji publicznych znajdziesz w dokumentacji modułu natywnego opinii w Google Play.

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

Jeśli funkcja się powiedzie, zarówno funkcja żądania, jak i funkcja uruchamiania zwracają REVIEW_NO_ERROR.

Konfigurowanie środowiska programistycznego

Pobierz Play Core Native SDK

Przed pobraniem musisz zaakceptować poniższe warunki.

Warunki korzystania z usługi

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.
Pobierz Play Core Native SDK

play-core-native-sdk-1.16.0.zip

  1. Wykonaj jedną z tych czynności:

  2. Przygotuj Androida Studio do tworzenia aplikacji natywnych, używając SDK Manager do zainstalowania najnowszych wersji CMake i Android Native Development Kit (NDK). 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.

    Pobierz link Rozmiar Suma kontrolna SHA-256
    54,8 MB 008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

  4. Zaktualizuj plik build.gradle aplikacji w sposób pokazany poniżej:

    Dynamiczny

        // 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. Zaktualizuj pliki CMakeLists.txt aplikacji w sposób pokazany poniżej:

    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 produktu. Dane te obejmują:

  • nazwę pakietu aplikacji,
  • wersję pakietu aplikacji,
  • wersję pakietu SDK podstawowej biblioteki Play do aplikacji natywnych.

Te dane będą zbierane, gdy prześlesz pakiet aplikacji do Konsoli Play. Aby zrezygnować z tego procesu zbierania danych, usuń import $playcoreDir/playcore-native-metadata.jar w pliku build.gradle.

Pamiętaj, że zbieranie danych związane z korzystaniem z pakietu SDK podstawowej biblioteki Play do aplikacji natywnych oraz wykorzystywanie zebranych danych przez Google jest oddzielne 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łączanie pliku review.h

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

#include "play/review.h"

Inicjowanie interfejsu Review API

Za każdym razem, gdy chcesz użyć interfejsu API, musisz go najpierw zainicjować, wywołując funkcję ReviewManager_init, jak pokazano w tym przykładzie utworzonym za pomocą 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.
  }
}

Wysyłanie prośby o uruchomienie procesu wystawiania opinii w aplikacji

Postępuj zgodnie z wytycznymi dotyczącymi momentów, w których warto prosić o opinie w aplikacji, aby określić odpowiednie punkty w wzorzec przeglądania, w których można poprosić go o opinię (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 ReviewManager_requestReviewFlow, aby asynchronicznie poprosić o informacje potrzebne aplikacji do uruchomienia procesu wystawiania opinii w aplikacji. Monitoruj postęp operacji ReviewManager_requestReviewFlow, wywołując ReviewManager_getReviewStatus, np. raz na klatkę. Może to potrwać kilka sekund, więc zacznij ten proces, zanim aplikacja osiągnie punkt, w którym chcesz wyświetlić proces wystawiania opinii 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 wystawiania opinii w aplikacji

Za każdym razem, gdy rozpocznie się żądanie lub uruchomi się proces wystawiania opinii w aplikacji, możesz sprawdzić stan za pomocą ReviewManager_getReviewStatus. Umożliwia to zdefiniowanie logiki w zależności od stanu interfejsu API. Jednym ze sposobów jest zachowanie stanu jako zmiennej globalnej i sprawdzanie, czy stan to REVIEW_REQUEST_FLOW_COMPLETED, gdy użytkownik wykona określoną czynność (np. kliknie przycisk „Następny poziom” w grze), jak pokazano 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 to REVIEW_REQUEST_FLOW_COMPLETED i aplikacja jest gotowa, uruchom proces wystawiania opinii 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 wystawiania opinii w aplikacji sprawdzaj, czy został on ukończony, i kontynuuj proces aplikacji. Powszechnym sposobem na to jest stosowanie wzorca pętli gry.

Zwalnianie zasobów

Nie zapomnij zwolnić zasobów, wywołując ReviewManager_destroy funkcję, gdy aplikacja skończy korzystać z interfejsu API (np. po zakończeniu procesu wystawiania opinii w aplikacji).

void ReviewManager_destroy();

Dalsze kroki

Przetestuj proces wystawiania opinii w aplikacji, aby sprawdzić, czy integracja działa prawidłowo.