Erste Schritte mit Firebase in C++

1. Übersicht

In diesem Codelab erfahren Sie, wie Sie das C++ Firebase Games SDK in ein Android-Beispielspiel einbinden. Als Beispiel wird Google Analytics verwendet. Sie können die benötigten Funktionen hinzufügen, eine grundlegende Analyselogik einbinden, um den Fortschritt der Spieler zu messen, und das Spiel mit Testern teilen, um frühzeitig Feedback zu erhalten.

Schritt-für-Schritt-Anleitung

Wenn Sie dieses Codelab mit den Autoren durchgehen möchten, sehen Sie sich dieses Video an:

Lerninhalte

• So fügen Sie Firebase zu Ihrem Android-Spiel auf CMake-Basis hinzu.
• So ermitteln Sie, welche C++- und Gradle-Abhängigkeiten Sie benötigen.
• So erfassen Sie Analytics-Ereignisse.
• Analyseereignisse debuggen
• So geben Sie Ihr Spiel mit App Distribution frei

Voraussetzungen

• Android Studio
• Der Beispielcode
• Ein Testgerät oder ein Emulator mit Google Play-Diensten

2. Beispielcode abrufen

GitHub:

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

Firebase SDK herunterladen

MacOS/Linux:

sh download.sh

Windows (über PowerShell):

./download.ps1

Sie können das SDK auch manuell herunterladen. In diesem Fall muss das Firebase C++ SDK in /third_party extrahiert werden, sodass ein Ordner mit dem Namen firebase_cpp_sdk den Stamm CMakeLists.txt aus dem Firebase SDK enthält.

3. Beispielspiel ausführen

Spielen Sie zuerst das Beispielspiel und prüfen Sie, ob alles funktioniert. Es ist ein einfacher Infinite Runner mit einem prozedural generierten Level und einer einzigen Taste zum Springen.

1. Wählen Sie „File“ > „New“ > „Import Project“ aus (oder wählen Sie „Import Project“ auf dem Startbildschirm aus).
2. Öffnen Sie den Ordner proj.android/ im Repository.

Es handelt sich um ein Cocos2dx-Projekt und nicht um ein typisches Android-Projekt. Normalerweise sollte sich eine build.gradle-Datei im Stammverzeichnis dieses Repositorys befinden. Sie befindet sich jedoch unter proj.android/, sodass jedes Zielbetriebssystem einen eigenen, in sich geschlossenen Build-Prozess haben kann.

3. [Optional] Öffnen Sie proj.android/gradle.properties und suchen Sie nach PROP_APP_ABI. Sie können alle Architekturen außer der Zielarchitektur entfernen, um die Build-Zeiten zu verkürzen. PROP_APP_ABI=x86 – nur für den Emulator erstellen PROP_APP_ABI=armeabi-v7a – für die meisten Smartphones erstellen
4. Klicken Sie auf die Schaltfläche „Debuggen“ , um das Spiel zu erstellen und auszuführen. Das Erstellen der Cocos2dx-Spiele-Engine dauert einige Zeit.

Erfahrene Cocos2dx-Entwickler können cocos run -p android verwenden, wenn sie die Cocos2dx-Befehlszeile installiert haben. Android-Entwickler bevorzugen möglicherweise ./gradlew installDebug. In dieser Anleitung wird davon ausgegangen, dass Sie Android Studio zum Entwickeln, Erstellen und Bereitstellen verwenden.

4. Firebase Console einrichten

1. Erstellen Sie ein neues Projekt in der Firebase Console.
2. Geben Sie ihm einen Namen wie „Popsicle Runner“.
3. Analytics aktivieren 
4. Analytics-Konto hinzufügen oder erstellen 
5. Neue Android-App zu Ihrem Projekt hinzufügen
6. Fügen Sie com.firebase.popsiclerunner als Paketnamen hinzu.

Für dieses Codelab benötigen Sie keinen SHA‑1-Fingerabdruck.

7. Laden Sie die Datei „google-services.json“ herunter und kopieren Sie sie in proj.android/app .

Viele Source-Hostingdienste kennzeichnen google-services.json als „secrets“, wenn Sie versuchen, die Datei zu committen. Nichts in dieser Datei ist jedoch ein echtes Geheimnis (in einem ausgelieferten Spiel ist es trivial, den Inhalt dieser Datei abzurufen). Sie sollten trotzdem Vorsicht walten lassen, wenn Sie planen, sie in ein öffentliches Quellcode-Repository zu übertragen. Es ist viel einfacher, Ihre Datenbanken oder Cloud Storage-Buckets zu finden, bevor Sie starke Sicherheitsregeln geschrieben haben, wenn diese Datei öffentlich veröffentlicht wird.

8. Ignorieren Sie die Anleitung zum Hinzufügen des Firebase SDK und klicken Sie auf „Weiter“.
9. Wenn Sie aufgefordert werden, die Installation zu bestätigen, können Sie auf „Diesen Schritt überspringen“ klicken.

5. Firebase zu Ihrem Spiel hinzufügen

Firebase SDK zu CMakeLists.txt hinzufügen

Öffnen Sie CMakeLists.txt auf der Stammebene. Dort sollte sich oben der folgende Code befinden:

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

Fügen Sie am Ende der Datei CMakeLists.txt die folgenden Zeilen hinzu:

CMakeLists.txt

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

add_subdirectory enthält das Firebase C++ SDK und stellt es für dieses Spiel zur Verfügung.

target_link_libraries Verbindet das Spiel mit den für Android entwickelten C++-Bibliotheken von Firebase.

In dieser Tabelle finden Sie die Bibliotheken, die Sie für die einzelnen Funktionen benötigen. So habe ich herausgefunden, dass für firebase_analytics firebase_app erforderlich ist.

Google-Dienste-Plug‑in hinzufügen

Um das Firebase SDK einzubinden, müssen Sie Ihrem Gradle-Build-Script das Google-Dienste-Plug-in hinzufügen. Öffnen Sie dazu die Datei build.gradle auf Projektebene (im Ordner proj.android). Fügen Sie classpath 'com.google.gms:google-services:4.3.3' als buildscript-Abhängigkeit hinzu.

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

Fügen Sie das Plug-in dann der Datei build.gradle auf Modulebene hinzu (diese befindet sich im Ordner proj.android/app). Fügen Sie apply plugin: 'com.google.gms.google-services' unter apply plugin: 'com.android.application' hinzu:

build.gradle

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

C++ SDK in Gradle suchen

Damit Gradle weiß, wo das Firebase C++ SDK zu finden ist, fügen Sie der Datei settings.gradle die folgenden Zeilen hinzu.

settings.gradle

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

Dieser muss auf denselben Speicherort verweisen wie der add_subdirectory-Aufruf in CMake.

Android-Abhängigkeiten hinzufügen

Um die Android-Abhängigkeiten für Firebase einzubinden, öffnen Sie die Gradle-Datei auf Modulebene für popsicle_runner (in proj.android/app/build.gradle) und fügen Sie Folgendes direkt vor dem typischen dependences {-Abschnitt am Ende ein:

build.gradle

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

Jedes C++ SDK wird für eine bestimmte Version des Android SDK erstellt. firebaseCpp.dependencies ist eine Hilfsfunktion, mit der die erforderlichen Gradle-Abhängigkeiten ermittelt und konfiguriert werden, damit Sie eine bestätigte Konfiguration haben.

AndroidX und Jetifier

Fügen Sie AndroidX- und Jetifier-Unterstützung hinzu, indem Sie gradle.properties öffnen und Folgendes am Ende einfügen:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Firebase in Ihrem Spiel initialisieren

Initialisieren Sie Firebase im Spiel, indem Sie Classes/AppDelegate.cpp öffnen. Fügen Sie oben die folgenden #include-Anweisungen hinzu:

AppDelegate.cpp

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

Fügen Sie dann App::Create hinzu und initialisieren Sie die benötigten Firebase-Funktionen. Suchen Sie dazu nach AppDelegate::applicationDidFinishLaunching und fügen Sie diesen Code vor auto scene = MainMenuScene::createScene() ein:

AppDelegate.cpp

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

Ich verwende lieber einen anonymen Block {}, um den Bereich von using-Anweisungen wie using namespace firebase; einzuschränken.

Wenn Sie das Spiel debuggen und das Firebase-Dashboard aktualisieren, sollte nach etwa einer Minute ein neuer Nutzer angezeigt werden.

6. Analytics hinzufügen

Auch in der frühen Entwicklungsphase sind Analysen ein nützliches Tool, um zu sehen, wie Betatester mit dem Spiel interagieren. Einige Analysen werden automatisch erfasst, z. B. Berichte zur Kundenbindung. Es ist jedoch sinnvoll, benutzerdefinierte Ereignisse hinzuzufügen, die auf Ihr spezifisches Spiel zugeschnitten sind.

Ein guter Ausgangspunkt ist, ein Analyseereignis zu protokollieren, wenn der Spieler ein Level startet. Anhand der Anzahl der Ereignisse zum Starten eines Levels können wir sehen, wie oft ein Spieler das Spiel in einer Sitzung wiederholt.

Wir protokollieren auch ein Ereignis, wenn der Spieler stirbt, und geben an, wie weit er gekommen ist. So können wir sehen, wie sich Änderungen, die wir vornehmen, auf die Dauer einer einzelnen Sitzung auswirken, und feststellen, ob Spieler ein kürzeres/schwierigeres oder ein längeres/einfacheres Spiel bevorzugen.

Analytics-Header hinzufügen

Öffnen Sie Classes/PopsicleScene.cpp und fügen Sie oben Firebase-Header hinzu, damit wir Analytics-Aufrufe ausführen können.

PopsicleScene.cpp

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

„Level Start“-Ereignis protokollieren

Wenn Sie ein Ereignis protokollieren möchten, wenn diese Szene vom Cocos2dx Director inszeniert wird, suchen Sie nach der Stub-Funktion PopsicleScene::onEnter(). Geben Sie den folgenden Code ein, um das Ereignis „Level Start“ zu protokollieren:

PopsicleScene.cpp

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

Ereignis „Level End“ protokollieren

Um zu sehen, wie gut ein Spieler ist, protokollieren wir ein „Level End“-Ereignis mit der Entfernung, die der Spieler zurückgelegt hat, bevor er gestorben ist. Suchen Sie dazu nach PopsicleScene::gameOver() und fügen Sie es am Ende des if(!_gameOver) {-Blocks ein, bevor Sie _gameOver = true; festlegen:

PopsicleScene.cpp

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

kEventLevelEnd ist das Ereignis zum Ende des Levels. "distance" ist ein „Ereignisparameter“. Wir fügen hier die zuletzt aufgezeichnete Distanz hinzu, die eine gute Annäherung dafür ist, wie weit ein Spieler vor seinem Tod zurückgelegt hat.

7. Ereignisse testen

Sie können jetzt auf „Debuggen“  klicken. Es dauert jedoch eine Weile, bis Ereignisse im Analytics-Dashboard erfasst werden. Dafür gibt es zwei Gründe: 1) Ereignisse werden gebündelt und etwa einmal pro Stunde hochgeladen, um den Akku zu schonen, und 2) Berichte werden alle 24 Stunden generiert.

Es gibt Mechanismen, mit denen Sie Ereignisse schneller aufrufen können. Wenn ein Ereignis als Conversion-Ereignis markiert ist, wird es unter vielen Umständen nahezu in Echtzeit gemeldet. Sie können auch Google Analytics für den Export nach BigQuery konfigurieren. In diesem Fall ist die Tagesabschlusstabelle nur etwa 4 Stunden alt.

Debug-Modus aktivieren

Sie können Analytics-Ereignisse weiterhin debuggen, indem Sie Ihr Gerät in den Debug-Modus versetzen.

Prüfen Sie zuerst, ob die Android Debug Bridge (ADB) installiert und eingerichtet ist. Wenn Sie adb devices eingeben, sollte das Gerät angezeigt werden, auf dem Sie testen möchten:

$ adb devices
List of devices attached
emulator-5554   device

Führen Sie dann den folgenden adb shell-Befehl aus:

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

Dadurch werden Ereignisse sofort in Firebase Analytics protokolliert und automatisch aus Ihren normalen Berichten ausgeschlossen, damit Ihre Live-Ereignisse beim Testen nicht beeinträchtigt werden. Wenn Sie diese Aktion später rückgängig machen möchten, schreiben Sie einfach:

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

Ereignisse ansehen

Öffnen Sie „DebugView“ in der Firebase Console 

Klicken Sie auf „Debuggen“  und spielen Sie das Spiel. Neue Ereignisse sollten fast sofort nach ihrem Eintreten im Spiel angezeigt werden.

Wenn Sie das Ereignis level_end aufrufen, sehen Sie auch den benutzerdefinierten Parameter „distance“, den Sie protokolliert haben.

Wenn das level_end-Ereignis schließlich in Ihren Ereignisberichten angezeigt wird, wird standardmäßig keine Distanz erfasst. Wählen Sie „Ereignisse“  aus, suchen Sie nach level_end, maximieren Sie die drei Punkte auf der rechten Seite  und wählen Sie Parameterberichte bearbeiten aus, um den Parameter in Ihre Ereignisberichte aufzunehmen. Danach können Sie Statistiken wie die durchschnittliche Distanz pro Spiel Ihrer Spieler sehen.

8. Tester finden

Als Nächstes solltest du dein Spiel von anderen testen lassen, egal ob von internen Mitarbeitern, engen Freunden oder Mitgliedern deiner Community. Mit Firebase App Distribution können Sie Spieler ganz einfach einladen, Ihr Spiel zu spielen.

Eigenständiges Binärprogramm erstellen

Erstellen Sie zuerst ein eigenständiges APK, das Sie freigeben können. Gehen Sie dazu zu „Build“ > „Build Bundles(s) / APK(s)“ > „Build APK(s)“ .

Wenn Sie Ihren ABI-Filter zuvor geändert haben, müssen Sie zu gradle.properties zurückkehren und PROP_APP_ABI so ändern, dass alle Geräte, auf denen Sie Tests durchführen möchten, berücksichtigt werden:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

In Android Studio wird ein Dialogfeld angezeigt, in dem Sie die erstellte Datei suchen können. Wenn Sie ihn verpassen, können Sie im „Ereignisprotokoll“ noch einmal auf den Link klicken.

In Firebase App Distribution hochladen

1. Öffnen Sie App Distribution und klicken Sie auf „Get Started“ (Jetzt starten) .
2. Ziehen Sie Ihre APK-Datei in das Feld mit der Aufschrift „.apk-Dateien hierher ziehen, um einen neuen Release zu erstellen“. 
3. Geben Sie Ihre E‑Mail-Adresse als ersten Tester ein.
4. Klicken Sie auf „Weiter“.
5. Fügen Sie eine Beschreibung hinzu und klicken Sie auf „Verteilen“.

Tester einladen

Anstatt jede E‑Mail-Adresse manuell eingeben zu müssen, können Sie einen Einladungslink erstellen. Wenn Sie einen Nutzer mit diesem Einladungslink erfassen, können Sie ihn auch einer Gruppe von Testern hinzufügen. So können Sie beispielsweise interne von externen Testern trennen.

1. Klicken Sie auf „Tester & Gruppen“ .
2. Erstellen Sie eine neue Gruppe  und geben Sie ihr einen Namen wie „Android-Tester“.
3. Klicken Sie auf „Einladungslinks“ .
4. Klicken Sie auf „Neuer Einladungslink“.
5. Legen Sie die Gruppe hier im Drop-down-Menü fest.
6. Klicken Sie auf „Link erstellen“.
7. Klicken Sie auf „Link kopieren“ und teilen Sie ihn nach Belieben.

9. Glückwunsch

Sie haben Ihrem C++-basierten Spiel erfolgreich Analysen hinzugefügt, einige Freunde zum Spielen eingeladen und wissen, wie Sie Firebase-Bibliotheken in einem CMake- und Gradle-basierten Build-System finden und verknüpfen, das in der Android-Entwicklung üblich ist.

Behandelte Themen

• So fügen Sie Firebase zu Ihrem Android-Spiel auf CMake-Basis hinzu.
• So ermitteln Sie, welche C++- und Gradle-Abhängigkeiten Sie benötigen.
• So erfassen Sie Analytics-Ereignisse.
• Analyseereignisse debuggen
• So geben Sie Ihr Spiel mit App Distribution frei

Nächste Schritte

• Versuchen Sie, einen Nutzer anonym anzumelden und seinen Highscore in Realtime Database zu speichern.
• Analytics-Ereignisse in Ihrem eigenen Spiel erfassen
• Fügen Sie einem iOS-Spiel Analysen hinzu.

Weitere Informationen

• Liste der spielspezifischen Ereignisse