Firebase is back at Google I/O on May 10! Register now

ตั้งค่าแอพไคลเอนต์ 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 ของแอปของคุณ:

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

<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();
        }
    });

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

การเรียกกลับ 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

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

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

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

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

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

Java

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

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

setAnalyticsCollectionEnabled(true);

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

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

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

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

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