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 Gửi thông báo qua đám mây của Firebase đa nền tảng bằng Unity, hãy sử dụng API Gửi thông báo qua đám mây của Firebase. SDK Unity 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 2019.1 trở lên. Các phiên bản trước đó cũng có thể tương thích nhưng sẽ không được hỗ trợ. Chúng tôi không còn hỗ trợ Unity 2019.1 nữa và sẽ không còn được hỗ trợ sau bản phát hành chính tiếp theo.

  • (chỉ dành cho nền tảng của Apple) Cài đặt như sau:

    • Xcode 13.3.1 trở lên
    • CacaoPods 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 mục tiêu iOS 11 trở lên
    • Đối với tvOS - nhắm mục tiêu tvOS 12 trở lên
    • Đối với Android – nhắm đến API cấp 19 (KitKat) trở lên

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

    • Đối với iOS hoặc tvOS — Thiết lập thiết bị thực để chạy ứng dụng và hoàn thành các tác vụ sau:

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

Nếu chưa có dự án Unity và chỉ muốn dùng thử sản phẩm của Firebase, bạn có thể tải một trong các mẫu bắt đầu 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 dự án Firebase để kết nối với dự án Unity. Hãy xem bài viết 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. Truy cập vào bảng điều khiển của Firebase.

  2. Ở giữa trang tổng quan về dự án, hãy nhấp vào biểu tượng Unity () để bắt đầu 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 Add app (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 của dự án Unity mà bạn muốn đăng ký, hoặc thậm chí bạn có thể chọn đăng ký cả hai mục tiêu ngay bây giờ.

  4. Nhập(các) mã nhận dạng 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 Android package name (Tên gói Android).
      Các thuật ngữ package name (tên gói) và application ID (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.
    Các biệt hiệu này là giá trị nhận dạng nội bộ, thuận tiện và chỉ bạn mới nhìn thấy trong bảng điều khiển của 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 của bạn trong quy trình thiết lập bảng điều khiển của Firebase.

    • Đối với iOS — Nhấp vào Download GoogleService-Info.plist.

    • Đố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. Quay lại bảng điều khiển của 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 của Firebase, hãy nhấp vào Tải Firebase Unity SDK xuống, sau đó giải nén SDK ở nơi thuận tiện.

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

    • Firebase Unity SDK không dành riêng cho từng 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. Từ SDK đã giải nén, hãy chọn các sản phẩm Firebase được 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 Giải pháp gửi thông báo qua đám mây của Firebase, 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 dành 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 Giải pháp gửi thông báo qua đám mây của Firebase: FirebaseMessaging.unitypackage

    Chưa bật Analytics

    Thêm gói cho Giải pháp gửi thông báo qua đám mây của Firebase: 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. Quay lại bảng điều khiển của 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 của Dịch vụ Google Play

Firebase Unity SDK dành cho Android yêu cầu Dịch vụ Google Play và dịch vụ này phải được cập nhật trước khi có thể sử dụng SDK.

Thêm câu lệnh using và mã khởi chạy sau đây ở đầu ứng dụng. Bạn có thể kiểm tra và tuỳ ý cập nhật Dịch vụ Google Play lên phiên bản mà SDK Unity của Firebase yêu cầu 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.

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ẻ Chung trong khu vực Trình 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 khung.

  3. Trong cửa sổ xuất hiện, hãy di chuyển đến UserNotifications.framework, nhấp vào mục nhập đó, 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 (Khả năng) trong khu vực Editor (Trình chỉnh sửa).

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

  3. Cuộn xuống Chế độ nền, sau đó chuyển sang Bật.

  4. Chọn hộp kiểm Remote notifications (Thông báo từ xa) bên dưới Background Modes (Chế độ nền).

Chạy Giải pháp gửi thông báo qua đám mây của Firebase

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

Sau khi khởi chạy, hệ thống sẽ yêu cầu mã thông báo đăng ký cho thực thể ứng dụng. Ứng dụng sẽ nhận được mã thông báo cùng với sự kiện OnTokenReceived. Sự kiện này sẽ được lưu vào bộ nhớ đệm để sử dụng sau này. 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 cho các tin nhắn.

Ngoài ra, bạn cần đăng ký sự kiện OnMessageReceived nếu muốn nhận 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, Giải pháp gửi thông báo qua đám mây của Firebase đi kèm với một hoạt động điểm truy cập tuỳ chỉnh sẽ thay thế UnityPlayerActivity mặc định. Nếu bạn không sử dụng điểm truy cập tuỳ chỉnh, quá trình thay thế sẽ tự động diễn ra và bạn không cần phải làm gì thêm. Những ứng dụng không sử dụng Hoạt động điểm truy cập mặc định hoặc cung cấp Assets/Plugins/AndroidManifest.xml của riêng chúng sẽ cần thêm cấu hình.

Trình bổ trợ Unity của giải pháp Gửi thông báo qua đám mây của Firebase 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 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 đến ứng dụng.

Các tệp này được cung cấp vì UnityPlayerActivity mặc định không xử lý các chuyển đổi vòng đời hoạt động onStop, onRestart hoặc triển khai onNewIntent cần thiết để Giải pháp gửi thông báo qua đám mây của Firebase xử lý chính xác các tin nhắn đế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 sử dụng UnityPlayerActivity mặc định, bạn cần xoá AndroidManifest.xml đã cung cấp và đảm bảo hoạt động tuỳ chỉnh của bạn xử lý đúng cách tất cả các lượt chuyển đổi của Vòng đời hoạt động trên Android (xem ví dụ về cách thực hiện việc này ở bên dưới). Nếu hoạt động tuỳ chỉnh của bạn mở rộng UnityPlayerActivity, bạn có thể mở rộng com.google.firebase.MessagingUnityPlayerActivity để 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 đưa 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 SDK C++ của Firebase (7.1.0 trở lên) sử dụng JobIntentService và cầ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="false" >
</service>

Lưu ý về tính năng gửi tin nhắn trên Android

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, theo mặc định, thông báo sẽ không được gửi 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, các phần tải tin nhắn sẽ được nhận thông qua một Intent dùng để khởi động ứng dụng.

Các tin nhắn nhận được khi ứng dụng đang ở chế độ nền sẽ có nội dung của trường thông báo được dùng để điền vào 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 việc khởi chạy tự động

FCM tạo một mã thông báo đăng ký để nhắm mục tiêu theo thiết bị. Khi 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 được chọn sử dụ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 tại thời điểm định cấu hình bằng cách tắt FCM (và trên Android, Analytics). Để thực hiện việc này, hãy thêm 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 trong thời gian chạy:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

Giá trị này sẽ vẫn tồn tại khi ứng dụng khởi động lại sau khi đặt.

FCM cho phép gửi thông báo chứa đường liên kết sâu đến ứng dụng của bạn. Để nhận thông báo chứa đường liên kết sâu, bạn phải thêm bộ lọc ý định mới vào hoạt động xử lý đường liên kết sâu cho ứng dụng. Bộ lọc ý định sẽ nắm bắt các đường liên kết sâu trong miền của bạn. Nếu thông báo của bạn không chứa đường liên kết sâu, thì cấu hình này là không cần thiết. Trong 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 chứa đường liên kết đến giao thức và máy chủ lưu trữ 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, bạn có thể gửi các thông báo theo chủ đề và thông báo tiếp theo 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 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 cần triển khai máy chủ để sử dụng các tính năng này.