集成应用内评价 (原生)

本指南介绍如何使用原生（C 或 C++）代码在您的应用中集成应用内评价。如果您使用的是 Kotlin 或 Java 或 Unity，则有单独的集成指南。

原生 SDK 概述

Play Core 原生 SDK 是 Google Play Core 库系列的一部分。Play Core 原生 SDK 包含一个 C 头文件 review.h，该文件包装了来自 Java Play 应用内评价库的 ReviewManager。此头文件允许您的应用直接从您的原生代码调用 API。有关可用公共函数的概述，请参阅 Play Review 原生模块文档。

ReviewManager_requestReviewFlow 启动一个请求，该请求收集启动应用内评价流程稍后所需的信息。您可以使用 ReviewManager_getReviewStatus 跟踪请求的结果。有关 ReviewManager_getReviewStatus 可以返回的所有状态的更多信息，请参阅 ReviewErrorCode。

如果函数成功，则请求和启动函数都将返回 REVIEW_NO_ERROR。

设置您的开发环境

下载 Play Core 原生 SDK

下载前，您必须同意以下条款和条件。

条款和条件

上次修改时间：2020 年 9 月 24 日

通过使用 Play Core 软件开发工具包，您同意这些条款以及 Google API 服务条款（“API 服务条款”）。如果这些条款之间存在冲突，则这些条款将优先于 API 服务条款。请仔细阅读这些条款和 API 服务条款。
出于这些条款的目的，“API”是指 Google 的 API、其他开发者服务和相关软件，包括任何可再发行代码。
“可再发行代码”是指 Google 提供的对象代码或调用 API 的头文件。
在遵守这些条款以及 API 服务条款的前提下，您仅可出于将其包含在 API 客户端中作为一部分的目的复制和分发可再发行代码。Google 及其许可方拥有可再发行代码中所有权利、所有权和权益，包括任何及所有知识产权和其他专有权利。您不得修改、翻译或创建可再发行代码的衍生作品。
Google 可能会随时更改这些条款，并会提供通知以及拒绝进一步使用 Play Core 软件开发工具包的机会。Google 将在https://developer.android.com/guide/playcore/license发布条款修改的通知。更改不具有追溯效力。

我已阅读并同意上述条款和条件

下载 Play Core 原生 SDK

play-core-native-sdk-1.14.0.zip

执行以下任一操作
- 安装 Android Studio 4.0 或更高版本。使用 SDK 管理器 UI 安装 Android SDK 平台版本 10.0（API 级别 29）。
- 安装 Android SDK 命令行工具并使用 sdkmanager 安装 Android SDK 平台版本 10.0（API 级别 29）。
使用 SDK 管理器安装最新的 CMake 和 Android 原生开发工具包 (NDK)，从而为原生开发准备 Android Studio。有关创建或导入原生项目的更多信息，请参阅NDK 入门。
下载 zip 文件并将其解压缩到您的项目旁边。

下载链接大小 SHA-256 校验和

36 MiB 782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

下载链接	大小	SHA-256 校验和
	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

按照如下所示更新应用的 build.gradle 文件

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.1'

        // 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.1")

    // Import these common dependencies.
    implementation("com.google.android.gms:play-services-tasks:18.0.2")
    implementation(files("$playcoreDir/playcore-native-metadata.jar"))
    ...
}

按照如下所示更新应用的 CMakeLists.txt 文件

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

数据收集

Play Core Native SDK 可能会收集与版本相关的数据，以帮助 Google 改善产品，包括

应用的包名称
应用的包版本
Play Core Native SDK 的版本

将应用包上传到 Play Console 时，将收集此数据。要选择退出此数据收集流程，请删除 build.gradle 文件中 $playcoreDir/playcore-native-metadata.jar 的导入。

请注意，与您使用 Play Core Native SDK 相关的数据收集以及 Google 对收集到的数据的使用，与您将应用包上传到 Play Console 时 Gradle 中声明的库依赖项的 Google 数据收集是分开且独立的。

将 Play Core Native SDK 集成到您的项目后，请在包含 API 调用的文件中包含以下行

包含 review.h

将 Play Core Native SDK 集成到您的项目后，请在将包含 API 调用的文件中包含以下行

#include "play/review.h"

初始化 Review API

每当您想要使用 API 时，都必须先通过调用 ReviewManager_init 函数对其进行初始化，如下例所示，该示例使用 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.
  }
}

请求应用内评价流程

请遵循有关何时请求应用内评价的指南，以确定在应用的用户流程中提示用户进行评价的最佳位置（例如，在用户在游戏关卡结束时关闭摘要屏幕后）。当您的应用接近这些位置之一时，请调用 ReviewManager_requestReviewFlow 以异步请求应用启动应用内评价流程所需的信息。例如，每帧调用一次 ReviewManager_getReviewStatus 来监控 ReviewManager_requestReviewFlow 操作的进度。这可能需要最多几秒钟的时间，因此您应该在应用达到想要显示应用内评价流程的点之前启动此流程。

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

处理状态并启动应用内评价流程

每当请求开始或启动应用内评价流程时，您都可以使用 ReviewManager_getReviewStatus 检查状态。这使您可以根据 API 状态定义逻辑。一种解决方法是将状态保留为全局变量，并在用户执行特定操作（例如，点击游戏中“下一级”按钮）时检查状态是否为 REVIEW_REQUEST_FLOW_COMPLETED，如下例所示

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

当状态为 REVIEW_REQUEST_FLOW_COMPLETED 且应用已准备好时，启动应用内评价流程

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

启动应用内评价流程后，请继续检查状态是否已完成，并继续执行应用流程。处理此问题的常用方法是遵循游戏循环模式。

释放资源

应用完成使用 API 后（例如，应用内评价流程完成后），请务必通过调用 ReviewManager_destroy 函数来释放资源。

void ReviewManager_destroy();

后续步骤

测试应用的应用内评价流程以验证您的集成是否正常运行。