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 sonraki sürümler
  • 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 Geliştirici hesabınız için bir Apple Push Bildirimi Kimlik Doğrulama Anahtarı alın.
    • 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.

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 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 konsolu kurulum iş akışında platformunuza özel Firebase yapılandırma dosyalarını alın.

   • 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ı dilediğiniz zaman tekrar indirebilirsiniz.

   • Yapılandırma dosyanıza fazladan karakter (ör. (2)) 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üp kurulum iş akışında İleri'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ı dilediğ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. Sıkıştırılmış dosyadan çı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 özelliğini etkinleştirmenizi öneririz. Ayrıca Analytics kurulumu kapsamında Analytics için Firebase paketini uygulamanıza 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 kullanacak şekilde kaydedilmiş ve yapılandırılmış olmalıdır.

Apple platformlarında kurulum yapma

FCM ürününü Unity ve Apple platformlarıyla 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ı altındaki APN kimlik doğrulama anahtarı bölümünde, geliştirme kimlik doğrulama anahtarınızı, üretim kimlik doğrulama anahtarınızı veya her ikisini birden 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ı seçin ve Aç'ı tıklayın. Anahtarın anahtar kimliğini (Apple Developer Member Center'da bulunur) ekleyin 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 konuma getirin.
6. Arka Plan Modları'na gidin ve Açık olarak ayarlayın.
7. Background Modes (Arka Plan Modları) bölümünde Remote notifications (Uzak 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, FID'yi RegistrationReceived etkinliğiyle alır. Bu etkinliği, 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 Kurulum Kimliği'ni aldıktan sonra uygulama sunucunuza gönderin ve tercih ettiğiniz yöntemi kullanarak depolayı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 etkinliğinin yerini alan ö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 dosya ile 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 kullanması için uygulamaya talimat verir.

Bu dosyalar, varsayılan UnityPlayerActivity; onStop, onRestart etkinlik yaşam döngüsü geçişlerini işlemediği veya Firebase Cloud Messaging'nin gelen mesajları doğru şekilde işlemesi için gereken 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'nın yeni sürümleri (7.1.0 ve sonraki sürümler), AndroidManifest.xml dosyasında ek değişiklikler gerektiren JobIntentService kullanır.

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

Intent 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 bu intent filtresiyle etkinliği başlatır.

Otomatik başlatmayı önleme

FCM, cihaz hedefleme için bir kayıt jetonu oluşturur. Bir jeton oluşturulduğunda kitaplık, 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 ç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çerli olur.

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