Premiers pas avec Firebase en C++

1. Présentation

Dans cet atelier de programmation, vous apprendrez à intégrer le SDK Firebase Games en C++ dans un exemple de jeu Android à l'aide de Google Analytics. Vous pourrez ajouter les fonctionnalités dont vous avez besoin, intégrer une logique d'analyse de base pour mesurer la progression de vos joueurs et partager le jeu avec des testeurs pour obtenir des commentaires précoces.

Tutoriel

Si vous souhaitez suivre cet atelier de programmation avec les auteurs, regardez cette vidéo :

Points abordés

• Ajouter Firebase à votre jeu Android basé sur CMake
• Déterminer les dépendances C++ et Gradle dont vous avez besoin
• Comment consigner des événements Analytics
• Comment déboguer les événements analytiques
• Découvrez comment partager votre jeu avec App Distribution.

Prérequis

• Android Studio
• Exemple de code
• Un appareil ou un émulateur de test avec les services Google Play

2. Obtenir l'exemple de code

Extraire ou télécharger depuis GitHub :

git clone https://github.com/FirebaseExtended/cmake-way-for-firebase.git

Télécharger le SDK Firebase

macOS/Linux :

sh download.sh

Windows (depuis PowerShell) :

./download.ps1

Vous pouvez également télécharger le SDK manuellement. Si vous le faites, le SDK Firebase C++ doit être extrait dans /third_party de sorte qu'un dossier nommé firebase_cpp_sdk contienne la racine CMakeLists.txt du SDK Firebase.

3. Exécuter l'exemple de jeu

Commencez par jouer au jeu exemple et assurez-vous que tout fonctionne. Il s'agit d'un simple jeu de course infini avec un niveau généré de manière procédurale et un seul bouton pour sauter.

1. Sélectionnez Fichier > Nouveau > Importer un projet (ou sélectionnez Importer un projet sur l'écran de démarrage).
2. Ouvrez le dossier proj.android/ inclus dans le dépôt.

Il s'agit d'un projet Cocos2dx et non d'un projet Android classique. Normalement, vous devriez voir un fichier build.gradle à la racine de ce dépôt, mais il se trouve sous proj.android/ afin que chaque système d'exploitation cible puisse avoir son propre processus de compilation autonome.

3. [Facultatif] Ouvrez proj.android/gradle.properties et affinez PROP_APP_ABI. Vous pouvez supprimer toutes les architectures, à l'exception de celle cible, pour réduire les temps de compilation. PROP_APP_ABI=x86 ne compilera que pour l'émulateur, tandis que PROP_APP_ABI=armeabi-v7a compilera pour la plupart des téléphones.
4. Cliquez sur le bouton Déboguer  pour créer et exécuter le jeu. La création du moteur de jeu Cocos2dx prendra du temps.

Les développeurs Cocos2dx expérimentés peuvent choisir d'utiliser cocos run -p android s'ils ont installé la CLI Cocos2dx. Les développeurs Android peuvent préférer ./gradlew installDebug. Pour ce tutoriel, je vais supposer que vous utilisez Android Studio pour développer, compiler et déployer.

4. Configurer la console Firebase

1. Créez un projet dans la console Firebase.
2. Donnez-lui un nom, par exemple "Popsicle Runner".
3. Activer Analytics 
4. Ajouter ou créer un compte Analytics
5. Ajouter une application Android à votre projet
6. Ajoutez com.firebase.popsiclerunner comme nom de package.

Vous n'aurez pas besoin de SHA-1 pour cet atelier de programmation.

7. Téléchargez le fichier google-services.json et copiez-le dans proj.android/app .

De nombreux services d'hébergement de sources signaleront google-services.json comme "secret" si vous essayez de l'enregistrer, mais rien dans ce fichier n'est réellement secret (dans un jeu commercialisé, il est trivial de récupérer le contenu de ce fichier). Toutefois, vous devez rester prudent si vous prévoyez de l'enregistrer dans un dépôt de code source public. Il sera beaucoup plus facile de trouver vos bases de données ou vos buckets Cloud Storage avant que vous n'ayez écrit des règles de sécurité strictes si ce fichier est publié publiquement.

8. Ignorez les instructions fournies pour ajouter le SDK Firebase, puis cliquez sur "Suivant".
9. Vous pouvez cliquer sur "Ignorer cette étape" lorsque vous êtes invité à valider votre installation.

5. Ajouter Firebase à votre jeu

Ajouter le SDK Firebase à CMakeLists.txt

Ouvrez le fichier CMakeLists.txt au niveau racine. Il doit comporter le code suivant en haut de la page :

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

et ajoutez les lignes suivantes à la fin de ce fichier CMakeLists.txt.

CMakeLists.txt

add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/third_party/firebase_cpp_sdk)
target_link_libraries(${APP_NAME} firebase_analytics firebase_app)

add_subdirectory inclut le SDK Firebase C++ et le rend disponible pour ce jeu.

target_link_libraries Connecte le jeu aux bibliothèques C++ de Firebase conçues pour Android.

Consultez ce tableau pour déterminer les bibliothèques dont vous avez besoin pour chaque fonctionnalité que vous souhaitez utiliser. C'est ainsi que j'ai su que firebase_analytics nécessite firebase_app.

Ajouter le plug-in Google Services

Pour connecter le SDK Firebase, vous devez ajouter le plug-in Google Services à votre script de compilation Gradle. Pour ce faire, ouvrez le fichier build.gradle au niveau du projet (dans le dossier proj.android). Ajoutez classpath 'com.google.gms:google-services:4.3.3' en tant que dépendance buildscript.

build.gradle

buildscript {
    repositories {
        google()
        jcenter()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:4.0.1'

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
        classpath 'com.google.gms:google-services:4.3.3'  // Google Services plugin
    }
}

Ajoutez ensuite le plug-in à votre fichier build.gradle au niveau du module (qui se trouve dans votre dossier proj.android/app). Ajoutez apply plugin: 'com.google.gms.google-services' sous apply plugin: 'com.android.application' :

build.gradle

apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'  // Google Services plugin

Localiser le SDK C++ dans Gradle

Pour indiquer à Gradle où trouver le SDK Firebase C++, ajoutez les lignes suivantes en bas du fichier settings.gradle.

settings.gradle

gradle.ext.firebase_cpp_sdk_dir = "$settingsDir/../third_party/firebase_cpp_sdk/"
includeBuild "$gradle.ext.firebase_cpp_sdk_dir"

Il doit pointer vers le même emplacement que l'appel add_subdirectory dans CMake.

Ajouter les dépendances Android

Pour connecter les dépendances Android pour Firebase, ouvrez le fichier Gradle au niveau du module pour popsicle_runner (dans proj.android/app/build.gradle) et ajoutez ce qui suit juste avant la section dependences { habituelle à la fin :

build.gradle

apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
    analytics
}

Chaque SDK C++ est conçu pour une version spécifique du SDK Android. firebaseCpp.dependencies est une fonction pratique qui permet de découvrir et de configurer les dépendances Gradle nécessaires pour vous assurer d'avoir une configuration validée.

AndroidX et Jetifier

Ajoutez la prise en charge d'AndroidX et de Jetifier en ouvrant gradle.properties et en ajoutant ce qui suit à la fin :

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Initialiser Firebase dans votre jeu

Initialisez Firebase dans le jeu en ouvrant Classes/AppDelegate.cpp. Ajoutez les directives #include suivantes en haut :

AppDelegate.cpp

#include <firebase/app.h>
#include <firebase/analytics.h>

Ajoutez ensuite App::Create et initialisez les fonctionnalités Firebase dont vous avez besoin. Pour ce faire, recherchez AppDelegate::applicationDidFinishLaunching et ajoutez le code suivant avant auto scene = MainMenuScene::createScene() :

AppDelegate.cpp

{
    using namespace firebase;
    auto app = App::Create(JniHelper::getEnv(), JniHelper::getActivity());
    analytics::Initialize(*app);
}

Je préfère utiliser un bloc anonyme {} pour limiter le champ d'application des instructions using telles que using namespace firebase;.

Si vous déboguez le jeu et actualisez le tableau de bord Firebase, un nouvel utilisateur devrait apparaître au bout d'une minute environ.

6. Ajouter Analytics

Même au début du développement, les données analytiques sont un outil utile pour évaluer la façon dont les bêta-testeurs interagissent avec le jeu. Certaines données analytiques sont collectées automatiquement (par exemple, les rapports sur la fidélisation), mais il est utile d'ajouter des événements personnalisés adaptés à votre jeu.

Un bon point de départ consiste à enregistrer un événement d'analyse lorsque le joueur commence un niveau. Nous pouvons utiliser le nombre d'événements de début de niveau pour voir à quelle fréquence un joueur peut rejouer au jeu au cours d'une session.

Nous enregistrerons également un événement lorsque le joueur meurt, en indiquant sa progression. Cela nous permettra de voir comment les modifications que nous apportons changent la durée d'une session unique et de déterminer si les joueurs préfèrent un jeu plus court/difficile ou plus long/facile.

Ajouter des en-têtes Analytics

Ouvrez Classes/PopsicleScene.cpp et ajoutez les en-têtes Firebase en haut pour pouvoir effectuer des appels Analytics.

PopsicleScene.cpp

#include <firebase/analytics.h>
#include <firebase/analytics/event_names.h>

Enregistrer un événement de début de niveau

Pour consigner un événement lorsque cette scène est mise en scène par le directeur Cocos2dx, recherchez la fonction stub PopsicleScene::onEnter(). Saisissez le code suivant pour enregistrer l'événement "Level Start" (Début du niveau) :

PopsicleScene.cpp

using namespace firebase;
analytics::LogEvent(analytics::kEventLevelStart);

Enregistrer un événement de fin de niveau

Pour voir les performances d'un joueur, enregistrons un événement de fin de niveau avec la distance parcourue par le joueur avant de mourir. Pour ce faire, recherchez PopsicleScene::gameOver() et ajoutez-le à la fin du bloc if(!_gameOver) { avant de définir _gameOver = true; :

PopsicleScene.cpp

{
    using namespace firebase;
    analytics::LogEvent(analytics::kEventLevelEnd, "distance", _lastDistance);
}

kEventLevelEnd est l'événement de fin de niveau. "distance" est un "paramètre d'événement". Nous ajoutons ici la dernière distance enregistrée, qui est une bonne approximation de la distance parcourue par un joueur avant de mourir.

7. Événements de test

Vous pouvez cliquer sur Déboguer  maintenant, mais il faudra du temps pour que les événements soient signalés dans le tableau de bord Analytics. Deux raisons l'expliquent : 1) les événements sont regroupés et importés environ une fois par heure pour préserver la batterie ; 2) les rapports sont générés toutes les 24 heures.

Il existe des mécanismes qui vous permettent de consulter les événements plus rapidement. Si un événement est marqué comme événement de conversion, il sera signalé en temps quasi réel dans de nombreuses circonstances. Vous pouvez également configurer Google Analytics pour exporter les données vers BigQuery, où la table intrajournalière ne sera obsolète que d'environ quatre heures.

Activer le mode débogage

Il est toujours possible de déboguer les événements Analytics en activant le mode débogage sur votre appareil.

Assurez-vous d'abord que l'Android Debug Bridge (ADB) est installé et configuré. Si vous saisissez adb devices, l'appareil sur lequel vous allez effectuer le test devrait s'afficher :

$ adb devices
List of devices attached
emulator-5554   device

Exécutez ensuite la commande adb shell suivante :

adb shell setprop debug.firebase.analytics.app com.firebase.popsiclerunner

Cela indique à Firebase Analytics de consigner immédiatement les événements et de les exclure automatiquement de vos rapports normaux pour éviter de polluer vos événements en direct lors des tests. Si vous souhaitez annuler cette action ultérieurement, il vous suffit d'écrire :

adb shell setprop debug.firebase.analytics.app .none.

Afficher des événements

Ouvrez "DebugView" dans la console Firebase 

Cliquez sur Déboguer , puis lancez le jeu. Vous devriez voir de nouveaux événements apparaître presque immédiatement après qu'ils se sont produits dans le jeu.

Si vous développez l'événement level_end, vous verrez également le paramètre personnalisé "distance" que vous avez enregistré.

Lorsque l'événement level_end apparaît dans vos rapports sur les événements, il ne collecte pas la distance par défaut. Vous devrez sélectionner Événements , rechercher level_end, développer les trois points sur la droite , puis sélectionner Modifier le reporting des paramètres pour l'ajouter en tant que paramètre dans vos rapports sur les événements. Vous pourrez alors consulter des statistiques telles que la distance moyenne parcourue par vos joueurs par match.

8. Trouver des testeurs

Ensuite, vous devez faire tester votre jeu, que ce soit en interne, par des amis proches ou par votre communauté. Firebase App Distribution vous permet d'inviter facilement des joueurs à tester votre jeu.

Créer un binaire autonome

Commencez par compiler un APK autonome à partager en sélectionnant Build > Build Bundle(s) / APK(s) > Build APK(s) 

Si vous avez déjà modifié votre filtre ABI, n'oubliez pas de revenir à gradle.properties et de modifier PROP_APP_ABI pour inclure tous les appareils sur lesquels vous prévoyez de tester :

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio affichera une boîte de dialogue vous permettant de localiser le fichier créé. Si vous le manquez, vous pouvez cliquer sur "Journal des événements" pour obtenir à nouveau le lien.

Importer dans Firebase App Distribution

1. Ouvrez App Distribution et cliquez sur "Commencer" .
2. Faites glisser votre fichier .apk dans la zone "Faites glisser un fichier .apk ici pour créer une version".
3. Saisissez votre adresse e-mail comme premier testeur.
4. Cliquez sur "Suivant".
5. Ajoutez une description, puis cliquez sur "Distribuer".

Inviter des testeurs

Au lieu de saisir manuellement chaque adresse e-mail, vous pouvez créer un lien d'invitation. Lorsque vous capturez un utilisateur avec ce lien d'invitation, vous pouvez également l'ajouter à un groupe de testeurs. Cela vous permettrait, par exemple, de séparer les testeurs internes des testeurs externes.

1. Cliquez sur "Testeurs et groupes" .
2. Créez un groupe  et donnez-lui un nom, par exemple "Testeurs Android".
3. Cliquez sur "Liens d'invitation" .
4. Cliquez sur "Nouveau lien d'invitation".
5. Définissez le groupe dans le menu déroulant.
6. Cliquez sur "Créer un lien".
7. Cliquez sur "Copier le lien" et partagez-le comme vous le souhaitez.

9. Félicitations

Vous avez réussi à ajouter des données analytiques à votre jeu basé sur C++, à inviter des amis à jouer et à trouver et associer des bibliothèques Firebase dans un système de compilation basé sur CMake et Gradle, couramment utilisé dans le développement Android.

Points abordés

• Ajouter Firebase à votre jeu Android basé sur CMake
• Déterminer les dépendances C++ et Gradle dont vous avez besoin
• Comment consigner des événements Analytics
• Comment déboguer les événements analytiques
• Découvrez comment partager votre jeu avec App Distribution.

Étapes suivantes

• Essayez de connecter un utilisateur de manière anonyme et d'enregistrer son meilleur score dans Realtime Database.
• Enregistrez des événements Analytics dans votre propre jeu.
• Essayez d'ajouter des données analytiques à un jeu iOS.

En savoir plus

• Consultez la liste des événements spécifiques aux jeux et réfléchissez à la façon dont ils pourraient s'intégrer à votre propre jeu.