Integrare le recensioni in-app (native)

Questa guida descrive come integrare le recensioni in-app nella tua app utilizzando codice nativo (C o C++). Esistono guide all'integrazione separate se utilizzi Kotlin o Java, Unity o Unreal Engine.

Panoramica dell'SDK nativo

L'SDK nativo della libreria di base Play fa parte della famiglia di librerie di base Play. L'SDK nativo della libreria di base Play include un file di intestazione C, review.h, che esegue il wrapping di ReviewManager dalle librerie Java Play In-App Review. Questo file di intestazione consente alla tua app di chiamare l'API direttamente dal codice nativo. Per una panoramica delle funzioni pubbliche disponibili, consulta la documentazione del modulo nativo Play Review.

ReviewManager_requestReviewFlow avvia una richiesta che raccoglie le informazioni necessarie per avviare il flusso di revisione in-app in un secondo momento. Puoi monitorare il risultato della richiesta utilizzando ReviewManager_getReviewStatus. Per ulteriori informazioni su tutti gli stati che ReviewManager_getReviewStatus può restituire, vedi ReviewErrorCode.

Le funzioni di richiesta e avvio restituiscono REVIEW_NO_ERROR se la funzione ha esito positivo.

Configura l'ambiente di sviluppo

Scarica Play Core Native SDK

Prima di scaricare, devi accettare i seguenti Termini e condizioni.

Termini e condizioni

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

play-core-native-sdk-1.15.3.zip

  1. Procedi in uno dei seguenti modi:

  2. Prepara Android Studio per lo sviluppo nativo utilizzando SDK Manager per installare le versioni più recenti di CMake e Android Native Development Kit (NDK). Per ulteriori informazioni sulla creazione o sull'importazione di progetti nativi, consulta Guida introduttiva all'NDK.

  3. Scarica il file ZIP ed estrailo insieme al progetto.

    Link di download Dimensioni Checksum SHA-256
    37,8 MiB 9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

  4. Aggiorna il file build.gradle della tua app come mostrato di seguito:

    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.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.3.0")
    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. Aggiorna i file CMakeLists.txt della tua app come mostrato di seguito:

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

Raccolta dei dati

L'SDK nativo della libreria di base Play potrebbe raccogliere dati relativi alla versione per consentire a Google di migliorare il prodotto, tra cui:

  • Nome del pacchetto dell'app
  • Versione del pacchetto dell'app
  • Versione dell'SDK nativo della libreria di base Play

Questi dati verranno raccolti quando carichi il pacchetto dell'app su Play Console. Per disattivare questo processo di raccolta dei dati, rimuovi l'importazione $playcoreDir/playcore-native-metadata.jar nel file build.gradle.

Tieni presente che questa raccolta di dati relativa al tuo utilizzo dell'SDK Play Core Native e l'utilizzo dei dati raccolti da parte di Google sono separati e indipendenti dalla raccolta delle dipendenze di libreria dichiarate in Gradle da parte di Google quando carichi il pacchetto dell'app su Play Console.

Dopo aver integrato l'SDK nativo della libreria di base Play nel tuo progetto, includi la seguente riga nei file che contengono chiamate API:

Includi review.h

Dopo aver integrato l'SDK nativo della libreria di base Play nel tuo progetto, includi la riga seguente nei file che conterranno chiamate API:

#include "play/review.h"

Inizializza l'API Review

Ogni volta che vuoi utilizzare l'API, devi prima inizializzarla chiamando la funzione ReviewManager_init, come mostrato nell'esempio seguente creato con 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.
  }
}

Richiedere il flusso di revisione in-app

Segui le indicazioni su quando richiedere recensioni in-app per determinare i punti migliori nel flusso utente della tua app per chiedere all'utente di lasciare una recensione (ad esempio, dopo che l'utente chiude la schermata di riepilogo alla fine di un livello di un gioco). Quando la tua app si avvicina a uno di questi punti, chiama ReviewManager_requestReviewFlow per richiedere in modo asincrono le informazioni di cui la tua app ha bisogno per avviare un flusso di recensione in-app. Monitora l'avanzamento dell'operazione ReviewManager_requestReviewFlow chiamando ReviewManager_getReviewStatus, ad esempio una volta ogni frame. Questa operazione potrebbe richiedere fino a un paio di secondi, quindi devi avviarla prima che la tua app raggiunga il punto in cui vuoi mostrare il flusso di revisione in-app.

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

Gestire gli stati e avviare il flusso di revisione in-app

Ogni volta che viene avviata una richiesta o viene lanciato il flusso di revisione in-app, puoi controllare lo stato utilizzando ReviewManager_getReviewStatus. In questo modo puoi definire la logica in base allo stato dell'API. Un modo per affrontare questo problema è mantenere lo stato come variabile globale e controllare se lo stato è REVIEW_REQUEST_FLOW_COMPLETED quando l'utente esegue una determinata azione (ad esempio tocca un pulsante "Livello successivo" in un gioco), come mostrato nel seguente esempio:

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

Quando lo stato è REVIEW_REQUEST_FLOW_COMPLETED e la tua app è pronta, avvia il flusso di revisione in-app:

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

Dopo aver avviato il flusso di revisione in-app, continua a controllare lo stato per il completamento e prosegui con il flusso dell'app. Un modo comune per gestire questo problema è seguire il pattern ciclo di gioco.

Risorse senza costi

Non dimenticare di liberare le risorse chiamando la funzione ReviewManager_destroy una volta che l'app ha terminato di utilizzare l'API (ad esempio, dopo aver completato il flusso di revisione in-app).

void ReviewManager_destroy();

Passaggi successivi

Testa il flusso di recensione in-app della tua app per verificare che l'integrazione funzioni correttamente.