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 o Unity.

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 iniciar la descarga, debes aceptar los siguientes términos y condiciones.

Términos y Condiciones

Última modificación: 24 de septiembre de 2020
  1. Si usas el kit de desarrollo de software de Play Core, aceptas estas condiciones, además de las Condiciones del Servicio de las API de Google ("Condiciones del Servicio de las API"). Si se encuentran en conflicto, estas tendrán prioridad sobre las Condiciones del Servicio de la API. Lee estas condiciones y las Condiciones del Servicio de la API minuciosamente.
  2. Para los propósitos de estas condiciones, "API" se refiere a las API de Google, otros servicios para desarrolladores y el software asociado, inclusive cualquier Código Redistribuible.
  3. Se llama "Código Redistribuible" a lo que provee Google como código de objeto o los archivos de encabezado que llaman a las API.
  4. Sujeto a estas condiciones y las de las Condiciones del Servicio de la API, puedes copiar y distribuir únicamente el Código Redistribuible a modo de inclusión como parte del Cliente de API. Google y sus proveedores de licencias son propietarios de todos los derechos, intereses y títulos; asimismo, de toda propiedad intelectual, otros derechos de propiedad y el Código Redistribuible. No modificarás, trasladarás ni crearás obras derivadas del Código Redistribuible.
  5. Google puede publicar un aviso sobre cambios en las condiciones en cualquier momento y brindará la opción de rechazar el uso del kit de desarrollo de software de Play Core. Google avisará sobre las modificaciones a las condiciones en https://developer.android.com/guide/playcore/license. Los cambios no se aplicarán de forma retroactiva.

Descargar Play Core Native SDK

Descargar Play Core Native SDK

play-core-native-sdk-1.11.0.zip

  1. Elige una de las siguientes opciones:

  2. Prepara Android Studio para el desarrollo nativo con SDK Manager a fin de 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
    55,6 MB 058b4069f09714da938656d43b6dc28d3bc6f821c9d406e9c96a1c3af014dc45
  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/per-feature-proguard-files"
                    ...
                }
                debug {
                    ...
                }
            }
            externalNativeBuild {
                cmake {
                    path 'src/main/CMakeLists.txt'
                }
            }
        }
    
        dependencies {
            // Use the Play Core AAR included with the SDK.
            implementation files("$playcoreDir/playcore.aar")
    
            // Use the following dependency for the Play Integrity API.
            implementation("com.google.android.play:integrity:1.0.0")
            ...
        }
        

    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/per-feature-proguard-files")
                ...
            }
            debug {
                ...
            }
        }
        externalNativeBuild {
            cmake {
                path = "src/main/CMakeLists.txt"
            }
        }
    }
    
    dependencies {
        // Use the Play Core AAR included with the SDK.
        implementation(files("$playcoreDir/playcore.aar"))
        ...
    }
    
  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
            ...)
    

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 a fin de 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. Eso te permite definir la lógica según el estado de la API. Una forma de abordar esto es mantener el estado como una variables globales 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 a fin de 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 a fin de verificar que la integración funcione correctamente.