Pierwsze kroki z Firebase w języku C++

1. Przegląd

Z tego laboratorium dowiesz się, jak zintegrować pakiet C++ SDK Firebase Games z przykładową grą na Androida, używając jako przykładu Google Analytics. Będziesz mieć możliwość dodania potrzebnych funkcji, zintegrowania podstawowej logiki analitycznej do pomiaru postępów gracza i udostępnienia gry testerom, aby uzyskać wczesne opinie.

Przewodnik

Jeśli chcesz przejść te ćwiczenia z autorami, obejrzyj ten film:

Czego się nauczysz

• Jak dodać Firebase do gry na Androida opartej na CMake.
• Jak określić, które zależności C++ i Gradle są potrzebne.
• Jak rejestrować zdarzenia Analytics.
• Jak debugować zdarzenia Analytics.
• Jak udostępnić grę za pomocą usługi Rozpowszechnianie aplikacji.

Czego potrzebujesz

• Android Studio
• Przykładowy kod
• Urządzenie testowe lub emulator z Usługami Google Play

2. Pobieranie przykładowego kodu

Pobierz lub sklonuj z GitHub:

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

Pobieranie pakietu Firebase SDK

macOS/Linux:

sh download.sh

Windows (z PowerShell):

./download.ps1

Możesz też ręcznie pobrać pakiet SDK. W takim przypadku pakiet Firebase C++ SDK musi zostać wyodrębniony do katalogu /third_party, tak aby folder o nazwie firebase_cpp_sdk zawierał katalog główny CMakeLists.txt z pakietu Firebase SDK.

3. Uruchamianie przykładowej gry

Najpierw zagraj w przykładową grę i upewnij się, że wszystko działa. To prosta gra typu infinite runner z generowanym proceduralnie poziomem i jednym przyciskiem do skakania.

1. Wybierz Plik > Nowy > Importuj projekt (lub wybierz Importuj projekt na ekranie powitalnym).
2. Otwórz folder proj.android/ w repozytorium.

Jest to projekt Cocos2dx, a nie typowy projekt aplikacji na Androida. Zwykle w katalogu głównym tego repozytorium powinien znajdować się plik build.gradle, ale jest on w katalogu proj.android/, dzięki czemu każdy docelowy system operacyjny może mieć własny, niezależny proces kompilacji.

3. [Opcjonalnie] Otwórz proj.android/gradle.properties i znajdź PROP_APP_ABI. Aby skrócić czas kompilacji, możesz usunąć wszystkie architektury z wyjątkiem docelowej. PROP_APP_ABI=x86 będzie tworzyć tylko na potrzeby emulatora, PROP_APP_ABI=armeabi-v7a będzie tworzyć na potrzeby większości telefonów.
4. Aby skompilować i uruchomić grę, kliknij przycisk Debuguj . Kompilacja silnika gry Cocos2dx zajmie trochę czasu.

Doświadczeni programiści Cocos2dx mogą używać cocos run -p android, jeśli mają zainstalowany interfejs Cocos2dx CLI. Deweloperzy aplikacji na Androida mogą preferować ./gradlew installDebug. W tym samouczku założę, że do programowania, kompilowania i wdrażania używasz Androida Studio.

4. Konfiguracja konsoli Firebase

1. Utwórz nowy projekt w konsoli Firebase.
2. Nadaj mu nazwę, np. „Popsicle Runner”.
3. Włącz Analytics 
4. Dodawanie lub tworzenie konta analitycznego
5. Dodawanie nowej aplikacji na Androida do projektu 
6. Dodaj com.firebase.popsiclerunner jako nazwę pakietu.

W tym ćwiczeniu nie będziesz potrzebować SHA-1.

7. Pobierz plik google-services.json i skopiuj go do folderu proj.android/app .

Wiele usług hostingowych oznaczy plik google-services.json jako „tajny”, jeśli spróbujesz go zatwierdzić, ale w tym pliku nie ma żadnych prawdziwych informacji poufnych (w przypadku wydanej gry odzyskanie zawartości tego pliku jest proste). Jeśli planujesz przesłać go do publicznego repozytorium kodu źródłowego, zachowaj ostrożność – jeśli ten plik zostanie opublikowany publicznie, znalezienie Twoich baz danych lub zasobników Cloud Storage będzie znacznie łatwiejsze, zanim napiszesz silne reguły bezpieczeństwa.

8. Zignoruj podane instrukcje dodawania pakietu SDK Firebase i kliknij Dalej.
9. Gdy pojawi się prośba o zweryfikowanie instalacji, możesz kliknąć „Pomiń ten krok”.

5. Dodawanie Firebase do gry

Dodawanie pakietu SDK Firebase do pliku CMakeLists.txt

Otwórz CMakeLists.txt na poziomie głównym. U góry powinien znajdować się ten kod:

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

i dodaj na końcu tego pliku CMakeLists.txt te wiersze:

CMakeLists.txt

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

add_subdirectory zawiera pakiet Firebase C++ SDK i udostępnia go w tej grze.

target_link_libraries Łączy grę z bibliotekami C++ Firebase przeznaczonymi na Androida.

Z tej tabeli dowiesz się, których bibliotek potrzebujesz do korzystania z poszczególnych funkcji. W ten sposób dowiedziałem się, że firebase_analytics wymaga firebase_app.

Dodawanie wtyczki Usług Google

Aby podłączyć pakiet SDK Firebase, musisz dodać wtyczkę Usług Google do skryptu kompilacji Gradle. Aby to zrobić, otwórz plik project level build.gradle (znajduje się on w folderze proj.android). Dodaj classpath 'com.google.gms:google-services:4.3.3' jako zależność skryptu kompilacji.

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

Następnie dodaj wtyczkę do pliku na poziomie modułu build.gradle (znajduje się on w folderze proj.android/app). Dodaj apply plugin: 'com.google.gms.google-services' pod apply plugin: 'com.android.application':

build.gradle

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

Znajdowanie pakietu SDK C++ w Gradle

Aby poinformować Gradle, gdzie znaleźć pakiet Firebase C++ SDK, dodaj te wiersze na końcu pliku settings.gradle.

settings.gradle

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

Musi on wskazywać tę samą lokalizację co wywołanie add_subdirectory w CMake.

Dodawanie zależności Androida

Aby połączyć zależności Androida z Firebase, otwórz plik Gradle na poziomie modułu dla popsicle_runner (w proj.android/app/build.gradle) i dodaj ten kod tuż przed typową sekcją dependences { na końcu:

build.gradle

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

Każdy pakiet SDK C++ jest tworzony pod kątem konkretnej wersji pakietu SDK Androida. firebaseCpp.dependencies to funkcja ułatwiająca wykrywanie i konfigurowanie niezbędnych zależności Gradle, aby zapewnić zweryfikowaną konfigurację.

AndroidX i Jetifier

Dodaj obsługę AndroidX i Jetifier, otwierając gradle.properties i dodając na końcu ten kod:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Inicjowanie Firebase w grze

Zainicjuj Firebase w grze, otwierając Classes/AppDelegate.cpp. Dodaj na górze te #include dyrektywy:

AppDelegate.cpp

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

Następnie dodaj App::Create i zainicjuj potrzebne funkcje Firebase. Aby to zrobić, znajdź AppDelegate::applicationDidFinishLaunching i dodaj ten kod przed auto scene = MainMenuScene::createScene():

AppDelegate.cpp

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

Wolę używać anonimowego bloku {}, aby ograniczyć zakres instrukcji using, takich jak using namespace firebase;.

Jeśli debugujesz grę i odświeżysz panel Firebase, po minucie lub dwóch powinien pojawić się nowy użytkownik.

6. Dodawanie Analytics

Nawet na wczesnym etapie rozwoju analityka jest przydatnym narzędziem do oceny interakcji beta-testerów z grą. Niektóre dane analityczne są zbierane automatycznie, np. raporty dotyczące utrzymania użytkowników, ale warto dodać zdarzenia niestandardowe dostosowane do konkretnej gry.

Dobrym punktem wyjścia jest rejestrowanie zdarzenia analitycznego, gdy gracz rozpoczyna poziom. Liczba zdarzeń rozpoczęcia poziomu może nam pokazać, jak często gracz powtarza grę w sesji.

Zarejestrujemy też zdarzenie, gdy gracz umrze, wraz z informacją o tym, jak daleko udało mu się zajść. Dzięki temu będziemy mogli sprawdzić, jak wprowadzane przez nas zmiany wpływają na długość pojedynczej sesji, i określić, czy gracze wolą krótszą i trudniejszą rozgrywkę, czy dłuższą i łatwiejszą.

Dodawanie nagłówków Analytics

Otwórz Classes/PopsicleScene.cpp i dodaj u góry nagłówki Firebase, abyśmy mogli wykonywać wywołania Analytics.

PopsicleScene.cpp

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

Rejestrowanie zdarzenia rozpoczęcia poziomu

Aby zarejestrować zdarzenie, gdy ta scena jest przygotowywana przez Cocos2dx Director, znajdź funkcję PopsicleScene::onEnter(). Aby zarejestrować zdarzenie rozpoczęcia poziomu, wpisz ten kod:

PopsicleScene.cpp

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

Rejestrowanie zdarzenia zakończenia poziomu

Aby sprawdzić, jak radzi sobie gracz, zarejestruj zdarzenie Level End (Koniec poziomu) z informacją o tym, jak daleko zaszedł gracz, zanim zginął. Aby to zrobić, znajdź znak PopsicleScene::gameOver() i dodaj go na końcu bloku if(!_gameOver) { przed ustawieniem _gameOver = true;:

PopsicleScene.cpp

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

kEventLevelEnd to zdarzenie zakończenia poziomu. Natomiast "distance" to „parametr zdarzenia”. Dodajemy tutaj ostatni zarejestrowany dystans, który jest dobrym przybliżeniem odległości pokonanej przez gracza przed śmiercią.

7. Testowanie zdarzeń

Możesz teraz kliknąć Debuguj , ale zanim jakiekolwiek zdarzenia zostaną zgłoszone w panelu Analytics, minie trochę czasu. Dzieje się tak z 2 powodów: 1) zdarzenia są przesyłane w pakietach mniej więcej raz na godzinę, aby oszczędzać baterię, oraz 2) raporty są generowane co 24 godziny.

Istnieją mechanizmy, dzięki którym możesz szybciej wyświetlać wydarzenia. Jeśli zdarzenie jest oznaczone jako zdarzenie konwersji, w wielu przypadkach będzie raportowane w czasie zbliżonym do rzeczywistego. Możesz też skonfigurować eksportowanie danych z Google Analytics do BigQuery, gdzie tabela z danymi w ciągu dnia będzie nieaktualna tylko o około 4 godziny.

Włączanie trybu debugowania

Nadal możesz debugować zdarzenia Analytics, przełączając urządzenie w tryb debugowania.

Najpierw upewnij się, że masz zainstalowane i skonfigurowane narzędzie Android Debug Bridge (ADB). Po wpisaniu adb devices powinno się wyświetlić urządzenie, na którym chcesz przeprowadzić test:

$ adb devices
List of devices attached
emulator-5554   device

Następnie uruchom to polecenie adb shell:

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

Dzięki temu Firebase Analytics będzie rejestrować zdarzenia natychmiast i automatycznie wykluczać je z normalnych raportów, aby podczas testowania nie zanieczyszczać zdarzeń na żywo. Jeśli chcesz później cofnąć tę czynność, po prostu napisz:

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

Wyświetlanie zdarzeń

Otwórz „DebugView” w konsoli Firebase.

Kliknij Debuguj  i zagraj w grę. Nowe zdarzenia powinny pojawiać się niemal natychmiast po wystąpieniu w grze.

Jeśli rozwiniesz zdarzenie level_end, zobaczysz też niestandardowy parametr „distance”, który został przez Ciebie zarejestrowany.

Gdy zdarzenie level_end pojawi się w raportach o zdarzeniach, domyślnie nie będzie zawierać informacji o dystansie. Musisz wybrać kolejno Zdarzenia , znaleźć level_end, rozwinąć 3 kropki po prawej stronie  i kliknąć Edytuj raportowanie parametrów, aby dodać go jako parametr w raportach o zdarzeniach. Gdy to zrobisz, zobaczysz statystyki, np. średni dystans pokonywany przez graczy w trakcie rozgrywki.

8. Znajdowanie testerów

Następnie musisz zadbać o to, aby Twoja gra była widoczna dla osób z Twojego studia, bliskich znajomych lub społeczności. Rozpowszechnianie aplikacji przez Firebase to świetny sposób na zapraszanie graczy do gry.

Tworzenie samodzielnego pliku binarnego

Najpierw utwórz samodzielny pakiet APK do udostępnienia, wybierając kolejno Utwórz > Utwórz pakiety / pliki APK > Utwórz pliki APK .

Jeśli wcześniej zmieniono filtr ABI, pamiętaj, aby wrócić do gradle.properties i zmienić PROP_APP_ABI, aby uwzględnić wszystkie urządzenia, na których planujesz przeprowadzić testy:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio wyświetli okno dialogowe, w którym możesz znaleźć skompilowany plik. Jeśli przegapisz ten komunikat, możesz ponownie uzyskać link, klikając „Dziennik zdarzeń”.

Przesyłanie do Rozpowszechniania aplikacji przez Firebase

1. Otwórz Rozpowszechnianie aplikacji i kliknij „Rozpocznij” .
2. Przeciągnij plik APK i upuść go w polu „Przeciągnij tu dowolny plik APK, aby utworzyć nową wersję”.
3. Wpisz swój adres e-mail jako pierwszego testera.
4. Kliknij Dalej.
5. Dodaj opis i kliknij Rozpowszechnij.

Zapraszanie testerów

Zamiast ręcznie wpisywać każdy adres e-mail, możesz utworzyć link z zaproszeniem. Gdy pozyskasz użytkownika za pomocą tego linku z zaproszeniem, możesz też dodać go do grupy testerów. Dzięki temu możesz na przykład oddzielić testerów wewnętrznych od zewnętrznych.

1. Kliknij „Testerzy i grupy” .
2. Utwórz nową grupę  i nadaj jej nazwę, np. „Testerzy Androida”.
3. Kliknij „Linki z zaproszeniem” .
4. Kliknij „Nowy link z zaproszeniem”.
5. Wybierz grupę w menu.
6. Kliknij „Utwórz link”.
7. Kliknij „Kopiuj link” i udostępnij go w dowolny sposób.

9. Gratulacje

Udało Ci się dodać do gry opartej na C++ funkcje analityczne i zaprosić do niej znajomych. Wiesz też, jak znaleźć i połączyć biblioteki Firebase w systemie kompilacji opartym na CMake i Gradle, który jest powszechnie stosowany w przypadku tworzenia aplikacji na Androida.

Omówione zagadnienia

• Jak dodać Firebase do gry na Androida opartej na CMake.
• Jak określić, które zależności C++ i Gradle są potrzebne.
• Jak rejestrować zdarzenia Analytics.
• Jak debugować zdarzenia Analytics.
• Jak udostępnić grę za pomocą usługi Rozpowszechnianie aplikacji.

Następne kroki

• Spróbuj zalogować użytkownika anonimowo i zapisać jego rekord w Bazie danych czasu rzeczywistego.
• Rejestruj zdarzenia Analytics w swojej grze.
• Spróbuj dodać Analytics do gry na iOS.

Więcej informacji

• Zapoznaj się z listą wydarzeń w konkretnych grach i zastanów się, jak możesz je wykorzystać w swojej grze.