ตั้งค่าแอพไคลเอนต์ 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 จริง เพื่อเรียกใช้แอพของคุณและทำงานเหล่านี้ให้เสร็จ:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

สรุป:

สถานะของแอป การแจ้งเตือน ข้อมูล ทั้งคู่
เบื้องหน้า Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
พื้นหลัง ถาดระบบ Firebase.Messaging.FirebaseMessaging.MessageReceived การแจ้งเตือน: ถาดระบบ
ข้อมูล: ในส่วนเพิ่มเติมของเจตนา

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

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

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

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 หากต้องการเรียนรู้เพิ่มเติม ดู ตัวอย่าง การเริ่มต้นอย่างรวดเร็วซึ่งสาธิตการทำงานนี้

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

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