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 khách Firebase Cloud Messaging trên nhiều nền tảng bằng Unity, hãy sử dụng API Firebase Cloud Messaging. SDK Unity hoạt động cho cả Android và Apple, nhưng cần thực hiện thêm một số bước thiết lập cho từng nền tảng.

Trước khi bắt đầu

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

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

• (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 13 trở lên
  • Đối với tvOS - nhắm mục tiêu tvOS 13 trở lên
  • Đối với Android – nhắm mục tiêu 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 nhiệm vụ sau:

    • Lấy Khoá xác thực thông báo đẩy của Apple cho Tài khoản nhà phát triển của Apple.
    • Bật thông báo đẩy trong XCode dưới App > Chức năng.

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

• Đăng nhập vào Firebase bằng tài khoản Google tài khoản.

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

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 Firebase dự án để kết nối với dự án Unity. Truy cập vào bài viết Tìm hiểu về Firebase Các dự án để 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 Firebase của mình dự án.

1. Chuyển đến 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 (plat_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 Thêm ứng dụng để hiển thị các tuỳ chọn 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ờ cùng lúc.

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 ID iOS của dự án Unity vào Gói iOS Mã nhận dạng .

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

   Bạn tìm thấy mã dự án Unity của mình ở đâu?

   Mở dự án Unity trong IDE Unity, sau đó chuyển đến phần cài đặt cho mỗi nền tảng:

   • Đối với iOS – Chuyển đến phần Build Settings > (Cài đặt bản dựng >) iOS.

   • Đối với Android — Chuyển đến Android > Cài đặt trình phát > Chế độ cài đặt khác.

   Mã dự án Unity của bạn là giá trị Bundle nhận dạng (mã ví dụ: com.yourcompany.yourproject).

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.
   Những biệt hiệu này là mã nhận dạng tiện lợi nội bộ và chỉ hiển thị cho bạn 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. Nhận(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 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.

   Bạn cần biết gì về tệp cấu hình này?

   • Tệp cấu hình Firebase chứa các giá trị nhận dạng duy nhất nhưng không bí mật của dự án của bạn. Để tìm hiểu thêm về tệp cấu hình này, hãy truy cập vào Tìm hiểu về Firebase Dự án.

   • Bạn có thể tải cấu hình Firebase xuống tệp bất cứ lúc nào.

   • Hãy đảm bảo tên của tệp cấu hình không được nối thêm các ký tự bổ sung, như (2).

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

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

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

   • SDK Firebase Unity 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 Thành phần > Nhập gói > Gói tuỳ chỉnh.

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

   Để 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 bạn. 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 bạn.

   Đã 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. Quay lại 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 của Dịch vụ Google Play

SDK Firebase Unity dành cho Android yêu cầu Google Play services phải 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 vào đầu . Bạn có thể kiểm tra và tuỳ ý cập nhật Google Play services thành phiên bản mà SDK Firebase Unity yêu cầu trước khi gọi bất kỳ phiên bản 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 APN lên để được Apple hỗ trợ

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

1. Bên trong dự án của bạn trong 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), sau đó chọn Thẻ Giải pháp gửi thông báo qua đám mây.

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

3. Duyệt tới vị trí bạn đã lưu khoá của mình, 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 dành cho nhà phát triển của 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) trên Khu vực chỉnh sửa.

2. Cuộn xuống Linked Frameworks and Libraries (Khung và thư viện được liên kết), rồi nhấp vào +. để thêm khung.

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

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

1. Nhấp vào dự án trong Xcode, rồi chọn thẻ Khả năng trên Khu vực 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).

Khởi chạy Firebase Cloud Messaging

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 sự kiện TokenReceived hoặc MessageReceived.

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

Ngoài ra, bạn cần đăng ký tham gia sự kiện OnMessageReceived nếu bạn 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, Firebase Cloud Messaging đi kèm với một điểm truy cập tuỳ chỉnh hoạt động thay thế UnityPlayerActivity mặc định. Nếu bạn không sử dụng một điểm truy cập tuỳ chỉnh, việc thay thế này diễn ra tự động và bạn không nên thực hiện hành động bất kỳ bổ sung. Ứng dụng không dùng điểm truy cập mặc định Hoạt động hoặc việc cung cấp Assets/Plugins/AndroidManifest.xml của riêng chúng sẽ cần cấu hình bổ sung.

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

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar có chứa có tên là MessagingUnityPlayerActivity sẽ thay thế cho hoạt động chuẩn UnityPlayerActivity.
• 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 để Firebase Cloud Messaging có thể thực hiện chính xác xử lý 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 dùng UnityPlayerActivity mặc định, bạn sẽ phải xoá AndroidManifest.xml đã cung cấp và đảm bảo rằng hoạt động tuỳ chỉnh của bạn xử lý đúng cách tất cả chuyển đổi của Vòng đời hoạt động trên Android (ví dụ về cách thực hiện việc này được trình bày bên dưới). Nếu tuỳ chỉnh hoạt động mở rộng UnityPlayerActivity. Thay vào đó, 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 bạn đ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 trong Hoạt động của bạn.

/**
 * 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à yêu cầu các nội dung sửa đổi bổ sung 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, tin nhắn không được định tuyến thông qua tính năng tích hợp của FCM lệnh gọi lại. Trong trường hợp này, phần tải tin nhắn được nhận thông qua Intent dùng để khởi động ứng dụng.

Tin nhắn nhận được khi ứng dụng chạy trong nền có nội dung là trường thông báo của họ được dùng để điền thông báo vào 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:

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 giá trị nhận dạng và dữ liệu cấu hình cho Firebase. Nếu bạn muốn nhận được chọn tham gia 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 vô hiệu hoá 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 của bạn (không phải GoogleService-Info.plist) trên Apple hoặc AndroidManifest.xml trên 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>

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.

Xử lý thư có đường liên kết sâu trên Android

FCM cho phép gửi tin nhắn chứa đường liên kết sâu đến ứng dụng của bạn. Để nhận thư chứa đườ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ý đường liên kết sâu cho ứng dụng của bạn. Bộ lọc ý định sẽ tìm đường liên kết sâu trong miền của bạn. Nếu thư của bạn không chứa liên kết sâu, 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 một ký tự đại diện để tăng bộ lọc ý định linh hoạt. 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 thông báo chứa đường liên kết đến lược đồ và lưu trữ 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ý .

Các bước tiếp theo

Sau khi thiết lập ứng dụng, bạn đã sẵn sàng gửi chủ đề và kênh tiếp theo tin nhắn 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 của bạn, hãy xem hướng dẫn gửi thông báo từ máy chủ ứng dụng:

• Gửi tin nhắn theo chủ đề
• Gửi đến các nhóm thiết bị
• Gửi thông báo ngược dòng

Xin lưu ý rằng bạn cần có triển khai máy chủ để tận dụng các tính năng AI mới.