Unity ile Firebase Cloud Messaging istemci uygulaması kurma

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

Başlamadan önce

Ön koşullar

  • Unity 2021 LTS veya sonraki sürümleri yükleyin. Unity 2020 desteği kullanımdan kaldırıldı olarak kabul ediliyor ve bir sonraki ana sürümden sonra artık aktif olarak desteklenmeyecek. Önceki sürümler de uyumlu olabilir ancak etkin olarak desteklenmezler.

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

    • Xcode 13.3.1 veya sonraki sürümler
    • CocoaPods 1.12.0 veya üstü

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

    • iOS için: iOS 13 veya sonraki sürümleri hedefler.
    • tvOS için: tvOS 13 veya sonraki sürümleri hedefler.
    • Android için: API düzeyi 21'i (Lollipop) veya üstünü hedefler.

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

    • iOS veya tvOS için: Uygulamanızı çalıştırmak ve aşağıdaki görevleri tamamlamak için bir fiziksel cihaz kurun:

      • Apple Geliştirici hesabınız için bir Apple Anında Bildirim Kimlik Doğrulama Anahtarı edinin.
      • XCode'ta Uygulama > Özellikler bölümünde Push Bildirimleri'ni etkinleştirin.

    • Android için: Emülatörler, Google Play ile bir emülatör resmi 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 eklemeden önce, 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ğlanacak 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 () tıklayın.

    Firebase projenize daha önce 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 veya dilerseniz her iki hedefi de hemen aynı anda kaydetmeyi seçebilirsiniz.

  4. Unity projenizin platforma özgü kimliklerini girin.

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

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

  5. (İsteğe bağlı) Unity projenizin platforma özgü takma adlarını girin.
    Bu takma adlar, dahili ve 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. Firebase konsolu kurulum iş akışında platforma özel Firebase yapılandırma dosyalarınızı 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.

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

  3. Firebase konsolunda, 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 yerde açın.

  2. Açık Unity projenizde Assets > Paketi İçe Aktar > Özel Paket'e 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'i etkinleştirmenizi öneririz. Ayrıca, Analytics kurulumunu yaparken Analytics için Firebase paketini uygulamanıza eklemeniz gerekir.

    Analytics etkin

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

    Analytics etkin değil

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

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

  5. Firebase konsolunda, kurulum iş akışında Sonraki'yi tıklayın.

5. Adım: Google Play Hizmetleri sürümüyle ilgili gereksinimleri onaylayın

Android için Firebase Unity SDK'sı, Google Play services'ı gerektirir. SDK'nın kullanılabilmesi için bu sürümün güncel olması gerekir.

Uygulamanızın başına aşağıdaki using beyanını ve ilk kullanıma hazırlama 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 Firebase Unity SDK'sı tarafından gereken 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 desteği için APNs kimlik doğrulama anahtarınızı yükleme

APNs kimlik doğrulama anahtarınızı Firebase'e yükleyin. APN kimlik doğrulama anahtarınız yoksa Apple Developer Üye Merkezi'nde bir anahtar oluşturduğunuzdan emin olun.

  1. Firebase Konsolu'ndaki projenizde dişli simgesini, ardından Proje Ayarları'nı ve Cloud Mesajlaşma sekmesini seçin.

  2. iOS uygulaması yapılandırması bölümündeki APN kimlik doğrulama anahtarı'nda Yükle düğmesini tıklayın.

  3. Anahtarınızı kaydettiğiniz konuma gidin, anahtarı seçin ve Aç'ı tıklayın. Anahtarın anahtar kimliğini ekleyin ( Apple Developer Üye Merkezi'nde bulunur) ve Yükle'yi tıklayın.

Apple platformlarında push bildirimlerini etkinleştirme

1. adım: Kullanıcı bildirim çerçevesini ekleyin

  1. Xcode'da projeyi tıklayın ve Düzenleyici alanından Genel sekmesini seçin.

  2. Bağlı Çerçeveler ve Kitaplıklar'a gidin ve çerçeve eklemek için + düğmesini tıklayın.

  3. Görüntülenen pencerede UserBildirimler.framework'e gidin, ilgili girişi ve ardından Ekle'yi tıklayın.

2. adım: Push bildirimlerini etkinleştirin

  1. Xcode'da projeyi tıklayın, ardından Düzenleyici alanından Özellikler sekmesini seçin.

  2. Push Bildirimleri'ni Açık konuma getirin.

  3. Arka Plan Modları'na gidin ve Açık'a getirin.

  4. Arka Plan Modları bölümünde Uzaktan bildirimler onay kutusunu işaretleyin.

Firebase Cloud Messaging başlatılıyor

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

Başlatma sonrasında istemci uygulama örneği için bir kayıt jetonu istenir. Uygulama, OnTokenReceived etkinliğiyle birlikte jetonu alır. Bu jeton daha sonra kullanılmak üzere önbelleğe alınmalıdır. Mesajlar için bu cihazı hedeflemek istiyorsanız bu jetona ihtiyacınız olacaktır.

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

Tüm ayarlar aşağıdaki gibi görünür:

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

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

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

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

Android'de Firebase Cloud Messaging, varsayılan UnityPlayerActivity'un yerini alan ö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 başka bir işlem yapmanız gerekmez. Varsayılan giriş noktası etkinliğini kullanmayan veya kendi Assets/Plugins/AndroidManifest.xml'lerini sağlayan uygulamaların ek yapılandırma yapması gerekir.

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

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar, UnityPlayerActivity standardının yerine geçen MessagingUnityPlayerActivity adlı bir etkinlik içeriyor.
  • Assets/Plugins/Android/AndroidManifest.xml, uygulamaya giriş noktası olarak MessagingUnityPlayerActivity kullanmasını söyler.

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şleyebilmesi için gerekli olan onNewIntent'ı uygulamadığı için bu dosyalar sağlanır.

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

Uygulamanız varsayılan UnityPlayerActivity kullanmıyorsa sağlanan AndroidManifest.xml'ı 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'ü genişletiyorsa bunun yerine gerekli tüm yöntemleri uygulayan com.google.firebase.MessagingUnityPlayerActivity'ü genişletebilirsiniz.

Özel bir etkinlik kullanıyorsanız ve com.google.firebase.MessagingUnityPlayerActivity'ü genişletmiyorsanız aşağıdaki snippet'leri etkinliğinize 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 older 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 ensures 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 sonraki sürümler) JobIntentService kullanır. Bu da AndroidManifest.xml dosyasında ek değişiklikler yapılmasını gerektirir.

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

Android'de mesaj teslimiyle ilgili not

Uygulama hiç çalışmadığında ve bir kullanıcı bir bildirime dokunduğunda, mesaj varsayılan olarak FCM'ın yerleşik geri çağırma işlevleri üzerinden yönlendirilmez. Bu durumda, mesaj yükü, uygulamayı başlatmak için kullanılan bir Intent aracılığıyla alınır.

Uygulama arka plandayken alınan iletilerin bildirim alanı, sistem tepsisi bildirimini doldurmak için kullanılır, ancak bu bildirim içeriği FCM ürününe iletilmez. Yani FirebaseMessage.Notification null olur.

Özet olarak:

Uygulama durumu Bildirim Veriler İkisi de
Ön plan Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Arka plan Sistem tepsisi Firebase.Messaging.FirebaseMessaging.MessageReceived Bildirim: sistem tepsisi
Veriler: intent'in ekstralarında.

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 katılım almak istiyorsanız FCM'yi (ve Android'de Analytics'i) devre dışı bırakarak yapılandırırken jeton oluşturulmasını önleyebilirsiniz. Bunu yapmak için Apple'da Info.plist cihazınıza (GoogleService-Info.plist değil) veya Android'de AndroidManifest.xml cihazınıza meta veri değeri ekleyin:

Android

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

Swift

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Bu değer, ayarlandıktan sonra uygulama yeniden başlatılsa bile değişmez.

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. Amaç filtresi, alanınızın derin bağlantılarını yakalamalıdır. Mesajlarınız derin bağlantı içermiyorsa bu yapılandırma gerekli değildir. 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>

Amaç filtresini daha esnek hale getirmek için joker karakter belirtmek de mümkündür. Ö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 şemanın ve barındırıcının bağlantısını içeren bir bildirime dokunduğunda uygulamanız, bağlantıyı işlemek için etkinliği bu intent filtresiyle başlatır.

Sonraki adımlar

İstemci uygulamasını ayarladıktan sonra Firebase ile yayın mesajları ve konu mesajları göndermeye hazırsınız demektir. Daha fazla bilgi edinmek için bu işlevi gösteren hızlı başlangıç örneğine göz atın.

Uygulamanıza daha gelişmiş başka davranışlar eklemek için uygulama sunucusundan mesaj göndermeyle ilgili kılavuzlara bakın:

Bu özelliklerden yararlanmak için sunucu uygulamasına ihtiyacınız olacağını unutmayın.