> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 알림 트레이 관리

> Android 및 iOS의 알림 트레이에서 OneSignal 모바일 푸시 알림이 동작하는 방식: 클릭 및 해제 처리, 복원된 알림, 배지, 프로그래밍 방식 알림 지우기, 서비스 확장.

이 가이드를 사용하여 푸시 알림이 기기에 표시된 후 어떤 일이 일어나는지 이해하고 제어하세요: 클릭과 해제가 하는 일, Android가 알림을 다시 표시하는 시점, 배지가 동기화되는 방식, 앱 코드에서 트레이를 관리할 수 있는 SDK 도구.

이 페이지는 모바일 푸시(Android 및 iOS)를 다룹니다. 웹 푸시 동작은 [웹 푸시 알림 동작](./push)을 참조하세요.

***

## 트레이에서의 알림 생명주기

기기에 표시된 모든 OneSignal 알림은 SDK가 추적합니다. 다음에 일어나는 일이 알림이 다시 나타날 수 있는지를 결정합니다:

| 이벤트                                                                      | 발생하는 일                                                                                                      | 다시 나타날 수 있나요?                                       |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **사용자가 클릭**                                                              | 트레이에서 제거되고, 클릭됨으로 표시되며, [클릭 리스너](./mobile-sdk-reference#addclicklistener-push)가 실행되고, 실행 URL 또는 인텐트가 실행됩니다. | 아니요                                                 |
| **사용자가 해제** (밀어서 제거 또는 모두 지우기)                                           | 해제됨으로 표시됩니다.                                                                                                | 아니요                                                 |
| **앱이 [OneSignal SDK 메서드](#clearing-notifications-programmatically)로 지움** | 트레이에서 제거되고 해제됨으로 표시됩니다.                                                                                     | 아니요                                                 |
| **앱이 Android 기본 `NotificationManager`로 취소**                              | 트레이에서 제거되지만 해제됨으로 표시되지 **않습니다**.                                                                            | 예, Android에서는 다음 앱 재시작 시 복원됩니다                      |
| **Android가 강제 제거** (기기 재부팅, 앱 업데이트, 강제 종료)                               | 사용자 조작 없이 OS가 제거합니다.                                                                                        | 예, [복원된 알림](#restored-notifications-android)을 참조하세요 |

<Warning>
  Android에서는 Android의 기본 `NotificationManager.cancel()` 또는 `cancelAll()` 대신 항상 OneSignal SDK 메서드로 알림을 지우세요. 기본 API로 취소된 알림은 해제됨으로 표시되지 않으므로, SDK가 다음 앱 재시작 시 이를 복원합니다.
</Warning>

***

## 클릭 및 해제 동작

알림을 **클릭**하면 앱(또는 알림의 실행 URL)이 열리고, 알림이 트레이에서 제거되며, 알림 페이로드와 클릭된 액션 버튼 ID와 함께 [`addClickListener()`](./mobile-sdk-reference#addclicklistener-push) 콜백이 실행됩니다. 클릭된 알림이 그룹에 속한 경우 SDK가 그룹 요약을 업데이트하거나 제거합니다. 클릭된 알림은 절대 복원되지 않습니다.

알림을 **해제**하면(밀어서 제거하거나 트레이에서 모두 지우기를 탭) 해제됨으로 표시되고 배지 수와 그룹 요약이 업데이트됩니다. 해제된 알림은 절대 복원되지 않습니다. SDK는 해제 리스너를 제공하지 않으며, 해제는 내부적으로 추적됩니다.

앱이 포그라운드에 있는 동안 표시되는 알림은 먼저 [포그라운드 생명주기 리스너](./mobile-sdk-reference#addforegroundlifecyclelistener-push)를 통과하며, 여기서 표시를 방지할 수 있습니다.

***

## 복원된 알림 (Android)

Android는 사용자 조작 없이 알림을 강제로 제거할 수 있습니다: 기기 재부팅, 앱 업데이트, 강제 종료 시(일부 기기의 공격적인 배터리 관리자 포함). Android SDK는 다음 앱 콜드 스타트 시 영향을 받은 알림을 자동으로 다시 표시(복원)하므로, 사용자가 보지 못했거나 해제하지 않은 전달된 메시지가 손실되지 않습니다.

복원된 알림은 낮은 중요도의 [Restored 카테고리](./android-notification-categories#restored)에서 조용히 다시 나타납니다. 클릭되거나 해제되지 않았고, TTL 이내이며, 최근 7일 이내에 수신된 알림만 최대 49개까지 복원됩니다.

전체 자격 규칙 및 제어 방법은 [복원된 알림 (Android)](./osnotification-payload#restored-notifications-android)에 있습니다. 복원을 줄이려면 전송 시 더 짧은 `ttl`을 사용하거나 [아래의 SDK 메서드](#clearing-notifications-programmatically)로 소비된 알림을 지우세요. iOS에는 복원 동작이 없습니다.

***

## 배지 동작

**iOS**에서 배지는 알림 페이로드(`ios_badgeType` 및 `ios_badgeCount`)로 설정되며, 서비스 확장이 개수를 정확하게 업데이트할 수 있도록 App Group이 필요합니다. 기본적으로 SDK는 앱이 열릴 때 배지를 지웁니다.

**Android**에서 앱 아이콘 배지는 트레이에 있는 활성 OneSignal 알림 수를 반영하며 [알림 카테고리](./android-notification-categories)를 통해 관리됩니다. SDK는 알림이 표시, 해제, 클릭 또는 지워질 때 자동으로 개수를 업데이트하고, `clearAllNotifications()`를 호출하면 `0`으로 재설정합니다.

설정, 플랫폼별 옵션 및 문제 해결은 [배지](./badges)에서 다룹니다.

***

## 프로그래밍 방식으로 알림 지우기

앱 생명주기 이벤트가 아니라 앱에서 알림의 콘텐츠가 소비되었을 때 알림을 지우세요. 일반적인 패턴:

* **콘텐츠 소비 동기화**: 사용자가 알림이 가리키는 화면(받은 편지함, 메시지 센터 또는 활동 피드)을 열어 알림이 더 이상 필요 없게 된 경우. 모두 지우거나, 일부 콘텐츠만 소비되었다면 대상 지정 메서드를 사용하세요.
* **로그아웃**: 이전 사용자의 알림이 다음 사용자에게 표시되지 않도록 모든 것을 지웁니다.

"트레이를 깔끔하게 유지"하기 위해 앱 실행 또는 포그라운드 전환마다 지우는 것은 피하세요. 트레이의 알림은 재참여를 유도하며, 이를 지우면 그 진입점이 제거됩니다. 알림이 쌓이는 것을 관리하려면 전송 시 `collapse_id`를 사용하여 알림을 쌓는 대신 교체하거나, 더 짧은 TTL을 사용하여 전달되지 않은 알림을 만료시키세요.

### `clearAllNotifications()`

트레이에서 앱의 알림을 제거하고 배지 수를 `0`으로 재설정합니다. Android에서는 OneSignal이 생성한 알림만 제거하고 해제됨으로 표시하여 복원되지 않도록 합니다. iOS에서는 로컬 알림과 다른 제공업체의 푸시를 포함하여 앱의 전달된 **모든** 알림을 제거합니다. [전체 메서드 참조](./mobile-sdk-reference#clearallnotifications)를 참조하세요.

<Note>
  복원된 알림을 방지하기 위해 앱 실행 시 지우는 경우, 크로스 플랫폼 앱에서는 호출을 Android로 제한하세요. iOS에서는 로컬 알림과 다른 제공업체의 푸시도 제거합니다.
</Note>

### `removeNotification()` 및 `removeGroupedNotifications()` (Android)

Android 알림 ID로 단일 알림을 제거하거나, 그룹 키로 그룹의 모든 알림을 제거합니다. 제거된 알림은 해제됨으로 표시되며 복원되지 않습니다. 여러 대화 중 하나만 확인한 경우처럼 트레이 콘텐츠의 일부만 소비되었을 때 사용하세요. [메서드 참조](./mobile-sdk-reference#removenotification-removegroupednotifications-android)를 참조하세요.

***

## 일정 시간 후 알림 자동 해제

일정 시간이 지난 후 표시된 알림을 제거하는 전송 시점 매개변수는 없습니다. 가능한 방법은 플랫폼마다 다릅니다:

* **Android 8.0(API 26) 이상**: [알림 서비스 확장](./service-extensions)에서 `setTimeoutAfter()`를 사용하여 타임아웃을 설정하세요. 타임아웃이 경과하면 Android가 알림 창에서 알림을 제거합니다. API 26 미만 기기에서는 호출이 무시되고 사용자가 상호 작용할 때까지 알림이 유지됩니다.
* **iOS**: 지원되지 않습니다. iOS에는 전달된 알림을 자동으로 만료시키는 방법이 없습니다. 가장 가까운 옵션은 [`collapse_id`](./push#collapse-id-mobile-push)를 통해 더 새로운 알림으로 교체하거나, 이후 푸시가 도착했을 때 Apple의 [`removeDeliveredNotifications(withIdentifiers:)`](https://developer.apple.com/documentation/usernotifications/unusernotificationcenter/removedeliverednotifications\(withidentifiers:\))로 Notification Service Extension에서 제거하는 것입니다.

<CodeGroup>
  ```kotlin Kotlin theme={null}
  class NotificationServiceExtension : INotificationServiceExtension {
      override fun onNotificationReceived(event: INotificationReceivedEvent) {
          event.notification.setExtender { builder ->
              // Remove this notification from the shade after 10 minutes (API 26+ only)
              builder.setTimeoutAfter(10 * 60 * 1000L)
          }
      }
  }
  ```

  ```java Java theme={null}
  public class NotificationServiceExtension implements INotificationServiceExtension {
      @Override
      public void onNotificationReceived(INotificationReceivedEvent event) {
          event.getNotification().setExtender(builder ->
              // Remove this notification from the shade after 10 minutes (API 26+ only)
              builder.setTimeoutAfter(10 * 60 * 1000L)
          );
      }
  }
  ```
</CodeGroup>

코드에 고정하지 않고 메시지별로 타임아웃을 지정하려면 [`additionalData`](./osnotification-payload)에 시간을 담아 전송하고 서비스 확장에서 이벤트로부터 읽으세요.

<Note>
  `setTimeoutAfter()`로 제거된 알림은 시스템에 의해 해제되므로 OneSignal SDK가 복원하지 않습니다. 이를 `ttl`과 혼동하지 마세요. `ttl`은 전달되지 않은 메시지가 오프라인 기기를 기다리는 시간을 제어하며, 표시된 알림을 제거하지 않습니다.
</Note>

***

## 서비스 확장으로 알림 커스터마이즈

[서비스 확장](./service-extensions)은 알림이 표시되기 전에 실행되어 모양을 수정하거나, 백그라운드 데이터를 수신하거나, 표시를 완전히 방지할 수 있습니다:

* **Android**에서는 `INotificationServiceExtension`을 구현하고 `setExtender()`를 사용하여 `NotificationCompat` 옵션을 변경하거나, `event.preventDefault()`를 호출하여 표시를 억제하세요.
* **iOS**에서는 리치 미디어, 배지 증가 및 확인된 전달을 위해 `UNNotificationServiceExtension`(설정 중 생성된 `OneSignalNotificationServiceExtension`)을 사용하세요.

<Warning>
  Android에서는 서비스 확장이 [복원된 알림](#restored-notifications-android)에서도 실행됩니다. `onNotificationReceived`의 부수 효과(분석 호출, API 요청, 데이터베이스 쓰기)는 알림이 복원될 때 다시 실행되며, `setChannelId()`와 같은 extender 변경 사항도 복원에 적용되어 시끄럽게 알림이 울릴 수 있습니다. 알림 옵션이 새로 전달된 알림에만 적용되도록 확장을 설계하세요.
</Warning>

***

## FAQ

### Android에서 앱을 열 때 오래된 알림이 다시 나타나는 이유는 무엇인가요?

Android SDK는 기기 재부팅, 앱 업데이트 또는 강제 종료 후처럼 트레이에서 강제로 제거된 알림을 복원합니다. 사용자가 해제하거나 클릭한 알림은 복원되지 않습니다. 자격 규칙 및 제어 방법은 [복원된 알림 (Android)](./osnotification-payload#restored-notifications-android)을 참조하세요.

### TTL이 만료되면 트레이에서 알림이 제거되나요?

아니요. TTL은 전달되지 않은 메시지가 오프라인 기기를 기다리는 시간을 제어하며, Android에서는 복원 가능한 알림의 범위도 제한합니다. 이미 트레이에 표시된 알림은 절대 제거하지 않습니다. 표시된 알림을 제거하려면 [지우기 메서드](#clearing-notifications-programmatically)를 사용하세요. Android에서 일정 시간 후 제거하려면 [일정 시간 후 알림 자동 해제](#dismiss-notifications-automatically-after-a-delay)를 참조하세요.

### 트레이를 지우지 않고 배지만 지울 수 있나요?

iOS에서는 가능합니다: 배지는 앱이 열릴 때 자동으로 지워지며(비활성화하지 않는 한) 트레이 내용은 그대로 유지됩니다. Android에서는 배지가 트레이의 활성 알림을 반영하므로 이와 독립적으로 설정할 수 없습니다. [배지](./badges)를 참조하세요.

### 사용자가 알림을 해제할 때를 위한 리스너가 있나요?

아니요. SDK는 해제된 알림이 복원되지 않도록 해제를 내부적으로 추적하지만 해제 이벤트를 노출하지 않습니다. [클릭 리스너](./mobile-sdk-reference#addclicklistener-push)는 클릭만 다룹니다.

***

<Columns cols={3}>
  <Card title="Mobile SDK 참조" icon="code" href="./mobile-sdk-reference">
    알림 메서드 및 리스너에 대한 전체 참조입니다.
  </Card>

  <Card title="OSNotification payload" icon="brackets-curly" href="./osnotification-payload">
    페이로드 필드 및 복원된 알림 규칙입니다.
  </Card>

  <Card title="모바일 서비스 확장" icon="puzzle-piece" href="./service-extensions">
    표시 전에 알림을 가로채고 커스터마이즈합니다.
  </Card>
</Columns>