| เลือกแพลตฟอร์ม | iOS+ Android เว็บ Flutter Unity C++ |
คู่มือนี้อธิบายวิธีเริ่มต้นใช้งาน Firebase Cloud Messaging ในแอปไคลเอ็นต์ Unity เพื่อให้คุณส่งข้อความได้อย่างน่าเชื่อถือ
หากต้องการเขียนแอปไคลเอ็นต์ Firebase Cloud Messaging ข้ามแพลตฟอร์มด้วย Unity ให้ใช้ API Firebase Cloud Messaging Unity SDK ใช้ได้กับทั้ง Android และ Apple โดยต้องมีการตั้งค่าเพิ่มเติมสำหรับแต่ละแพลตฟอร์ม
ก่อนเริ่มต้น
ข้อกำหนดเบื้องต้น
ติดตั้ง Unity 2021 LTS ขึ้นไป เวอร์ชันก่อนหน้าอาจใช้งานร่วมกันได้ แต่เราจะไม่รองรับอย่างเต็มที่
(แพลตฟอร์ม Apple เท่านั้น) ติดตั้งรายการต่อไปนี้
- Xcode 26.2 ขึ้นไป
- CocoaPods 1.12.0 ขึ้นไป
ตรวจสอบว่าโปรเจ็กต์ Unity เป็นไปตามข้อกำหนดต่อไปนี้
- สำหรับ iOS - กำหนดเป้าหมายเป็น iOS 15 ขึ้นไป
- สำหรับ tvOS - กำหนดเป้าหมายเป็น tvOS 15 ขึ้นไป
- สำหรับ Android - กำหนดเป้าหมายเป็น API ระดับ 24 (Nougat) ขึ้นไป
ตั้งค่าอุปกรณ์หรือใช้โปรแกรมจำลองเพื่อเรียกใช้โปรเจ็กต์ Unity
สำหรับ iOS หรือ tvOS — ตั้งค่าอุปกรณ์จริงเพื่อเรียกใช้แอป และทำงานต่อไปนี้ให้เสร็จสมบูรณ์
- รับคีย์การตรวจสอบสิทธิ์ข้อความ Push ของ Apple สำหรับบัญชีนักพัฒนาแอป Apple
- เปิดใช้ข้อความ Push ใน XCode ที่ส่วนแอป > ความสามารถ
สำหรับ Android - โปรแกรมจำลองต้องใช้อิมเมจโปรแกรมจำลองกับ Google Play
หากยังไม่มีโปรเจ็กต์ Unity และต้องการลองใช้ผลิตภัณฑ์ Firebase คุณสามารถดาวน์โหลดตัวอย่างการเริ่มต้นใช้งานด่วนของเราได้
ขั้นตอนที่ 1: สร้างโปรเจ็กต์ Firebase
ก่อนที่จะเพิ่ม Firebase ลงในโปรเจ็กต์ Unity คุณต้องสร้างโปรเจ็กต์ Firebase เพื่อเชื่อมต่อกับโปรเจ็กต์ Unity ดูข้อมูลเพิ่มเติมเกี่ยวกับโปรเจ็กต์ Firebase ได้ที่ทำความเข้าใจโปรเจ็กต์ Firebase
ขั้นตอนที่ 2: ลงทะเบียนแอปกับ Firebase
คุณสามารถลงทะเบียนแอปหรือเกมอย่างน้อย 1 รายการเพื่อเชื่อมต่อกับโปรเจ็กต์ Firebase
ไปที่Firebaseคอนโซล
คลิกไอคอน Unity () ตรงกลางหน้าภาพรวมโปรเจ็กต์เพื่อเปิดเวิร์กโฟลว์การตั้งค่า
หากเพิ่มแอปไปยังโปรเจ็กต์ Firebase แล้ว ให้คลิกเพิ่มแอป เพื่อแสดงตัวเลือกแพลตฟอร์ม
เลือกเป้าหมายบิลด์ของโปรเจ็กต์ Unity ที่ต้องการลงทะเบียน หรือจะเลือกลงทะเบียนทั้ง 2 เป้าหมายพร้อมกันเลยก็ได้
ป้อนรหัสเฉพาะแพลตฟอร์มของโปรเจ็กต์ Unity
สำหรับ iOS - ป้อนรหัส iOS ของโปรเจ็กต์ Unity ในฟิลด์รหัสชุด iOS
สําหรับ Android - ป้อนรหัส Android ของโปรเจ็กต์ Unity ในช่องชื่อแพ็กเกจ Android
คำว่าชื่อแพ็กเกจและรหัสแอปพลิเคชันมักใช้แทนกันได้
(ไม่บังคับ) ป้อนชื่อเล่นเฉพาะแพลตฟอร์มของโปรเจ็กต์ Unity
ชื่อเล่นเหล่านี้เป็นตัวระบุภายในเพื่อความสะดวก และมีเพียงคุณเท่านั้นที่จะเห็นในคอนโซล Firebaseคลิกลงทะเบียนแอป
ขั้นตอนที่ 3: เพิ่มไฟล์การกำหนดค่า Firebase
รับไฟล์การกำหนดค่า Firebase สำหรับแพลตฟอร์มที่เฉพาะเจาะจงในเวิร์กโฟลว์การตั้งค่าคอนโซล Firebase
สำหรับ iOS — คลิกดาวน์โหลด GoogleService-Info.plist
สำหรับ Android - คลิกดาวน์โหลด google-services.json
เปิดหน้าต่างโปรเจ็กต์ของโปรเจ็กต์ Unity แล้วย้ายไฟล์การกำหนดค่าไปยังโฟลเดอร์
Assetsกลับไปที่คอนโซล Firebase ในเวิร์กโฟลว์การตั้งค่า ให้คลิกถัดไป
ขั้นตอนที่ 4: เพิ่ม Firebase Unity SDK
ในคอนโซล Firebase ให้คลิกดาวน์โหลด SDK Unity ของ Firebase แล้วแตกไฟล์ SDK ไว้ในตำแหน่งที่สะดวก
คุณสามารถดาวน์โหลด Firebase Unity SDK อีกครั้งได้ทุกเมื่อ
Firebase Unity SDK ไม่ได้เจาะจงแพลตฟอร์ม
ในโปรเจ็กต์ Unity ที่เปิดอยู่ ให้ไปที่ Assets > Import Package > Custom Package
จาก SDK ที่แตกไฟล์แล้ว ให้เลือกผลิตภัณฑ์ Firebase ที่รองรับซึ่งคุณต้องการใช้ในแอป
เราขอแนะนำให้เปิดใช้ Google Analytics ในโปรเจ็กต์เพื่อให้ได้รับประสบการณ์การใช้งาน Firebase Cloud Messaging ที่ดีที่สุด นอกจากนี้ ในการตั้งค่า Analytics คุณต้องเพิ่มแพ็กเกจ Firebase สำหรับ Analytics ลงในแอปด้วย
เปิดใช้แล้ว Analytics รายการ
- เพิ่มแพ็กเกจ Firebase สำหรับ Google Analytics:
FirebaseAnalytics.unitypackage - เพิ่มแพ็กเกจสำหรับ Firebase Cloud Messaging:
FirebaseMessaging.unitypackage
ไม่ได้เปิดใช้ Analytics รายการ
เพิ่มแพ็กเกจสำหรับ Firebase Cloud Messaging:
FirebaseMessaging.unitypackage- เพิ่มแพ็กเกจ Firebase สำหรับ Google Analytics:
คลิกนำเข้า ในหน้าต่างนำเข้าแพ็กเกจ Unity
กลับไปที่คอนโซล Firebase ในเวิร์กโฟลว์การตั้งค่า ให้คลิกถัดไป
ขั้นตอนที่ 5: ยืนยันข้อกำหนดด้านเวอร์ชันของบริการ Google Play
ผลิตภัณฑ์บางอย่างใน Firebase Unity SDK สำหรับ Android ต้องใช้ Google Play services ดูว่าผลิตภัณฑ์ใดมีการขึ้นต่อกันนี้ Google Play services ต้องเป็นเวอร์ชันล่าสุดก่อนจึงจะใช้ผลิตภัณฑ์เหล่านั้นได้
เพิ่มusingคำสั่งและโค้ดการเริ่มต้นต่อไปนี้ที่จุดเริ่มต้นของแอปพลิเคชัน คุณสามารถตรวจสอบและอัปเดต Google Play services เป็นเวอร์ชันที่จำเป็นก่อนเรียกใช้เมธอดอื่นๆ ใน 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.
}
});
มีการลงทะเบียนและกำหนดค่าโปรเจ็กต์ Unity เพื่อใช้ Firebase แล้ว
ตั้งค่าด้วยแพลตฟอร์ม Apple
ใช้วิธีการต่อไปนี้เพื่อตั้งค่า FCM กับแพลตฟอร์ม Unity และ Apple
อัปโหลดคีย์การตรวจสอบสิทธิ์ APN
อัปโหลดคีย์การตรวจสอบสิทธิ์ APNs ไปยัง Firebase หากยังไม่มีคีย์การตรวจสอบสิทธิ์ APNs ให้สร้างคีย์ใน Apple Developer Member Center
-
ในFirebaseคอนโซล ให้ไปที่
การตั้งค่า > ทั่วไป จากนั้นคลิกแท็บ Cloud Messaging - ในคีย์การตรวจสอบสิทธิ์ APNs ในส่วนการกำหนดค่าแอป iOS ให้คลิกอัปโหลดเพื่ออัปโหลดคีย์การตรวจสอบสิทธิ์เวอร์ชันพัฒนาหรือคีย์การตรวจสอบสิทธิ์เวอร์ชันที่ใช้งานจริง หรือทั้ง 2 อย่าง ทั้งนี้คุณต้องระบุอย่างน้อย 1 รายการ
- เรียกดูตำแหน่งที่คุณบันทึกคีย์ เลือกคีย์ แล้วคลิก เปิด เพิ่มรหัสคีย์สำหรับคีย์ (มีอยู่ใน ศูนย์สมาชิก Apple Developer) แล้วคลิกอัปโหลด
เปิดใช้ข้อความ Push ในแพลตฟอร์มของ Apple
- คลิกโปรเจ็กต์ใน Xcode แล้วเลือกแท็บทั่วไปจาก พื้นที่แก้ไข
- เลื่อนไปที่เฟรมเวิร์กและไลบรารีที่ลิงก์ แล้วคลิกปุ่ม + เพื่อเพิ่มเฟรมเวิร์ก
- ในหน้าต่างที่ปรากฏขึ้น ให้เลื่อนไปที่ UserNotifications.framework คลิก รายการนั้น แล้วคลิกเพิ่ม
- คลิกโปรเจ็กต์ใน Xcode แล้วเลือกแท็บความสามารถจาก พื้นที่แก้ไข
- เปลี่ยนข้อความ Push เป็นเปิด
- เลื่อนไปที่โหมดพื้นหลัง แล้วเปลี่ยนเป็นเปิด
- เลือกช่องทำเครื่องหมายการแจ้งเตือนระยะไกลในส่วนโหมดเบื้องหลัง
เริ่มต้น Firebase Cloud Messaging
เปิดใช้การลงทะเบียนโดยใช้รหัสการติดตั้ง Firebase
หากต้องการเปิดใช้การลงทะเบียนอินสแตนซ์แอปกับ Firebase Cloud Messaging โดยใช้ รหัสการติดตั้ง Firebase (FID) คุณ ต้องเปิดใช้ FID ในการกําหนดค่าของแอปสําหรับทั้งแพลตฟอร์ม Android และ Apple ก่อน
Android
เพิ่มองค์ประกอบ <meta-data> ต่อไปนี้ภายในองค์ประกอบ <application> ของ AndroidManifest.xml
<meta-data android:name="firebase_messaging_installation_id_enabled" android:value="true" />
Swift
เพิ่มคีย์ FirebaseMessagingInstallationIdEnabled ลงใน Info.plist แล้วตั้งค่าเป็น YES โดยทำดังนี้
FirebaseMessagingInstallationIdEnabled = YES
ลงทะเบียนเข้าร่วมกิจกรรม FCM
ระบบจะเริ่มต้นไลบรารี Firebase Cloud Messaging เมื่อเพิ่มเครื่องจัดการสำหรับเหตุการณ์ RegistrationReceived หรือ MessageReceived
เมื่อเริ่มต้น Firebase Cloud Messaging จะลงทะเบียนอินสแตนซ์ของแอปไคลเอ็นต์
เพื่อรับข้อความโดยใช้
รหัสการติดตั้ง Firebase (FID) แอปจะได้รับ FID พร้อมเหตุการณ์ RegistrationReceived ซึ่งคุณควรแคชไว้ในเซิร์ฟเวอร์เพื่อกำหนดเป้าหมายอุปกรณ์นี้ด้วยข้อความ
นอกจากนี้ คุณจะต้องลงทะเบียนสำหรับเหตุการณ์ OnMessageReceived หากต้องการรับข้อความขาเข้า
การตั้งค่าจะมีลักษณะดังนี้
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); }
หลังจากได้รับรหัสการติดตั้ง Firebase แล้ว ให้ส่งไปยังเซิร์ฟเวอร์แอป และจัดเก็บโดยใช้วิธีที่คุณต้องการ
ลงทะเบียนด้วยตนเองเมื่อปิดใช้การเริ่มต้นอัตโนมัติ
นอกจากนี้ คุณยังทริกเกอร์การลงทะเบียนด้วย FCM ด้วยตนเองขณะรันไทม์ได้โดยใช้ 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"); } });
เข้าถึงโทเค็นการลงทะเบียน FCM (เลิกใช้งานแล้ว)
หากแอปยังคงใช้ API โทเค็นที่เลิกใช้งานแล้ว คุณสามารถรอรับ
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); }
ตั้งค่าด้วยแพลตฟอร์ม Android
ใช้วิธีการต่อไปนี้เพื่อตั้งค่า FCM ด้วยแพลตฟอร์ม Unity และ Android
กำหนดค่ากิจกรรมจุดแรกเข้าของ Android
Firebase Cloud Messaging มาพร้อมกับกิจกรรมจุดแรกเข้าที่กำหนดเองซึ่งจะแทนที่ UnityPlayerActivity เริ่มต้น หากไม่ได้ใช้
จุดแรกเข้าที่กําหนดเอง การแทนที่จะเกิดขึ้นโดยอัตโนมัติและคุณไม่ควร
ต้องดําเนินการใดๆ เพิ่มเติม
ปลั๊กอิน Unity ของ Firebase Cloud Messaging ใน Android จะมาพร้อมกับไฟล์เพิ่มเติม 2 ไฟล์ ได้แก่
Assets/Plugins/Android/libmessaging_unity_player_activity.jarมีกิจกรรมที่ชื่อMessagingUnityPlayerActivityซึ่งจะแทนที่UnityPlayerActivityมาตรฐานAssets/Plugins/Android/AndroidManifest.xmlจะสั่งให้แอปใช้MessagingUnityPlayerActivityเป็นจุดแรกเข้าของแอป
ระบบจะจัดเตรียมไฟล์เหล่านี้เนื่องจาก UnityPlayerActivity เริ่มต้นไม่จัดการการเปลี่ยนวงจรกิจกรรม onStop, onRestart หรือใช้ onNewIntent ซึ่งจำเป็นสำหรับ Firebase Cloud Messaging ในการจัดการข้อความขาเข้าอย่างถูกต้อง
กำหนดค่ากิจกรรมจุดแรกเข้าที่กำหนดเอง
หากแอปไม่ได้ใช้ UnityPlayerActivityเริ่มต้น คุณจะต้อง
นำ AndroidManifest.xml ที่ให้มาออก และตรวจสอบว่ากิจกรรมที่กำหนดเอง
จัดการการเปลี่ยนสถานะทั้งหมดของวงจรของกิจกรรม Android ได้อย่างถูกต้อง
(ตัวอย่างวิธีดำเนินการแสดงอยู่ด้านล่าง) หากกิจกรรมที่กำหนดเองขยาย UnityPlayerActivity คุณสามารถขยาย com.google.firebase.MessagingUnityPlayerActivity แทนได้ ซึ่งจะใช้เมธอดที่จำเป็นทั้งหมด
หากคุณใช้กิจกรรมที่กำหนดเองและไม่ได้ขยาย
com.google.firebase.MessagingUnityPlayerActivity คุณควรใส่ข้อมูลโค้ดต่อไปนี้ในกิจกรรม
/** * 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); }
Firebase C++ SDK เวอร์ชันใหม่ (7.1.0 ขึ้นไป) ใช้ JobIntentService ซึ่ง
ต้องมีการแก้ไขเพิ่มเติมในไฟล์ AndroidManifest.xml
<service android:name="com.google.firebase.messaging.MessageForwardingService" android:permission="android.permission.BIND_JOB_SERVICE" android:exported="false" > </service>
การส่งข้อความใน Android
เมื่อแอปไม่ได้ทำงานเลยและผู้ใช้แตะการแจ้งเตือน
ระบบจะไม่กำหนดเส้นทางข้อความผ่านการเรียกกลับในตัวของ FCM โดยค่าเริ่มต้น
ในกรณีนี้ เพย์โหลดของข้อความจะได้รับผ่าน Intent
ที่ใช้เพื่อเริ่มแอปพลิเคชัน
ข้อความที่ได้รับขณะที่แอปทำงานอยู่เบื้องหลังจะมีเนื้อหาของช่องการแจ้งเตือนที่ใช้เพื่อสร้างการแจ้งเตือนในถาดระบบ แต่เนื้อหาการแจ้งเตือนนั้นจะไม่ได้รับการสื่อสารไปยัง FCM ซึ่งหมายความว่า FirebaseMessage.Notification จะเป็น Null
บทสรุปมีดังนี้:
| สถานะแอป | การแจ้งเตือน | ข้อมูล | ทั้งสอง |
|---|---|---|---|
| เบื้องหน้า | Firebase.Messaging.FirebaseMessaging.MessageReceived |
Firebase.Messaging.FirebaseMessaging.MessageReceived |
Firebase.Messaging.FirebaseMessaging.MessageReceived |
| ข้อมูลเบื้องต้น | ถาดระบบ | Firebase.Messaging.FirebaseMessaging.MessageReceived |
การแจ้งเตือน: ถาดระบบ ข้อมูล: ในส่วนพิเศษของ Intent |
การจัดการข้อความที่มี Deep Link ใน Android
FCM อนุญาตให้ส่งข้อความที่มี Deep Link ไปยังแอปของคุณได้ หากต้องการรับข้อความที่มี Deep Link คุณต้องเพิ่มตัวกรอง Intent ใหม่ลงในกิจกรรมที่จัดการ Deep Link สำหรับแอปของคุณ ตัวกรอง Intent ควรตรวจจับ Deep Link ของโดเมนของคุณ ใน 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>
นอกจากนี้ คุณยังระบุไวลด์การ์ดเพื่อให้ตัวกรอง Intent มีความยืดหยุ่นมากขึ้นได้ด้วย เช่น
<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>
เมื่อผู้ใช้แตะการแจ้งเตือนที่มีลิงก์ไปยัง Scheme และโฮสต์ที่คุณระบุ แอปจะเริ่มกิจกรรมด้วยตัวกรอง Intent นี้เพื่อจัดการลิงก์
ป้องกันการเริ่มต้นอัตโนมัติ
FCM สร้างโทเค็นการจดทะเบียนสำหรับการกำหนดอุปกรณ์เป้าหมาย
เมื่อสร้างโทเค็น ไลบรารีจะอัปโหลดตัวระบุและข้อมูลการกำหนดค่าไปยัง Firebase
หากต้องการรับการเลือกใช้ที่ชัดเจนก่อนใช้โทเค็น คุณสามารถป้องกันการสร้างโทเค็นในเวลาที่กำหนดค่าได้โดยปิดใช้ FCM (และ Analytics ใน Android) คุณสามารถเพิ่มค่าข้อมูลเมตาลงใน Info.plist (ไม่ใช่ GoogleService-Info.plist) บน Apple หรือ AndroidManifest.xml บน 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
หากต้องการเปิดใช้ FCM อีกครั้ง คุณสามารถเรียกใช้รันไทม์ได้โดยทำดังนี้
Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;
ค่านี้จะยังคงอยู่เมื่อรีสตาร์ทแอปเมื่อตั้งค่าแล้ว
ขั้นตอนถัดไป
หลังจากทำตามขั้นตอนการตั้งค่าเสร็จแล้ว ต่อไปนี้คือตัวเลือกบางส่วนสำหรับการดำเนินการต่อด้วย FCM สำหรับ Unity