หน้านี้ได้รับการแปลโดย Cloud Translation API

ตั้งค่าแอปไคลเอ็นต์ Firebase Cloud Messaging บน Android

ไคลเอ็นต์ FCM กำหนดให้ใช้อุปกรณ์ที่ใช้ Android 4.4 ขึ้นไปซึ่งติดตั้งแอป Google Play Store ด้วย หรือโปรแกรมจำลองที่ใช้ Android 4.4 ที่มี Google API โปรดทราบว่าคุณไม่ได้ถูกจำกัดการทำให้แอป Android ใช้งานได้ผ่าน Google Play Store

ตั้งค่า SDK

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

แก้ไขไฟล์ Manifest ของแอป

เพิ่มโค้ดต่อไปนี้ลงในไฟล์ Manifest ของแอป

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

<service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>AndroidManifest.xml

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

<!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
     See README(https://goo.gl/l4GJaQ) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />AndroidManifest.xml

(ไม่บังคับ) สำหรับ Android 8.0 (API ระดับ 26) ขึ้นไป เรารองรับและแนะนำ ช่องทางการแจ้งเตือน FCM มีช่องทางการแจ้งเตือนเริ่มต้นพร้อมการตั้งค่าพื้นฐาน หากต้องการ สร้างและใช้ช่องทางเริ่มต้นของคุณเอง ให้ตั้งค่า default_notification_channel_id เป็นรหัสของออบเจ็กต์ช่องทางการแจ้งเตือนตามที่แสดง FCM จะใช้ค่านี้เมื่อใดก็ตามที่ข้อความขาเข้าไม่ได้ตั้งค่าช่องทางการแจ้งเตือนไว้อย่างชัดแจ้ง ดูข้อมูลเพิ่มเติมได้ที่ จัดการช่องทางการแจ้งเตือน

<meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />AndroidManifest.xml

ขอสิทธิ์การแจ้งเตือนรันไทม์ใน Android 13 ขึ้นไป

Android 13 เปิดตัวสิทธิ์รันไทม์แบบใหม่สำหรับแสดงการแจ้งเตือน การดําเนินการนี้ส่งผลต่อแอปทั้งหมดที่ทํางานใน Android 13 ขึ้นไปที่ใช้การแจ้งเตือน FCM

โดยค่าเริ่มต้น FCM SDK (เวอร์ชัน 23.0.6 ขึ้นไป) จะรวมสิทธิ์ POST_NOTIFICATIONS ที่กำหนดไว้ในไฟล์ Manifest อย่างไรก็ตาม แอปของคุณจะต้องขอสิทธิ์นี้ในเวอร์ชันรันไทม์ผ่านค่าคงที่ android.permission.POST_NOTIFICATIONS ด้วย แอปของคุณจะไม่ได้รับอนุญาตให้แสดงการแจ้งเตือนจนกว่า ผู้ใช้จะให้สิทธิ์นี้

วิธีขอสิทธิ์รันไทม์ใหม่

Kotlin+KTX

// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission(),
) { isGranted: Boolean ->
    if (isGranted) {
        // FCM SDK (and your app) can post notifications.
    } else {
        // TODO: Inform user that that your app will not show notifications.
    }
}

private fun askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED
        ) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}MainActivity.kt

Java

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // FCM SDK (and your app) can post notifications.
            } else {
                // TODO: Inform user that that your app will not show notifications.
            }
        });

private void askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}MainActivity.java

โดยปกติแล้วคุณควรแสดง UI ที่อธิบายถึงฟีเจอร์ที่จะเปิดใช้หากผู้ใช้ให้สิทธิ์แก่แอปในการโพสต์การแจ้งเตือน UI นี้ควรมีตัวเลือกแก่ผู้ใช้ในการยอมรับหรือปฏิเสธ เช่น ปุ่มตกลงและไม่เป็นไร หากผู้ใช้เลือกตกลง ให้ขอสิทธิ์โดยตรง หากผู้ใช้เลือกไม่เป็นไร ให้ ผู้ใช้ดำเนินการต่อโดยไม่มีการแจ้งเตือน

ดูแนวทางปฏิบัติแนะนำเพิ่มเติมว่าแอปควรขอสิทธิ์ POST_NOTIFICATIONS จากผู้ใช้เมื่อใดได้ที่สิทธิ์รันไทม์ของการแจ้งเตือน

สิทธิ์การแจ้งเตือนสำหรับแอปที่กำหนดเป้าหมายเป็น Android 12L (API ระดับ 32) หรือต่ำกว่า

Android จะขอสิทธิ์จากผู้ใช้โดยอัตโนมัติในครั้งแรกที่แอปสร้างช่องทางการแจ้งเตือน ตราบใดที่แอปยังทำงานอยู่ในเบื้องหน้า อย่างไรก็ตาม มีข้อควรระวังที่สำคัญเกี่ยวกับช่วงเวลาในการสร้างช่องและคำขอสิทธิ์

หากแอปสร้างช่องทางการแจ้งเตือนแรกเมื่อทำงานในเบื้องหลัง (ซึ่ง FCM SDK สร้างเมื่อได้รับการแจ้งเตือน FCM) Android จะไม่อนุญาตให้แสดงการแจ้งเตือนและจะไม่แสดงข้อความขอสิทธิ์การแจ้งเตือนผู้ใช้จนกว่าจะมีการเปิดแอปของคุณในครั้งถัดไป ซึ่งหมายความว่าการแจ้งเตือนที่ได้รับก่อนเปิดแอปและผู้ใช้ยอมรับสิทธิ์จะหายไป
เราขอแนะนำอย่างยิ่งให้คุณอัปเดตแอปให้กำหนดเป้าหมายเป็น Android 13 ขึ้นไปเพื่อใช้ประโยชน์จาก API ของแพลตฟอร์มในการขอสิทธิ์ หากดำเนินการไม่ได้ แอปของคุณควรสร้างช่องทางการแจ้งเตือนก่อนที่คุณจะส่งการแจ้งเตือนไปยังแอปเพื่อเรียกใช้กล่องโต้ตอบสิทธิ์การแจ้งเตือน และตรวจสอบว่าไม่มีการแจ้งเตือนใดสูญหาย ดูข้อมูลเพิ่มเติมได้ที่แนวทางปฏิบัติแนะนำสำหรับสิทธิ์การแจ้งเตือน

ไม่บังคับ: นำสิทธิ์`POST_NOTIFICATIONS`ออก

โดยค่าเริ่มต้น FCM SDK จะรวมสิทธิ์ POST_NOTIFICATIONS ไว้ หากแอปไม่ได้ใช้ข้อความแจ้งเตือน (ไม่ว่าจะผ่านการแจ้งเตือน FCM, ผ่าน SDK อื่น, หรือที่แอปโพสต์โดยตรง) และไม่ต้องการให้แอปรวมสิทธิ์ คุณสามารถนำสิทธิ์ออกได้โดยใช้เครื่องหมาย การควบรวมไฟล์ Manifest remove โปรดทราบว่าการนำสิทธิ์นี้ออกจะทำให้ระบบแสดงการแจ้งเตือนทั้งหมด ไม่ใช่แค่การแจ้งเตือน FCM เพิ่มโค้ดต่อไปนี้ลงในไฟล์ Manifest ของแอป

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

เข้าถึงโทเค็นการลงทะเบียนอุปกรณ์

ในการเริ่มต้นแอปครั้งแรก FCM SDK จะสร้างโทเค็นการลงทะเบียนสำหรับอินสแตนซ์แอปไคลเอ็นต์ หากต้องการกำหนดเป้าหมายอุปกรณ์เดียวหรือสร้างกลุ่มอุปกรณ์ คุณจะต้องเข้าถึงโทเค็นนี้โดยขยาย FirebaseMessagingService และลบล้าง onNewToken

หัวข้อนี้จะอธิบายวิธีเรียกข้อมูลโทเค็นและวิธีตรวจสอบการเปลี่ยนแปลงโทเค็น เนื่องจากโทเค็นอาจมีการหมุนเวียนได้หลังจากเริ่มต้นระบบครั้งแรก ขอแนะนําอย่างยิ่งให้ดึงข้อมูลโทเค็นการลงทะเบียนที่อัปเดตล่าสุด

โทเค็นการลงทะเบียนอาจเปลี่ยนแปลงในกรณีต่อไปนี้

แอปได้รับการกู้คืนในอุปกรณ์เครื่องใหม่
ผู้ใช้ถอนการติดตั้ง/ติดตั้งแอปอีกครั้ง
ผู้ใช้ล้างข้อมูลแอป

ดึงข้อมูลโทเค็นการลงทะเบียนปัจจุบัน

หากต้องการเรียกข้อมูลโทเค็นปัจจุบัน ให้เรียก FirebaseMessaging.getInstance().getToken():

Kotlin+KTX

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

Java

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

ตรวจสอบการสร้างโทเค็น

Callback ของ onNewToken จะเริ่มทำงานเมื่อมีการสร้างโทเค็นใหม่

Kotlin+KTX

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}MyFirebaseMessagingService.kt

Java

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(@NonNull String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}MyFirebaseMessagingService.java

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

ตรวจหาบริการ Google Play

แอปที่ใช้ SDK บริการ Google Play ควรตรวจสอบอุปกรณ์เพื่อหา APK ของบริการ Google Play ที่เข้ากันได้ก่อนเข้าถึงฟีเจอร์ของบริการ Google Play ขอแนะนำให้ดำเนินการนี้ใน 2 ที่ ได้แก่ ในเมธอด onCreate() ของกิจกรรมหลักและในเมธอด onResume() การเช็คอิน onCreate() จะทำให้ใช้งานแอปไม่ได้หากไม่ผ่านการตรวจสอบ การตรวจสอบใน onResume() ช่วยให้แน่ใจว่าหากผู้ใช้กลับไปยังแอปที่กำลังทำงานด้วยวิธีอื่น เช่น ผ่านทางปุ่มย้อนกลับ ระบบจะยังคงตรวจสอบอยู่

หากอุปกรณ์ไม่มีบริการ Google Play เวอร์ชันที่เข้ากันได้ แอปจะเรียกใช้ GoogleApiAvailability.makeGooglePlayServicesAvailable() เพื่ออนุญาตให้ผู้ใช้ดาวน์โหลดบริการ Google Play จาก Play Store ได้

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

เมื่อมีการสร้างโทเค็นการจดทะเบียน FCM ไลบรารีจะอัปโหลดตัวระบุและข้อมูลการกำหนดค่าไปยัง Firebase หากคุณไม่ต้องการสร้างโทเค็นโดยอัตโนมัติ ให้ปิดใช้การรวบรวมข้อมูล Analytics และการเริ่มต้นโดยอัตโนมัติของ FCM (คุณต้องปิดใช้ทั้ง 2 อย่าง) โดยเพิ่มค่าข้อมูลเมตาเหล่านี้ลงใน AndroidManifest.xml

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />AndroidManifest.xml

หากต้องการเปิดใช้ FCM เริ่มอัตโนมัติอีกครั้ง ให้เรียกใช้รันไทม์โดยทำดังนี้

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = trueMainActivity.kt

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);MainActivity.java

หากต้องการเปิดใช้การเก็บรวบรวมข้อมูลของ Analytics อีกครั้ง ให้เรียกเมธอด setAnalyticsCollectionEnabled() ของคลาส FirebaseAnalytics ตัวอย่างเช่น

setAnalyticsCollectionEnabled(true);

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

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

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

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

โปรดทราบว่าหากต้องการใช้ประโยชน์จากฟีเจอร์เหล่านี้ คุณจะต้อง ติดตั้งใช้งานเซิร์ฟเวอร์และโปรโตคอลเซิร์ฟเวอร์ (HTTP หรือ XMPP) หรือการติดตั้งใช้งาน Admin SDK

ตั้งค่าแอปไคลเอ็นต์ Firebase Cloud Messaging บน Android

ตั้งค่า SDK

แก้ไขไฟล์ Manifest ของแอป

ขอสิทธิ์การแจ้งเตือนรันไทม์ใน Android 13 ขึ้นไป

Kotlin+KTX

Java

สิทธิ์การแจ้งเตือนสำหรับแอปที่กำหนดเป้าหมายเป็น Android 12L (API ระดับ 32) หรือต่ำกว่า

ไม่บังคับ: นำสิทธิ์POST_NOTIFICATIONSออก

เข้าถึงโทเค็นการลงทะเบียนอุปกรณ์

ดึงข้อมูลโทเค็นการลงทะเบียนปัจจุบัน

Kotlin+KTX

Java

ตรวจสอบการสร้างโทเค็น

Kotlin+KTX

Java

ตรวจหาบริการ Google Play

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

Kotlin+KTX

Java

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

ไม่บังคับ: นำสิทธิ์`POST_NOTIFICATIONS`ออก