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

Bu kılavuzda, mesajları güvenilir bir şekilde gönderebilmek için Unity istemci uygulamalarınızda Firebase Cloud Messaging 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 gerekir.

Başlamadan önce

Ön koşullar

• Unity 2021 LTS veya sonraki bir sürümü yükleyin. Önceki sürümler de uyumlu olabilir ancak etkin bir şekilde desteklenmez.

• (Yalnızca Apple platformları) Şunları 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 24 (Nougat) veya sonraki sürümleri hedeflemelidir.

• 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 için fiziksel bir cihaz kurun 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 (Yetenekler) bölümünde Push Bildirimleri'ni etkinleştirin.

  • Android için: Emülatörler, Google Play'de bir emülatör görüntüsü 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 sayfasını ziyaret edin.

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

Firebase projenize bağlamak 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ından 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 kaydetmek istediğiniz derleme hedefini seçin. İsterseniz her iki hedefi de aynı anda kaydetmeyi seçebilirsiniz.

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 gidin.

   • Android için: Android > Player Settings (Oynatıcı Ayarları) > Other Settings (Diğer Ayarlar) bölümüne gidin.

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

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

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

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

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

   • iOS için: Download GoogleService-Info.plist'i (GoogleService-Info.plist'i İndir) 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ı dilediğiniz zaman tekrar indirebilirsiniz.

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

2. Unity projenizin Project(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 Firebase Unity SDK'sını indir'i tıklayın, ardından SDK'yı uygun bir yere açın.

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

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

2. Açık Unity projenizde Assets (Öğeler) > Import Package (Paketi İçe Aktar) > Custom Package'a (Özel Paket) gidin.

3. Açı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üp kurulum iş akışında İleri'yi tıklayın.

5. adım: Google Play Hizmetleri sürüm şartlarını 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 güncel olmalıdır.

Uygulamanızın başı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.

APN kimlik doğrulama anahtarınızı yükleme

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 anahtar oluşturun.

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ı'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 Düzenleyici alanından Genel sekmesini seçin.
2. Linked Frameworks and Libraries (Bağlı Çerçeveler ve Kitaplıklar) bölümüne gidin ve çerçeve eklemek için + düğmesini tıklayın.
3. Açılan pencerede UserNotifications.framework'e gidin, bu girişi ve ardından Add'i (Ekle) tıklayın.
4. Xcode'da projenizi tıklayın, ardından Düzenleyici alanından Özellikler sekmesini seçin.
5. Push Bildirimleri'ni Açık konumuna 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 Kurulum Kimliği'ni kullanarak kaydı etkinleştirme

Firebase Kurulum Kimliği'ni (FID) kullanarak uygulama örneğinizi Firebase Cloud Messaging ile kaydetmeyi etkinleştirmek için öncelikle uygulamanızın hem Android hem de Apple platformlarındaki 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 kaydolun

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

Başlatma sırasında Firebase Cloud Messaging, Firebase Kurulum Kimliği'ni (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 cihaza hedefleme yapmak ü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 RegisterAsync() kullanarak FCM ile kaydı manuel olarak tetikleyebilirsiniz:

// 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 şunları dinleyebilirsiniz: 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ını kurma

Unity ve Android platformlarında FCM kurulumu yapmak 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 bir giriş noktası kullanmıyorsanız bu değişiklik otomatik olarak gerçekleşir ve ek bir 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 geçen 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 Etkinlik Yaşam Döngüsü'nün tüm geçişlerini düzgün şekilde işlediğinden emin olmanı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 mesaj teslimi

Uygulama hiç çalışmıyorken kullanıcı bir bildirime dokunduğunda mesaj, varsayılan olarak FCM'nin yerleşik geri çağırmaları ü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ındaki içerik, sistem tepsisi bildirimini doldurmak için kullanılır ancak bu bildirim içeriği FCM ile paylaşılmaz. Bu, FirebaseMessage.Notification değerinin boş olacağı anlamına gelir.

Ö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ızın derin bağlantılarını 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 bir etkinleştirme almak istiyorsanız FCM'yi (ve Android'de Analytics'i) devre dışı bırakarak yapılandırma sırasında oluşturmayı engelleyebilirsiniz. Apple'da Info.plist (GoogleService-Info.plist değil) veya Android'de AndroidManifest.xml için 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 devam etmek üzere kullanabileceğiniz birkaç seçenek vardır:

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