Integrar avaliações no app (nativo)

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

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 ReviewManager das bibliotecas Java de avaliação no app do Google Play. Esse arquivo de cabeçalho 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 retornam REVIEW_NO_ERROR se a função for bem-sucedida.

Configurar seu ambiente de desenvolvimento

Fazer o download Play Core Native SDK

Antes de fazer o download, é necessário concordar com os Termos e Condições a seguir.

Termos e Condições

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.
Fazer o download de Play Core Native SDK

play-core-native-sdk-1.15.3.zip

  1. Realize uma das seguintes ações:

  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
    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.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. 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 que um usuário dispensar a tela de resumo ao final de um nível em um jogo). Quando o app se aproximar de um desses pontos, chame ReviewManager_requestReviewFlow para solicitar de forma assíncrona as informações de que o app precisa para iniciar um fluxo de avaliação no app. 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 em que você quer mostrar 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 definir a lógica dependendo do status da API. Uma maneira de abordar isso é manter o status como uma variável global e verificar se ele é REVIEW_REQUEST_FLOW_COMPLETED quando o usuário realiza uma determinada ação (por exemplo, tocar em um botão "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();

Próximas etapas

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