Inizia a utilizzare Firebase in C++

1. Panoramica

In questo codelab imparerai a integrare l'SDK Firebase Games C++ in un gioco Android di esempio utilizzando Google Analytics come esempio. Potrai aggiungere le funzionalità che ti servono, integrare una logica di analisi di base per misurare i progressi dei giocatori e condividere il gioco con i tester per ricevere un feedback iniziale.

Procedura dettagliata

Se vuoi seguire questo codelab con gli autori, guarda questo video:

Obiettivi didattici

• Come aggiungere Firebase al tuo gioco basato su CMake per Android.
• Come capire quali dipendenze C++ e Gradle ti servono.
• Come registrare gli eventi Analytics.
• Come eseguire il debug degli eventi di analisi.
• Come condividere il tuo gioco con la distribuzione di app.

Che cosa ti serve

• Android Studio
• Il codice campione
• Un dispositivo di test o un emulatore con Google Play Services

2. recupera il codice campione

Esegui il checkout o il download da GitHub:

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

Scarica l'SDK Firebase

macOS/Linux:

sh download.sh

Windows (da PowerShell):

./download.ps1

Puoi anche scaricare manualmente l'SDK. Se lo fai, l'SDK Firebase C++ deve essere estratto in /third_party in modo che una cartella denominata firebase_cpp_sdk contenga la radice CMakeLists.txt dell'SDK Firebase.

3. Esegui il gioco di esempio

Innanzitutto, gioca alla partita di esempio e assicurati che tutto funzioni. È un semplice runner infinito con un livello generato proceduralmente e un solo tasto per saltare.

1. Seleziona File > Nuovo > Importa progetto (o seleziona Importa progetto dalla schermata iniziale).
2. Apri la cartella proj.android/ inclusa nel repository.

Si tratta di un progetto Cocos2dx anziché di un tipico progetto Android. Normalmente ti aspetteresti di vedere un file build.gradle nella radice di questo repository, ma si trova in proj.android/, in modo che ogni sistema operativo di destinazione possa avere il proprio processo di compilazione autonomo.

3. [Facoltativo] Apri proj.android/gradle.properties e cerca PROP_APP_ABI. Puoi rimuovere tutte le architetture tranne quella di destinazione per ridurre i tempi di compilazione. PROP_APP_ABI=x86 verrà creato solo per l'emulatore PROP_APP_ABI=armeabi-v7a verrà creato per la maggior parte degli smartphone
4. Fai clic sul pulsante Debug per creare ed eseguire il gioco. La creazione del motore di gioco Cocos2dx richiederà del tempo.

Gli sviluppatori esperti di Cocos2dx possono scegliere di utilizzare cocos run -p android se hanno installato l'interfaccia a riga di comando di Cocos2dx. Gli sviluppatori Android potrebbero preferire ./gradlew installDebug. Per questo tutorial, presupporrò che utilizzi Android Studio per sviluppare, creare e implementare.

4. Configurazione della console Firebase

1. Crea un nuovo progetto nella console Firebase.
2. Assegna un nome come "Popsicle Runner".
3. Attivare Analytics
4. Aggiungere o creare un account Analytics
5. Aggiungi una nuova app per Android al tuo progetto
6. Aggiungi com.firebase.popsiclerunner come nome del pacchetto.

Per questo codelab non è necessario un SHA-1

7. Scarica il file google-services.json e copialo in proj.android/app

Molti servizi di hosting delle origini contrassegnano google-services.json come "segreti" se provi a eseguirne il commit, ma nulla in questo file è un segreto effettivo (in un gioco pubblicato, è banale recuperare i contenuti di questo file). Devi comunque prestare attenzione se prevedi di eseguirne il commit in un repository di codice sorgente pubblico: sarà molto più facile trovare i tuoi database o bucket di archiviazione cloud prima di aver scritto regole di sicurezza efficaci se questo file viene pubblicato pubblicamente.

8. Ignora le istruzioni fornite per aggiungere l'SDK Firebase e fai clic su Avanti.
9. Quando ti viene chiesto di verificare l'installazione, puoi fare clic su "Salta questo passaggio".

5. Aggiungere Firebase al tuo gioco

Aggiungi l'SDK Firebase a CMakeLists.txt

Apri CMakeLists.txt a livello di root. Dovrebbe avere il seguente codice vicino alla parte superiore

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

e aggiungi le seguenti righe alla fine del file 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 include l'SDK Firebase C++ e lo rende disponibile per questo gioco

target_link_libraries Collega il gioco alle librerie C++ di Firebase create per Android.

Utilizza questa tabella per capire quali librerie ti servono per ogni funzionalità che vuoi utilizzare. Ecco come ho capito che firebase_analytics richiede firebase_app.

Aggiungere il plug-in Google Services

Per collegare l'SDK Firebase, devi aggiungere il plug-in dei servizi Google allo script di build Gradle. Per farlo, apri il file build.gradle a livello di progetto (si trova nella cartella proj.android). e aggiungi classpath 'com.google.gms:google-services:4.3.3' come dipendenza di 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
    }
}

Poi aggiungi il plug-in al file a livello di modulo build.gradle (si trova nella cartella proj.android/app). Aggiungi apply plugin: 'com.google.gms.google-services' sotto apply plugin: 'com.android.application':

build.gradle

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

Individua l'SDK C++ in Gradle

Per indicare a Gradle dove trovare l'SDK Firebase C++, aggiungi le seguenti righe in fondo al file settings.gradle.

settings.gradle

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

Deve puntare alla stessa posizione della chiamata add_subdirectory in CMake.

Aggiungi le dipendenze Android

Per collegare le dipendenze Android per Firebase, apri il file gradle a livello di modulo per popsicle_runner (in proj.android/app/build.gradle) e aggiungi quanto segue appena prima della tipica sezione dependences { alla fine:

build.gradle

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

Ogni SDK C++ è creato in base a una versione specifica dell'SDK Android. firebaseCpp.dependencies è una funzione utile che rileva e configura le dipendenze Gradle necessarie per garantire una configurazione verificata.

AndroidX e Jetifier

Aggiungi il supporto di AndroidX e Jetifier aprendo gradle.properties e aggiungendo questo codice alla fine:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Inizializza Firebase nel tuo gioco

Inizializza Firebase nel gioco aprendo Classes/AppDelegate.cpp. Aggiungi le seguenti direttive #include all'inizio:

AppDelegate.cpp

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

Quindi aggiungi App::Create e inizializza le funzionalità di Firebase di cui hai bisogno. Per farlo, trova AppDelegate::applicationDidFinishLaunching e aggiungi questo codice prima di auto scene = MainMenuScene::createScene():

AppDelegate.cpp

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

Preferisco utilizzare un blocco anonimo {} per limitare l'ambito delle istruzioni using come using namespace firebase;.

Se esegui il debug del gioco e aggiorni la dashboard Firebase, dopo circa un minuto dovrebbe essere visualizzato un nuovo utente.

6. Aggiungere Analytics

Anche nelle prime fasi di sviluppo, Analytics è uno strumento utile per valutare il modo in cui i beta tester interagiscono con il gioco. Alcune analisi vengono raccolte automaticamente, ad esempio i report sulla fidelizzazione, ma è utile aggiungere eventi personalizzati in base al tuo gioco specifico.

Un buon punto di partenza è registrare un evento Analytics quando il giocatore inizia un livello. Possiamo utilizzare il numero di eventi di inizio livello per vedere con quale frequenza un giocatore potrebbe rigiocare la partita in una sessione.

Registreremo anche un evento quando il giocatore muore, indicando a che punto era arrivato. In questo modo, potremo vedere come le modifiche che apportiamo cambiano la durata di una singola sessione e ci aiuterà a determinare se i giocatori preferiscono una partita più breve/difficile o più lunga/facile.

Aggiungere intestazioni di Analytics

Apri Classes/PopsicleScene.cpp e aggiungi le intestazioni Firebase in alto per poter effettuare chiamate di analisi.

PopsicleScene.cpp

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

Registrare un evento Inizio livello

Per registrare un evento quando questa scena viene preparata dal Director di Cocos2dx, trova la funzione stub PopsicleScene::onEnter(). Inserisci il seguente codice per registrare l'evento Inizio livello qui:

PopsicleScene.cpp

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

Registrare un evento di fine livello

Per vedere come sta andando un giocatore, registriamo un evento di fine livello con il punto in cui è arrivato prima di morire. Per farlo, trova PopsicleScene::gameOver() e aggiungilo alla fine del blocco if(!_gameOver) { prima di impostare _gameOver = true;:

PopsicleScene.cpp

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

kEventLevelEnd è l'evento di fine livello. mentre "distance" è un "parametro evento". Qui aggiungiamo l'ultima distanza registrata, che è una buona approssimazione della distanza percorsa da un giocatore prima di morire.

7. Eventi di test

Ora puoi fare clic su Debug , ma ci vorrà del tempo prima che gli eventi vengano segnalati nella dashboard di Analytics. Ciò è dovuto a due motivi: 1) gli eventi vengono raggruppati e caricati circa una volta all'ora per preservare la batteria e 2) i report vengono generati ogni 24 ore.

Esistono meccanismi che ti consentono di visualizzare gli eventi più rapidamente. Se un evento è contrassegnato come evento di conversione, verrà segnalato quasi in tempo reale in molte circostanze. Puoi anche configurare Google Analytics per l'esportazione in BigQuery, dove la tabella intraday sarà aggiornata con un ritardo di sole 4 ore.

Attivare la modalità di debug

È comunque possibile eseguire il debug degli eventi Analytics mettendo il dispositivo in modalità di debug.

Innanzitutto, assicurati di aver installato e configurato Android Debug Bridge (ADB). Se digiti adb devices, dovrebbe essere visualizzato il dispositivo su cui eseguire il test:

$ adb devices
List of devices attached
emulator-5554   device

Quindi, esegui questo comando adb shell:

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

In questo modo, Firebase Analytics registra immediatamente gli eventi e li esclude automaticamente dai report normali per evitare di contaminare gli eventi live durante i test. Se vuoi annullare questa azione in un secondo momento, scrivi:

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

Visualizzazione degli eventi

Apri "DebugView" nella console Firebase

Fai clic su Debug e gioca. Dovresti vedere i nuovi eventi apparire quasi immediatamente dopo che si verificano nel gioco.

Se espandi l'evento level_end, vedrai anche il parametro personalizzato "distance" che hai registrato.

Quando l'evento level_end viene visualizzato nei report sugli eventi, non rileva la distanza per impostazione predefinita. Devi selezionare Eventi , individuare level_end, espandere i tre puntini sul lato destro e selezionare Modifica report sui parametri per aggiungerlo come parametro nei report sugli eventi. Una volta fatto, puoi visualizzare statistiche come la distanza media per partita dei tuoi giocatori.

8. Trovare tester

Il passo successivo è far conoscere il tuo gioco, che si tratti di persone interne al tuo studio, di amici stretti o della tua community. Firebase App Distribution ti offre un ottimo modo per invitare i giocatori a provare il tuo gioco.

Creazione di un file binario autonomo

Per prima cosa, crea un APK indipendente da condividere da Build > Build Bundles(s) / APK(s) > Build APK(s)

Se in precedenza hai modificato il filtro ABI, ricorda di tornare a gradle.properties e modificare PROP_APP_ABI in modo da includere qualsiasi dispositivo su cui prevedi di eseguire test:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio mostrerà una finestra di dialogo che ti consente di individuare il file creato. Se non lo vedi, puoi fare clic su "Log eventi" per recuperare il link.

Caricare su Firebase App Distribution

1. Apri App Distribution e fai clic su "Inizia"
2. Trascina il file .apk nella casella con il testo "Trascina i file .apk qui per creare una nuova release".
3. Inserisci il tuo indirizzo email come primo tester.
4. Fai clic su Avanti.
5. Aggiungi una descrizione e fai clic su Distribuisci.

Invita tester

Invece di dover inserire manualmente ogni indirizzo email, puoi creare un link di invito. Quando acquisisci un utente con questo link di invito, puoi anche aggiungerlo a un gruppo di tester. In questo modo, ad esempio, potresti separare i tester interni da quelli esterni.

1. Fai clic su "Tester e gruppi" .
2. Crea un nuovo gruppo e assegnagli un nome come "Tester Android".
3. Fai clic su "Link di invito" .
4. Fai clic su "Nuovo link di invito".
5. Imposta il gruppo qui dal menu a discesa.
6. Fai clic su "Crea link".
7. Fai clic su "Copia link" e condividilo come preferisci.

9. Complimenti

Hai aggiunto correttamente Analytics al tuo gioco basato su C++, invitato alcuni amici a giocare e sai come trovare e collegare le librerie Firebase in un sistema di compilazione basato su CMake e Gradle, comune nello sviluppo per Android.

Argomenti trattati

• Come aggiungere Firebase al tuo gioco basato su CMake per Android.
• Come capire quali dipendenze C++ e Gradle ti servono.
• Come registrare gli eventi Analytics.
• Come eseguire il debug degli eventi di analisi.
• Come condividere il tuo gioco con la distribuzione di app.

Passaggi successivi

• Prova ad accedere a un utente in modo anonimo e a salvare il suo punteggio più alto in Realtime Database.
• Registra gli eventi Analytics nel tuo gioco.
• Prova ad aggiungere Analytics a un gioco per iOS.

Scopri di più

• Consulta l'elenco degli eventi specifici per i giochi e valuta come potrebbero adattarsi al tuo gioco.