Thiết lập ứng dụng nhắn tin qua đám mây của Firebase bằng Unity

Để viết ứng dụng Firebase Cloud Messaging trên nhiều nền tảng bằng Unity, hãy sử dụng API Firebase Cloud Messaging. Unity SDK hoạt động cho cả Android và Apple, với một số chế độ thiết lập bổ sung cần thiết cho mỗi nền tảng.

Trước khi bắt đầu

Điều kiện tiên quyết

  • Cài đặt Unity 2021 LTS trở lên. Chúng tôi coi việc hỗ trợ Unity 2020 là không còn được dùng nữa và sẽ không còn hỗ trợ tích cực sau bản phát hành chính tiếp theo. Các phiên bản cũ hơn cũng có thể tương thích nhưng sẽ không được hỗ trợ tích cực.

  • (Chỉ dành cho nền tảng Apple) Cài đặt những nội dung sau:

    • Xcode 13.3.1 trở lên
    • CocoaPods 1.12.0 trở lên

  • Đảm bảo rằng dự án Unity của bạn đáp ứng các yêu cầu sau:

    • Đối với iOS – nhắm đến iOS 13 trở lên
    • Đối với tvOS – nhắm đến tvOS 13 trở lên
    • Đối với Android – nhắm đến API cấp 21 (Lollipop) trở lên

  • Thiết lập một thiết bị hoặc sử dụng trình mô phỏng để chạy dự án Unity.

    • Đối với iOS hoặc tvOS – Thiết lập một thiết bị thực để chạy ứng dụng của bạn và hoàn tất các việc sau:

      • Lấy Khoá xác thực thông báo đẩy của Apple cho tài khoản Apple Developer của bạn.
      • Bật thông báo đẩy trong XCode trong mục App (Ứng dụng) > Capabilities (Tính năng).

    • Đối với Android – Trình mô phỏng phải sử dụng một hình ảnh trình mô phỏng có Google Play.

Nếu chưa có dự án Unity và chỉ muốn dùng thử một sản phẩm của Firebase, bạn có thể tải một trong các mẫu khởi động nhanh của chúng tôi xuống.

Bước 1: Tạo dự án Firebase

Trước khi có thể thêm Firebase vào dự án Unity, bạn cần tạo một dự án Firebase để kết nối với dự án Unity. Hãy truy cập vào trang Tìm hiểu về các dự án Firebase để tìm hiểu thêm về các dự án Firebase.

Bước 2: Đăng ký ứng dụng của bạn với Firebase

Bạn có thể đăng ký một hoặc nhiều ứng dụng hoặc trò chơi để kết nối với dự án Firebase của mình.

  1. Chuyển đến bảng điều khiển Firebase.

  2. Ở giữa trang tổng quan của dự án, hãy nhấp vào biểu tượng Unity () để chạy quy trình thiết lập.

    Nếu bạn đã thêm một ứng dụng vào dự án Firebase, hãy nhấp vào Thêm ứng dụng để hiển thị các lựa chọn về nền tảng.

  3. Chọn mục tiêu bản dựng mà bạn muốn đăng ký cho dự án Unity của mình, hoặc bạn thậm chí có thể chọn đăng ký cả hai mục tiêu cùng một lúc.

  4. Nhập(các) mã dành riêng cho nền tảng của dự án Unity.

    • Đối với iOS – Nhập mã nhận dạng iOS của dự án Unity vào trường Mã nhận dạng gói iOS.

    • Đối với Android – Nhập mã nhận dạng Android của dự án Unity vào trường Tên gói Android.
      Các thuật ngữ tên gói và mã ứng dụng thường được dùng thay thế cho nhau.

  5. (Không bắt buộc) Nhập(các) biệt hiệu dành riêng cho nền tảng của dự án Unity.
    Đây là tên gọi thân mật nội bộ, là các giá trị nhận dạng thuận tiện và chỉ bạn mới thấy được trong bảng điều khiển Firebase.

  6. Nhấp vào Đăng ký ứng dụng.

Bước 3: Thêm tệp cấu hình Firebase

  1. Lấy(các) tệp cấu hình Firebase dành riêng cho nền tảng trong quy trình thiết lập bảng điều khiển Firebase.

    • Đối với iOS – Nhấp vào Tải GoogleService-Info.plist xuống.

    • Đối với Android – Nhấp vào Tải google-services.json xuống.

  2. Mở cửa sổ Project (Dự án) của dự án Unity, sau đó di chuyển (các) tệp cấu hình vào thư mục Assets.

  3. Trong bảng điều khiển Firebase, trong quy trình thiết lập, hãy nhấp vào Tiếp theo.

Bước 4: Thêm Firebase Unity SDK

  1. Trong bảng điều khiển Firebase, hãy nhấp vào Tải SDK Firebase Unity xuống, sau đó giải nén SDK ở một nơi thuận tiện.

    • Bạn có thể tải lại Firebase Unity SDK xuống bất cứ lúc nào.

    • SDK Firebase Unity không dành riêng cho nền tảng.

  2. Trong dự án Unity đang mở, hãy chuyển đến Assets (Tài sản) > Import Package (Nhập gói) > Custom Package (Gói tuỳ chỉnh).

  3. Trong SDK đã giải nén, hãy chọn các sản phẩm được Firebase hỗ trợ mà bạn muốn sử dụng trong ứng dụng của mình.

    Để có trải nghiệm tối ưu với Firebase Cloud Messaging, bạn nên bật Google Analytics trong dự án của mình. Ngoài ra, trong quá trình thiết lập Analytics, bạn cần thêm gói Firebase cho Analytics vào ứng dụng của mình.

    Đã bật Analytics

    • Thêm gói Firebase cho Google Analytics: FirebaseAnalytics.unitypackage
    • Thêm gói cho Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    Chưa bật Analytics

    Thêm gói cho Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. Trong cửa sổ Import Unity Package (Nhập gói Unity), hãy nhấp vào Import (Nhập).

  5. Trong bảng điều khiển Firebase, trong quy trình thiết lập, hãy nhấp vào Tiếp theo.

Bước 5: Xác nhận các yêu cầu về phiên bản Dịch vụ Google Play

Một số sản phẩm trong SDK Firebase Unity dành cho Android yêu cầu Google Play services. Tìm hiểu những sản phẩm có phần phụ thuộc này. Bạn phải cập nhật Google Play services thì mới sử dụng được các sản phẩm đó.

Thêm câu lệnh using và mã khởi chạy sau đây vào đầu ứng dụng của bạn. Bạn có thể kiểm tra và tuỳ ý cập nhật Google Play services lên phiên bản bắt buộc trước khi gọi bất kỳ phương thức nào khác trong SDK.

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.
  }
});

Dự án Unity của bạn đã được đăng ký và định cấu hình để sử dụng Firebase.

Tải khoá xác thực APNs lên để được Apple hỗ trợ

Tải khoá xác thực APNs lên Firebase. Nếu bạn chưa có khoá xác thực APNs, hãy nhớ tạo một khoá trong Trung tâm thành viên của nhà phát triển Apple.

  1. Trong dự án của bạn trên bảng điều khiển Firebase, hãy chọn biểu tượng bánh răng, chọn Project Settings (Cài đặt dự án), rồi chọn thẻ Cloud Messaging (Nhắn tin qua đám mây).

  2. Trong phần Khoá xác thực APNs trong Cấu hình ứng dụng iOS, hãy nhấp vào nút Tải lên.

  3. Duyệt đến vị trí mà bạn đã lưu khoá, chọn khoá đó rồi nhấp vào Mở. Thêm mã khoá cho khoá (có trong Trung tâm thành viên của nhà phát triển Apple) rồi nhấp vào Tải lên.

Bật thông báo đẩy trên các nền tảng của Apple

Bước 1: Thêm khung thông báo cho người dùng

  1. Nhấp vào dự án trong Xcode, sau đó chọn thẻ General (Chung) trong Editor area (Khu vực chỉnh sửa).

  2. Di chuyển xuống phần Linked Frameworks and Libraries (Khung và thư viện được liên kết), sau đó nhấp vào nút + để thêm một khung.

  3. Trong cửa sổ xuất hiện, hãy di chuyển đến UserNotifications.framework, nhấp vào mục đó rồi nhấp vào Add (Thêm).

Bước 2: Bật thông báo đẩy

  1. Nhấp vào dự án trong Xcode, sau đó chọn thẻ Capabilities (Tính năng) trong Editor area (Khu vực chỉnh sửa).

  2. Chuyển Thông báo đẩy sang trạng thái Bật.

  3. Di chuyển xuống phần Chế độ nền, sau đó chuyển sang trạng thái Bật.

  4. Chọn hộp đánh dấu Remote notifications (Thông báo từ xa) trong mục Background Modes (Chế độ nền).

Khởi chạy Firebase Cloud Messaging

Thư viện Giải pháp gửi thông báo qua đám mây của Firebase sẽ được khởi chạy khi bạn thêm trình xử lý cho sự kiện TokenReceived hoặc MessageReceived.

Khi khởi chạy, một mã thông báo đăng ký sẽ được yêu cầu cho phiên bản ứng dụng khách. Ứng dụng sẽ nhận được mã thông báo bằng sự kiện OnTokenReceived. Mã thông báo này cần được lưu vào bộ nhớ đệm để sử dụng sau. Bạn sẽ cần mã thông báo này nếu muốn nhắm đến thiết bị cụ thể này để gửi thông báo.

Ngoài ra, bạn cần đăng ký sự kiện OnMessageReceived nếu muốn nhận được tin nhắn đến.

Toàn bộ quá trình thiết lập sẽ có dạng như sau:

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

Định cấu hình Hoạt động điểm truy cập Android

Trên Android, Firebase Cloud Messaging đi kèm với một hoạt động tuỳ chỉnh tại điểm truy cập thay thế UnityPlayerActivity mặc định. Nếu không sử dụng điểm truy cập tuỳ chỉnh, thì quá trình thay thế này sẽ diễn ra tự động và bạn không cần làm gì thêm. Những ứng dụng không sử dụng Activity điểm truy cập mặc định hoặc cung cấp Assets/Plugins/AndroidManifest.xml riêng sẽ cần có cấu hình bổ sung.

Firebase Cloud Messaging Trình bổ trợ Unity trên Android đi kèm với 2 tệp bổ sung:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar chứa một hoạt động có tên là MessagingUnityPlayerActivity thay thế UnityPlayerActivity tiêu chuẩn.
  • Assets/Plugins/Android/AndroidManifest.xml hướng dẫn ứng dụng sử dụng MessagingUnityPlayerActivity làm điểm truy cập vào ứng dụng.

Các tệp này được cung cấp vì UnityPlayerActivity mặc định không xử lý các quá trình chuyển đổi vòng đời hoạt động onStop, onRestart hoặc triển khai onNewIntent cần thiết để Firebase Cloud Messaging xử lý chính xác các thông báo đến.

Định cấu hình Hoạt động điểm truy cập tuỳ chỉnh

Nếu ứng dụng của bạn không dùng UnityPlayerActivity mặc định, bạn sẽ cần xoá AndroidManifest.xml được cung cấp và đảm bảo rằng hoạt động tuỳ chỉnh của bạn xử lý đúng tất cả các quá trình chuyển đổi của Vòng đời hoạt động của Android (ví dụ về cách thực hiện việc này được minh hoạ bên dưới). Nếu hoạt động tuỳ chỉnh của bạn mở rộng UnityPlayerActivity, thì bạn có thể mở rộng com.google.firebase.MessagingUnityPlayerActivity thay vì UnityPlayerActivity. com.google.firebase.MessagingUnityPlayerActivity sẽ triển khai tất cả các phương thức cần thiết.

Nếu đang sử dụng một Hoạt động tuỳ chỉnh và không mở rộng com.google.firebase.MessagingUnityPlayerActivity, bạn nên thêm các đoạn mã sau vào Hoạt động của mình.

/**
 * 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);
}

Các phiên bản mới của Firebase C++ SDK (từ 7.1.0 trở lên) sử dụng JobIntentService. Điều này đòi hỏi bạn phải sửa đổi thêm trong tệp AndroidManifest.xml.

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

Lưu ý về việc gửi tin nhắn trên Android

Theo mặc định, khi ứng dụng hoàn toàn không chạy và người dùng nhấn vào một thông báo, thông báo sẽ không được định tuyến thông qua các lệnh gọi lại tích hợp của FCM. Trong trường hợp này, tải trọng thông báo được nhận thông qua một Intent dùng để khởi động ứng dụng.

Những tin nhắn nhận được khi ứng dụng ở chế độ nền sẽ có nội dung của trường thông báo được dùng để điền sẵn thông báo trên khay hệ thống, nhưng nội dung thông báo đó sẽ không được truyền đến FCM. Tức là FirebaseMessage.Notification sẽ có giá trị rỗng.

Tóm lại:

Trạng thái ứng dụng Thông báo Dữ liệu Cả hai
Màu nổi Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Thông tin khái quát Khay hệ thống Firebase.Messaging.FirebaseMessaging.MessageReceived Thông báo: khay hệ thống
Dữ liệu: trong phần bổ sung của ý định.

Ngăn quá trình khởi chạy tự động

FCM tạo mã đăng ký để nhắm đến thiết bị. Khi một mã thông báo được tạo, thư viện sẽ tải dữ liệu cấu hình và giá trị nhận dạng lên Firebase. Nếu muốn nhận được sự đồng ý rõ ràng trước khi sử dụng mã thông báo, bạn có thể ngăn việc tạo mã thông báo tại thời điểm định cấu hình bằng cách tắt FCM (và Analytics trên Android). Để làm việc này, hãy thêm một giá trị siêu dữ liệu vào Info.plist (không phải GoogleService-Info.plist) trên Apple hoặc AndroidManifest.xml trên Android:

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

Để bật lại FCM, bạn có thể thực hiện một lệnh gọi thời gian chạy:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Giá trị này vẫn giữ nguyên khi ứng dụng khởi động lại sau khi được đặt.

FCM cho phép gửi các thông báo có chứa một đường liên kết sâu vào ứng dụng của bạn. Để nhận các thông báo có chứa một đường liên kết sâu, bạn phải thêm một bộ lọc ý định mới vào hoạt động xử lý các đường liên kết sâu cho ứng dụng của mình. Bộ lọc ý định này sẽ nắm bắt các đường liên kết sâu của miền. Nếu thông báo của bạn không chứa đường liên kết sâu, thì bạn không cần phải thiết lập cấu hình này. Trong tệp AndroidManifest.xml:

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

Bạn cũng có thể chỉ định ký tự đại diện để giúp bộ lọc ý định linh hoạt hơn. Ví dụ:

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

Khi người dùng nhấn vào một thông báo có chứa đường liên kết đến lược đồ và máy chủ mà bạn chỉ định, ứng dụng của bạn sẽ bắt đầu hoạt động bằng bộ lọc ý định này để xử lý đường liên kết.

Các bước tiếp theo

Sau khi thiết lập ứng dụng khách, bạn đã sẵn sàng gửi các thông báo truyền tin và thông báo theo chủ đề bằng Firebase. Để tìm hiểu thêm, hãy xem mẫu bắt đầu nhanh minh hoạ chức năng này.

Để thêm các hành vi khác, nâng cao hơn vào ứng dụng, hãy xem hướng dẫn gửi thông báo từ máy chủ ứng dụng:

Xin lưu ý rằng bạn sẽ cần triển khai máy chủ để sử dụng các tính năng này.