> ## 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, Amazon 앱에 사용자 지정 알림 사운드 추가 — 파일 형식, SDK 설정 및 API 파라미터 포함.

사용자 지정 사운드를 사용하면 앱에 더욱 독특하고 브랜드화된 경험을 제공할 수 있습니다. 모든 알림에 사용자 지정 사운드를 추가하거나 특정 유형의 알림에만 사운드를 추가할 수 있습니다. 예를 들어 소셜 앱은 시스템 알림과 구별하기 위해 다이렉트 메시지에만 고유한 사운드를 재생할 수 있습니다.

<Warning>
  모바일 앱 전용입니다. Web Push에서는 사용자 지정 사운드가 지원되지 않습니다.
</Warning>

## 설정

### 사운드 파일 생성

아래의 플랫폼 요구사항에 따라 사운드 파일을 생성하세요. 장치가 지정된 파일을 찾을 수 없거나 파일 형식이 지원되지 않는 경우 기본 시스템 알림 사운드로 대체됩니다.

<Note>
  일부 플랫폼은 사운드 파일의 대문자를 무시하므로 사운드 파일 이름을 소문자로 유지하세요. `AwesomeSound.wav` 대신 `awesomesound.wav` 또는 `awesome_sound.wav`를 사용하세요.
</Note>

| Platform | Extensions            | Notes                                                                      |
| -------- | --------------------- | -------------------------------------------------------------------------- |
| iOS      | `.wav` `.aiff` `.caf` | 사운드는 Linear PCM, MA4 (IMA/ADPCM), µLaw 또는 aLaw로 인코딩되어야 합니다. 30초 미만이어야 합니다. |
| Android  | `.wav` `.mp3` `.ogg`  | 30초 미만의 길이를 권장합니다. 파일 크기를 작게 유지하세요. 큰 파일은 일부 장치에서 재생되지 않을 수 있습니다.          |
| Huawei   | `.wav` `.mp3` `.wma`  | 30초 미만의 길이를 권장합니다. 파일 크기를 작게 유지하세요. 큰 파일은 일부 장치에서 재생되지 않을 수 있습니다.          |
| Amazon   | `.wav` `.mp3` `.ogg`  | 30초 미만의 길이를 권장합니다. 파일 크기를 작게 유지하세요. 큰 파일은 일부 장치에서 재생되지 않을 수 있습니다.          |

### 앱에 사운드 파일 추가

사운드 파일은 앱 내의 리소스로 포함되어야 합니다. 외부 URL은 지원되지 않습니다.

<Tabs>
  <Tab title="iOS">
    SDK에 따라 Xcode 프로젝트의 적절한 위치에 사운드 파일을 추가하세요.

    | SDK            | Folder                                                                                           |
    | -------------- | ------------------------------------------------------------------------------------------------ |
    | iOS Native     | Xcode 프로젝트 루트에 파일을 추가합니다. 파일을 추가할 때 **Add to targets**가 선택되어 있는지 확인하여 번들 리소스에 자동으로 추가되도록 하세요.    |
    | Cordova, Ionic | `<project-root>/platforms/ios/project-name.xcodeproj`의 Xcode 프로젝트 내 `Resources` 디렉토리에 파일을 추가합니다. |
    | Unity          | Unity 프로젝트의 아무 곳에나 사운드를 추가하고 프로젝트를 빌드한 다음 해당 사운드를 Xcode 프로젝트 루트로 이동합니다.                          |
  </Tab>

  <Tab title="Android, Huawei, and Amazon">
    SDK에 따라 프로젝트의 적절한 폴더에 사운드 파일을 추가하세요. **폴더가 없으면 생성하세요.**

    | SDK                            | Folder                                                                                                         |
    | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
    | Android, Huawei, Amazon Native | `res/raw`                                                                                                      |
    | React Native                   | `<project-root>/android/app/src/main/res/raw`                                                                  |
    | Cordova                        | `<project-root>/platforms/android/res/raw/`                                                                    |
    | Ionic                          | `/android/app/src/main/res/raw/`                                                                               |
    | Unity                          | `Assets/Plugins/Android/OneSignalConfig/res/raw` *참고: 사운드 및 아이콘 파일 이름은 소문자여야 하며 밑줄과 숫자를 제외한 다른 것을 포함할 수 없습니다.* |
    | Flutter                        | `main/res/raw`                                                                                                 |
    | .NET                           | `<project-root>/Platforms/Android/Resources/raw/`                                                              |
  </Tab>
</Tabs>

### 알림 전송

<Tabs>
  <Tab title="iOS">
    사운드 리소스를 참조할 때 파일 확장자를 포함하세요(예: `explode_sound.wav`). 푸시 메시지를 보낼 때 대시보드에서 사운드를 설정하거나 [Create Notification](/reference/create-message) API `ios_sound` 속성을 사용하세요.

    사운드가 없으면 **Sound** 필드에 `nil`을 전달하세요.

    <Frame caption="OneSignal 대시보드에서 iOS의 사용자 지정 사운드 설정.">
      <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/a05af7e-Screenshot_2023-02-28_at_3.16.55_PM.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=9d33c9837ac9f67b0d6c6a7a87d03212" alt="OneSignal dashboard push composer showing the iOS Sound field" width="423" height="606" data-path="images/docs/a05af7e-Screenshot_2023-02-28_at_3.16.55_PM.png" />
    </Frame>
  </Tab>

  <Tab title="Android, Huawei, and Amazon">
    Android 8+에서는 알림 사운드를 사용자 지정하려면 설정해야 하는 [Notification Categories](./android-notification-categories)가 도입되었습니다. OneSignal은 모든 버전의 Android에 대해 Notification Channel에 설정된 사운드를 사용합니다.

    **Settings > Push & In-App > Android Notification Channels**에서 그룹 및 채널을 생성합니다.

    <Frame caption="알림 채널 생성.">
      <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/8f39237-Screenshot_2023-02-28_at_3.11.52_PM.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=b18a97c1706dde194bd4e5c13cd9f593" alt="OneSignal dashboard showing the notification channel creation form" width="877" height="487" data-path="images/docs/8f39237-Screenshot_2023-02-28_at_3.11.52_PM.png" />
    </Frame>

    * 사운드를 재생하려면 **Importance**를 "Urgent" 또는 "High"로 설정하세요.
    * 필요에 따라 **Sound**를 "Default" 또는 "Custom"으로 설정하세요. 사운드 리소스를 참조할 때 파일 확장자를 추가하지 **마세요**(예: `cat_meow_sound`).
    * 사운드가 없으려면 **Importance**를 "Urgent" 또는 "High"로, **Sound**를 "Off"로 설정하세요. 또는 **Importance**를 "Medium" 또는 "Low"로 설정하면 사운드가 없습니다.

    <Frame caption="알림 채널의 사운드 설정.">
      <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/f7950b6-Screenshot_2023-02-28_at_3.11.03_PM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=88d88df41d360b190b4c083709e8119c" alt="OneSignal notification channel settings showing sound configuration options" width="429" height="498" data-path="images/docs/f7950b6-Screenshot_2023-02-28_at_3.11.03_PM.png" />
    </Frame>

    그런 다음 푸시 메시지를 보낼 때 대시보드에서 카테고리 이름을 설정하거나 [Create Notification](/reference/create-message) API `android_channel_id` 및 `huawei_channel_id` 속성을 사용할 수 있습니다. 카테고리에 설정된 사운드는 모든 Android 버전에서 작동합니다.

    <Frame caption="푸시 컴포저에서 알림 카테고리 선택.">
      <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/5e8625c-Screenshot_2023-02-28_at_3.15.19_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=c02f9a68fcb73b913a1de93e01d0f4aa" alt="OneSignal push composer showing the notification category dropdown" width="423" height="517" data-path="images/docs/5e8625c-Screenshot_2023-02-28_at_3.15.19_PM.png" />
    </Frame>
  </Tab>

  <Tab title="REST API">
    REST API를 통해 각 플랫폼에 적합한 파라미터를 사용하여 사운드가 포함된 알림을 보낼 수 있습니다. 자세한 내용은 [Create Notification API 참조](/reference/push-notification)를 확인하세요.

    | Platform | API Parameter                                                                                                                                                                    | Details                                                                      |
    | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
    | iOS      | `ios_sound`                                                                                                                                                                      | 파일 확장자를 포함합니다. 예: `"ios_sound": "explode_sound.wav"`. 사운드가 없으면 `nil`을 전달합니다. |
    | Android  | `android_channel_id` — OneSignal 대시보드의 [Notification Categories](./android-notification-categories)에서 채널을 생성한 경우 사용합니다. `existing_android_channel_id` — 다른 곳에서 채널을 생성한 경우 사용합니다. | [Notification Categories](./android-notification-categories)를 사용하는 것을 권장합니다. |
    | Huawei   | `huawei_channel_id` — OneSignal 대시보드의 [Notification Categories](./android-notification-categories)에서 채널을 생성한 경우 사용합니다. `huawei_existing_channel_id` — 다른 곳에서 채널을 생성한 경우 사용합니다.   | [Notification Categories](./android-notification-categories)를 사용하는 것을 권장합니다. |
    | Amazon   | `adm_sound`                                                                                                                                                                      | 파일 확장자를 포함하지 마세요. 예: `"adm_sound": "explode_sound"`.                         |
  </Tab>
</Tabs>

<Warning>
  앱에 사운드 리소스를 최근에 추가한 경우 해당 사운드를 사용하여 알림을 보내기 전에 며칠 기다리는 것을 고려하세요. 대부분의 사용자가 새 사운드 파일이 포함된 최신 앱 버전으로 업데이트하는 데 며칠 또는 몇 주가 걸릴 수 있습니다.

  사운드 리소스가 없는 이전 버전의 앱을 가진 사용자가 이를 참조하는 알림을 받으면 기본 시스템 알림 사운드만 들립니다.
</Warning>

***

## FAQ

### 기본 사운드를 설정할 수 있나요?

사운드 및/또는 Android Notification Channel을 참조하는 [Template](./templates)을 사용하세요. 해당 템플릿으로 전송된 모든 알림은 자동으로 구성된 사운드를 사용합니다.

### 다른 사용자에게 다른 알림 사운드를 보낼 수 있나요?

`ios_sound`와 `android_channel_id` 파라미터는 요청 수준입니다 — 해당 API 호출의 **모든** 수신자에게 적용됩니다. 단일 요청에서 다른 사용자에게 다른 사운드를 지정할 수 없습니다.

다른 사용자에게 다른 사운드를 전달하려면 **팬아웃 패턴**을 사용하세요: 각 사운드 변형에 대해 별도의 API 호출을 하고 태그 또는 세그먼트로 사용자를 타겟팅합니다. 예를 들어 각 사용자의 선호 사운드를 `preferred_sound`와 같은 [태그](./add-user-data-tags)에 저장한 다음 사운드 값당 하나의 요청을 보냅니다.

<CodeGroup>
  ```json Request 1 — "chime" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "chime.wav",
    "android_channel_id": "CHIME_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "chime"}
    ]
  }
  ```

  ```json Request 2 — "bell" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "bell.wav",
    "android_channel_id": "BELL_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "bell"}
    ]
  }
  ```
</CodeGroup>

각 요청은 `preferred_sound` 태그가 일치하는 사용자만 타겟팅하므로 각 그룹은 자신의 사운드를 듣습니다. 필요한 만큼 변형을 추가하세요 — 사운드당 하나의 API 호출입니다.

### 알림이 사용자 지정 사운드 파일을 재생하지 않는 이유는 무엇인가요?

몇 가지 일반적인 원인이 있습니다:

* 사운드 파일의 파일 확장자가 잘못되었습니다
* 사운드 파일이 지원되는 형식으로 인코딩되지 않았습니다
* 사운드 파일이 프로젝트의 잘못된 위치에 있습니다
* 사운드 파일이 30초를 초과합니다

**iOS** — 인코딩 및 테스트 가이드는 [Apple 문서](https://developer.apple.com/documentation/usernotifications/unnotificationsound?language=objc)를 참조하세요.

**Android** — APK를 추출하고 `res/raw/`에 존재하는지 확인하여 사운드 파일이 APK에 포함되어 있는지 검증하세요.

리소스 축소가 활성화된 경우 `res/raw/`에 `keep.xml`을 생성하여 사운드 파일이 제거되지 않도록 보호하세요:

```xml theme={null}
<resources xmlns:tools="http://schemas.android.com/tools"
  tools:keep="@raw/sound_file"/>
```

### 알림이 기본 사운드 파일을 재생하는 이유는 무엇인가요?

설정 지침을 따랐는지, SDK에 대한 올바른 위치에 사운드 파일이 있는지 확인하세요. 파일 이름 대소문자를 다시 확인하세요 — 일부 플랫폼은 대문자를 무시합니다.

### 잘못된 사운드가 재생되는 이유는 무엇인가요?

Android에서는 일정 수의 알림이 열리지 않고 수신되면 알림이 함께 그룹화됩니다. 그룹화된 알림은 기본 사운드를 재생합니다. 모든 알림에 대해 [그룹 키](https://developer.android.com/training/notify-user/group)로 사운드를 설정할 수 있습니다.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="알림 카테고리" icon="layer-group" href="./android-notification-categories">
    사운드, 진동 및 중요도를 제어하기 위한 Android 알림 채널 설정.
  </Card>

  <Card title="템플릿" icon="file-lines" href="./templates">
    미리 정의된 사운드로 재사용 가능한 알림 템플릿 만들기.
  </Card>

  <Card title="Create Notification API" icon="code" href="/reference/push-notification">
    ios\_sound, android\_channel\_id, adm\_sound 파라미터의 API 참조.
  </Card>

  <Card title="알림 아이콘" icon="image" href="./notification-icons">
    모바일 앱의 알림 아이콘 사용자 지정.
  </Card>
</Columns>