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

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

ก่อนที่คุณจะเริ่ม

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

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

  • (แพลตฟอร์ม Apple เท่านั้น) ติดตั้งสิ่งต่อไปนี้:

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

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

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

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

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

      • รับคีย์การรับรองความถูกต้องการแจ้งเตือน Apple Push สำหรับ บัญชี Apple Developer ของคุณ
      • เปิดใช้งานการแจ้งเตือนแบบพุชใน XCode ภายใต้ App > Capabilities

    • สำหรับ 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. ป้อนรหัสเฉพาะแพลตฟอร์มของโปรเจ็กต์ Unity

    • สำหรับ iOS — ป้อนรหัส iOS ของโปรเจ็กต์ Unity ในช่อง รหัสชุด 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 ที่เปิดอยู่ ให้ไปที่ Assets > Import Package > Custom Package

  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. ในหน้าต่าง นำเข้า Unity Package คลิก นำเข้า

  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 แล้ว

เปิดใช้งานการแจ้งเตือนแบบพุชบนแพลตฟอร์ม Apple

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

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

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

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

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

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

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

  3. เลื่อนลงไปที่ โหมดพื้นหลัง จากนั้นสลับไปที่ เปิด

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

เริ่มต้น Firebase Cloud Messaging

ไลบรารี 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 เพื่อจัดการข้อความขาเข้าอย่างถูกต้อง

การกำหนดค่ากิจกรรมจุดเริ่มต้นที่กำหนดเอง

หากแอปของคุณไม่ได้ใช้ 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 จะเป็นโมฆะ

สรุป:

สถานะแอป การแจ้งเตือน ข้อมูล ทั้งคู่
เบื้องหน้า 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:

หุ่นยนต์

<?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;

ค่านี้จะคงอยู่ตลอดทั้งการรีสตาร์ทแอปเมื่อตั้งค่าแล้ว

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

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

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