ตั้งค่าแอพไคลเอนต์ Firebase Cloud Messaging ด้วย Unity

หากต้องการเขียนแอปไคลเอ็นต์ Firebase Cloud Messaging ข้ามแพลตฟอร์มด้วย Unity ให้ใช้ Firebase Cloud Messaging API Unity SDK ใช้งานได้กับทั้ง Android และ Apple โดยมีการตั้งค่าเพิ่มเติมบางอย่างที่จำเป็นสำหรับแต่ละแพลตฟอร์ม

ก่อนจะเริ่ม

ข้อกำหนดเบื้องต้น

• ติดตั้ง Unity 2018.4 หรือใหม่กว่า เวอร์ชันก่อนหน้าอาจใช้งานร่วมกันได้ แต่จะไม่ได้รับการสนับสนุนอย่างแข็งขัน การสนับสนุนสำหรับ Unity 2018.4 ถือว่าเลิกใช้แล้ว และจะไม่ได้รับการสนับสนุนอย่างแข็งขันอีกต่อไปหลังจากการเปิดตัวครั้งใหญ่ครั้งถัดไป

• (iOS เท่านั้น) ติดตั้งสิ่งต่อไปนี้:

  • Xcode 13.3.1 หรือสูงกว่า
  • CocoaPods 1.10.0 หรือสูงกว่า

• ตรวจสอบให้แน่ใจว่าโครงการ Unity ของคุณตรงตามข้อกำหนดเหล่านี้:

  • สำหรับ iOS — กำหนดเป้าหมายเป็น iOS 10 หรือสูงกว่า

  • สำหรับ Android — กำหนดเป้าหมายเป็น API ระดับ 19 (KitKat) หรือสูงกว่า

• ตั้งค่าอุปกรณ์หรือใช้โปรแกรมจำลองเพื่อเรียกใช้โครงการ Unity ของคุณ

  • สำหรับ iOS — ตั้งค่า อุปกรณ์ iOS จริง เพื่อเรียกใช้แอพของคุณและทำงานเหล่านี้ให้เสร็จ:

    • รับ Apple Push Notification Authentication Key สำหรับ บัญชีนักพัฒนา Apple ของคุณ
    • เปิดใช้งาน Push Notifications ใน XCode ภายใต้ App > Capabilities

  • สำหรับ Android — อีมู เลเตอร์ต้องใช้อิมเมจอีมูเลเตอร์กับ Google Play

• ลงชื่อเข้าใช้ Firebase โดยใช้บัญชี Google ของคุณ

หากคุณยังไม่มีโปรเจ็กต์ Unity และต้องการลองใช้ผลิตภัณฑ์ Firebase คุณสามารถดาวน์โหลดหนึ่งใน ตัวอย่าง การเริ่มต้นอย่างรวดเร็วของเรา

ขั้นตอนที่ 1: สร้างโปรเจ็กต์ Firebase

ก่อนที่คุณจะเพิ่ม Firebase ลงในโปรเจ็กต์ Unity ได้ คุณต้องสร้างโปรเจ็กต์ Firebase เพื่อเชื่อมต่อกับโปรเจ็กต์ Unity ไปที่ ทำความเข้าใจโปรเจ็กต์ Firebase เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับโปรเจ็กต์ Firebase

ขั้นตอนที่ 2: ลงทะเบียนแอปของคุณด้วย Firebase

คุณลงทะเบียนแอปหรือเกมได้ตั้งแต่ 1 รายการขึ้นไปเพื่อเชื่อมต่อกับโปรเจ็กต์ Firebase

1. ไปที่ คอนโซล Firebase

2. ตรงกลางหน้าภาพรวมโครงการ ให้คลิกไอคอน Unity ( plat_unity ) เพื่อเริ่มเวิร์กโฟลว์การตั้งค่า

   หากคุณได้เพิ่มแอปลงในโปรเจ็กต์ Firebase แล้ว ให้คลิก เพิ่มแอป เพื่อแสดงตัวเลือกแพลตฟอร์ม

3. เลือกเป้าหมายการสร้างของโปรเจ็กต์ Unity ของคุณที่คุณต้องการลงทะเบียน หรือคุณสามารถเลือกลงทะเบียนทั้งสองเป้าหมายได้พร้อมกัน

4. ป้อน ID เฉพาะแพลตฟอร์มของโปรเจ็กต์ Unity

   • สำหรับ iOS — ป้อนรหัส iOS ของโปรเจ็กต์ Unity ของคุณในฟิลด์ ID บันเดิล iOS

   • สำหรับ Android — ป้อนรหัส Android ของโครงการ Unity ของคุณในช่อง ชื่อแพ็คเกจ Android
     เงื่อนไข ชื่อแพ็คเกจ และ รหัสแอปพลิเคชัน มักใช้สลับกันได้

   ID ของโครงการ Unity ของคุณอยู่ที่ไหน

   เปิดโปรเจ็กต์ Unity ของคุณใน Unity IDE จากนั้นไปที่ส่วนการตั้งค่าสำหรับแต่ละแพลตฟอร์ม:

   • สำหรับ iOS — ไปที่ Build Settings > iOS

   • สำหรับ Android — ไปที่ Android > การตั้งค่าผู้เล่น > การตั้งค่าอื่นๆ

   ID โปรเจ็กต์ Unity ของคุณคือค่า Bundle Identifier (รหัสตัวอย่าง: com.yourcompany.yourproject )

5. (ไม่บังคับ) ป้อนชื่อเล่นเฉพาะแพลตฟอร์มของโปรเจ็กต์ Unity
   ชื่อเล่นเหล่านี้เป็นตัวระบุความสะดวกภายใน และมีเพียงคุณเท่านั้นที่เห็นในคอนโซล Firebase

6. คลิก ลงทะเบียนแอป

ขั้นตอนที่ 3: เพิ่มไฟล์การกำหนดค่า Firebase

1. รับไฟล์การกำหนดค่า Firebase เฉพาะแพลตฟอร์มในเวิร์กโฟลว์การตั้งค่าคอนโซล Firebase

   • สำหรับ iOS — คลิก ดาวน์โหลด GoogleService-Info.plist

   • สำหรับ Android — คลิก ดาวน์โหลด google-services.json

   สิ่งที่คุณต้องรู้เกี่ยวกับไฟล์ปรับแต่งนี้

   • ไฟล์กำหนดค่า Firebase มีตัวระบุที่ไม่ซ้ำแต่ไม่เป็นความลับสำหรับโปรเจ็กต์ของคุณ หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับไฟล์กำหนดค่านี้ โปรดไปที่ ทำความเข้าใจโปรเจ็กต์ Firebase

   • คุณดาวน์โหลด ไฟล์กำหนดค่า Firebase อีกครั้งได้ทุกเมื่อ

   • ตรวจสอบให้แน่ใจว่าชื่อไฟล์ปรับแต่งไม่ได้ต่อท้ายด้วยอักขระเพิ่มเติม เช่น (2)

2. เปิดหน้าต่าง โปรเจ็ กต์ของโปรเจ็กต์ Unity ของคุณ จากนั้นย้ายไฟล์ปรับแต่งของคุณไปที่โฟลเดอร์ Assets

3. กลับไปที่คอนโซล Firebase ในเวิร์กโฟลว์การตั้งค่า คลิก ถัดไป

ขั้นตอนที่ 4: เพิ่ม Firebase Unity SDK

1. ในคอนโซล Firebase คลิก ดาวน์โหลด Firebase Unity SDK จากนั้นคลายซิป SDK ในตำแหน่งที่สะดวก

   • คุณดาวน์โหลด Firebase Unity SDK อีกครั้งได้ทุกเมื่อ

   • Firebase Unity SDK ไม่ใช่เฉพาะแพลตฟอร์ม

2. ในโครงการ Unity ที่เปิดอยู่ ให้ไปที่ เนื้อหา > นำเข้าแพ็คเกจ > แพ็คเกจที่กำหนดเอง

3. จาก SDK ที่คลายซิป ให้เลือก ผลิตภัณฑ์ Firebase ที่รองรับ ซึ่งคุณต้องการใช้ในแอปของคุณ

   เพื่อประสบการณ์ที่ดีที่สุดกับ Firebase Cloud Messaging เราขอแนะนำให้ เปิดใช้ Google Analytics ในโปรเจ็กต์ของคุณ นอกจากนี้ ในการตั้งค่า Analytics คุณต้องเพิ่มแพ็กเกจ Firebase สำหรับ Analytics ในแอปของคุณ

   เปิดใช้งานการวิเคราะห์

   • เพิ่มแพ็คเกจ Firebase สำหรับ Google Analytics: FirebaseAnalytics.unitypackage
   • เพิ่มแพ็คเกจสำหรับ Firebase Cloud Messaging: FirebaseMessaging.unitypackage

   ไม่ได้เปิดใช้งานการวิเคราะห์

   เพิ่มแพ็คเกจสำหรับ Firebase Cloud Messaging: FirebaseMessaging.unitypackage

4. ในหน้าต่าง Import Unity Package ให้คลิก Import

5. กลับไปที่คอนโซล Firebase ในเวิร์กโฟลว์การตั้งค่า คลิก ถัดไป

ขั้นตอนที่ 5: ยืนยันข้อกำหนดเวอร์ชันบริการ Google Play

Firebase Unity SDK สำหรับ Android ต้องการ บริการ Google Play ซึ่งต้องอัปเดตก่อนจึงจะสามารถใช้ SDK ได้

เพิ่มรหัสต่อไปนี้เมื่อเริ่มต้นแอปพลิเคชันของคุณ คุณตรวจสอบและเลือกที่จะอัปเดตบริการ Google Play เป็นเวอร์ชันที่ Firebase Unity SDK ต้องการได้ก่อนที่จะเรียกใช้วิธีอื่นๆ ใน SDK

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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 แล้ว

ขั้นตอนที่ 7: เพิ่มกรอบการแจ้งเตือนผู้ใช้

1. คลิกที่โปรเจ็กต์ใน Xcode จากนั้นเลือกแท็บ ทั่วไป จาก พื้นที่ตัวแก้ไข

2. เลื่อนลงไปที่ Linked Frameworks and Libraries จากนั้นคลิกปุ่ม + เพื่อเพิ่มเฟรมเวิร์ก

3. ในหน้าต่างที่ปรากฏขึ้น ให้เลื่อนไปที่ UserNotifications.framework คลิกรายการนั้น จากนั้นคลิก Add

ขั้นตอนที่ 8: เปิดใช้งานการแจ้งเตือนแบบพุช

1. คลิกที่โปรเจ็กต์ใน Xcode จากนั้นเลือกแท็บ Capabilities จากส่วน Editor

2. เปลี่ยน การแจ้งเตือนแบบพุช เป็น เปิด

3. เลื่อนลงไปที่ โหมดพื้นหลัง แล้วเปลี่ยนเป็น เปิด

4. เลือกช่องทำเครื่องหมาย การแจ้งเตือนระยะไกล ภายใต้ โหมดพื้นหลัง

เริ่มต้นการรับส่งข้อความบนคลาวด์ของ Firebase

ไลบรารี Firebase Cloud Message จะเริ่มต้นเมื่อเพิ่มตัวจัดการสำหรับเหตุการณ์ TokenReceived หรือ MessageReceived

เมื่อเริ่มต้น จะมีการขอโทเค็นการลงทะเบียนสำหรับอินสแตนซ์แอปไคลเอ็นต์ แอปจะได้รับโทเค็นพร้อมเหตุการณ์ OnTokenReceived ซึ่งควรแคชไว้เพื่อใช้ในภายหลัง คุณจะต้องใช้โทเค็นนี้หากต้องการกำหนดเป้าหมายอุปกรณ์เฉพาะนี้สำหรับข้อความ

นอกจากนี้ คุณจะต้องลงทะเบียนสำหรับเหตุการณ์ OnMessageReceived หากคุณต้องการรับข้อความขาเข้า

การตั้งค่าทั้งหมดมีลักษณะดังนี้:

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

การกำหนดค่าจุดเข้าใช้งาน Android กิจกรรม

บน Android Firebase Cloud Messaging มาพร้อมกับกิจกรรมจุดเข้าใช้งานแบบกำหนดเองที่แทนที่ UnityPlayerActivity ที่เป็นค่าเริ่มต้น หากคุณไม่ได้ใช้จุดเริ่มต้นที่กำหนดเอง การแทนที่นี้จะเกิดขึ้นโดยอัตโนมัติ และคุณไม่ควรดำเนินการใดๆ เพิ่มเติม แอปที่ไม่ได้ใช้กิจกรรมจุดเริ่มต้นเริ่มต้นหรือจัดหา Assets/Plugins/AndroidManifest.xml ของตนเอง จะต้องมีการกำหนดค่าเพิ่มเติม

ปลั๊กอิน Firebase Cloud Messaging Unity บน Android มาพร้อมกับไฟล์เพิ่มเติมสองไฟล์:

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar มีกิจกรรมที่เรียกว่า MessagingUnityPlayerActivity ซึ่งมาแทนที่ UnityPlayerActivity มาตรฐาน
• Assets/Plugins/Android/AndroidManifest.xml สั่งให้แอปใช้ MessagingUnityPlayerActivity เป็นจุดเริ่มต้นไปยังแอป

ไฟล์เหล่านี้มีให้เนื่องจาก UnityPlayerActivity เริ่มต้นไม่ได้จัดการ onStop , การเปลี่ยนวงจรชีวิตกิจกรรม onRestart หรือใช้ onNewIntent ซึ่งจำเป็นสำหรับ Firebase Cloud Messaging เพื่อจัดการข้อความขาเข้าอย่างถูกต้อง

การกำหนดค่าจุดเข้าใช้งานที่กำหนดเองActivity

หากแอปของคุณไม่ได้ใช้ 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 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);
}

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 จะเป็นโมฆะ

สรุป:

ป้องกันการเริ่มต้นอัตโนมัติ

FCM สร้างโทเค็นการลงทะเบียนสำหรับการกำหนดเป้าหมายอุปกรณ์ เมื่อมีการสร้างโทเค็น ไลบรารีจะอัปโหลดตัวระบุและข้อมูลการกำหนดค่าไปยัง Firebase หากคุณต้องการเลือกเข้าร่วมอย่างชัดเจนก่อนใช้โทเค็น คุณสามารถป้องกันการสร้างในเวลาที่กำหนดค่าได้โดยการปิดใช้งาน FCM (และใน Android, Analytics) ในการดำเนินการนี้ ให้เพิ่มค่าข้อมูลเมตาให้กับ Info.plist ของคุณ (ไม่ใช่ GoogleService-Info.plist ของคุณ) บน Apple หรือ AndroidManifest.xml บน 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

หากต้องการเปิดใช้งาน FCM อีกครั้ง คุณสามารถโทรรันไทม์ได้:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

ค่านี้ยังคงอยู่ในการรีสตาร์ทแอปเมื่อตั้งค่า

การจัดการข้อความด้วย Deep Links บน Android

FCM อนุญาตให้ส่งข้อความที่มีลิงก์ในรายละเอียดในแอปของคุณ หากต้องการรับข้อความที่มีลิงก์ในรายละเอียด คุณต้องเพิ่มตัวกรองความตั้งใจใหม่ให้กับกิจกรรมที่จัดการลิงก์ในรายละเอียดสำหรับแอปของคุณ ตัวกรองเจตนาควรจับลิงก์ในรายละเอียดโดเมนของคุณ หากข้อความของคุณไม่มีลิงก์ในรายละเอียด การกำหนดค่านี้ไม่จำเป็น ใน 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-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>

เมื่อผู้ใช้แตะการแจ้งเตือนที่มีลิงก์ไปยังสคีมและโฮสต์ที่คุณระบุ แอปของคุณจะเริ่มกิจกรรมด้วยตัวกรองความตั้งใจนี้เพื่อจัดการลิงก์

ขั้นตอนถัดไป

หลังจากตั้งค่าแอปไคลเอ็นต์ คุณก็พร้อมที่จะส่งข้อความดาวน์สตรีมและหัวข้อด้วย Firebase หากต้องการเรียนรู้เพิ่มเติม ดู ตัวอย่าง การเริ่มต้นอย่างรวดเร็วซึ่งสาธิตฟังก์ชันการทำงานนี้

หากต้องการเพิ่มลักษณะการทำงานขั้นสูงอื่นๆ ให้กับแอปของคุณ โปรดดูคำแนะนำในการส่งข้อความจากเซิร์ฟเวอร์แอป:

• ส่งข้อความหัวข้อ
• ส่งไปยังกลุ่มอุปกรณ์
• ส่งข้อความต้นน้ำ

โปรดทราบว่าคุณจะต้อง ติดตั้งเซิร์ฟเวอร์ เพื่อใช้คุณสมบัติเหล่านี้