Cómo integrar opiniones integradas en la app (código nativo)

En esta guía, se describe cómo integrar opiniones integradas en tu app usando código nativo (C o C++). Hay guías de integración separadas que puedes usar con Kotlin o Java, Unity o Unreal Engine.

Descripción general del SDK nativo

El SDK nativo de Play Core forma parte de la familia de bibliotecas de Google Play Core. El SDK nativo de Play Core incluye un archivo de encabezado C, review.h, que une ReviewManager de las bibliotecas de Opiniones integradas en la app de Play de Java. Ese archivo de encabezado permite que la app llame a la API directamente desde tu código nativo. Para obtener una descripción general de las funciones públicas que están disponibles, consulta la documentación del módulo nativo de opiniones de Play.

ReviewManager_requestReviewFlow inicia una solicitud que recopila la información necesaria para iniciar el flujo de opiniones integradas en la app más tarde. Puedes realizar un seguimiento del resultado de la solicitud mediante ReviewManager_getReviewStatus. Para obtener más información sobre todos los estados que puede mostrar ReviewManager_getReviewStatus, consulta ReviewErrorCode.

Las funciones de solicitud y de inicio muestran REVIEW_NO_ERROR si la función tiene éxito.

Cómo configurar tu entorno de desarrollo

Descargar Play Core Native SDK

Antes de la descarga, debes aceptar los Términos y Condiciones.

Términos y Condiciones

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.
Descargar Play Core Native SDK

play-core-native-sdk-1.15.3.zip

  1. Elige una de las siguientes opciones:

  2. Prepara Android Studio para el desarrollo nativo con SDK Manager para instalar la versión más reciente del kit de desarrollo nativo (NDK) de CMake y Android. Obtén más información para crear o importar proyectos nativos en la sección Cómo comenzar a usar el NDK.

  3. Descarga el archivo ZIP y extráelo junto con tu proyecto.

    Vínculo de descarga Tamaño Suma de comprobación SHA-256
    37.8 MiB 9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

  4. Actualiza el archivo build.gradle de tu app como se muestra a continuación:

    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. Actualiza los archivos CMakeLists.txt de tu app como se muestra a continuación:

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

Recopilación de datos

Para permitir que Google mejore el producto, el SDK nativo de Play Core puede recopilar datos relacionados con la versión como los siguientes:

  • Nombre del paquete de la app
  • Versión del paquete de la app
  • Versión del SDK nativo de Play Core

Estos datos se recopilarán cuando subas el paquete de tu app a Play Console. Para inhabilitar este proceso de recopilación de datos, quita la importación de $playcoreDir/playcore-native-metadata.jar en el archivo build.gradle.

Ten en cuenta que la recopilación de datos relacionada con tu uso del SDK nativo de Play Core y el uso que Google hace de los datos recopilados es independiente de la colección de dependencias de bibliotecas declarada por Google en Gradle cuando subes tu paquete de app a Play Console.

Después de integrar el SDK nativo de Play Core en tu proyecto, incluye la siguiente línea en los archivos que contengan llamadas a la API:

Incluye review.h

Después de integrar el SDK nativo de Play Core en tu proyecto, incluye la siguiente línea en los archivos que contendrán llamadas a la API:

#include "play/review.h"

Inicializa la API de opiniones

Siempre que quieras usar la API, deberás inicializarla primero llamando a la función ReviewManager_init, como se muestra en el siguiente ejemplo compilado 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.
  }
}

Solicita el flujo de opiniones integrado en la app

Sigue las instrucciones sobre cuándo solicitar opiniones integradas en la app para determinar buenos puntos en el flujo de usuarios de tu app para solicitarle al usuario que brinde una opinión (por ejemplo, después de que descarte la pantalla de resumen al final de un nivel en un juego). Cuando tu app se acerque a uno de esos puntos, llama a ReviewManager_requestReviewFlow para solicitar de forma asíncrona la información que tu app necesita para iniciar un flujo de opiniones integradas. Supervisa el progreso de la operación ReviewManager_requestReviewFlow llamando a ReviewManager_getReviewStatus, por ejemplo, una vez en cada fotograma. Esto puede tardar unos segundos, por lo que deberías iniciar este proceso antes de que tu app alcance el punto en el que quieras mostrar el flujo de opiniones integradas.

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

Controla los estados e inicia el flujo de opiniones integradas en la app

Cada vez que se inicia una solicitud o el flujo de opiniones integradas en la app, puedes verificar el estado mediante ReviewManager_getReviewStatus. Esto te permite definir la lógica según el estado de la API. Una forma de abordar esto es mantener el estado como una variable global y verificar si este es REVIEW_REQUEST_FLOW_COMPLETED cuando el usuario realiza una acción determinada (por ejemplo, presionar un botón "Nivel siguiente" en un juego), como se muestra a continuación:

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

Cuando el estado sea REVIEW_REQUEST_FLOW_COMPLETED y tu app esté lista, inicia el flujo de opiniones integradas en la 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;
}

Después de iniciar el flujo, continúa revisando el estado para detectar la finalización y continúa con el flujo de la app. Una forma común de procesar esto sería seguir el patrón de Bucle de juego.

Recursos gratuitos

No te olvides de liberar recursos llamando a la función ReviewManager_destroy una vez que tu app haya terminado de usar la API (por ejemplo, después de que se complete el flujo de opiniones integradas en la app).

void ReviewManager_destroy();

Próximos pasos

Prueba el flujo de opiniones integradas en la app para verificar que la integración funcione correctamente.