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

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

ก่อนเริ่มต้น

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

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

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

    • Xcode 13.3.1 ขึ้นไป
    • CocoaPods 1.12.0 ขึ้นไป

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

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

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

    • สำหรับ iOS หรือ tvOS - ตั้งค่าอุปกรณ์จริงเพื่อเรียกใช้แอป แล้วทำตามขั้นตอนต่อไปนี้

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

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

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

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

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

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

    • SDK ของ Firebase Unity ไม่ได้เจาะจงแพลตฟอร์ม

  2. ในโปรเจ็กต์ Unity แบบเปิด ให้ไปที่เนื้อหา > นําเข้าแพ็กเกจ > แพ็กเกจที่กําหนดเอง

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

    เราขอแนะนําให้เปิดใช้ Google Analytics ในโปรเจ็กต์เพื่อให้ได้รับประสบการณ์การใช้งาน Firebase Cloud Messaging ที่ดีที่สุด นอกจากนี้ ในการตั้งค่า 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

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

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

อัปโหลดคีย์การตรวจสอบสิทธิ์ APNs ไปยัง Firebase หากยังไม่มีคีย์การตรวจสอบสิทธิ์ APNs โปรดสร้างคีย์ในศูนย์สมาชิกนักพัฒนาแอปของ Apple

  1. ในโปรเจ็กต์ในคอนโซล Firebase ให้เลือกไอคอนรูปเฟือง เลือกการตั้งค่าโปรเจ็กต์ แล้วเลือกแท็บการรับส่งข้อความระบบคลาวด์

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

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

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

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

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

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

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

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

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

  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 Cloud Messaging จะมาพร้อมกับกิจกรรมจุดแรกเข้าที่กําหนดเองซึ่งจะแทนที่ UnityPlayerActivity เริ่มต้น หากคุณไม่ได้ใช้จุดแรกเข้าที่กำหนดเอง การเปลี่ยนทดแทนนี้จะดำเนินการโดยอัตโนมัติและคุณไม่จําเป็นต้องดําเนินการใดๆ เพิ่มเติม แอปที่ไม่ได้ใช้จุดแรกเข้าเริ่มต้น Activity หรือแอปที่ระบุ 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 ที่ระบุออก และตรวจสอบว่า Activity ที่กําหนดเองจัดการการเปลี่ยนผ่านทั้งหมดของวงจรชีวิตของ Activity ของ 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

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

ข้อความที่ได้รับขณะที่แอปทำงานอยู่เบื้องหลังจะมีเนื้อหาของช่องการแจ้งเตือนที่ใช้ในการสร้างการแจ้งเตือนในถาดระบบ แต่ระบบจะไม่ส่งเนื้อหาการแจ้งเตือนนั้นไปยัง FCM กล่าวคือ FirebaseMessage.Notification จะเป็นค่า Null

บทสรุปมีดังนี้:

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

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

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

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

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