Unity uygulamalarında Firebase Cloud Messaging'i kullanmaya başlama

Bu kılavuzda, güvenilir bir şekilde mesaj gönderebilmeniz için Unity istemci uygulamalarınızda Firebase Cloud Messaging'yı kullanmaya nasıl başlayacağınız açıklanmaktadır.

Unity ile platformlar arası Firebase Cloud Messaging istemci uygulamanızı yazmak için Firebase Cloud Messaging API'sini kullanın. Unity SDK'sı hem Android hem de Apple için çalışır. Her platform için ek kurulum yapılması gerekir.

Başlamadan önce

Ön koşullar

• Unity 2021 LTS veya sonraki bir sürümü yükleyin. Daha eski sürümler de uyumlu olabilir ancak aktif olarak desteklenmez.

• (Yalnızca Apple platformları) Aşağıdakileri yükleyin:

  • Xcode 26.2 veya daha yeni bir sürüm
  • CocoaPods 1.12.0 veya sonraki sürümler

• Unity projenizin aşağıdaki koşulları karşıladığından emin olun:

  • iOS için: iOS 15 veya sonraki sürümleri hedefler.
  • tvOS için: tvOS 15 veya sonraki sürümleri hedefler.
  • Android için: API düzeyi 23 (Marshmallow) veya sonraki sürümleri hedefler.

• Unity projenizi çalıştırmak için bir cihaz ayarlayın veya emülatör kullanın.

  • iOS veya tvOS için: Uygulamanızı çalıştırmak üzere fiziksel bir cihaz ayarlayın ve aşağıdaki görevleri tamamlayın:

    • Apple Developer hesabınız için Apple Anında Bildirim Kimlik Doğrulama Anahtarı edinin.
    • XCode'da App (Uygulama) > Capabilities (Özellikler) bölümünde push bildirimlerini etkinleştirin.

  • Android için: Emülatörler Google Play'i içeren bir emülatör resmi kullanmalıdır.

Henüz bir Unity projeniz yoksa ve yalnızca bir Firebase ürününü denemek istiyorsanız hızlı başlangıç örneklerimizden birini indirebilirsiniz.

1. adım: Firebase projesi oluşturun

Firebase'i Unity projenize ekleyebilmek için öncelikle Unity projenize bağlanacak bir Firebase projesi oluşturmanız gerekir. Firebase projeleri hakkında daha fazla bilgi edinmek için Firebase Projelerini Anlama başlıklı makaleyi inceleyin.

2. adım: Uygulamanızı Firebase'e kaydedin

Firebase projenize bağlanmak için bir veya daha fazla uygulama ya da oyun kaydedebilirsiniz.

1. Firebase konsoluna gidin.

2. Kurulum iş akışını başlatmak için projeye genel bakış sayfasının ortasındaki Unity simgesini (plat_unity) tıklayın.

   Firebase projenize zaten bir uygulama eklediyseniz platform seçeneklerini görüntülemek için Uygulama ekle'yi tıklayın.

3. Unity projenizin hangi derleme hedefini kaydetmek istediğinizi seçin. Dilerseniz her iki hedefi de aynı anda kaydedebilirsiniz.

4. Unity projenizin platforma özel kimliklerini girin.

   • iOS için: Unity projenizin iOS kimliğini iOS paket kimliği alanına girin.

   • Android için: Unity projenizin Android kimliğini Android paket adı alanına girin.
     Paket adı ve uygulama kimliği terimleri genellikle birbirinin yerine kullanılır.

   Unity projenizin kimliğini nerede bulabilirsiniz?

   Unity projenizi Unity IDE'nizde açın, ardından her platformun ayarlar bölümüne gidin:

   • iOS için: Build Settings > iOS'e (Derleme Ayarları > iOS) gidin.

   • Android için: Android > Player Settings > Other Settings'e (Android > Oynatıcı Ayarları > Diğer Ayarlar) gidin.

   Unity projenizin kimliği, Bundle Identifier değeridir (örnek kimlik: com.yourcompany.yourproject).

5. (İsteğe bağlı) Unity projenizin platforma özel takma adlarını girin.
   Bu takma adlar dahili, kolaylık tanımlayıcılarıdır ve yalnızca Firebase konsolunda size görünür.

6. Uygulamayı kaydet'i tıklayın.

3. adım: Firebase yapılandırma dosyalarını ekleyin

1. Platforma özel Firebase yapılandırma dosyalarınızı Firebase konsol kurulumu iş akışında edinin.

   • iOS için: GoogleService-Info.plist dosyasını indir'i tıklayın.

   • Android için: google-services.json dosyasını indir'i tıklayın.

   Bu yapılandırma dosyası hakkında bilmeniz gerekenler nelerdir?

   • Firebase yapılandırma dosyasında projenize ve uygulamanıza özgü, gizli olmayan tanımlayıcılar bulunur. Bu yapılandırma dosyası hakkında daha fazla bilgi edinmek için Firebase projelerini anlama başlıklı makaleyi inceleyin.

   • Firebase yapılandırma dosyanızı istediğiniz zaman tekrar indirebilirsiniz.

   • Yapılandırma dosyası adına (2) gibi ek karakterler eklenmediğinden emin olun.

2. Unity projenizin Proje penceresini açın, ardından yapılandırma dosyalarınızı Assets klasörüne taşıyın.

3. Firebase konsoluna geri dönün ve kurulum iş akışında Sonraki'yi tıklayın.

4. adım: Firebase Unity SDK'larını ekleyin

1. Firebase konsolunda Download Firebase Unity SDK'yı tıklayın, ardından SDK'yı uygun bir yere çıkarın.

   • Firebase Unity SDK'sını istediğiniz zaman tekrar indirebilirsiniz.

   • Firebase Unity SDK platforma özgü değildir.

2. Açık Unity projenizde Assets > Import Package > Custom Package'a gidin.

3. Arşivden çıkarılan SDK'dan, uygulamanızda kullanmak istediğiniz desteklenen Firebase ürünlerini seçin.

   Firebase Cloud Messaging ile en iyi deneyimi yaşamak için projenizde Google Analytics'ı etkinleştirmenizi öneririz. Ayrıca Analytics kurulumunun bir parçası olarak, uygulamanıza Analytics için Firebase paketini eklemeniz gerekir.

   Analytics etkinleştirildi

   • Google Analytics için Firebase paketini ekleyin: FirebaseAnalytics.unitypackage
   • Firebase Cloud Messaging için paketi ekleyin: FirebaseMessaging.unitypackage

   Analytics etkinleştirilmedi

   Firebase Cloud Messaging için paketi ekleyin: FirebaseMessaging.unitypackage

4. Unity Paketini İçe Aktar penceresinde İçe Aktar'ı tıklayın.

5. Firebase konsoluna geri dönün ve kurulum iş akışında Sonraki'yi tıklayın.

5. adım: Google Play Hizmetleri sürüm gereksinimlerini onaylayın

Android için Firebase Unity SDK'sındaki bazı ürünler Google Play services gerektirir. Hangi ürünlerin bu bağımlılığa sahip olduğunu öğrenin. Bu ürünlerin kullanılabilmesi için Google Play services uygulamasının güncel olması gerekir.

Uygulamanızın başlangıcına aşağıdaki using ifadesini ve başlatma kodunu ekleyin. SDK'daki diğer yöntemleri çağırmadan önce Google Play services sürümünü kontrol edebilir ve isteğe bağlı olarak gerekli sürüme güncelleyebilirsiniz.

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

Unity projeniz, Firebase'i kullanmak üzere kaydedilmiş ve yapılandırılmış olmalıdır.

Apple platformlarında kurulum yapma

Unity ve Apple platformlarında FCM'yı ayarlamak için aşağıdaki talimatları uygulayın.

APNs kimlik doğrulama anahtarınızı yükleyin

APNs kimlik doğrulama anahtarınızı Firebase'e yükleyin. Henüz bir APNs kimlik doğrulama anahtarınız yoksa Apple Developer Member Center'da bir tane oluşturduğunuzdan emin olun.

1. Firebase konsolunda settings Ayarlar > Genel'e gidin. Ardından Cloud Messaging sekmesini tıklayın.
2. iOS uygulama yapılandırması bölümündeki APNs kimlik doğrulama anahtarı altında, geliştirme kimlik doğrulama anahtarınızı veya üretim kimlik doğrulama anahtarınızı ya da her ikisini de yüklemek için Yükle'yi tıklayın. En az bir tane bildirmeniz gerekir.
3. Anahtarınızı kaydettiğiniz konuma gidin, anahtarınızı seçin ve Aç'ı tıklayın. Anahtarın anahtar kimliğini ekleyin (Apple Developer Member Center'da bulunur) ve Yükle'yi tıklayın.

Apple platformlarında push bildirimlerini etkinleştirme

1. Xcode'da projenizi tıklayın, ardından Editor area'dan General (Genel) sekmesini seçin.
2. Bağlı Framework'ler ve Kitaplıklar'a gidin, ardından framework eklemek için + düğmesini tıklayın.
3. Görüntülenen pencerede UserNotifications.framework'e gidin, bu girişi ve ardından Ekle'yi tıklayın.
4. Xcode'da projenizi tıklayın, ardından Editor area'dan Capabilities sekmesini seçin.
5. Push Bildirimleri'ni Açık duruma getirin.
6. Arka Plan Modları'na gidin ve Açık olarak değiştirin.
7. Arka Plan Modları bölümünde Uzaktan bildirimler onay kutusunu işaretleyin.

Firebase Cloud Messaging başlatılıyor

Firebase Installation ID kullanılarak kaydı etkinleştirme

Uygulama örneğinizi Firebase Cloud Messaging ile Firebase yükleme kimliğini (FID) kullanarak kaydetmeyi etkinleştirmek için öncelikle Android ve Apple platformları için uygulamanızın yapılandırmasında FID'leri etkinleştirmeniz gerekir:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

FCM etkinliklerine kaydolma

RegistrationReceived veya MessageReceived etkinlikleri için işleyiciler eklenirken Firebase Cloud Messaging kitaplığı başlatılır.

Başlatma sırasında Firebase Cloud Messaging, Firebase yükleme kimliğini (FID) kullanarak mesaj almak için istemci uygulama örneğini kaydeder. Uygulama, RegistrationReceived etkinliğiyle birlikte FID'yi alır. Bu FID'yi, mesajlar için bu belirli cihazı hedeflemek üzere sunucunuzda önbelleğe almanız gerekir.

Ayrıca, gelen mesajları almak istiyorsanız OnMessageReceived etkinliğine kaydolmanız gerekir.

Kurulum şu şekilde görünür:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

Firebase yükleme kimliğini aldıktan sonra uygulama sunucunuza gönderin ve tercih ettiğiniz yöntemi kullanarak saklayın.

Otomatik başlatma devre dışı bırakıldığında manuel olarak kaydetme

Ayrıca, çalışma zamanında FCM kullanarak kaydı manuel olarak da tetikleyebilirsiniz: RegisterAsync():

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

FCM kayıt jetonuna erişme (kullanımdan kaldırıldı)

Uygulamanız hâlâ desteği sonlandırılmış jeton API'lerini kullanıyorsa TokenReceived:

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

Android platformlarında kurulum yapma

Unity ve Android platformlarında FCM'yı ayarlamak için aşağıdaki talimatları uygulayın.

Android giriş noktası etkinliği yapılandırma

Firebase Cloud Messaging, varsayılan UnityPlayerActivity yerine özel bir giriş noktası etkinliğiyle birlikte gelir. Özel giriş noktası kullanmıyorsanız bu değiştirme işlemi otomatik olarak gerçekleşir ve herhangi bir ek işlem yapmanız gerekmez.

Android'deki Firebase Cloud Messaging Unity eklentisi iki ek dosyayla birlikte gelir:

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar, standart UnityPlayerActivity yerine kullanılan MessagingUnityPlayerActivity adlı bir etkinlik içerir.
• Assets/Plugins/Android/AndroidManifest.xml, uygulamaya giriş noktası olarak MessagingUnityPlayerActivity kullanılmasını ister.

Bu dosyalar, varsayılan UnityPlayerActivity, onStop, onRestart etkinlik yaşam döngüsü geçişlerini işlemediği veya Firebase Cloud Messaging'in gelen mesajları doğru şekilde işlemesi için gerekli olan onNewIntent'yi uygulamadığı için sağlanır.

Özel giriş noktası etkinliği yapılandırma

Uygulamanız varsayılan UnityPlayerActivity kullanmıyorsa sağlanan AndroidManifest.xml öğesini kaldırmanız ve özel etkinliğinizin Android Activity Lifecycle'ın tüm geçişlerini düzgün şekilde işlemesini sağlamanız gerekir (Bunun nasıl yapılacağına dair bir örnek aşağıda gösterilmiştir). Özel etkinliğiniz UnityPlayerActivity'yi genişletiyorsa bunun yerine gerekli tüm yöntemleri uygulayan com.google.firebase.MessagingUnityPlayerActivity'yi genişletebilirsiniz.

Özel bir Activity kullanıyorsanız ve com.google.firebase.MessagingUnityPlayerActivity öğesini genişletmiyorsanız Activity'nize aşağıdaki snippet'leri eklemeniz gerekir.

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For earlier versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This makes sure that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

Firebase C++ SDK'sının yeni sürümleri (7.1.0 ve sonrası) JobIntentService kullanır. Bu nedenle, AndroidManifest.xml dosyasında ek değişiklikler yapılması gerekir.

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Android'de ileti teslimi

Uygulama hiç çalışmıyorken kullanıcı bir bildirime dokunduğunda mesaj, varsayılan olarak FCM'nın yerleşik geri aramaları üzerinden yönlendirilmez. Bu durumda, mesaj yükleri uygulamayı başlatmak için kullanılan bir Intent aracılığıyla alınır.

Uygulama arka plandayken alınan mesajların bildirim alanı içeriği, sistem tepsisi bildirimini doldurmak için kullanılır ancak bu bildirim içeriği FCM ile paylaşılmaz. Bu durumda FirebaseMessage.Notification değeri boş olur.

Özet olarak:

Android'de derin bağlantı içeren mesajları işleme

FCM, uygulamanıza derin bağlantı içeren mesajların gönderilmesine olanak tanır. Derin bağlantı içeren mesajlar almak için uygulamanızdaki derin bağlantıları işleyen etkinliğe yeni bir intent filtresi eklemeniz gerekir. Intent filtresi, alanınızın derin bağlantılarını yakalamalıdır. AndroidManifest.xml dosyasında:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

Ayrıca, amaç filtresini daha esnek hale getirmek için joker karakter de belirtebilirsiniz. Örneğin:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

Kullanıcılar, belirttiğiniz şemaya ve ana makineye bağlantı içeren bir bildirime dokunduğunda uygulamanız, bağlantıyı işlemek için etkinliği bu intent filtresiyle başlatır.

Otomatik başlatmayı önleme

FCM, cihaz hedefleme için bir kayıt jetonu oluşturur. Kitaplık, jeton oluşturulduğunda tanımlayıcıyı ve yapılandırma verilerini Firebase'e yükler. Jetonu kullanmadan önce açıkça izin almak istiyorsanız FCM'yi (ve Android'de Analytics'i) devre dışı bırakarak yapılandırma sırasında jeton oluşturulmasını engelleyebilirsiniz. Apple'da Info.plist (GoogleService-Info.plist değil) veya Android'de AndroidManifest.xml öğenize meta veri değeri ekleyebilirsiniz:

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

FirebaseMessagingAutoInitEnabled = NO

FCM'yi yeniden etkinleştirmek için bir çalışma zamanı çağrısı yapabilirsiniz:

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

Bu değer, ayarlandıktan sonra uygulama yeniden başlatıldığında da geçerliliğini korur.

Sonraki adımlar

Kurulum adımlarını tamamladıktan sonra Unity için FCM ile ilerlemeye yönelik birkaç seçeneği aşağıda bulabilirsiniz:

• Cihazlara mesaj gönderme
• Unity istemcisinde mesaj alma
• Konu mesajları gönderme