Integrare le recensioni in-app (native)

Questa guida descrive come integrare le recensioni in-app nella tua app utilizzando il codice nativo (C o C++). Se usi Kotlin o Java o Unity, sono disponibili guide all'integrazione separate.

Panoramica dell'SDK nativo

L'SDK nativo di base di Play fa parte della famiglia delle librerie Google Play Core. L'SDK nativo di base di Play include un file di intestazione C, review.h, che esegue il wrapping di ReviewManager dalle librerie Revisione in-app di Java Play. Questo file di intestazione consente all'app di chiamare l'API direttamente dal codice nativo. Per una panoramica delle funzioni pubbliche disponibili, consulta la documentazione relativa ai moduli nativi di Play Review.

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

Entrambe le funzioni di richiesta e lancio restituiscono REVIEW_NO_ERROR se la funzione ha esito positivo.

Configura l'ambiente di sviluppo

1. Procedi in uno dei seguenti modi:

   • Installa Android Studio versione 4.0 o successive. Utilizza l'interfaccia utente di SDK Manager per installare Android SDK Platform versione 10.0 (livello API 29).
   • Installa gli strumenti a riga di comando dell'SDK Android e utilizza sdkmanager per installare Android SDK Platform versione 10.0 (livello API 29).

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

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

   Link di download	Dimensioni	Checksum SHA-256
   play-core-native-sdk-1.14.0.zip	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

4. Aggiorna il file build.gradle dell'app come mostrato di seguito:

   trendy

       // 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.0.0'
           implementation 'com.google.android.play:asset-delivery:2.0.0'
           implementation 'com.google.android.play:integrity:1.0.1'
           implementation 'com.google.android.play:review:2.0.0'
   
           // 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.0.0")
       implementation("com.google.android.play:asset-delivery:2.0.0")
       implementation("com.google.android.play:integrity:1.0.1")
       implementation("com.google.android.play:review:2.0.0")
   
       // 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 dell'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 Play Core Native SDK

Questi dati verranno raccolti quando caricherai il pacchetto dell'app in 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 all'utilizzo dell'SDK nativo di Play Core e all'uso dei dati raccolti da parte di Google è separata e indipendente dalla raccolta di dipendenze di libreria dichiarate in Gradle quando carichi il pacchetto di app in Play Console.

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

Includi recensione.h

Dopo aver integrato l'SDK nativo della libreria di base Play nel progetto, includi la seguente riga 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 le revisioni in-app per stabilire i punti positivi nel flusso utente della tua app per richiedere una revisione (ad esempio, dopo che un utente chiude la schermata di riepilogo alla fine di un livello in un gioco). Quando la tua app si avvicina a uno di questi punti, chiama ReviewManager_requestReviewFlow per richiedere in modo asincrono le informazioni necessarie alla tua app per lanciare un flusso di revisione in-app. Monitora l'avanzamento dell'operazione ReviewManager_requestReviewFlow chiamando ReviewManager_getReviewStatus, ad esempio una volta ogni frame. L'operazione potrebbe richiedere fino a un paio di secondi, quindi devi avviare il processo prima che l'app raggiunga il momento 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.
}

Gestisci gli stati e avvia il flusso di revisione in-app

Ogni volta che una richiesta è stata avviata o viene avviato il flusso di revisione in-app, puoi controllare lo stato utilizzando ReviewManager_getReviewStatus. Ciò consente di definire la logica in base allo stato dell'API. Un modo per ovviare a 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, toccando un pulsante "Livello successivo" in un gioco), come mostrato nell'esempio seguente:

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 di completamento e continua con il flusso dell'app. Un modo comune per gestire questo problema è seguire il pattern Ciclo di gioco.

Risorse senza costi

Non dimenticare di utilizzare le risorse senza costi chiamando la funzione ReviewManager_destroy una volta che l'app ha finito di utilizzare l'API (ad esempio, dopo il completamento del flusso di revisione in-app).

void ReviewManager_destroy();

Passaggi successivi

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