Intégrer des avis dans l'application (natif)

Ce guide explique comment intégrer des avis dans votre application à l'aide de code natif (C ou C++). Il existe des guides d'intégration distincts si vous utilisez Kotlin, Java ou Unity.

Présentation du SDK natif

Le SDK natif Play Core fait partie de la famille des bibliothèques Google Play Core. Le SDK natif Play Core inclut un fichier d'en-tête C, review.h, qui encapsule ReviewManager à partir des bibliothèques Java Play In-App Review. Ce fichier d'en-tête permet à votre application d'appeler l'API directement à partir de votre code natif. Pour une présentation des fonctions publiques disponibles, consultez la documentation du module natif Play Review.

ReviewManager_requestReviewFlow lance une requête qui rassemble les informations nécessaires pour lancer ultérieurement le flux d'avis dans l'application. Vous pouvez suivre le résultat de la requête à l'aide de ReviewManager_getReviewStatus. Pour en savoir plus sur tous les états que ReviewManager_getReviewStatus peut renvoyer, consultez ReviewErrorCode.

Les fonctions de requête et de lancement renvoient REVIEW_NO_ERROR si la fonction aboutit.

Configurer l'environnement de développement

Download Play Core Native SDK

Before downloading, you must agree to the following terms and conditions.

Terms and Conditions

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

play-core-native-sdk-1.12.1.zip

  1. Effectuez l'une des opérations suivantes :

    • Installez Android Studio version 4.0 ou ultérieure. À l'aide de l'interface utilisateur SDK Manager, installez la version 10.0 d'Android SDK Platform (niveau d'API 29).
    • Installez les outils de ligne de commande du SDK Android et utilisez sdkmanager pour installer la version 10.0 d'Android SDK Platform (niveau d'API 29).

  2. Préparez Android Studio pour le développement natif en installant la dernière version de CMake et du kit de développement natif Android (NDK) à l'aide de SDK Manager. Pour en savoir plus sur la création ou l'importation de projets natifs, consultez Premiers pas avec le kit NDK.

  3. Téléchargez le fichier ZIP et extrayez-le avec votre projet.

    Lien de téléchargement Taille Somme de contrôle SHA256
    70,9 Mio 84c9e9579f05d6e29bbbd9c9cde2fde8210947f2007866b0045f4c40fabb7368

  4. Mettez à jour le fichier build.gradle de votre application comme indiqué ci-dessous :

    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. Mettez à jour les fichiers CMakeLists.txt de votre application comme indiqué ci-dessous :

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

Collecte des données

Le SDK natif Play Core peut collecter des données liées à la version pour permettre à Google d'améliorer le produit, y compris :

  • Nom du package de l'application
  • Version du package de l'application
  • Version du SDK natif Play Core

Ces données seront collectées lorsque vous importerez votre package d'application dans la Play Console. Pour désactiver ce processus de collecte des données, supprimez l'importation $playcoreDir/playcore-native-metadata.jar dans le fichier build.gradle.

Notez que cette collecte de données liée à votre utilisation du SDK natif Play Core et l'utilisation par Google des données collectées sont des opérations distinctes et indépendantes de la collecte de dépendances de bibliothèque que Google déclare dans Gradle lorsque vous importez votre package d'application dans la Play Console.

Une fois le SDK natif Play Core intégré dans votre projet, incluez la ligne suivante dans les fichiers contenant des appels d'API :

Inclure review.h

Après avoir intégré le SDK natif Play Core à votre projet, incluez la ligne suivante dans les fichiers qui contiendront des appels d'API :

#include "play/review.h"

Initialiser l'API Review

Chaque fois que vous souhaitez utiliser l'API, vous devez d'abord l'initialiser en appelant la fonction ReviewManager_init, comme indiqué dans l'exemple suivant, créé avec 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.
  }
}

Flux de demande d'avis dans l'application

Suivez les conseils pour demander des avis dans l'application afin d'identifier les endroits les plus adaptés du parcours utilisateur de votre application pour inviter l'utilisateur à donner son avis (par exemple, après qu'un utilisateur a fermé l'écran récapitulatif à la fin d'un niveau dans un jeu). Lorsque votre application se rapproche de l'un de ces points, appelez ReviewManager_requestReviewFlow pour demander de manière asynchrone les informations nécessaires à votre application pour lancer un flux d'avis dans l'application. Surveillez la progression de l'opération ReviewManager_requestReviewFlow en appelant ReviewManager_getReviewStatus, par exemple une fois par frame. Cette opération peut prendre quelques secondes. Vous devez donc commencer ce processus avant que votre application ait atteint le point où vous souhaitez afficher le flux d'avis dans l'application.

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

Gérer les états et lancer le flux d'avis dans l'application

Chaque fois qu'une requête démarre ou que le flux d'avis dans l'application est lancé, vous pouvez vérifier l'état à l'aide de ReviewManager_getReviewStatus. Cela vous permet de définir la logique en fonction de l'état de l'API. Une approche possible consiste à conserver l'état en tant que variable globale et à vérifier si l'état est REVIEW_REQUEST_FLOW_COMPLETED lorsque l'utilisateur effectue une certaine action (par exemple, appuyer sur un bouton pour passer au niveau supérieur dans un jeu), comme dans l'exemple suivant :

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

Lorsque l'état est REVIEW_REQUEST_FLOW_COMPLETED et que votre application est prête, lancez le flux d'avis dans l'application :

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

Après avoir lancé le flux d'avis dans l'application, vérifiez régulièrement l'état d'avancement et poursuivez votre parcours. Une méthode courante consiste à suivre le schéma boucle de jeu.

Libérer les ressources

N'oubliez pas de libérer vos ressources en appelant la fonction ReviewManager_destroy une fois que votre application a fini d'utiliser l'API (par exemple, à la fin du flux d'avis dans l'application).

void ReviewManager_destroy();

Étapes suivantes

Testez le flux d'avis dans votre application afin de vérifier que l'intégration fonctionne correctement.