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

1. Elige una de las siguientes opciones:

   • Instala la versión 4.0 o una posterior de Android Studio. Usa la IU del SDK Manager para instalar la versión 10.0 de la plataforma del SDK de Android (nivel de API 29).
   • Instala las herramientas de línea de comandos del SDK de Android y usa sdkmanager para instalar la versión 10.0 de la plataforma del SDK de Android (nivel de API 29).

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
   play-core-native-sdk-1.12.1.zip	70.9 MiB	84c9e9579f05d6e29bbbd9c9cde2fde8210947f2007866b0045f4c40fabb7368

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.0.0'
           implementation 'com.google.android.play:asset-delivery:2.0.0'
           implementation 'com.google.android.play:integrity:1.0.1'
           implementation 'com.google.android.play:review:2.0.0'
   
           // 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.0.0")
       implementation("com.google.android.play:asset-delivery:2.0.0")
       implementation("com.google.android.play:integrity:1.0.1")
       implementation("com.google.android.play:review:2.0.0")
   
       // 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

El SDK nativo de Play Core puede recopilar datos relacionados con la versión para permitir que Google mejore el producto, por ejemplo:

• 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 $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 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.