Erste Schritte mit Firebase in C++

1. Übersicht

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

Schritt-für-Schritt-Anleitung

Wenn du dieses Codelab mit den Autoren durchgehen möchtest, sieh dir dieses Video an:

Lerninhalte

• So fügen Sie Firebase zu Ihrem auf Android CMake basierenden Spiel hinzu.
• So finden Sie heraus, welche C++- und Gradle-Abhängigkeiten Sie benötigen.
• Analytics-Ereignisse protokollieren.
• Fehlerbehebung bei Analyseereignissen
• So geben Sie Ihr Spiel über die App-Bereitstellung frei.

Voraussetzungen

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

2. Beispielcode abrufen

Zur Kasse oder zum Download von 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. Testspiel ausführen

Spielen Sie zuerst das Beispielspiel und vergewissern Sie sich, dass alles funktioniert. Es ist ein einfacher Infinite Runner mit einem Level, das prozediv generiert wird, und einer einzigen Taste, über die man springen kann.

1. Wählen Sie Datei > Neu > Projekt importieren (oder „Projekt importieren“ auf dem Begrüßungsbildschirm auswählen)
2. Öffnen Sie den Ordner proj.android/ im Repository.

Dies ist ein Cocos2dx-Projekt und kein typisches Android-Projekt. Normalerweise würde man erwarten, eine build.gradle-Datei im Stammverzeichnis dieses Repositorys zu sehen. Sie befindet sich jedoch unter proj.android/, sodass jedes Zielbetriebssystem einen eigenen eigenständigen Build-Prozess haben kann.

3. [Optional] proj.android/gradle.properties öffnen und in Ordnung PROP_APP_ABI. Sie können alle bis auf die Zielarchitektur entfernen, um die Build-Zeiten zu verkürzen. PROP_APP_ABI=x86 wird nur für den Emulator erstellt PROP_APP_ABI=armeabi-v7a wird für die meisten Smartphones erstellt
4. Klicken Sie auf die Schaltfläche „Fehlerbehebung“ , um das Spiel zu erstellen und auszuführen. Es wird einige Zeit dauern, die Cocos2dx-Spiel-Engine zu entwickeln.

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 nehme ich an, dass Sie Android Studio zum Entwickeln, Erstellen und Bereitstellen verwenden.

4. Firebase Console-Einrichtung

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

Für dieses Codelab ist kein SHA-1 erforderlich

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

Viele Quell-Hostingdienste kennzeichnen google-services.json als „secrets“ Wenn Sie versuchen, einen Commit durchzuführen, aber nichts in dieser Datei ist ein echtes Geheimnis (in einem Versandspiel ist es einfach, den Inhalt dieser Datei abzurufen). Sie sollten dennoch vorsichtig sein, wenn Sie planen, die Datei mit einem öffentlichen Quellcode-Repository zu speichern. Ihre Datenbanken oder Cloud Storage-Buckets lassen sich viel leichter finden, bevor Sie strenge Sicherheitsregeln schreiben, wenn diese Datei veröffentlicht wird.

8. Ignorieren Sie die Anleitung zum Hinzufügen des Firebase SDK und klicken Sie auf „Weiter“.
9. Sie können auf „Diesen Schritt überspringen“ klicken. wenn Sie aufgefordert werden, Ihre Installation zu überprüfen

5. Firebase zum Spiel hinzufügen

Firebase SDK zu CMakeLists.txt hinzufügen

Öffnen Sie die Stammebene CMakeLists.txt. Dies sollte am Anfang den folgenden Code enthalten:

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

und 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 Fesseln Sie das Spiel mit den für Android entwickelten C++-Bibliotheken von Firebase.

Verwenden Sie diese Tabelle, um herauszufinden, welche Bibliotheken Sie für die einzelnen Funktionen benötigen, die Sie verwenden möchten. So wusste ich, dass für firebase_analytics firebase_app erforderlich ist.

Google Services-Plug-in hinzufügen

Um das Firebase SDK zu verknüpfen, müssen Sie das Google Services-Plug-in zu Ihrem Gradle-Build-Skript hinzufügen. Öffnen Sie dazu die Datei build.gradle auf Projektebene . Sie befindet sich 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' unterhalb von 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

Fügen Sie am Ende der Datei settings.gradle die folgenden Zeilen hinzu, um Gradle mitzuteilen, wo das Firebase C++ SDK zu finden ist.

settings.gradle

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

Er 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 zu verknüpfen, ö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 hinzu:

build.gradle

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

Jedes C++ SDK basiert auf einer bestimmten Version des Android SDK. firebaseCpp.dependencies ist eine praktische Funktion, die die erforderlichen Gradle-Abhängigkeiten erkennt und konfiguriert, um sicherzustellen, dass Sie eine bestätigte Konfiguration haben.

AndroidX und Jetifier

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

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Firebase in Ihrem Spiel initialisieren

Initialisiere Firebase im Spiel, indem du Classes/AppDelegate.cpp öffnest. 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 erforderlichen 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 die anonyme Blockierung {}, um den Umfang von using-Anweisungen wie using namespace firebase; einzuschränken.

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

6. Analytics hinzufügen

Schon zu Beginn der Entwicklung sind Analysen ein nützliches Tool, um festzustellen, wie Betatester mit dem Spiel interagieren. Einige Analysen werden automatisch erfasst, z. B. Berichte zur Nutzerbindung, aber es ist hilfreich, benutzerdefinierte Ereignisse hinzuzufügen, die auf Ihr Spiel zugeschnitten sind.

Ein guter Ausgangspunkt ist das Protokollieren eines Analytics-Ereignisses, wenn der Spieler ein Level startet. Wir können die Anzahl der Level-Startereignisse verwenden, um zu sehen, wie oft ein Spieler das Spiel in einer Sitzung wiederholen könnte.

Außerdem wird ein Ereignis protokolliert, wenn der Spieler stirbt. Dabei wird auch angegeben, wie weit er gekommen ist. So können wir sehen, wie unsere Änderungen die Dauer einer einzelnen Sitzung verändern und ob die Spieler ein kürzeres/schwereres Spiel 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>

Ereignis „Level Start“ protokollieren

Um ein Ereignis zu protokollieren, wenn diese Szene vom Cocos2dx Director bereitgestellt wird, suchen Sie die gekürzte Funktion PopsicleScene::onEnter(). Gib den folgenden Code ein, um das Level-Startereignis hier zu protokollieren:

PopsicleScene.cpp

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

Ereignis „Level End“ protokollieren

Um zu sehen, wie gut ein Spieler abschneidet, lass uns ein Level-End-Ereignis protokollieren, in dem angegeben wird, wie weit der Spieler nach dem Tod gekommen ist. Suchen Sie dazu nach PopsicleScene::gameOver() und fügen Sie Folgendes am Ende des Blocks if(!_gameOver) { ein, bevor Sie _gameOver = true; festlegen:

PopsicleScene.cpp

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

kEventLevelEnd ist das Endereignis des Levels. "distance" ist hingegen ein „Ereignisparameter“. Wir fügen hier die letzte aufgezeichnete Strecke hinzu. Sie ist ein guter Anhaltspunkt dafür, wie weit ein Spieler vor seinem Tod zurückgelegt hat.

7. Testereignisse

Sie können jetzt auf „Fehler beheben“ klicken. Es dauert jedoch einige Zeit, bis Ereignisse im Analytics-Dashboard erfasst werden. Dafür gibt es zwei Gründe: 1) Ereignisse werden in Batches zusammengefasst und einmal pro Stunde hochgeladen, um den Akku zu schonen, und 2) Berichte werden alle 24 Stunden erstellt.

Es gibt Mechanismen, mit denen Sie Ereignisse schneller anzeigen können. Wenn ein Ereignis als Conversion-Ereignis gekennzeichnet ist, wird es unter vielen Umständen nahezu in Echtzeit erfasst. Sie können Google Analytics auch für den Export nach BigQuery konfigurieren, wobei die Tabelle mit dem Tagesverlauf nur etwa vier Stunden veraltet ist.

Debug-Modus aktivieren

Sie können Analytics-Ereignisse weiterhin debuggen, indem Sie das Gerät in den Fehlerbehebungsmodus versetzen.

Prüfen Sie zuerst, ob Sie Android Debug Bridge (ADB) installiert und eingerichtet haben. Wenn Sie adb devices eingeben, sollte das Gerät angezeigt werden, das 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 in Firebase Analytics sofort protokolliert und automatisch aus Ihren normalen Berichten ausgeschlossen, um Ihre Live-Ereignisse beim Testen nicht zu verschmutzen. 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

DebugView öffnen in der Firebase Console

Klicken Sie auf „Fehler beheben“ und spielen Sie das Spiel. Neue Ereignisse sollten fast unmittelbar nach ihrem Auftreten im Spiel angezeigt werden.

Wenn Sie das Ereignis level_end maximieren, sehen Sie auch die benutzerdefinierte „Entfernung“. Parameter, den Sie protokolliert haben.

Sobald das level_end-Ereignis in Ihren Ereignisberichten aufgeführt wird, wird standardmäßig keine Entfernung erfasst. Wählen Sie „Ereignisse“ aus, suchen Sie nach level_end, maximieren Sie rechts das Dreipunkt-Menü und wählen Sie „Parameterbericht bearbeiten“ aus, um den Parameter in Ihre Ereignisberichte einzufügen. Danach sehen Sie Statistiken, z. B. die durchschnittliche Distanz pro Spiel.

8. Tester finden

Als Nächstes solltest du die Zuschauer auf dein Spiel aufmerksam machen – unabhängig davon, ob es innerhalb deines Studios, bei engen Freunden oder aus deiner Community ist. Mit Firebase App Distribution können Sie Spieler ganz einfach zu Ihrem Spiel einladen.

Eigenständige Binärdatei erstellen

Erstelle zuerst ein eigenständiges APK, das du über „Build“ teilen kannst > Build-Bundles/APKs > Build-APK(s)

Wenn Sie Ihren ABI-Filter zuvor geändert haben, denken Sie daran, zu gradle.properties zurückzukehren und PROP_APP_ABI so zu ändern, dass alle Geräte eingeschlossen sind, auf denen Sie testen möchten:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

In Android Studio wird ein Dialogfeld geöffnet, in dem Sie die erstellte Datei finden können. Wenn du es verpasst, kannst du auf „Ereignisprotokoll“ klicken um den Link wieder abzurufen.

In Firebase App Distribution hochladen

1. Öffnen Sie die App-Bereitstellung und klicken Sie auf „Jetzt starten“.
2. Ziehen Sie Ihre APK-Datei in das Feld mit dem Text "Ziehen Sie eine APK-Datei hierher, um einen neuen Release zu erstellen".
3. Geben Sie als ersten Tester Ihre E-Mail-Adresse ein.
4. Klicken Sie auf "Weiter".
5. Füge eine Beschreibung hinzu und klicke 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 aufnehmen, können Sie ihn auch einer Testergruppe hinzufügen. So können Sie beispielsweise interne von externen Testern trennen.

1. Klicken Sie auf „Tester und Gruppen“
2. Erstelle eine neue Gruppe namens „“ und gib ihr einen Namen, z. B. „Android Testers“.
3. Klicken Sie auf „Einladungslinks“.
4. Klicke 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 ganz 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 auf Android CMake basierenden Spiel hinzu.
• So finden Sie heraus, welche C++- und Gradle-Abhängigkeiten Sie benötigen.
• Analytics-Ereignisse protokollieren.
• Fehlerbehebung bei Analyseereignissen
• So geben Sie Ihr Spiel über die App-Bereitstellung frei.

Nächste Schritte

• Versuchen Sie, einen Nutzer anonym anzumelden und seinen Highscore in Realtime Database zu speichern.
• Log Analytics-Ereignisse in Ihrem eigenen Spiel.
• Versuchen Sie, einem iOS Analysefunktionen hinzuzufügen.

Weitere Informationen

• Sehen Sie sich die Liste spielspezifischer Ereignisse an und überlegen Sie, wie Sie sie in Ihr Spiel einbinden können.