Bắt đầu sử dụng Giải pháp gửi thông báo qua đám mây của Firebase trong các ứng dụng Unity

Hướng dẫn này mô tả cách bắt đầu sử dụng Firebase Cloud Messaging trong ứng dụng khách Unity để bạn có thể gửi thông báo một cách đáng tin cậy.

Để viết ứng dụng khách Firebase Cloud Messaging 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, nhưng bạn cần thiết lập thêm một số bước 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 2021 LTS trở lên. 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 của Apple) Cài đặt những thành phần sau:

  • Xcode 26.2 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 15 trở lên
  • Đối với tvOS – nhắm đến tvOS 15 trở lên
  • Đối với Android – nhắm đến cấp độ API mục tiêu 24 (Nougat) trở lên

• Thiết lập 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 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 Apple của bạn.
    • Bật Thông báo đẩy trong XCode trong phần App (Ứng dụng) > Capabilities (Khả năng).

  • Đối với Android – Trình mô phỏng phải sử dụng 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 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 một dự án Firebase để kết nối với dự án Unity. Hãy truy cập vào 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 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 về dự án, hãy nhấp vào biểu tượng Unity (plat_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 của dự án Unity mà bạn muốn đăng ký, 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ã 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 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.

   Bạn có thể tìm thấy mã nhận dạng dự án Unity ở đâu?

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

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

   • Đối với Android — Chuyển đến Android > Player Settings > Other Settings (Android > Cài đặt trình phát > Cài đặt khác).

   Mã dự án Unity là giá trị Mã nhận dạng gói (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à giá trị nhận dạng nội bộ, thuận tiện và chỉ bạn mới có thể nhìn thấy trong bảng điều khiển Firebase.

6. Nhấp vào Register app (Đă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 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.

   Bạn cần biết những 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 và ứng dụng. Để tìm hiểu thêm về tệp cấu hình này, hãy xem bài viết Tìm hiểu về các dự án Firebase.

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

   • Đảm bảo tên tệp cấu hình không có ký tự thừa, chẳng hạn như (2).

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 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 vị trí thuận tiện.

   • Bạn có thể tải lại SDK Firebase Unity 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. 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 Dịch vụ Google Play

Một số sản phẩm trong SDK Firebase Unity 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 có thể sử dụng 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à cập nhật Google Play services lên phiên bản bắt buộc (không 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.

Thiết lập với các nền tảng của Apple

Hãy làm theo hướng dẫn sau để thiết lập FCM với nền tảng Unity và Apple.

Tải khoá xác thực APNs lên

Tải khoá xác thực APNs lên Firebase. Nếu bạn 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. Trong bảng điều khiển Firebase, hãy chuyển đến phần settings Cài đặt > Chung. Sau đó, hãy nhấp vào thẻ Gửi thông báo qua đám mây.
2. Trong phần Khoá xác thực APN trong Cấu hình ứng dụng iOS, hãy nhấp vào Tải lên để tải khoá xác thực phát triển hoặc khoá xác thực chính thức lên, hoặc cả hai. Bạn phải cung cấp ít nhất một biểu trưng.
3. Duyệt đến vị trí 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 Apple Developer) 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

1. Nhấp vào dự án của bạn trong Xcode, sau đó chọn thẻ Chung trong Khu vực trình chỉnh sửa.
2. Di chuyển đến Linked Frameworks and Libraries (Thư viện và khung đượ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).
4. Nhấp vào dự án của bạn trong Xcode, sau đó chọn thẻ Capabilities (Khả năng) trong Editor area (Khu vực trình chỉnh sửa).
5. Chuyển Thông báo đẩy sang trạng thái Bật.
6. Di chuyển đến Chế độ nền, sau đó chuyển sang Bật.
7. Chọn hộp đánh dấu Thông báo từ xa trong phần Chế độ nền.

Khởi chạy Firebase Cloud Messaging

Bật tính năng đăng ký bằng Mã cài đặt Firebase

Để cho phép đăng ký thực thể ứng dụng của bạn với Firebase Cloud Messaging bằng Mã cài đặt Firebase (FID), trước tiên, bạn phải bật FID trong cấu hình của ứng dụng cho cả nền tảng Android và Apple:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

Đăng ký tham gia sự kiện FCM

Thư viện Firebase Cloud Messaging sẽ được khởi chạy khi thêm trình xử lý cho sự kiện RegistrationReceived hoặc MessageReceived.

Khi khởi chạy, Firebase Cloud Messaging sẽ đăng ký phiên bản ứng dụng khách để nhận thông báo bằng Mã cài đặt Firebase (FID). Ứng dụng nhận được FID cùng với sự kiện RegistrationReceived. Bạn nên lưu sự kiện này vào bộ nhớ đệm trên máy chủ để nhắm mục tiêu thiết bị cụ thể này cho các thông báo.

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

Cách thiết lập sẽ có dạng như sau:

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

Sau khi bạn nhận được Mã cài đặt Firebase, hãy gửi mã đó đến máy chủ ứng dụng và lưu trữ mã đó bằng phương thức bạn muốn.

Đăng ký theo cách thủ công khi tính năng khởi chạy tự động bị tắt

Bạn cũng có thể kích hoạt quá trình đăng ký theo cách thủ công bằng FCM trong thời gian chạy bằng cách sử dụng RegisterAsync():

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

Truy cập vào mã thông báo đăng ký FCM (không dùng nữa)

Nếu ứng dụng của bạn vẫn sử dụng các API mã thông báo không dùng nữa, bạn có thể theo dõi 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);
}

Thiết lập bằng nền tảng Android

Hãy làm theo hướng dẫn sau để thiết lập FCM bằng Unity và các nền tảng Android.

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

Firebase Cloud Messaging đi kèm với một hoạt động điểm truy cập tuỳ chỉnh 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 thực hiện thêm bất kỳ hành động nào.

Trình bổ trợ Unity Firebase Cloud Messaging trên Android đi kèm với hai 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 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 chuyển đổi vòng đời của activity onStop, onRestart hoặc triển khai onNewIntent cần thiết để Firebase Cloud Messaging xử lý chính xác các tin nhắn đến.

Định cấu hình một 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 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 cách tất cả các 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 trình bày 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 để 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 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);
}

Các phiên bản mới của SDK C++ của Firebase (từ 7.1.0 trở đi) sử dụng JobIntentService, yêu cầu 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>

Gửi thông báo 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 đị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.

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 thông báo trên khay hệ thống, nhưng nội dung thông báo đó sẽ không được thông báo cho FCM. Điều này có nghĩa là FirebaseMessage.Notification sẽ rỗng.

Tóm lại:

Xử lý thông báo 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 vào ứng dụng của bạn. Để nhận tin nhắn 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 mình. Bộ lọc ý định phải bắt được các đường liên kết sâu của miền. 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 để 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ủ 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.

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

FCM tạo mã thông báo đăng ký để nhắm mục tiêu theo thiết bị. Khi một mã thông báo được tạo, thư viện sẽ tải dữ liệu về 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). Bạn có thể 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:

<?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 thời gian chạy:

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

Giá trị này sẽ được giữ lại sau khi ứng dụng khởi động lại.

Các bước tiếp theo

Sau khi hoàn tất các bước thiết lập, bạn có thể chọn một trong số các cách sau để tiếp tục sử dụng FCM cho Unity:

• Gửi thông báo đến thiết bị
• Nhận thông báo trong ứng dụng Unity
• Gửi thông báo theo chủ đề