Comienza a usar Firebase en C++

1. Descripción general

En este codelab, aprenderás a integrar el SDK de juegos de Firebase de C++ en un juego de Android de muestra con Google Analytics como ejemplo. Podrás agregar las funciones que necesites, integrar lógica de analítica básica para medir el progreso de los jugadores y compartir el juego con los verificadores para recibir comentarios anticipados.

Explicación

Si quieres revisar 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

Confirmación de la compra o descarga desde GitHub:

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

Descarga el SDK de Firebase

MacOS/Linux:

sh download.sh

Windows (de PowerShell):

./download.ps1

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

3. Ejecuta el juego de muestra

Primero, prueba el juego de muestra y asegúrate de que todo funcione correctamente. Se trata de un simple juego de corredores infinitos con un nivel generado mediante procedimientos y un solo botón para saltar.

1. Selecciona Archivo > Nuevo > Importa el proyecto (o selecciona Importar proyecto 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. Por lo general, esperarías ver un archivo build.gradle en la raíz de este repositorio, pero se encuentra en proj.android/, por lo que cada sistema operativo de destino puede tener su propio proceso de compilación independiente.

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

Los desarrolladores experimentados de Cocos2dx pueden optar por usar cocos run -p android si tienen la CLI de Cocos2dx instalada. Es posible que los desarrolladores de Android prefieran ./gradlew installDebug. Para este instructivo, supongo que usas Android Studio para desarrollar, compilar e implementar.

4. Configuración de Firebase console

1. Crea un proyecto nuevo en Firebase console.
2. Asígnale un nombre como "Paleta corredor".
3. Habilitar 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 de paquete.

No necesitarás un SHA-1 para este codelab

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

Muchos servicios de hosting de origen marcarán google-services.json como “Secrets” si intentas confirmarlo, pero nada de este archivo es un secreto real (en un juego de envío, recuperar el contenido de este archivo es trivial). Aún debes tener cuidado si planeas confirmarlo en un repositorio público de código fuente, ya que será mucho más fácil encontrar tus bases de datos o buckets de almacenamiento en la nube antes de escribir 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 tu instalación.

5. Agrega Firebase a tu juego

Agrega el SDK de Firebase a CMakeLists.txt

Abre el nivel raíz CMakeLists.txt. Debe 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 para este juego.

target_link_libraries Conecta el juego con las bibliotecas C++ de Firebase compiladas para Android.

Usa esta tabla para averiguar qué bibliotecas necesitas para cada función que quieres usar. Así es como sabía 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 de nivel de proyecto (que se encuentra en la carpeta proj.android). Además, agrega classpath 'com.google.gms:google-services:4.3.3' como dependencia 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 de nivel de módulo (que se encuentra en tu 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

Localiza el SDK de C++ en Gradle.

Para indicar a Gradle dónde encontrar el SDK de Firebase C++, agrega las siguientes líneas al final 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 a add_subdirectory en CMake.

Cómo agregar las dependencias de Android

Para conectar las dependencias de Android para Firebase, abre el archivo de 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 conveniente 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

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

AppDelegate.cpp

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

Luego, agrega App::Create e inicializa las funciones de Firebase que necesitas. Para ello, busca AppDelegate::applicationDidFinishLaunching y agrega este código antes del 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 sentencias using, como using namespace firebase;.

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

6. Agregar estadísticas

Incluso al principio del desarrollo, el análisis es una herramienta útil para medir cómo interactúan con el juego los verificadores beta. Hay algunas estadísticas que se recopilan automáticamente, como los informes de retención, pero es útil agregar eventos personalizados adaptados a tu juego específico.

Un buen punto de partida es registrar un evento de Analytics cuando el jugador inicia un nivel. Podemos usar la cantidad de eventos de inicio de niveles para ver la frecuencia con la que un jugador podría volver a jugar el juego en una sesión.

También registraremos un evento en el que el jugador muera según la distancia que haya llegado. 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 quieren un juego más corto o más difícil, o uno más largo o sencillo.

Agrega encabezados de Analytics

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

PopsicleScene.cpp

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

Registrar un evento de inicio de nivel

Para registrar un evento cuando Cocos2dx Director pone en escena este ambiente, busca la función con stub PopsicleScene::onEnter(). Ingresa el siguiente código para registrar el evento Level Start aquí:

PopsicleScene.cpp

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

Registrar un evento de finalización de nivel

Para ver qué tan bien le está yendo a un jugador, registremos un evento de finalización de nivel que indique qué tan lejos llegó 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 de nivel. Mientras que "distance" es un "parámetro de evento". Aquí agregamos la última distancia registrada, que es una buena aproximación de la distancia que recorrió un jugador antes de morir.

7. Cómo probar eventos

Puedes hacer clic en Depurar ahora, pero los eventos tomarán un tiempo en registrarse en el panel de Analytics. Esto puede deberse a dos motivos: 1) los eventos se agrupan en lotes y se suben aproximadamente una vez por hora para conservar la batería y 2) los informes se generan cada 24 horas.

Existen mecanismos para ver 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 exportar a BigQuery, donde la tabla intradía estará desactualizada solo unas 4 horas.

Cómo habilitar el modo de depuración

Aún puedes 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). Al escribir adb devices, se debería mostrar el dispositivo en el que vas a probar:

$ 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

Esta acción le indica a Firebase Analytics que registre eventos de inmediato y los excluirá automáticamente de tus informes normales para evitar contaminar tus eventos en vivo 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 la "DebugView". en tu de Firebase console

Haz clic en Debug y comienza el juego. Los eventos nuevos deberían aparecer casi inmediatamente después de que ocurran en el juego.

Si expandes el evento level_end, también verás la "distancia" personalizada parámetro que hayas registrado.

Cuando el evento level_end llegue a tus informes de eventos, no recopilará la distancia de forma predeterminada. Deberás seleccionar Eventos , ubicar level_end, expandir los tres puntos a la derecha y seleccionar Editar informes de parámetros para agregarlo como parámetro a tus informes de eventos. Una vez que hagas esto, podrás ver las estadísticas, distancia promedio por partido.

8. Cómo encontrar verificadores

A continuación, querrás conocer tu juego, ya sea que pertenezcan a tu estudio, a amigos cercanos o a tu comunidad. Firebase App Distribution te ofrece una excelente manera de invitar a los jugadores a jugar tu juego.

Compila un objeto binario independiente

Primero, compila un APK independiente para compartirlo desde Compilación > Compila paquetes o APK > Compilar APK

Si cambiaste tu filtro de ABI anteriormente, recuerda volver a gradle.properties y cambiar PROP_APP_ABI para incluir todos los dispositivos en los que planeas 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 te lo pierdes, puedes hacer clic en "Registro de eventos" para volver a obtener el vínculo.

Sube 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 un nuevo lanzamiento".
3. Ingresa tu dirección de correo electrónico como primer verificador.
4. Haz clic en Continuar.
5. Agrega una descripción y haz clic en Distribuir.

Invitar a verificadores

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

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

9. Felicitaciones

Agregaste correctamente análisis 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 de 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 a un usuario de forma anónima y guardar su puntuación alta en Realtime Database.
• Registra eventos de Analytics en tu propio juego.
• Intenta agregar estadísticas a un juego para iOS.

Más información

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