C++'te Firebase'i kullanmaya başlayın

1. Genel Bakış

Bu codelab'de, örnek olarak Google Analytics'i kullanarak C++ Firebase Games SDK'sını örnek bir Android oyununa nasıl entegre edeceğinizi öğreneceksiniz. İhtiyacınız olan özellikleri ekleyebilir, oyuncunuzun ilerlemesini ölçmek için temel analiz mantığı entegre edebilir ve erken geri bildirim almak için oyunu test kullanıcılarıyla paylaşabilirsiniz.

Adım adım açıklama

Bu codelab'i yazarlarla birlikte adım adım incelemek istiyorsanız şu videoyu izleyin:

Neler öğreneceksiniz?

• Android CMake tabanlı oyununuza Firebase'i ekleme
• Hangi C++ ve Gradle bağımlılıklarına ihtiyacınız olduğunu belirleme
• Analytics etkinlikleri nasıl günlüğe kaydedilir?
• Analiz etkinliklerinde hata ayıklama
• App Distribution ile oyununuzu paylaşma

İhtiyacınız olanlar

• Android Studio
• Örnek kod
• Google Play Hizmetleri'nin yüklü olduğu bir test cihazı veya emülatör

2. Örnek kodu alın

GitHub'dan kullanıma alma veya indirme:

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

Firebase SDK'sını indirin

macOS/Linux:

sh download.sh

Windows (PowerShell'den):

./download.ps1

SDK'yı manuel olarak da indirebilirsiniz. Bu işlemi yaparsanız Firebase C++ SDK'sı, /third_party içine çıkarılmalıdır. Böylece firebase_cpp_sdk adlı klasörde Firebase SDK'sından CMakeLists.txt kökü bulunur.

3. Örnek oyunu çalıştırma

Öncelikle örnek oyunu oynayın ve her şeyin çalıştığından emin olun. Prosedürel olarak oluşturulmuş bir seviyeye ve zıplamak için tek bir düğmeye sahip basit bir sonsuz koşu oyunudur.

1. Dosya > Yeni > Projeyi İçe Aktar'ı seçin (veya açılış ekranından Projeyi İçe Aktar'ı seçin).
2. Depoya dahil edilen proj.android/ klasörünü açın.

Bu, tipik bir Android projesi değil, Cocos2dx projesidir. Normalde bu depolama alanının kökünde bir build.gradle dosyası görmeyi beklersiniz ancak bu dosya proj.android/ altında yer alır. Böylece her hedef işletim sistemi kendi bağımsız derleme işlemine sahip olabilir.

3. [İsteğe bağlı] proj.android/gradle.properties simgesini açın ve PROP_APP_ABI simgesini bulun. Derleme sürelerini kısaltmak için hedef mimariniz dışındaki tüm mimarileri kaldırabilirsiniz. PROP_APP_ABI=x86 yalnızca emülatör için oluşturulur. PROP_APP_ABI=armeabi-v7a çoğu telefon için oluşturulur.
4. Oyunu oluşturup çalıştırmak için Hata Ayıklama düğmesini tıklayın. Cocos2dx oyun motorunun oluşturulması zaman alır.

Deneyimli Cocos2dx geliştiricileri, Cocos2dx CLI'yı yüklediyseniz cocos run -p android kullanmayı tercih edebilir. Android geliştiriciler ./gradlew installDebug'ı tercih edebilir. Bu eğitimde, geliştirme, derleme ve dağıtım için Android Studio'yu kullandığınızı varsayacağım.

4. Firebase Konsolu Kurulumu

1. Firebase Konsolu'nda yeni bir proje oluşturun.
2. "Popsicle Runner" gibi bir ad verin.
3. Analytics'i etkinleştirin
4. Analytics hesabı ekleme veya oluşturma
5. Projenize yeni bir Android uygulaması ekleme
6. com.firebase.popsiclerunner paket adınız olarak ekleyin.

Bu codelab için SHA-1'e ihtiyacınız yoktur.

7. google-services.json dosyasını indirip proj.android/app içine kopyalayın.

Birçok kaynak barındırma hizmeti, google-services.json dosyasını işlemeye çalıştığınızda "sırlar" olarak işaretler. Ancak bu dosyadaki hiçbir şey gerçek bir sır değildir (bir gönderim oyununda bu dosyanın içeriğini almak kolaydır). Yine de herkese açık bir kaynak kodu deposuna göndermeyi planlıyorsanız dikkatli olmanız gerekir. Bu dosya herkese açık olarak yayınlanırsa güçlü güvenlik kuralları yazmadan önce veritabanlarınızı veya bulut depolama alanlarınızı bulmak çok daha kolay olur.

8. Firebase SDK'sını eklemeyle ilgili talimatları yoksayın ve İleri'yi tıklayın.
9. Kurulumunuzu doğrulamanız istendiğinde "Bu adımı atla"yı tıklayabilirsiniz.

5. Firebase'i oyununuza ekleme

Firebase SDK'sını CMakeLists.txt dosyasına ekleyin

Kök düzeyindeki CMakeLists.txt öğesini açın. Bu dosyada, üst kısımlara yakın bir yerde aşağıdaki kod bulunmalıdır:

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

ve bu CMakeLists.txt dosyasının sonuna aşağıdaki satırları ekleyin.

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'sını içerir ve bu oyunda kullanılabilir hâle getirir.

target_link_libraries Oyunu, Firebase'in Android için oluşturulmuş C++ kitaplıklarına bağlar.

Kullanmak istediğiniz her özellik için hangi kitaplıklara ihtiyacınız olduğunu öğrenmek üzere bu tabloyu kullanın. Bu nedenle firebase_analytics için firebase_app gerektiğini biliyordum.

Google Hizmetleri eklentisini ekleme

Firebase SDK'sını bağlamak için Google Hizmetleri eklentisini gradle derleme komut dosyanıza eklemeniz gerekir. Bunu yapmak için proje düzeyindeki build.gradle dosyayı (proj.android klasöründe bulunur) açın. Ayrıca classpath 'com.google.gms:google-services:4.3.3' öğesini derleme komut dosyası bağımlılığı olarak ekleyin.

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

Ardından, eklentiyi modül düzeyindeki build.gradle dosyanıza (bu dosya proj.android/app klasörünüzdedir) ekleyin. apply plugin: 'com.android.application' altına apply plugin: 'com.google.gms.google-services' ekleyin:

build.gradle

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

Gradle'da C++ SDK'sını bulma

Gradle'a Firebase C++ SDK'sını nerede bulacağını söylemek için aşağıdaki satırları settings.gradle dosyasının en altına ekleyin.

settings.gradle

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

Bu, add_subdirectory çağrısının CMake'te yaptığı gibi aynı konuma işaret etmelidir.

Android bağımlılıklarını ekleme

Firebase için Android bağımlılıklarını bağlamak üzere popsicle_runner modül düzeyinde Gradle dosyasını (proj.android/app/build.gradle içinde) açın ve aşağıdaki kodu, sondaki normal dependences { bölümünden hemen önce ekleyin:

build.gradle

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

Her C++ SDK'sı, Android SDK'nın belirli bir sürümüne göre oluşturulur. firebaseCpp.dependencies, doğrulanmış bir yapılandırmaya sahip olmanızı sağlamak için gerekli Gradle bağımlılıklarını keşfedip yapılandıran, kullanım kolaylığı amaçlı bir işlevdir.

AndroidX ve Jetifier

gradle.properties dosyasını açıp sonuna şunu ekleyerek AndroidX ve Jetifier desteği ekleyin:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Oyununuzda Firebase'i başlatma

Classes/AppDelegate.cpp simgesini açarak oyunda Firebase'i başlatın. En üste aşağıdaki #include yönergeleri ekleyin:

AppDelegate.cpp

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

Ardından App::Create ekleyin ve ihtiyacınız olan Firebase özelliklerini başlatın. Bunu yapmak için AppDelegate::applicationDidFinishLaunching öğesini bulun ve bu kodu auto scene = MainMenuScene::createScene() öğesinden önce ekleyin:

AppDelegate.cpp

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

using namespace firebase; gibi using ifadelerinin kapsamını kısıtlamak için anonim blok {} kullanmayı tercih ediyorum.

Oyunda hata ayıklama yapıp Firebase kontrol panelini yenilerseniz bir dakika sonra yeni bir kullanıcı görürsünüz.

6. Analytics ekleme

Geliştirme sürecinin başlarında bile beta test kullanıcılarının oyunla nasıl etkileşim kurduğunu ölçmek için analizler kullanışlı bir araçtır. Elde tutma raporları gibi bazı analizler otomatik olarak toplanır ancak oyununuza özel olarak uyarlanmış özel etkinlikler eklemek faydalıdır.

İyi bir başlangıç noktası, oyuncu bir seviyeye başladığında bir analiz etkinliği kaydetmektir. Bir oyuncunun bir oturumda oyunu kaç kez tekrar oynayabileceğini görmek için seviye başlatma etkinliklerinin sayısını kullanabiliriz.

Oyuncu öldüğünde de ne kadar ilerlediğini belirten bir etkinlik kaydedilir. Bu sayede, yaptığımız değişikliklerin tek bir oturumun süresini nasıl etkilediğini görebilir ve oyuncuların daha kısa/zor veya daha uzun/kolay bir oyun isteyip istemediğini belirleyebiliriz.

Analytics üstbilgileri ekleme

Classes/PopsicleScene.cpp dosyasını açın ve analiz çağrıları yapabilmemiz için Firebase üstbilgilerini en üste ekleyin.

PopsicleScene.cpp

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

Seviye Başlangıcı etkinliğini günlüğe kaydetme

Bu Sahne, Cocos2dx Director tarafından aşamalı hale getirildiğinde bir günlük kaydı yapmak için PopsicleScene::onEnter() kaba kod işlevini bulun. Level Start etkinliğini buraya kaydetmek için aşağıdaki kodu girin:

PopsicleScene.cpp

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

Seviye Sonu etkinliğini günlüğe kaydetme

Bir oyuncunun ne kadar iyi oynadığını görmek için oyuncu öldüğünde ne kadar ilerlediğini içeren bir Level End etkinliği kaydedelim. Bunu yapmak için PopsicleScene::gameOver() simgesini bulun ve _gameOver = true; ayarını yapmadan önce if(!_gameOver) { bloğunun sonuna ekleyin:

PopsicleScene.cpp

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

kEventLevelEnd, seviye bitiş etkinliğidir. "distance" ise bir "etkinlik parametresidir". Buraya, kaydedilen son mesafeyi ekliyoruz. Bu mesafe, oyuncunun ölmeden önce ne kadar yol katettiği konusunda iyi bir tahmin sunar.

7. Test Etkinlikleri

Şimdi Hata Ayıklama'yı tıklayabilirsiniz ancak etkinliklerin Analytics kontrol panelinde raporlanması biraz zaman alacaktır. Bunun iki nedeni vardır: 1) Pili korumak için etkinlikler yaklaşık saatte bir kez toplu olarak yüklenir ve 2) raporlar 24 saatte bir oluşturulur.

Etkinlikleri daha hızlı görüntüleyebileceğiniz mekanizmalar vardır. Bir etkinlik dönüşüm etkinliği olarak işaretlenirse birçok durumda neredeyse gerçek zamanlı olarak raporlanır. Ayrıca Google Analytics'i BigQuery'ye veri aktaracak şekilde yapılandırabilirsiniz. Bu durumda gün içi tablosu yalnızca yaklaşık 4 saat güncel olmayacaktır.

Hata ayıklama modunu etkinleştirme

Cihazınızı hata ayıklama moduna alarak Analytics etkinliklerinde hata ayıklama yapmaya devam edebilirsiniz.

Öncelikle Android Debug Bridge'in (ADB) yüklü ve ayarlanmış olduğundan emin olun. adb devices yazıldığında, test edeceğiniz cihaz gösterilmelidir:

$ adb devices
List of devices attached
emulator-5554   device

Ardından aşağıdaki adb shell komutunu çalıştırın:

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

Bu, Firebase Analytics'e etkinlikleri hemen günlüğe kaydetmesini söyler ve test sırasında canlı etkinliklerinizi etkilememek için bu etkinlikleri normal raporlarınızın dışında tutar. Bu işlemi daha sonra geri almak isterseniz şunları yazmanız yeterlidir:

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

Etkinlikleri görüntüleme

Firebase konsolunuzda "DebugView"ı açın

Hata ayıklama simgesini tıklayın ve oyunu oynayın. Yeni etkinlikler, oyunda gerçekleşmelerinin ardından neredeyse anında gösterilir.

level_end etkinliğini genişletirseniz kaydettiğiniz özel "distance" parametresini de görürsünüz.

level_end etkinliği etkinlik raporlarınıza eklendiğinde varsayılan olarak mesafeyi almaz. Etkinlikler'i seçmeniz, level_end konumunu bulmanız, sağ taraftaki üç noktayı genişletmeniz ve etkinlik raporlarınıza parametre olarak eklemek için Parametre raporlamasını düzenle'yi seçmeniz gerekir. Bu işlemi yaptıktan sonra oyuncularınızın maç başına ortalama mesafesi gibi istatistikleri görebilirsiniz.

8. Test kullanıcılarını bulma

Ardından, stüdyonuzdaki kişiler, yakın arkadaşlarınız veya topluluğunuzdaki kişiler tarafından oyununuzun incelenmesini sağlayın. Firebase App Distribution, oyuncuları oyununuzu oynamaya davet etmenin harika bir yolunu sunar.

Bağımsız bir ikili program oluşturma

Öncelikle, Paylaşmak için Bağımsız APK oluşturun (Derleme > Paketleri/APK'ları Derle > APK'ları Derle)

Daha önce ABI filtrenizi değiştirdiyseniz gradle.properties bölümüne geri dönüp PROP_APP_ABI ayarını, test etmeyi planladığınız tüm cihazları içerecek şekilde değiştirmeyi unutmayın:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio, oluşturulan dosyayı bulmanızı sağlayan bir iletişim kutusu gösterir. Bu e-postayı kaçırırsanız bağlantıyı tekrar almak için "Etkinlik Günlüğü"nü tıklayabilirsiniz.

Firebase App Distribution'a yükleme

1. App Distribution'ı açıp "Başlayın"ı tıklayın.
2. "Yeni bir sürüm oluşturmak için tüm .apk dosyalarını buraya sürükleyin." yazan kutuya .apk dosyanızı sürükleyip bırakın.
3. İlk test kullanıcısı olarak e-posta adresinizi girin.
4. İleri'yi tıklayın.
5. Açıklama ekleyin ve Dağıt'ı tıklayın.

Test kullanıcılarını davet etme

Her e-posta adresini manuel olarak girmeniz gerekmez. Bunun yerine bir davet bağlantısı oluşturabilirsiniz. Bu davet bağlantısıyla yakaladığınız kullanıcıları test kullanıcıları grubuna da ekleyebilirsiniz. Bu sayede, örneğin dahili test kullanıcılarını harici test kullanıcılarından ayırabilirsiniz.

1. "Test kullanıcıları ve gruplar"ı tıklayın.
2. Yeni bir grup oluşturun ve bu gruba "Android Test Kullanıcıları" gibi bir ad verin.
3. "Davet bağlantıları"nı tıklayın.
4. "Yeni davet bağlantısı"nı tıklayın.
5. Açılır listeden grubu ayarlayın.
6. "Bağlantı Oluştur"u tıklayın.
7. "Bağlantıyı kopyala"yı tıklayın ve istediğiniz şekilde paylaşın.

9. Tebrikler

C++ tabanlı oyununuza başarıyla analiz eklediniz, bazı arkadaşlarınızı oyuna davet ettiniz ve Android geliştirmede yaygın olarak kullanılan CMake ve Gradle tabanlı bir derleme sisteminde Firebase kitaplıklarını nasıl bulup bağlayacağınızı biliyorsunuz.

İşlediğimiz konular

• Android CMake tabanlı oyununuza Firebase'i ekleme
• Hangi C++ ve Gradle bağımlılıklarına ihtiyacınız olduğunu belirleme
• Analytics etkinlikleri nasıl günlüğe kaydedilir?
• Analiz etkinliklerinde hata ayıklama
• App Distribution ile oyununuzu paylaşma

Sonraki Adımlar

• Bir kullanıcının anonim olarak giriş yapmasını ve yüksek skorunu Realtime Database'e kaydetmesini deneyin.
• Analytics etkinliklerini kendi oyununuzda günlüğe kaydedin.
• iOS oyununa analiz eklemeyi deneyin.

Daha Fazla Bilgi

• Oyuna özgü etkinliklerin listesini inceleyin ve bu etkinliklerin kendi oyununuza nasıl uyabileceğini değerlendirin.