Integrar avaliações no app (nativo)

Este guia descreve como integrar avaliações no seu app usando o código nativo (C ou C++). Há guias de integração separados se você estiver usando o Kotlin ou Java ou o Unity.

Visão geral do SDK nativo

O SDK nativo da Play Core faz parte da família de Bibliotecas Google Play Core. O SDK nativo da Play Core inclui um arquivo principal C, review.h, que envolve o ReviewManager das bibliotecas Java de avaliação no app do Google Play. Esse arquivo principal permite que o app chame a API diretamente do código nativo. Para uma visão geral das funções públicas disponíveis, consulte a documentação do módulo nativo de avaliação do Google Play.

ReviewManager_requestReviewFlow inicia uma solicitação que coleta as informações necessárias para iniciar o fluxo de avaliação no app mais tarde. É possível acompanhar o resultado da solicitação usando ReviewManager_getReviewStatus. Para mais informações sobre todos os status que ReviewManager_getReviewStatus pode retornar, consulte ReviewErrorCode.

As funções de solicitação e inicialização retornarão REVIEW_NO_ERROR se a função for bem-sucedida.

Configurar seu ambiente de desenvolvimento

1. Realize uma das seguintes ações:

   • Instale o Android Studio versão 4.0 ou mais recente. Use a IU do SDK Manager para instalar o Android SDK Platform versão 10.0 (nível 29 da API).
   • Instale as ferramentas de linha de comando do SDK do Android e use o sdkmanager para instalar o Android SDK Platform versão 10.0 (API de nível 29).

2. Prepare o Android Studio para o desenvolvimento nativo usando o SDK Manager para instalar o CMake e o Android Native Development Kit (NDK) mais recentes. Para saber mais sobre como criar ou importar projetos nativos, consulte Começar a usar o NDK.

3. Faça o download do arquivo ZIP e extraia ele junto com o projeto.

   Link de download	Tamanho	Soma de verificação SHA-256
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. Atualize o arquivo build.gradle do app como mostrado abaixo:

   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. Atualize os arquivos CMakeLists.txt do app como mostrado abaixo:

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

Coleta de dados

O SDK nativo da Play Core pode coletar dados relacionados à versão para que o Google melhore o produto, incluindo:

• Nome do pacote do app
• Versão do pacote do app
• Versão do SDK nativo da Play Core

Esses dados vão ser coletados quando você fizer upload do seu pacote de apps para o Play Console. Para desativar esse processo de coleta de dados, remova a importação de $playcoreDir/playcore-native-metadata.jar no arquivo build.gradle.

Essa coleta de dados relacionada ao seu uso do SDK nativo da Play Core e o uso do Google dos dados coletados são independentes e não estão relacionados à coleta de dependências de biblioteca do Google declaradas no Gradle quando você faz upload do pacote do app para o Play Console.

Depois de integrar o SDK nativo da Play Core ao projeto, inclua a linha abaixo nos arquivos que contêm chamadas de API:

Incluir review.h

Depois de integrar o SDK do Play Core Native ao projeto, inclua a seguinte linha nos arquivos que contêm chamadas de API:

#include "play/review.h"

Inicializar a API Review

Sempre que você quiser usar a API, inicialize-a primeiro chamando a função ReviewManager_init, conforme mostrado no exemplo a seguir criado com 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.
  }
}

Solicitar o fluxo de avaliação no app

Siga as orientações sobre quando solicitar avaliações no app para determinar bons pontos no fluxo do usuário para solicitar uma avaliação (por exemplo, depois de um usuário dispensar a tela de resumo ao final de um nível em um jogo). Quando seu app se aproximar de um desses pontos, chame ReviewManager_requestReviewFlow para solicitar de forma assíncrona as informações de que seu app precisa para iniciar uma avaliação no app fluxo. Monitore o progresso da operação ReviewManager_requestReviewFlow chamando ReviewManager_getReviewStatus, por exemplo, uma vez por frame. Isso pode levar alguns segundos. Portanto, inicie esse processo antes que o app chegue ao ponto quando você quiser exibir o fluxo de revisão.

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

Processar status e iniciar o fluxo de avaliação no app

Sempre que uma solicitação ou o fluxo de avaliação no app são iniciados, é possível verificar o status usando ReviewManager_getReviewStatus. Isso permite que você defina a lógica dependendo do status da API. Uma maneira de abordar isso é manter o status como uma variável global e verificar se o status é REVIEW_REQUEST_FLOW_COMPLETED quando o usuário realiza uma determinada ação (por exemplo, tocar em uma “Próxima Fase”. em um jogo), conforme mostrado no exemplo a seguir:

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 o status for REVIEW_REQUEST_FLOW_COMPLETED e o app estiver pronto, inicie o fluxo de avaliação no 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;
}

Depois de iniciar o fluxo de avaliação no app, continue verificando o status para continuar e prossiga com o fluxo do app. Uma maneira comum de lidar com isso é seguir o padrão Loop de jogo.

Liberar os recursos

Não se esqueça de liberar os recursos chamando a função ReviewManager_destroy quando seu app terminar de usar a API (por exemplo, após a conclusão do fluxo de avaliação no app).

void ReviewManager_destroy();

A seguir

Teste o fluxo de avaliações no app para verificar se a integração está funcionando corretamente.