ตั้งค่าแอปไคลเอ็นต์ 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.12.0 ขึ้นไป

  • ตรวจสอบว่าโปรเจ็กต์ Unity เป็นไปตามข้อกำหนดต่อไปนี้

    • สำหรับ iOS — กำหนดเป้าหมายเป็น iOS 11 ขึ้นไป
    • สำหรับ tvOS - กำหนดเป้าหมายเป็น tvOS 12 ขึ้นไป
    • สำหรับ Android — กำหนดเป้าหมายเป็น API ระดับ 19 (KitKat) ขึ้นไป

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

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

      • รับคีย์การตรวจสอบสิทธิ์ข้อความ Push ของ Apple สำหรับ บัญชีนักพัฒนาแอป Apple
      • เปิดใช้ข้อความ Push ใน XCode ในส่วน App > ความสามารถ

    • สำหรับ Android — โปรแกรมจำลองต้องใช้ รูปภาพจำลองที่มี Google Play

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

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

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

ขั้นตอนที่ 2: ลงทะเบียนแอปกับ Firebase

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

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

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

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

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

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

    • สำหรับ iOS — ป้อนรหัส iOS ของโครงการ Unity ใน ชุดข้อมูล iOS รหัส ด้วย

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

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

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

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

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

    • สำหรับ iOS — คลิก Download 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 มาที่แอปของคุณ

    เปิดใช้ Analytics แล้ว

    • เพิ่มแพ็กเกจ Firebase สำหรับ Google Analytics ดังนี้ FirebaseAnalytics.unitypackage
    • เพิ่มแพ็กเกจสำหรับ Firebase Cloud Messaging โดยทำดังนี้ FirebaseMessaging.unitypackage

    ไม่ได้เปิดใช้ Analytics

    เพิ่มแพ็กเกจสำหรับ Firebase Cloud Messaging โดยทำดังนี้ FirebaseMessaging.unitypackage

  4. คลิกนำเข้า ในหน้าต่างนำเข้าแพ็กเกจ Unity

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

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

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

เพิ่มคำสั่ง using และโค้ดการเริ่มต้นต่อไปนี้ไว้ที่ตอนต้นของ แอปพลิเคชัน คุณสามารถตรวจหาและเลือกอัปเดตบริการ Google Play เป็น ที่ Firebase Unity SDK จำเป็นต้องใช้ก่อนที่จะเรียกใช้เวอร์ชันอื่นๆ ใน 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 แล้ว

อัปโหลดคีย์การตรวจสอบสิทธิ์ APNs สําหรับการสนับสนุนของ Apple

อัปโหลดคีย์การตรวจสอบสิทธิ์ APN ไปยัง Firebase หากคุณยังไม่มีคีย์การตรวจสอบสิทธิ์ APNs โปรดสร้างคีย์ใน Apple Developer Member Center

  1. ภายในโปรเจ็กต์ในคอนโซล Firebase ให้เลือก ไอคอนรูปเฟือง, เลือก การตั้งค่าโปรเจ็กต์ แล้วเลือก Cloud Messaging

  2. ในคีย์การตรวจสอบสิทธิ์ AAP ในส่วนการกำหนดค่าแอป iOS ให้คลิกอัปโหลด

  3. เรียกดูตำแหน่งที่คุณบันทึกกุญแจไว้ จากนั้นเลือกคีย์แล้วคลิก เปิด เพิ่มรหัสคีย์สำหรับคีย์ (มีอยู่ใน Apple Developer Member Center) แล้วคลิก อัปโหลด

เปิดใช้ข้อความ Push ในแพลตฟอร์ม Apple

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

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

  2. เลื่อนลงไปที่เฟรมเวิร์กและไลบรารีที่ลิงก์ แล้วคลิก + เพื่อเพิ่มเฟรมเวิร์ก

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

ขั้นตอนที่ 2: เปิดใช้ข้อความ Push

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

  2. เปลี่ยนข้อความ Push เป็นเปิด

  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 มาพร้อมกับจุดแรกเข้าที่กำหนดเอง กิจกรรมที่มาแทนที่ UnityPlayerActivity เริ่มต้น หากคุณไม่ได้ใช้ จุดแรกเข้าที่กำหนดเอง การแทนที่นี้จะเกิดขึ้นโดยอัตโนมัติ และคุณไม่ควร ต้องดำเนินการใดๆ เพิ่มเติม แอปที่ไม่ได้ใช้จุดแรกเข้าเริ่มต้น กิจกรรมหรือที่ระบุ Assets/Plugins/AndroidManifest.xml ของตนเอง การกำหนดค่าเพิ่มเติม

ปลั๊กอิน Firebase Cloud Messaging ใน Unity บน 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 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 ในตัว Callback ในกรณีนี้ เพย์โหลดข้อความจะได้รับผ่าน 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 อนุญาตให้ส่งข้อความที่มี Deep Link ไปยังแอปของคุณได้ หากต้องการรับข้อความที่มี Deep Link คุณจะต้องเพิ่มตัวกรอง Intent ใหม่ ไปยังกิจกรรมที่จัดการ Deep Link สำหรับแอปของคุณ ตัวกรอง Intent ควร ตรวจจับ Deep Link ในโดเมนของคุณ หากข้อความไม่มี 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>

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

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

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

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

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