> ## 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.

# 배지

> iOS, Android 및 Huawei의 푸시 알림에 대한 앱 아이콘 배지 수를 관리합니다. 자동 지우기, API 제어 및 네이티브 배지 로직을 포함합니다.

배지는 모바일 앱 아이콘에 나타나는 작은 숫자 점입니다. 사용자의 주의를 끌고 참여 행동에 영향을 미칠 수 있습니다. 특히 iOS에서는 배지에 추가 설정이 필요하며 아래에 설명된 대로 유연한 제어를 제공합니다.

<Note>
  Android 웹 푸시 알림의 경우 배지는 앱 아이콘이 아닌 알림에 표시되는 작은 아이콘을 의미하며 사용자 지정할 수 있습니다. [웹 푸시 배지](./push#badges)를 참조하세요.
</Note>

***

## Android 배지

Android 앱 아이콘 배지 동작은 [Android 알림 카테고리](./android-notification-categories)를 통해 관리할 수 있습니다. 카테고리(채널)가 배지를 표시할지 여부를 제어하고 카테고리별로 배지 동작을 설정할 수 있습니다.

***

## Huawei 배지

Huawei 기기에서 배지는 사용자의 기기 설정에 따라 앱 아이콘에 숫자 또는 점으로 표시될 수 있습니다. 배지는 읽지 않은 메시지나 대기 중인 작업을 나타내어 사용자가 앱을 열도록 유도하는 데 도움이 됩니다. OneSignal을 사용하면 대시보드 또는 API를 통해 Huawei 배지 수를 직접 제어할 수 있습니다.

### Huawei 배지 작동 방식

배지는 사용자의 기기 설정(**설정 > 알림 > 앱 아이콘 배지**)에 따라 앱 아이콘에 **숫자 수** 또는 **점**으로 표시됩니다. API 호출이 기본 수를 제어하고 기기가 시각적 스타일을 결정합니다.

#### 매개변수

| 매개변수                   | 유형      | 범위   | 설명                                                                                                          |
| ---------------------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------- |
| `huawei_badge_class`   | string  | —    | **(필수)** 앱 런처 Activity의 정규화된 클래스 이름(예: `com.example.myapp.MainActivity`). Huawei 시스템에 배지를 표시할 앱 아이콘을 알려줍니다. |
| `huawei_badge_set_num` | integer | 0–99 | 배지를 정확한 숫자로 설정합니다. `0`은 배지를 지웁니다.                                                                           |
| `huawei_badge_add_num` | integer | 1–99 | 기존 배지 수를 이 양만큼 증가시킵니다.                                                                                      |

#### 동작 규칙

* `huawei_badge_class`는 모든 배지 작업에 필수입니다.
* `huawei_badge_set_num`과 `huawei_badge_add_num`이 모두 제공되면 `huawei_badge_set_num`이 우선합니다.
* 둘 다 제공되지 않은 경우(`huawei_badge_class`가 설정된 경우) 배지 수는 기본적으로 1 증가합니다.

### 배지와 함께 Huawei 푸시 보내기

<Tabs>
  <Tab title="대시보드">
    1. **메시지 > 푸시** 또는 **템플릿**으로 이동
    2. **플랫폼 설정 > Huawei Android로 보내기 > 배지** 아래
    3. 다음 중 하나를 선택:
       * **설정 안 함** — 이 알림은 배지에 영향을 미치지 않음
       * **설정** — 배지를 특정 숫자(0-99)로 설정
       * **증가** — 기존 배지 수 증가(1-99)
  </Tab>

  <Tab title="API">
    [Create message](/reference/create-message) API에서 다음 매개변수를 사용합니다:

    * `huawei_badge_class` — *(문자열, 배지에 필수)* 앱의 런처 Activity의 정규화된 클래스 이름(예: `"com.example.myapp.MainActivity"`)
    * `huawei_badge_set_num` — *(정수, 0-99)* 배지 수를 이 정확한 숫자로 설정합니다. `0`으로 설정하면 배지가 지워집니다.
    * `huawei_badge_add_num` — *(정수, 1-99)* 기존 배지 수를 이 숫자만큼 증가시킵니다. `huawei_badge_set_num`과 함께 생략되면 기본적으로 1 증가합니다.

    **배지를 특정 숫자로 설정:**

    ```json theme={null}
    {
      "huawei_badge_class": "com.example.myapp.MainActivity",
      "huawei_badge_set_num": 5
    }
    ```

    **배지를 특정 양만큼 증가:**

    ```json theme={null}
    {
      "huawei_badge_class": "com.example.myapp.MainActivity",
      "huawei_badge_add_num": 1
    }
    ```

    **배지 지우기:**

    ```json theme={null}
    {
      "huawei_badge_class": "com.example.myapp.MainActivity",
      "huawei_badge_set_num": 0
    }
    ```
  </Tab>
</Tabs>

### 배지 지우기

Huawei는 사용자가 앱을 열거나 알림을 탭할 때 배지를 **자동으로 지우지 않습니다**. 배지를 지우려면 두 가지 옵션이 있습니다:

* **API 또는 대시보드를 통해**: `huawei_badge_set_num`을 `0`으로 설정한 알림을 보냅니다(또는 대시보드에서 **설정 > 0** 사용). 보이는 알림을 표시하지 않으려면 [데이터/백그라운드 알림](./data-notifications)을 사용할 수 있습니다.
* **클라이언트 측 코드를 통해**: 앱은 Huawei 배지 API를 사용하여 로컬에서 배지를 지울 수 있습니다. 이를 위해서는 `AndroidManifest.xml`에 `com.huawei.android.launcher.permission.CHANGE_BADGE` 권한이 필요합니다. 구현 세부 정보는 [Huawei 배지 개발 가이드](https://developer.huawei.com/consumer/en/doc/hmscore-guides/android-badging-0000001050042083)를 참조하세요.

<Note>
  `huawei_badge_set_num` 매개변수에는 EMUI 10.0.0 이상 및 Push SDK 10.1.0 이상이 필요합니다. 이전 기기에서는 `huawei_badge_add_num`만 지원됩니다.
</Note>

***

## iOS 배지

iOS에서 배지 수가 올바르게 증가하도록 하려면 다음을 구성해야 합니다:

* `OneSignalNotificationServiceExtension`
* App Groups

전체 지침은 [모바일 SDK 설정](./mobile-sdk-setup)을 참조하세요.

기본적으로 OneSignal SDK는 다음을 수행합니다:

1. 앱이 열릴 때 앱 아이콘 배지를 지웁니다.
2. 알림 센터에서 알림을 제거합니다.

알림을 유지하고 배지 로직을 수동으로 관리하려는 경우(예: 자체 카운터를 사용하거나 기기 간에 상태를 동기화) 이 자동 동작을 비활성화할 수 있습니다.

**수동 배지 제어를 위한 일반적인 사용 사례**

* 앱이 시작되거나 재개될 때 배지 재설정
* 포그라운드에서 알림이 수신될 때 배지 증가
* 메시지를 읽거나 해제할 때 감소
* App Groups 또는 백엔드를 통해 기기 또는 앱 확장 간에 배지 상태 동기화

### 자동 알림 및 배지 지우기 비활성화

앱의 `info.plist`에서 키: `OneSignal_disable_badge_clearing`를 Boolean 타입으로 추가하고 값을 `YES`로 설정합니다

<Frame caption="OneSignal_disable_badge_clearing가 YES로 설정된 info.plist.">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/ea4fbad85bfcb4909ce88668e3882fc8749624c781a66d7c78c440b7e267999c-Screenshot_2025-04-01_at_4.37.05_PM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=e2aafae9e93e16b63e263f34770f262a" alt="Xcode Info.plist editor showing OneSignal_disable_badge_clearing set to YES" width="2284" height="1484" data-path="images/docs/ea4fbad85bfcb4909ce88668e3882fc8749624c781a66d7c78c440b7e267999c-Screenshot_2025-04-01_at_4.37.05_PM.png" />
</Frame>

```xml theme={null}
<key>OneSignal_disable_badge_clearing</key>
<true/>
```

이렇게 하면 앱이 열릴 때 SDK가 자동으로 알림을 제거하거나 배지를 재설정하는 것을 방지합니다.

#### iOS 네이티브 배지 관리

OneSignal의 자동 배지 지우기를 비활성화하면 Apple의 네이티브 API를 사용하여 배지 동작을 제어할 수 있습니다.

<Warning>
  Apple은 iOS 17에서 `UIApplication.shared.applicationIconBadgeNumber`를 더 이상 사용하지 않습니다. 이제 [UserNotifications 프레임워크](https://developer.apple.com/documentation/UserNotifications/UNUserNotificationCenter/setBadgeCount\(_:withCompletionHandler:\))의 다음 메서드를 사용해야 합니다:
</Warning>

**배지 수 설정**

앱 아이콘의 배지를 특정 값으로 설정하려면:

```swift theme={null}
import UserNotifications
import UIKit

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(5) { error in
    if let error = error {
      print("Failed to set badge count: \(error.localizedDescription)")
    } else {
      print("Badge count updated successfully.")
    }
  }
} else {
  UIApplication.shared.applicationIconBadgeNumber = 5
}
```

**현재 배지 수 가져오기**

iOS는 시스템에서 현재 배지 수를 검색하는 메서드를 제공하지 않습니다. 앱의 상태에서 배지 수를 추적해야 합니다(예: `UserDefaults`, 앱의 데이터 모델 또는 백엔드와 동기화 사용).

```swift theme={null}
// Example: Store and retrieve badge count using UserDefaults
let badgeCount = UserDefaults.standard.integer(forKey: "badgeCount")
// Update badge count as needed
UserDefaults.standard.set(badgeCount, forKey: "badgeCount")
```

**배지 증가 또는 감소**

페이로드에서 상대적 변경(예: +1 또는 -1)이 지원되지 않으므로 배지 로직을 수동으로 관리해야 합니다. 저장된 배지 수를 업데이트한 다음 설정합니다:

```swift theme={null}
// Example: Increment badge count and update system badge
let currentCount = UserDefaults.standard.integer(forKey: "badgeCount")
let updatedCount = max(0, currentCount + 1)
UserDefaults.standard.set(updatedCount, forKey: "badgeCount")

if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(updatedCount)
} else {
  UIApplication.shared.applicationIconBadgeNumber = updatedCount
}
```

**배지 지우기**

배지를 완전히 제거하려면:

```swift theme={null}
if #available(iOS 17.0, *) {
  UNUserNotificationCenter.current().setBadgeCount(0)
} else {
  UIApplication.shared.applicationIconBadgeNumber = 0
}
```

### 배지와 함께 iOS 푸시 보내기

OneSignal 대시보드 또는 API를 사용하여 배지 수를 설정할 수 있습니다.

<Tabs>
  <Tab title="대시보드">
    1. **메시지 > 푸시** 또는 **템플릿**으로 이동.
    2. **플랫폼 설정 > Apple iOS로 보내기 > 배지**에서.
    3. 다음 중 하나를 선택:
       * 특정 숫자로 설정.
       * 상대적인 양만큼 증가.

    <Frame caption="OneSignal 대시보드 메시지 양식에서 배지를 설정합니다.">
      <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a6f4a4c0d5869fd9ba5c83ded26752f83c1350c4f6f5213a985cf522fa4d0387-Screenshot_2025-04-01_at_4.42.50_PM.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=8b428dfec1995ea5ec296d717bad9524" alt="OneSignal dashboard push message form showing iOS badge count options" width="1528" height="558" data-path="images/docs/a6f4a4c0d5869fd9ba5c83ded26752f83c1350c4f6f5213a985cf522fa4d0387-Screenshot_2025-04-01_at_4.42.50_PM.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    [Create message](/reference/create-message) API에서 다음 매개변수를 사용합니다:

    * `ios_badgeType` — `SetTo` 또는 `Increase`로 설정.
    * `ios_badgeCount` — 설정하거나 증가시킬 숫자.

    ```json theme={null}
    {
      "ios_badgeType": "Increase",
      "ios_badgeCount": 1
    }
    ```
  </Tab>
</Tabs>

iOS 푸시 알림을 보낼 때 배지 수는 이러한 옵션에 따라 변경됩니다.

앱이 열려 있는 경우 [자동 배지 지우기를 비활성화](#자동-알림-및-배지-지우기-비활성화)하지 않는 한 배지 수가 재설정됩니다.

***

## FAQ

### iOS에서 배지 수가 증가하지 않는 이유는 무엇인가요?

`OneSignalNotificationServiceExtension`과 App Groups를 구성했는지 확인하세요. 이것들이 없으면 배지 수가 올바르게 증가할 수 없습니다. 전체 지침은 [모바일 SDK 설정](./mobile-sdk-setup)을 참조하세요.

### Huawei에서 배지를 지우려면 어떻게 해야 하나요?

`huawei_badge_set_num`을 `0`으로 설정한 알림을 보내거나 대시보드에서 **설정 > 0**을 사용하세요. 또한 [데이터/백그라운드 알림](./data-notifications)을 사용하여 보이는 알림 없이 배지를 지울 수 있습니다. 또는 Huawei 배지 API를 사용하여 클라이언트 측에서 배지를 지우세요.

### 웹 푸시에 배지를 설정할 수 있나요?

아니요. 앱 아이콘 배지는 iOS, Android 및 Huawei에서만 지원됩니다. Android 웹 푸시의 경우 "배지"는 알림 자체에 표시되는 작은 아이콘을 의미합니다 — [웹 푸시 배지](./push#badges)를 참조하세요.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="Android 알림 카테고리" icon="android" href="./android-notification-categories">
    Android에서 알림 채널별 배지 표시 및 동작을 제어합니다.
  </Card>

  <Card title="Huawei 승인" icon="mobile" href="./authorize-onesignal-to-send-huawei-push">
    OneSignal로 Huawei 푸시 메시지를 설정합니다.
  </Card>

  <Card title="푸시 개요" icon="bell" href="./push">
    웹 푸시 배지를 포함한 푸시 알림 기능의 전체 참조입니다.
  </Card>

  <Card title="모바일 SDK 설정" icon="code" href="./mobile-sdk-setup">
    iOS의 배지 전제 조건을 포함한 OneSignal SDK를 구성합니다.
  </Card>
</Columns>