Comece a usar o Firebase no C++

1. Visão geral

Neste codelab, você vai aprender a integrar o SDK do Firebase Games em C++ em um jogo Android de exemplo usando o Google Analytics como exemplo. Você poderá adicionar os recursos necessários, integrar uma lógica de análise básica para medir o progresso do jogador e compartilhar o jogo com testadores para receber feedback antecipado.

Tutorial

Se quiser fazer este codelab com os autores, assista a este vídeo:

O que você vai aprender

• Como adicionar o Firebase ao seu jogo baseado em Android CMake.
• Como descobrir quais dependências de C++ e Gradle você precisa.
• Como registrar eventos do Google Analytics.
• Como depurar eventos de análise.
• Como compartilhar seu jogo com o App Distribution.

O que é necessário

• Android Studio
• Código de amostra
• Um dispositivo de teste ou emulador com o Google Play Services

2. Acessar o exemplo de código

Faça o checkout ou o download no GitHub:

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

Baixar o SDK do Firebase

MacOS/Linux:

sh download.sh

Windows (do PowerShell):

./download.ps1

Você também pode fazer o download manual do SDK. Se você fizer isso, o SDK do Firebase para C++ precisará ser extraído para /third_party para que uma pasta chamada firebase_cpp_sdk tenha a raiz CMakeLists.txt do SDK do Firebase.

3. Executar o jogo de exemplo

Primeiro, jogue o jogo de exemplo e confira se tudo está funcionando. É um jogo de corrida infinita simples com um nível gerado por procedimento e um único botão para pular.

1. Selecione File > New > Import Project ou selecione Import Project na tela inicial.
2. Abra a pasta proj.android/ incluída no repositório.

Este é um projeto Cocos2dx, e não um Projeto do Android típico. Normalmente, você esperaria ver um arquivo build.gradle na raiz desse repositório, mas ele está em proj.android/ para que cada sistema operacional de destino tenha um processo de build independente.

3. [Opcional] Abra proj.android/gradle.properties e encontre PROP_APP_ABI. É possível remover todas, exceto a arquitetura de destino, para reduzir os tempos de build. PROP_APP_ABI=x86 vai criar apenas para o emulador PROP_APP_ABI=armeabi-v7a vai criar para a maioria dos smartphones
4. Clique no botão "Debug" para criar e executar o jogo. Isso vai levar algum tempo para criar o mecanismo de jogo Cocos2dx.

Desenvolvedores experientes do Cocos2dx podem usar o cocos run -p android se tiverem a CLI do Cocos2dx instalada. Os desenvolvedores Android podem preferir ./gradlew installDebug. Neste tutorial, vamos presumir que você está usando o Android Studio para desenvolver, criar e implantar.

4. Configuração do console do Firebase

1. Crie um projeto no console do Firebase.
2. Dê um nome como "Popsicle Runner"
3. Ativar o Google Analytics
4. Adicionar ou criar uma conta do Google Analytics
5. Adicionar um novo app Android ao projeto
6. Adicione com.firebase.popsiclerunner como o nome do pacote.

Não é necessário um SHA-1 para este codelab.

7. Faça o download do google-services.json e copie para proj.android/app

Muitos serviços de hospedagem de origem vão sinalizar google-services.json como "segredos" se você tentar fazer commit dele, mas nada nesse arquivo é um segredo real. Em um jogo de envio, é trivial recuperar o conteúdo desse arquivo. Ainda assim, tenha cuidado se você planeja confirmar em um repositório de código-fonte público. Será muito mais fácil encontrar seus bancos de dados ou buckets do Cloud Storage antes de escrever regras de segurança fortes se esse arquivo for publicado publicamente.

8. Ignore as instruções fornecidas para adicionar o SDK do Firebase e clique em "Próxima".
9. Clique em "Pular esta etapa" quando for solicitado a verificar a instalação.

5. Adicionar o Firebase ao seu jogo

Adicionar o SDK do Firebase a CMakeLists.txt

Abra o CMakeLists.txt no nível raiz. Ele precisa ter o seguinte código perto da parte de cima

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

e adicione estas linhas ao final do arquivo 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 inclui o SDK do Firebase para C++ e o disponibiliza para esse jogo.

target_link_libraries Conecta o jogo às bibliotecas C++ do Firebase criadas para Android.

Use esta tabela para descobrir quais bibliotecas são necessárias para cada recurso que você quer usar. Foi assim que descobri que firebase_analytics exige firebase_app.

Adicionar o plug-in do Google Services

Para conectar o SDK do Firebase, adicione o plug-in dos Serviços do Google ao script de build do Gradle. Para fazer isso, abra o arquivo build.gradle no nível do projeto (na pasta proj.android). E adicione classpath 'com.google.gms:google-services:4.3.3' como uma dependência do script de build.

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

Em seguida, adicione o plug-in ao arquivo build.gradle no nível do módulo (na pasta proj.android/app). Adicione apply plugin: 'com.google.gms.google-services' abaixo de apply plugin: 'com.android.application':

build.gradle

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

Localizar o SDK para C++ no Gradle

Para informar ao Gradle onde encontrar o SDK do Firebase para C++, adicione as seguintes linhas à parte de baixo do arquivo settings.gradle.

settings.gradle

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

Ele precisa apontar para o mesmo local que a chamada add_subdirectory fez no CMake.

Adicionar as dependências do Android

Para conectar as dependências do Android ao Firebase, abra o arquivo gradle no nível do módulo para popsicle_runner (em proj.android/app/build.gradle) e adicione o seguinte logo antes da seção dependences { típica no final:

build.gradle

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

Cada SDK do C++ é criado para uma versão específica do SDK do Android. firebaseCpp.dependencies é uma função de conveniência que descobre e configura as dependências necessárias do Gradle para garantir que você tenha uma configuração verificada.

AndroidX e Jetifier

Adicione o suporte do AndroidX e do Jetifier abrindo gradle.properties e adicionando isto ao final:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Inicializar o Firebase no seu jogo

Inicialize o Firebase no jogo abrindo Classes/AppDelegate.cpp. Adicione as seguintes diretivas #include à parte de cima:

AppDelegate.cpp

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

Em seguida, adicione App::Create e inicialize os recursos do Firebase necessários. Para fazer isso, encontre AppDelegate::applicationDidFinishLaunching e adicione 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);
}

Prefiro usar um bloco anônimo {} para restringir o escopo de instruções using, como using namespace firebase;.

Se você depurar o jogo e atualizar o painel do Firebase, um novo usuário vai aparecer depois de um minuto.

6. Adicionar o Analytics

Mesmo no início do desenvolvimento, a análise é uma ferramenta útil para avaliar como os testadores Beta estão interagindo com o jogo. Algumas análises são coletadas automaticamente, como os relatórios de retenção, mas é útil adicionar eventos personalizados feitos para seu jogo específico.

Um bom ponto de partida é registrar um evento de análise quando o jogador inicia um nível. Podemos usar o número de eventos de início de nível para ver com que frequência um jogador pode repetir o jogo em uma sessão.

Também vamos registrar um evento quando o jogador morrer, com a distância que ele percorreu. Isso nos permite ver como as mudanças que fazemos alteram a duração de uma única sessão e nos ajuda a determinar se os jogadores querem um jogo mais curto/difícil ou mais longo/fácil.

Adicionar cabeçalhos do Analytics

Abra Classes/PopsicleScene.cpp e adicione cabeçalhos do Firebase na parte de cima para que possamos fazer chamadas de análise.

PopsicleScene.cpp

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

Registrar um evento de início de nível

Para registrar um evento quando essa cena é organizada pelo Cocos2dx Director, encontre a função stubbed PopsicleScene::onEnter(). Insira o código a seguir para registrar o evento "Início do nível":

PopsicleScene.cpp

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

Registrar um evento de fim de nível

Para saber como um jogador está se saindo, vamos registrar um evento de fim de nível com a distância que ele percorreu antes de morrer. Para fazer isso, encontre PopsicleScene::gameOver() e adicione o seguinte ao final do bloco if(!_gameOver) { antes de definir _gameOver = true;:

PopsicleScene.cpp

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

kEventLevelEnd é o evento de término do nível. Já "distance" é um "parâmetro de evento". Estamos adicionando aqui a última distância registrada, que é uma boa aproximação de quanto um jogador viajou antes de morrer.

7. Testar eventos

Clique em Depurar agora, mas vai levar algum tempo para que os eventos sejam informados no painel do Google Analytics. Isso acontece por dois motivos: 1) os eventos são agrupados e enviados aproximadamente uma vez por hora para preservar a bateria e 2) os relatórios são gerados a cada 24 horas.

Existem mecanismos para visualizar eventos mais rapidamente. Se um evento for marcado como um evento de conversão, ele será informado quase em tempo real em muitas circunstâncias. Você também pode configurar o Google Analytics para exportar para o BigQuery, em que a tabela intradiária fica desatualizada em apenas quatro horas.

Ativar o modo de depuração

Ainda é possível depurar eventos do Analytics colocando seu dispositivo no modo de depuração.

Primeiro, verifique se o Android Debug Bridge (ADB) está instalado e configurado. Ao digitar adb devices, o dispositivo em que você vai testar vai aparecer:

$ adb devices
List of devices attached
emulator-5554   device

Em seguida, execute o comando adb shell:

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

Isso informa ao Firebase Analytics para registrar eventos imediatamente e os exclui automaticamente dos seus relatórios normais para evitar a poluição dos eventos ativos durante o teste. Se quiser desfazer essa ação depois, basta escrever:

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

Como visualizar eventos

Abra a "DebugView" no Console do Firebase

Clique em Depurar e jogue. Os novos eventos vão aparecer quase imediatamente após ocorrerem no jogo.

Se você expandir o evento level_end, também vai ver o parâmetro personalizado "distance" registrado.

Quando o evento level_end aparecer nos seus relatórios de eventos, ele não vai coletar a distância por padrão. Selecione "Eventos" , localize level_end, clique nos três pontos à direita e selecione Editar relatórios de parâmetros para adicionar como um parâmetro nos seus relatórios de eventos. Depois disso, você pode conferir estatísticas como a distância média percorrida pelos jogadores por partida.

8. Encontrar testadores

Em seguida, você vai querer mostrar seu jogo para outras pessoas, sejam elas internas do seu estúdio, amigos próximos ou da sua comunidade. O Firebase App Distribution é uma ótima maneira de convidar jogadores para testar seu jogo.

Como criar um binário independente

Primeiro, crie um APK autônomo para compartilhar em Build > Build Bundles(s) / APK(s) > Build APK(s)

Se você já tiver mudado o filtro de ABI, volte para gradle.properties e mude PROP_APP_ABI para incluir qualquer dispositivo em que você planeja testar:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

O Android Studio vai abrir uma caixa de diálogo para você localizar o arquivo criado. Se você perder, clique em "Registro de eventos" para acessar o link novamente.

Fazer upload para o Firebase App Distribution

1. Abra a App Distribution e clique em "Começar"
2. Arraste e solte o arquivo .apk na caixa que diz "Arraste qualquer .apk para cá caso queira criar um novo lançamento".
3. Insira seu endereço de e-mail como o primeiro testador.
4. Clique em "Próxima".
5. Adicione uma descrição e clique em "Distribuir"

Convidar testadores

Em vez de inserir manualmente todos os endereços de e-mail, você pode criar um link de convite. Ao capturar um usuário com esse link de convite, você também pode adicioná-lo a um grupo de testadores. Isso permite separar testadores internos e externos, por exemplo.

1. Clique em "Testadores e grupos"
2. Crie um grupo e dê um nome a ele, como "Testadores do Android".
3. Clique em "Links de convite"
4. Clique em "Novo link de convite".
5. Defina o grupo aqui no menu suspenso.
6. Clique em "Criar link".
7. Clique em "Copiar link" e compartilhe como quiser.

9. Parabéns

Você adicionou análises ao seu jogo baseado em C++, convidou alguns amigos para jogar e sabe como encontrar e vincular bibliotecas do Firebase em um sistema de build baseado em CMake e Gradle, comum no desenvolvimento para Android.

O que aprendemos

• Como adicionar o Firebase ao seu jogo baseado em Android CMake.
• Como descobrir quais dependências de C++ e Gradle você precisa.
• Como registrar eventos do Google Analytics.
• Como depurar eventos de análise.
• Como compartilhar seu jogo com o App Distribution.

Próximas etapas

• Tente fazer login de um usuário anonimamente e salvar a maior pontuação dele no Realtime Database.
• Registre eventos de Análise de dados de registros no seu próprio jogo.
• Tente adicionar o Google Analytics a um jogo para iOS.

Saiba mais

• Confira a lista de eventos específicos de jogos e pense em como eles podem se encaixar no seu jogo.