Comienza a usar Firebase en C++

1. Descripción general

En este codelab, aprenderás a integrar el SDK de Firebase Games en C++ en un juego de Android de ejemplo usando Google Analytics como ejemplo. Podrás agregar las funciones que necesites, integrar cierta lógica de análisis básica para medir el progreso de los jugadores y compartir el juego con los verificadores para obtener comentarios anticipados.

Explicación

Si quieres realizar este codelab con los autores, mira este video:

Qué aprenderás

• Cómo agregar Firebase a tu juego basado en CMake para Android
• Cómo determinar qué dependencias de C++ y Gradle necesitas
• Cómo registrar eventos de Analytics
• Cómo depurar eventos de Analytics
• Cómo compartir tu juego con App Distribution

Requisitos

• Android Studio
• El código de muestra
• Un dispositivo de prueba o emulador con los Servicios de Google Play

2. Obtén el código de muestra

Descarga o extrae de GitHub:

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

Descarga el SDK de Firebase

macOS/Linux:

sh download.sh

Windows (desde PowerShell):

./download.ps1

También puedes descargar el SDK de forma manual. Si lo haces, el SDK de Firebase C++ se debe extraer en /third_party de modo que una carpeta llamada firebase_cpp_sdk tenga la raíz CMakeLists.txt del SDK de Firebase.

3. Ejecuta el juego de ejemplo

Primero, juega el juego de ejemplo y asegúrate de que todo funcione. Es un juego de corredor infinito simple con un nivel generado de forma procedimental y un solo botón para saltar.

1. Selecciona File > New > Import Project (o selecciona Import Project en la pantalla de presentación).
2. Abre la carpeta proj.android/ incluida en el repositorio.

Este es un proyecto de Cocos2dx, no un proyecto típico de Android. Normalmente, esperarías ver un archivo build.gradle en la raíz de este repositorio, pero se encuentra en proj.android/ para que cada sistema operativo de destino pueda tener su propio proceso de compilación autónomo.

3. [Opcional] Abre proj.android/gradle.properties y ajusta PROP_APP_ABI. Puedes quitar todas las arquitecturas, excepto la de destino, para reducir los tiempos de compilación. PROP_APP_ABI=x86 se compilará solo para el emulador PROP_APP_ABI=armeabi-v7a se compilará para la mayoría de los teléfonos
4. Haz clic en el botón Debug para compilar y ejecutar el juego. La compilación del motor de juegos de Cocos2dx llevará tiempo.

Los desarrolladores experimentados de Cocos2dx pueden optar por usar cocos run -p android si tienen instalada la CLI de Cocos2dx. Los desarrolladores de Android pueden preferir ./gradlew installDebug. En este instructivo, se da por sentado que usas Android Studio para desarrollar, compilar y realizar la implementación.

4. Configuración de Firebase console

1. Crea un proyecto nuevo en la consola de Firebase.
2. Asigna un nombre, como "Popsicle Runner".
3. Habilita Analytics
4. Agrega o crea una cuenta de Analytics
5. Agrega una nueva app para Android a tu proyecto
6. Agrega com.firebase.popsiclerunner como nombre del paquete.

No necesitarás un SHA-1 para este codelab.

7. Descarga el archivo google-services.json y cópialo en proj.android/app .

Muchos servicios de hosting de código fuente marcarán google-services.json como "secretos" si intentas confirmarlo, pero nada en este archivo es un secreto real (en un juego de lanzamiento, es trivial recuperar el contenido de este archivo). Sin embargo, debes tener precaución si planeas confirmarlo en un repositorio de código fuente público, ya que será mucho más fácil encontrar tus bases de datos o buckets de Cloud Storage antes de que escribas reglas de seguridad sólidas si este archivo se publica de forma pública.

8. Ignora las instrucciones proporcionadas para agregar el SDK de Firebase y haz clic en Siguiente.
9. Puedes hacer clic en "Omitir este paso" cuando se te solicite que verifiques la instalación.

5. Agrega Firebase a tu juego

Agrega el SDK de Firebase a CMakeLists.txt

Abre CMakeLists.txt a nivel de la raíz. Debería tener el siguiente código cerca de la parte superior:

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

y agrega las siguientes líneas al final de ese archivo 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 incluye el SDK de Firebase C++ y lo pone a disposición de este juego

target_link_libraries Vincula el juego con las bibliotecas de C++ de Firebase creadas para Android.

Usa esta tabla para determinar qué bibliotecas necesitas para cada función que quieras usar. Así supe que firebase_analytics requiere firebase_app.

Agrega el complemento de Google Services

Para conectar el SDK de Firebase, debes agregar el complemento de Google Services a tu secuencia de comandos de compilación de Gradle. Para ello, abre el archivo build.gradle del nivel del proyecto (se encuentra en la carpeta proj.android). Además, agrega classpath 'com.google.gms:google-services:4.3.3' como dependencia de 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
    }
}

Luego, agrega el complemento al archivo build.gradle a nivel del módulo (que se encuentra en la carpeta proj.android/app). Agrega apply plugin: 'com.google.gms.google-services' debajo de apply plugin: 'com.android.application':

build.gradle

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

Cómo encontrar el SDK de C++ en Gradle

Para indicarle a Gradle dónde encontrar el SDK de Firebase C++, agrega las siguientes líneas en la parte inferior del archivo settings.gradle.

settings.gradle

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

Debe apuntar a la misma ubicación que la llamada add_subdirectory en CMake.

Agrega las dependencias de Android

Para conectar las dependencias de Android para Firebase, abre el archivo Gradle a nivel del módulo para popsicle_runner (en proj.android/app/build.gradle) y agrega lo siguiente justo antes de la sección dependences { típica al final:

build.gradle

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

Cada SDK de C++ se compila en función de una versión específica del SDK de Android. firebaseCpp.dependencies es una función de conveniencia que descubrirá y configurará las dependencias de Gradle necesarias para garantizar que tengas una configuración verificada.

AndroidX y Jetifier

Para agregar compatibilidad con AndroidX y Jetifier, abre gradle.properties y agrega lo siguiente al final:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Inicializa Firebase en tu juego

Para inicializar Firebase en el juego, abre Classes/AppDelegate.cpp. Agrega las siguientes directivas #include en la parte superior:

AppDelegate.cpp

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

Luego, agrega App::Create y, luego, inicializa las funciones de Firebase que necesites. Para ello, busca AppDelegate::applicationDidFinishLaunching y agrega este código antes de auto scene = MainMenuScene::createScene():

AppDelegate.cpp

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

Prefiero usar un bloque anónimo {} para restringir el alcance de las instrucciones using, como using namespace firebase;.

Si depuras el juego y actualizas el panel de Firebase, deberías ver un usuario nuevo después de un minuto.

6. Agrega Analytics

Incluso en las primeras etapas del desarrollo, Analytics es una herramienta útil para evaluar cómo interactúan los verificadores beta con el juego. Algunas estadísticas se recopilan automáticamente, como los informes de retención, pero es útil agregar eventos personalizados diseñados para tu juego específico.

Un buen punto de partida es registrar un evento de Analytics cuando el jugador comienza un nivel. Podemos usar la cantidad de eventos de inicio de nivel para ver con qué frecuencia un jugador puede volver a jugar el juego en una sesión.

También registraremos un evento cuando el jugador muera con la distancia que recorrió. Esto nos permitirá ver cómo los cambios que realizamos modifican la duración de una sola sesión y nos ayudará a determinar si los jugadores prefieren un juego más corto y difícil, o uno más largo y fácil.

Agrega encabezados de Analytics

Abre Classes/PopsicleScene.cpp y agrega encabezados de Firebase en la parte superior para que podamos realizar llamadas de Analytics.

PopsicleScene.cpp

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

Registra un evento de Level Start

Para registrar un evento cuando el Director de Cocos2dx organiza esta escena, busca la función PopsicleScene::onEnter(). Ingresa el siguiente código para registrar el evento Level Start aquí:

PopsicleScene.cpp

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

Registra un evento de Level End

Para ver qué tan bien le está yendo a un jugador, registraremos un evento de finalización del nivel con la distancia que recorrió el jugador cuando finalmente murió. Para ello, busca PopsicleScene::gameOver() y agrega lo siguiente al final del bloque if(!_gameOver) { antes de configurar _gameOver = true;:

PopsicleScene.cpp

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

kEventLevelEnd es el evento de finalización del nivel. Mientras que "distance" es un "parámetro del evento". Aquí agregamos la última distancia registrada, que es una buena aproximación de la distancia que recorrió un jugador antes de morir.

7. Eventos de prueba

Ahora puedes hacer clic en Depurar , pero los eventos tardarán en aparecer en el panel de Analytics. Esto se debe a dos motivos: 1) los eventos se agrupan y suben aproximadamente una vez por hora para preservar la batería, y 2) los informes se generan cada 24 horas.

Existen mecanismos con los que puedes ver los eventos más rápido. Si un evento se marca como evento de conversión, se registrará casi en tiempo real en muchas circunstancias. También puedes configurar Google Analytics para que exporte datos a BigQuery, donde la tabla de datos del día tendrá una antigüedad de solo 4 horas.

Cómo habilitar el modo de depuración

Aún es posible depurar los eventos de Analytics si pones tu dispositivo en modo de depuración.

Primero, asegúrate de tener instalado y configurado Android Debug Bridge (ADB). Si escribes adb devices, debería aparecer el dispositivo en el que realizarás la prueba:

$ adb devices
List of devices attached
emulator-5554   device

Luego, ejecuta el siguiente comando adb shell:

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

Esto le indica a Firebase Analytics que registre eventos de inmediato y los excluirá automáticamente de tus informes normales para evitar que se contaminen tus eventos activos durante las pruebas. Si quieres deshacer esta acción más adelante, simplemente escribe lo siguiente:

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

Visualiza eventos

Abre "DebugView" en Firebase console.

Haz clic en Depurar y juega. Deberías ver los eventos nuevos casi de inmediato después de que ocurran en el juego.

Si expandes el evento level_end, también verás el parámetro personalizado "distance" que registraste.

Cuando el evento level_end finalmente aparezca en tus informes de eventos, no registrará la distancia de forma predeterminada. Deberás seleccionar Eventos , buscar level_end, expandir los tres puntos que se encuentran en el lado derecho y seleccionar Editar la generación de informes de parámetros para agregarlo como parámetro en tus informes de eventos. Una vez que lo hagas, podrás ver estadísticas como la distancia promedio por partido de tus jugadores.

8. Cómo encontrar verificadores

A continuación, querrás que la gente vea tu juego, ya sea que se trate de personas internas de tu estudio, amigos cercanos o miembros de tu comunidad. Firebase App Distribution te ofrece una excelente manera de invitar a los jugadores a probar tu juego.

Cómo compilar un objeto binario independiente

Primero, compila un APK independiente para compartirlo desde Build > Build Bundles(s) / APK(s) > Build APK(s) .

Si antes cambiaste el filtro de ABI, recuerda volver a gradle.properties y cambiar PROP_APP_ABI para incluir cualquier dispositivo en el que planees realizar pruebas:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio mostrará un cuadro de diálogo que te permitirá ubicar el archivo compilado. Si no lo ves, puedes hacer clic en "Registro de eventos" para obtener el vínculo de nuevo.

Subir a Firebase App Distribution

1. Abre App Distribution y haz clic en "Comenzar"
2. Arrastra y suelta tu archivo .apk en el cuadro que dice “Arrastra cualquier archivo .apk aquí para crear una versión nueva”.
3. Ingresa tu dirección de correo electrónico como el primer verificador.
4. Haz clic en Siguiente.
5. Agrega una descripción y haz clic en Distribuir

Invitar a verificadores

En lugar de tener que ingresar manualmente cada dirección de correo electrónico, puedes crear un vínculo de invitación. Cuando capturas a un usuario con este vínculo de invitación, también puedes agregarlo a un grupo de verificadores. Por ejemplo, esto te permitiría separar a los verificadores internos de los externos.

1. Haz clic en "Verificadores y grupos".
2. Crea un grupo nuevo y asígnale un nombre, como "Testers de Android".
3. Haz clic en "Vínculos de invitación" .
4. Haz clic en "Nuevo vínculo de invitación".
5. Establece el grupo aquí desde el menú desplegable.
6. Haz clic en "Crear vínculo".
7. Haz clic en "Copiar vínculo" y compártelo como quieras.

9. Felicitaciones

Agregaste estadísticas correctamente a tu juego basado en C++, invitaste a algunos amigos a jugar y sabes cómo encontrar y vincular bibliotecas de Firebase en un sistema de compilación basado en CMake y Gradle que es común en el desarrollo para Android.

Temas abordados

• Cómo agregar Firebase a tu juego basado en CMake para Android
• Cómo determinar qué dependencias de C++ y Gradle necesitas
• Cómo registrar eventos de Analytics
• Cómo depurar eventos de Analytics
• Cómo compartir tu juego con App Distribution

Próximos pasos

• Intenta acceder con un usuario anónimo y guardar su puntuación más alta en Realtime Database.
• Registra eventos de Analytics en tu propio juego.
• Intenta agregar Analytics a un juego para iOS.

Más información

• Consulta la lista de eventos específicos de juegos y considera cómo podrían adaptarse a tu juego.