Начните работу с Firebase на C++

1. Обзор

В этом практическом занятии вы научитесь интегрировать SDK Firebase Games на C++ в пример игры для Android, используя Google Analytics в качестве образца. Вы сможете добавить необходимые функции, интегрировать базовую логику аналитики для измерения прогресса игрока и поделиться игрой с тестировщиками, чтобы получить предварительную обратную связь.

Пошаговое руководство

Если вы хотите пройти этот практический урок вместе с авторами, посмотрите это видео:

Что вы узнаете

• Как добавить Firebase в вашу игру для Android, созданную с помощью CMake.
• Как определить, какие зависимости C++ и Gradle вам необходимы.
• Как регистрировать события Analytics.
• Как отлаживать события аналитики.
• Как поделиться своей игрой с помощью сервиса распространения приложений.

Что вам понадобится

• Android Studio
• Пример кода
• Тестовое устройство или эмулятор с поддержкой Google Play Services

2. Получите пример кода.

Загрузите или скачайте с GitHub :

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

Загрузите Firebase SDK

MacOS/Linux:

sh download.sh

Windows (из PowerShell):

./download.ps1

Вы также можете загрузить SDK вручную . В этом случае Firebase C++ SDK необходимо распаковать в папку /third_party таким образом, чтобы папка с именем firebase_cpp_sdk содержала корневой файл CMakeLists.txt из Firebase SDK.

3. Запустите тестовую игру.

Для начала, сыграйте в тестовую игру и убедитесь, что всё работает. Это простой бесконечный раннер с процедурно сгенерированным уровнем и одной кнопкой для прыжка.

1. Выберите Файл > Создать > Импортировать проект (или выберите Импортировать проект на экране загрузки).
2. Откройте папку proj.android/ , входящую в состав репозитория.

Это проект Cocos2dx, а не типичный проект Android. Обычно в корне этого репозитория находится файл build.gradle , но он расположен в proj.android/ , поэтому для каждой целевой операционной системы может быть свой собственный автономный процесс сборки.

3. [Необязательно] Откройте proj.android/gradle.properties и найдите параметр PROP_APP_ABI . Вы можете удалить все параметры, кроме целевой архитектуры, чтобы сократить время сборки. PROP_APP_ABI=x86 обеспечит сборку только для эмулятора, PROP_APP_ABI=armeabi-v7a для большинства телефонов.
4. Нажмите кнопку «Отладка». Для создания и запуска игры потребуется время. Разработка игрового движка Cocos2dx займет некоторое время.

Опытные разработчики Cocos2dx могут использовать команду cocos run -p android если у них установлен CLI Cocos2dx . Разработчики Android могут предпочесть ./gradlew installDebug . В этом руководстве я буду предполагать, что вы используете Android Studio для разработки, сборки и развертывания.

4. Настройка консоли Firebase

1. Создайте новый проект в консоли Firebase .
2. Дайте ему название, например, "Бегун на мороженом".
3. Включить аналитику
4. Добавить или создать учетную запись аналитики
5. Добавьте новое Android-приложение в свой проект.
6. Добавьте com.firebase.popsiclerunner в качестве имени пакета.

Для выполнения этого практического задания вам не понадобится SHA-1.

7. Скачайте файл google-services.json и скопируйте его в папку proj.android/app

Многие сервисы, предоставляющие хостинг исходного кода, пометят файл google-services.json как «секретный», если вы попытаетесь его добавить в репозиторий, но на самом деле в этом файле нет ничего секретного (в сфере разработки программного обеспечения получить содержимое этого файла не составляет труда). Тем не менее, следует проявлять осторожность, если вы планируете добавить его в общедоступный репозиторий исходного кода — ваши базы данных или облачные хранилища будет гораздо проще найти до того, как вы разработаете надежные правила безопасности, если этот файл будет опубликован публично.

8. Проигнорируйте приведенные инструкции по добавлению Firebase SDK и нажмите «Далее».
9. При проверке установки вы можете нажать кнопку «Пропустить этот шаг».

5. Добавьте Firebase в свою игру.

Добавьте SDK Firebase в файл CMakeLists.txt.

Откройте корневой файл CMakeLists.txt . В самом начале должен быть следующий код.

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

и добавьте следующие строки в конец файла 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 включает в себя Firebase C++ SDK и делает его доступным для этой игры.

target_link_libraries Подключает игру к библиотекам C++ от Firebase, разработанным для Android.

Используйте эту таблицу , чтобы определить, какие библиотеки вам нужны для каждой функции, которую вы хотите использовать. Вот как я узнал, что firebase_analytics требует firebase_app .

Добавьте плагин Google Services.

Для подключения Firebase SDK необходимо добавить плагин Google Services в скрипт сборки Gradle. Для этого откройте файл build.gradle на уровне проекта (он находится в папке proj.android ) и добавьте classpath 'com.google.gms:google-services:4.3.3' в качестве зависимости скрипта сборки.

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

Затем добавьте плагин в файл build.gradle вашего модуля (он находится в папке proj.android/app ). Добавьте apply plugin: 'com.google.gms.google-services' под строкой apply plugin: 'com.android.application' .

build.gradle

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

Найдите C++ SDK в Gradle.

Чтобы указать Gradle, где найти Firebase C++ SDK, добавьте следующие строки в конец файла settings.gradle .

settings.gradle

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

Это должно указывать на то же местоположение, что и вызов add_subdirectory в CMake.

Добавьте зависимости Android.

Чтобы подключить зависимости Android к Firebase, откройте файл gradle модуля popsicle_runner (в proj.android/app/build.gradle ) и добавьте следующее непосредственно перед стандартным разделом dependences { в конце:

build.gradle

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

Каждый C++ SDK собирается для конкретной версии Android SDK. firebaseCpp.dependencies — это удобная функция, которая обнаруживает и настраивает необходимые зависимости Gradle, чтобы обеспечить проверенную конфигурацию.

AndroidX и Jetifier

Добавьте поддержку AndroidX и Jetifier, открыв файл gradle.properties и добавив в конец следующую строку:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Инициализируйте Firebase в вашей игре.

Для инициализации Firebase в игре откройте файл Classes/AppDelegate.cpp . Добавьте в начало следующие директивы #include :

AppDelegate.cpp

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

Затем добавьте App::Create и инициализируйте необходимые функции Firebase. Для этого найдите AppDelegate::applicationDidFinishLaunching и добавьте этот код перед auto scene = MainMenuScene::createScene() :

AppDelegate.cpp

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

Я предпочитаю использовать анонимный блок {} для ограничения области действия операторов using , таких как using namespace firebase; .

Если вы отладите игру и обновите панель управления Firebase, то примерно через минуту должен появиться один новый пользователь.

6. Добавьте аналитику.

Даже на ранних этапах разработки аналитика является полезным инструментом для оценки того, как бета-тестеры взаимодействуют с игрой. Некоторые аналитические данные собираются автоматически — например, отчеты об удержании пользователей, — но полезно добавлять пользовательские события, адаптированные для вашей конкретной игры.

Хорошей отправной точкой является регистрация события аналитики, когда игрок начинает уровень. Мы можем использовать количество событий начала уровня, чтобы увидеть, как часто игрок может переигрывать игру в течение одной сессии.

Мы также будем регистрировать событие смерти игрока с указанием пройденного им расстояния. Это позволит нам увидеть, как внесенные нами изменения влияют на продолжительность одной игровой сессии, и поможет определить, хотят ли игроки более короткую/сложную игру или более длинную/легкую.

Добавить заголовки аналитики

Откройте Classes/PopsicleScene.cpp и добавьте в начало заголовочные файлы Firebase, чтобы мы могли выполнять запросы к аналитическим инструментам.

PopsicleScene.cpp

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

Зарегистрируйте событие «Начало уровня».

Чтобы зарегистрировать событие при создании этой сцены с помощью Cocos2dx Director, найдите заглушенную функцию PopsicleScene::onEnter() . Введите следующий код для регистрации события «Начало уровня»:

PopsicleScene.cpp

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

Зарегистрировать событие "Завершение уровня"

Чтобы оценить успехи игрока, давайте запишем в лог событие "Завершение уровня", в котором будет указано, как далеко игрок продвинулся до своей смерти. Для этого найдите PopsicleScene::gameOver() и добавьте следующий код в конец блока if(!_gameOver) { перед установкой _gameOver = true; :

PopsicleScene.cpp

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

kEventLevelEnd — это событие завершения уровня. А "distance" — это "параметр события". Здесь мы добавляем последнее зарегистрированное расстояние, которое является хорошим приближением к тому, какое расстояние игрок прошёл до своей смерти.

7. Тестовые события

Вы можете нажать кнопку «Отладка». Сейчас это возможно, но для отображения событий на панели аналитики потребуется время. Этому есть две причины: 1) события группируются и загружаются примерно раз в час для экономии заряда батареи, и 2) отчеты генерируются каждые 24 часа.

Существуют механизмы, позволяющие быстрее просматривать события. Если событие помечено как событие конверсии , оно будет отображаться практически в режиме реального времени во многих случаях. Вы также можете настроить Google Analytics на экспорт данных в BigQuery , где внутридневная таблица будет устаревать всего примерно на 4 часа.

Включение режима отладки

Отладка событий Analytics по-прежнему возможна, если перевести устройство в режим отладки.

Для начала убедитесь, что у вас установлен и настроен Android Debug Bridge (ADB) . Введя команду adb devices вы должны увидеть устройство, на котором будете проводить тестирование:

$ adb devices
List of devices attached
emulator-5554   device

Затем выполните следующую команду adb shell :

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

Это указывает Firebase Analytics немедленно регистрировать события и автоматически исключать их из ваших обычных отчетов, чтобы избежать загрязнения данных в реальных отчетах при тестировании. Если вы захотите отменить это действие позже, просто напишите:

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

Просмотр событий

Откройте окно отладки (DebugView) в консоли Firebase.

Нажмите «Отладка» и начните играть. Вы должны увидеть, как новые события появляются почти сразу после того, как они происходят в игре.

Если вы развернете событие level_end , вы также увидите пользовательский параметр "distance", который вы зарегистрировали.

Когда событие level_end наконец-то появится в ваших отчетах о событиях, оно по умолчанию не будет учитывать расстояние. Вам потребуется выбрать раздел «События». Найдите level_end и разверните три точки справа. и выберите Отредактируйте отчеты по параметрам, чтобы добавить этот параметр в отчеты о событиях. После этого вы сможете просматривать статистику, например, среднее расстояние, пройденное игроками за игру.

8. Поиск тестировщиков

Далее вам нужно будет привлечь внимание к вашей игре, будь то внутри вашей студии, среди близких друзей или в вашем сообществе. Firebase App Distribution предоставляет отличный способ пригласить игроков в вашу игру.

Создание автономного исполняемого файла

Сначала соберите автономный APK-файл для обмена, выбрав Build > Build Bundles / APK(s) > Build APK(s).

Если вы ранее изменяли фильтр ABI, не забудьте вернуться к gradle.properties и изменить PROP_APP_ABI , чтобы он включал все устройства, на которых вы планируете проводить тестирование:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

В Android Studio появится диалоговое окно, позволяющее найти скомпилированный файл. Если вы его пропустили, вы можете нажать на «Журнал событий», чтобы снова получить ссылку.

Загрузите приложение в Firebase App Distribution.

1. Откройте приложение «Распространение приложений» и нажмите «Начать».
2. Перетащите свой файл .apk в поле с надписью «Перетащите любой файл .apk сюда, чтобы создать новый релиз».
3. Введите свой адрес электронной почты в качестве первого участника тестирования.
4. Нажмите «Далее».
5. Добавьте описание и нажмите «Распространить».

Пригласить тестировщиков

Вместо того чтобы вручную вводить каждый адрес электронной почты, вы можете создать ссылку-приглашение. Получив пользователя по этой ссылке, вы также можете добавить его в группу тестировщиков. Это позволит, например, разделить внутренних и внешних тестировщиков.

1. Нажмите «Тестировщики и группы».
2. Создать новую группу и дайте ему название, например, "Тестировщики Android".
3. Нажмите «Пригласить ссылки»
4. Нажмите «Создать новую ссылку-приглашение»
5. Выберите группу из выпадающего списка.
6. Нажмите «Создать ссылку».
7. Нажмите «Скопировать ссылку» и поделитесь ею любым удобным для вас способом.

9. Поздравляем!

Вы успешно добавили аналитику в свою игру на C++, пригласили друзей поиграть и знаете, как найти и подключить библиотеки Firebase в системах сборки на основе CMake и Gradle, распространенных в разработке под Android.

Что мы рассмотрели

• Как добавить Firebase в вашу игру для Android, созданную с помощью CMake.
• Как определить, какие зависимости C++ и Gradle вам необходимы.
• Как регистрировать события Analytics.
• Как отлаживать события аналитики.
• Как поделиться своей игрой с помощью сервиса распространения приложений.

Следующие шаги

• Попробуйте войти в систему анонимно и сохранить его лучший результат в базе данных Realtime Database.
• Записывайте события Log Analytics в своей игре.
• Попробуйте добавить аналитику в игру для iOS .

Узнать больше

• Ознакомьтесь со списком событий, специфичных для каждой игры , и подумайте, как они могут вписаться в вашу собственную игру.