Как интегрировать отзывы в приложении (нативные)

В этом руководстве описано, как интегрировать отзывы в приложение с помощью нативного кода (C или C++). Если вы используете Kotlin или Java, Unity или Unreal Engine, ознакомьтесь с отдельными руководствами по интеграции.

Обзор Native SDK

Нативный SDK Play Core входит в семейство библиотек Google Play Core. Play Core Native SDK включает заголовочный файл C review.h, который упаковывает ReviewManager из библиотек Java Play In-App Review. Этот заголовочный файл позволяет приложению вызывать API напрямую из нативного кода. Обзор доступных общедоступных функций можно найти в документации по нативному модулю Play Review.

ReviewManager_requestReviewFlow запускает запрос на сбор информации, необходимой для последующего запуска процесса оценки в приложении. Отслеживать результат запроса можно с помощью ReviewManager_getReviewStatus. Подробнее о статусах, которые может возвращать ReviewManager_getReviewStatus, читайте в статье ReviewErrorCode.

Обе функции возвращают REVIEW_NO_ERROR в случае успеха.

Как настроить среду разработки

Скачать Play Core Native SDK

Перед загрузкой вы должны согласиться со следующими условиями.

Условия и положения

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.
Скачать Play Core Native SDK

play-core-native-sdk-1.16.0.zip

  1. Выполните одно из следующих действий:

  2. Подготовьте Android Studio к нативной разработке. Для этого с помощью SDK Manager установите последние версии CMake и Android Native Development Kit (NDK). Подробную информацию о создании и импорте нативных проектов можно найти в статье Начало работы с NDK.

  3. Скачайте ZIP-файл и распакуйте его в папку проекта.

    Ссылка для скачивания Размер Контрольная сумма SHA-256
    54,8 МиБ 008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

  4. Обновите файл build.gradle приложения, как показано ниже.

    Яркий

        // 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.6.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.6.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. Обновите файлы 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 может собирать данные о версии, чтобы мы могли улучшать продукт. К таким данным относятся:

  • Название пакета приложения.
  • Версия пакета приложения.
  • Версия Play Core Native SDK

Эти данные будут собраны, когда вы загрузите пакет приложения в Play Console. Чтобы отказаться от сбора данных, удалите импорт $playcoreDir/playcore-native-metadata.jar в файле build.gradle.

Обратите внимание, что сбор данных, связанный с использованием Play Core Native SDK, и использование собранных данных компанией Google не зависят от сбора данных о зависимостях библиотек, объявленных в Gradle, который выполняется, когда вы загружаете пакет приложения в Play Console.

После интеграции нативного SDK Play Core в проект добавьте следующую строку в файлы, содержащие вызовы API:

Добавьте review.h.

После интеграции нативного SDK Play Core в проект добавьте следующую строку в файлы, которые будут содержать вызовы 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_requestReviewFlow, вызывая ReviewManager_getReviewStatus, например один раз для каждого кадра. Это может занять несколько секунд, поэтому процесс следует запустить до того, как приложение достигнет точки, в которой вы хотите показать форму отзыва.

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

После запуска процесса отзыва в приложении продолжайте проверять статус завершения и продолжайте работу с приложением. Обычно для этого используется шаблон игрового цикла.

Бесплатные ресурсы

Не забудьте освободить ресурсы, вызвав функцию ReviewManager_destroy, когда приложение закончит использовать API (например, после завершения процесса оценки).

void ReviewManager_destroy();

Дальнейшие действия

Протестируйте процесс оставления отзыва в приложении, чтобы убедиться, что интеграция работает правильно.