建立通話應用程式的通話樣式通知

在 Android 12.0 (API 級別 31) 以上版本中，系統會提供 CallStyle 通知範本，以便區分來電通知與其他類型的通知。請使用這個範本建立來電或通話中通知。此範本支援大型通知，其中包含呼叫端資訊和必要動作，例如接聽或拒接來電。

由於來電和進行中的呼叫屬於高優先順序事件，因此這類通知會在通知欄中優先顯示。此排名也可讓系統將這些優先呼叫轉送給其他裝置。

CallStyle 通知範本包含下列必要操作：

• 選擇「接聽」或「拒接」來電。
• 掛斷進行中的通話。
• 接聽或掛斷來電過濾。

此樣式中的動作會顯示為按鈕，且系統會自動新增適當的圖示和文字。不支援手動為按鈕加上標籤。如要進一步瞭解通知設計原則，請參閱「通知」。

必要動作會以意圖的形式傳遞，例如下列各節中的 hangupIntent 和 answerIntent。每個項目都是系統維護權杖的參照。權杖是可在不同應用程式和程序之間傳遞的輕量物件。系統會負責管理權杖的生命週期，並確保 PendingIntent 可用於建立權杖的應用程式，即使建立該權杖的應用程式已停止執行也沒問題。將 PendingIntent 授予其他應用程式，即表示您授權該應用程式執行指定的作業，例如拒絕或回答。即使建立意圖的應用程式目前並未執行，也會獲得這項權限。詳情請參閱 PendingIntent 的參考說明文件。

從 Android 14 (API 級別 34) 開始，您可以將來電通知設為不可關閉。方法是搭配 Notification.FLAG_ONGOING_EVENT 至 Notification.Builder#setOngoing(true) 使用 CallStyle 通知。

以下是搭配使用各種方法與 CallStlye 通知的範例。

// Create a new call, setting the user as the caller.
val incomingCaller = Person.Builder()
    .setName("Jane Doe")
    .setImportant(true)
    .build()

// Create a new call with the user as the caller.
Person incomingCaller = new Person.Builder()
    .setName("Jane Doe")
    .setImportant(true)
    .build();

來電

使用 forIncomingCall() 方法，建立來電的呼叫樣式通知。

// Create a call style notification for an incoming call.
val builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setStyle(
         Notification.CallStyle.forIncomingCall(caller, declineIntent, answerIntent))
    .addPerson(incomingCaller)

// Create a call style notification for an incoming call.
Notification.Builder builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setStyle(
        Notification.CallStyle.forIncomingCall(caller, declineIntent, answerIntent))
    .addPerson(incomingCaller);

通話中

使用 forOngoingCall() 方法，建立進行中呼叫的呼叫樣式通知。

// Create a call style notification for an ongoing call.
val builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setStyle(
         Notification.CallStyle.forOngoingCall(caller, hangupIntent))
    .addPerson(second_caller)

// Create a call style notification for an ongoing call.
Notification.Builder builder = new Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setStyle(
        Notification.CallStyle.forOngoingCall(caller, hangupIntent))
    .addPerson(second_caller);

過濾來電

使用 forScreeningCall() 方法，建立用於篩選呼叫的呼叫樣式通知。

// Create a call style notification for screening a call.
val builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setStyle(
         Notification.CallStyle.forScreeningCall(caller, hangupIntent, answerIntent))
    .addPerson(second_caller)

// Create a call style notification for screening a call.
Notification.Builder builder = new Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setStyle(
        Notification.CallStyle.forScreeningCall(caller, hangupIntent, answerIntent))
    .addPerson(second_caller);

為更多 Android 版本提供相容性

將 API 30 以下版本的 CallStyle 通知與前景服務建立關聯，以便為其指派 API 級別 31 或以上版本所授予的最高排名。此外，API 30 以下版本的 CallStyle 通知可以使用 setColorized() 方法，將通知標示為顏色，藉此達到類似的排名。

搭配 CallStyle 通知使用 Telecom API。詳情請參閱電信架構總覽。