ตั้งค่าแอพไคลเอนต์ 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 สำหรับ บัญชีนักพัฒนา Apple ของคุณ
    • เปิดใช้งานการแจ้งเตือนแบบพุชใน 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 ในช่อง รหัสบันเดิล iOS

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

   คุณจะหารหัสโครงการ Unity ของคุณได้ที่ไหน

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

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

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

   รหัสโครงการ 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 อีกครั้งได้ทุกเมื่อ

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

2. เปิดหน้าต่าง Project ของโปรเจ็กต์ 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

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

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

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

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

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

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

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

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

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

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

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

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