Inizia a utilizzare Firebase in C++

1. Panoramica

In questo codelab, imparerai a integrare l'SDK C++ di Firebase Games in un gioco Android di esempio utilizzando Google Analytics come esempio. Potrai aggiungere le funzionalità di cui hai bisogno, integrare alcune logiche di analisi di base per misurare i progressi dei giocatori e condividere il gioco con i tester per ricevere feedback tempestivi.

Procedura dettagliata

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

Obiettivi didattici

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

Che cosa ti serve

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

2. recupera il codice campione

Pagamento o 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. In questo caso, l'SDK Firebase C++ deve essere estratto in /third_party in modo che una cartella denominata firebase_cpp_sdk abbia la radice CMakeLists.txt dell'SDK Firebase al suo interno.

3. Esegui il gioco di esempio

Innanzitutto, prova il gioco di esempio e assicurati che tutto funzioni. È un semplice runner infinito con un livello generato proceduralmente e un singolo pulsante 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 ci si aspetta di trovare un file build.gradle nella radice di questo repository, ma è inferiore a proj.android/, quindi ogni sistema operativo di destinazione può avere un proprio processo di compilazione autonomo.

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

Gli sviluppatori Cocos2dx esperti possono scegliere di utilizzare cocos run -p android se hai installato l'interfaccia a riga di comando Cocos2dx. Gli sviluppatori Android potrebbero preferire ./gradlew installDebug. Per questo tutorial, presumo che usi Android Studio per lo sviluppo, la creazione e il deployment.

4. Configurazione della console Firebase

1. Crea un nuovo progetto nella Console Firebase.
2. Scegli un nome come "popsicle Runner"
3. Abilita Analytics
4. Aggiungi o crea un account Analytics
5. Aggiungi una nuova app per Android al progetto
6. Aggiungi com.firebase.popsiclerunner come nome del pacchetto.

Non avrai bisogno di un'algoritmo SHA-1 per questo codelab

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

Molti servizi di hosting di origini segnalano google-services.json come "segreti" se provi a eseguire il commit, ma nulla in questo file è effettivamente un segreto (in un gioco di spedizione è semplice recuperare i contenuti di questo file). Dovresti comunque fare attenzione se prevedi di eseguire il commit in un repository di codice sorgente pubblico: sarà molto più facile trovare i tuoi database o i bucket Cloud Storage 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. Puoi fare clic su "Ignora questo passaggio" quando ti viene chiesto di verificare l'installazione

5. Aggiungi Firebase al tuo gioco

Aggiungi l'SDK Firebase a CMakeLists.txt

Apri il livello principale CMakeLists.txt. Dovrebbe avere il seguente codice nella 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 con le librerie C++ di Firebase create per Android.

Utilizza questa tabella per capire quali librerie sono necessarie per ciascuna funzionalità che vuoi utilizzare. Ecco come sapevo che firebase_analytics richiede firebase_app.

Aggiungi il plug-in dei servizi Google

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

Quindi, aggiungi il plug-in al file build.gradle a livello di modulo (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 di Android per Firebase, apri il file Gradle a livello di modulo per popsicle_runner (in proj.android/app/build.gradle) e aggiungi quanto segue poco 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++ è basato su una versione specifica dell'SDK Android. firebaseCpp.dependencies è una funzione di convenienza che troverà e configurerà le dipendenze gradle necessarie per garantire una configurazione verificata.

AndroidX e Jetifier

Per aggiungere il supporto di AndroidX e Jetifier, apri gradle.properties e aggiungi questo testo 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 istruzioni #include all'inizio:

AppDelegate.cpp

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

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

AppDelegate.cpp

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

È preferibile utilizzare un blocco {} anonimo per limitare l'ambito di istruzioni using come using namespace firebase;.

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

6. Aggiungi dati e analisi

Anche nelle fasi iniziali di sviluppo, i dati e le analisi sono uno strumento utile per valutare l'interazione dei beta tester con il gioco. Esistono alcune analisi che vengono raccolte automaticamente, come i report sulla fidelizzazione, ma è utile aggiungere eventi personalizzati per il tuo gioco specifico.

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

Inoltre, in caso di decesso del giocatore, viene registrato anche un evento che indica la distanza percorsa. In questo modo potremo vedere in che modo le modifiche che apportiamo cambiano la durata di una singola sessione e ci aiuterà a determinare se i giocatori preferiscono una partita più breve/più difficile o più lunga/facile.

Aggiungi intestazioni Analytics

Apri Classes/PopsicleScene.cpp e aggiungi intestazioni Firebase in alto per consentirci di effettuare chiamate per l'analisi.

PopsicleScene.cpp

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

Registra un evento Inizio livello

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

PopsicleScene.cpp

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

Registra un evento di fine livello

Per vedere i risultati di un giocatore, registriamo un evento di fine livello con la distanza percorsa dal giocatore quando è morto. 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 stiamo aggiungendo l'ultima distanza registrata, che è una buona approssimazione della distanza percorsa un giocatore prima di morire.

7. Test degli eventi

Ora puoi fare clic su Debug , ma occorrerà un po' di tempo prima che gli eventi vengano registrati nella dashboard di Analytics. I motivi sono due: 1) gli eventi vengono raggruppati e caricati circa una volta all'ora per risparmiare batteria e 2) i report vengono generati ogni 24 ore.

Esistono meccanismi mediante i quali puoi visualizzare gli eventi più velocemente. Se un evento viene 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 infragiornaliera sarà obsoleta solo di circa 4 ore.

Attivazione della modalità di debug

È comunque possibile eseguire il debug degli eventi di Analytics attivando la modalità di debug sul dispositivo.

Innanzitutto, assicurati di avere installato e configurato Android Debug Bridge (ADB). L'inserimento di adb devices dovrebbe mostrare il dispositivo su cui intendi 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, comunichi a Firebase Analytics di registrare immediatamente gli eventi e li escluderà automaticamente dai normali report per evitare di inquinare gli eventi dal vivo durante i test. Se desideri annullare questa azione in un secondo momento, è sufficiente scrivere:

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

Visualizzazione degli eventi

Apri "DebugView" nella tua console Firebase

Fai clic su Esegui il debug di e inizia a giocare. I nuovi eventi verranno visualizzati quasi immediatamente dopo che si sono verificati nel gioco.

Se espandi l'evento level_end, vedrai anche la "distanza" personalizzata che hai registrato.

Quando l'evento level_end viene inserito nei report sugli eventi, non rileva la distanza per impostazione predefinita. Dovrai selezionare Eventi , individuare level_end, espandere i tre puntini a destra e selezionare Modifica report parametro per aggiungerlo come parametro nei report sugli eventi. Dopodiché, potrai vedere statistiche come i dati dei tuoi giocatori distanza media per gioco.

8. Ricerca tester in corso...

Dovrai poi far attenzione al gioco, a prescindere dal fatto che si tratti di utenti interni al tuo studio, di amici stretti o della community. Firebase App Distribution è un ottimo modo per invitare i giocatori a giocare.

Creazione di un file binario autonomo

Innanzitutto crea un APK autonomo da condividere da Build > Creare bundle/APK > APK di build

Se in precedenza hai modificato il filtro ABI, ricorda di tornare a gradle.properties e modifica PROP_APP_ABI per includere i dispositivi su cui prevedi di eseguire il 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 l'hai ancora fatto, puoi fare clic su "Log eventi". per recuperare il link.

Carica su Firebase App Distribution

1. Apri App Distribution e fai clic su "Inizia"
2. Trascina il file .apk nella casella con il messaggio "Trascina qui un file .apk 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

Anziché 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. Ad esempio, potrai separare i tester interni da quelli esterni.

1. Fai clic su "Tester e "Gruppi"
2. Crea un nuovo gruppo () e assegnagli un nome, ad esempio "Android Testers".
3. Fai clic su "Link di invito"
4. Fai clic su "Nuovo link di invito"
5. Imposta qui il gruppo dal menu a discesa.
6. Fai clic su "Crea link"
7. Fai clic su "Copia link". e condividilo come desideri

9. Complimenti

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

Argomenti trattati

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

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 di Analytics nel tuo gioco.
• Prova ad aggiungere dati e analisi a un gioco per iOS.

Scopri di più

• Consulta l'elenco di eventi specifici dei giochi e considera come possono adattarsi al tuo gioco.