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

# Firebase Installation ID 등록

> Android의 Firebase Installation ID(FID) 등록, 앱에서 활성화되어 있는지 확인하는 방법, OneSignal의 요구 사항을 알아봅니다.

Firebase Installation ID(FID) 등록은 `firebase-messaging` 25.1.x에서 도입된 **Firebase** 기능으로, 레거시 FCM 등록 토큰을 Firebase Installation ID로 대체합니다.

이 기능은 `firebase_messaging_installation_id_enabled`라는 매니페스트 설정으로 제어됩니다. **이것은 OneSignal 설정이 아니라 Firebase 설정입니다.** OneSignal은 푸시 등록 방식을 결정하기 위해 이 설정을 읽지만, 이 설정을 정의하지 않으며 변경할 수도, OneSignal에만 적용할 수도 없습니다.

> [!WARNING]
>
> `firebase_messaging_installation_id_enabled`는 **앱 전체**에 적용됩니다. `true`이면 Firebase는 프로세스의 모든 SDK(OneSignal, 다른 공급업체 SDK, 자체 Firebase 코드)에서 `getToken()`을 비활성화합니다.
>
> Android는 종속성의 매니페스트를 병합하므로 **다른 SDK가 이 설정을 대신 활성화할 수 있습니다.** 직접 선택하지 않았더라도 이 경로를 사용하고 있을 수 있습니다.

***

## 활성화해야 하나요? \\

FID 등록은 선택 사항이지만 **권장됩니다**. Google은 Firebase Installation ID를 위해 [FCM 등록 토큰을 지원 중단](https://firebase.google.com/docs/cloud-messaging/android/client#access-fcm-registration-token)했으므로, 결국 모든 앱이 전환해야 합니다. 전환해도 기존 사용자는 구독 상태를 유지하고 메시지를 계속 받으며, OneSignal은 계속 FCM Service Account를 통해 전송합니다. 각 기기는 다음 실행 시 레거시 FCM 등록 토큰을 새 푸시 토큰 값(FID)으로 교체합니다.

### 켜기 전에 \\

FID 등록을 활성화하기 전에 다음 사항을 검토하세요:

* **오래된 기기.** FID 등록에는 Google Play 서비스 `261200000` 이상이 필요합니다. 이미 구독된 기기는 현재 푸시 토큰을 유지합니다. 오래된 Android 기기나 Google Play 서비스 업데이트를 받지 않는 기기의 신규 설치는 Google Play 서비스가 업데이트될 때까지 푸시를 받을 수 없습니다. 이러한 기기는 notification\_type 상태 [`-34`](#34-fid-registration-failed)를 표시합니다.
* **다른 푸시 SDK.** 이 설정은 앱 전체에 적용되며 모든 SDK에서 `getToken()`과 `deleteToken()`을 비활성화합니다. 주로 푸시 알림을 보내는 다른 SDK가 영향을 받습니다. 각 SDK가 Firebase Installation ID를 지원하는지 확인하세요.
* **푸시 토큰 형식.** `OneSignal.User.pushSubscription.token`과 `IPushSubscriptionObserver`는 FCM 등록 토큰 대신 Firebase Installation ID를 반환합니다. 속성 유형은 바뀌지 않으므로 컴파일 시점에 실패하는 것은 없습니다. 이 값을 FCM 토큰으로 저장, 검증 또는 전송하는 코드는 오류 없이 동작하지 않게 됩니다.
* **사용자 지정 Firebase 통합.** 앱에 자체 `FirebaseMessagingService`가 있으면 Firebase는 `onNewToken()` 대신 `onRegistered()`를 호출합니다. 토큰 처리를 `onRegistered()`로 옮기세요. 앱이 (예: 로그아웃 시) `deleteToken()`을 호출한다면 `unregister()`로 전환하세요. OneSignal에는 두 콜백 모두 필요하지 않습니다. Firebase의 [Firebase Installation ID를 통한 등록](https://firebase.google.com/docs/cloud-messaging/android/client#enable-registration-via-firebase-installation-id) 가이드와, OneSignal과 함께 실행하는 방법은 [Firebase Messaging SDK 충돌](https://documentation.onesignal.com/docs/ko/notifications-show-successful-but-are-not-being-shown.md#firebase-messaging-sdk-conflict)을 참조하세요.
* **빌드 요구 사항.** 앱은 `firebase-messaging` 25.1.2 이상을 선언하고 `minSdk` 23 이상을 사용해야 합니다. `firebase-messaging` 26.x에서는 `minSdk` 24 이상과 Kotlin 2.0.0 이상이 필요합니다. [요구 사항](#requirements)을 참조하세요.
* **롤백하려면 새 릴리스가 필요합니다.** 이 설정은 앱 빌드의 일부입니다. 켜거나 끄려면 새 앱 빌드와 스토어 릴리스가 필요합니다. 서버 측 스위치는 없습니다.

***

## 앱에서 활성화되어 있나요? \\

자체 `AndroidManifest.xml`만이 아니라 **병합된** 매니페스트를 확인하세요. 종속성이 소스에 나타나지 않고 이 설정을 추가할 수 있습니다.

**1. 병합된 매니페스트 빌드**

```bash theme={null}
./gradlew :app:processDebugManifest
```

**2. 병합된 출력 검색**

```bash theme={null}
grep -r "firebase_messaging_installation_id_enabled" app/build/intermediates/ --include=AndroidManifest.xml
```

grep 결과만으로는 충분하지 않습니다. 병합된 `android:value`를 확인하세요. FID 등록은 이 값이 불리언 `true`일 때만 활성화됩니다.

`meta-data` 항목이 없거나 병합된 값이 `false`이면 레거시 토큰 경로를 사용하고 있는 것입니다. 종속성이 `true`로 설정할 때 값을 강제로 `false`로 만들려면 [FID 등록 비활성화](#disable-fid-registration)를 참조하세요.

등록이 실패하면 오류에 매니페스트 값, 기본 `FirebaseApp`을 찾았는지 여부, `register()`를 사용할 수 있는지 여부가 포함됩니다. 등록에 성공하면 이 세 가지가 로그에 기록되지 않으므로, 정상적인 기기에서는 [상세 로깅](https://documentation.onesignal.com/docs/ko/capturing-a-debug-log.md)에 표시되지 않습니다. 설정을 확인하려면 병합된 매니페스트를 사용하세요.

> [!NOTE]
>
> **이 설정을 활성화하는 것으로 알려진 SDK.** Braze Android SDK 43.0.0 이상은 매니페스트 병합을 통해 `firebase_messaging_installation_id_enabled="true"`를 추가합니다. 앱에 Braze 43 이상이 포함되어 있으면 직접 설정을 추가했는지와 관계없이 FID 등록이 활성화됩니다.

***

## FID 등록 활성화 \\

FID 등록을 활성화하려면 앱에 자체 Firebase 구성을 추가하고, `firebase-messaging` 25.1.2 이상을 요구하고, 매니페스트 설정을 켭니다. 그런 다음 기기가 Firebase Installation ID로 등록되는지 확인합니다.

### 요구 사항 \\

FID 등록에는 다음이 모두 필요합니다. 하나라도 누락되면 [문제 해결](#troubleshooting)의 상태 중 하나로 등록이 실패합니다.

* **OneSignal Android SDK** `5.11.0` 이상 또는 이를 포함하는 래퍼 SDK 버전. [최소 OneSignal SDK 버전](#minimum-onesignal-sdk-versions)을 참조하세요
* 앱에서 선언한 **`com.google.firebase:firebase-messaging`** `25.1.2` 이상. 이전 25.1.x 버전에는 백업 복원 후 또는 앱 데이터 복제 시 실패하는 등의 등록 버그가 있습니다
* **Android API 23 이상**(`firebase-messaging` 25.0.0에서 최소값이 21에서 23으로 상향됨). `firebase-messaging` 26.x에서는 API 24 이상과 Kotlin 2.0.0 이상. [firebase-messaging 26.x 사용](#using-firebase-messaging-26-x)을 참조하세요
* 기기의 **Google Play 서비스** 버전 `261200000` 이상
* **자체 Firebase 프로젝트의 기본 `FirebaseApp`.** [1단계: 앱에 google-services.json 추가](#step-1-add-google-services-json-to-your-app)를 참조하세요
* **일치하는 Firebase 프로젝트.** `google-services.json`의 프로젝트는 OneSignal에 업로드한 FCM Service Account와 같은 프로젝트여야 합니다. [Firebase 프로젝트 일치시키기](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md#match-your-firebase-projects)를 참조하세요

#### 최소 OneSignal SDK 버전 \\

FID 등록 지원은 OneSignal Android SDK `5.11.0`에서 제공되었습니다. 아래의 각 래퍼 SDK 버전은 이를 포함하는 첫 번째 버전입니다. 이전 버전은 레거시 토큰 경로만 사용하므로, 설정이 켜져 있으면 해당 버전에서는 푸시 등록이 실패합니다.

| SDK | 최소 버전 | 참고 |
| - | - | - |
| Android(네이티브) | `5.11.0` | |
| Flutter | `5.7.2` | |
| React Native | `5.5.16` | |
| Expo | `react-native-onesignal` `5.5.16` | `onesignal-expo-plugin` `2.8.0`에서 매니페스트 설정을 자동으로 작성하는 `enableFirebaseInstallationId` 속성이 추가되었습니다. 개발 빌드가 필요합니다. Expo Go는 지원되지 않습니다 |
| Cordova | `5.6.2` | |
| Capacitor | `1.2.2` | |
| Unity | `5.4.2` | |
| .NET / MAUI | `6.4.2` | |

### 1단계: 앱에 google-services.json 추가 \\

FID 등록에는 클라이언트 측에서 Firebase 프로젝트 세부 정보가 필요합니다. OneSignal에 업로드한 FCM Service Account와 같은 Firebase 프로젝트에서 `google-services.json`을 다운로드합니다. 프로젝트가 일치하지 않으면 [`-6`](#6-sender-id-mismatch)으로 등록이 실패합니다. 파일을 앱에 추가하고 Google Services Gradle 플러그인을 적용합니다. 파일 위치는 앱에 따라 다릅니다. 단계는 [Firebase 구성 파일 추가](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md#add-your-firebase-configuration-file)를 참조하세요. 이미 추가되어 있을 수도 있습니다.

### 2단계: firebase-messaging 25.1.2 이상 선언 \\

OneSignal은 레거시 FCM 등록 토큰에 `FirebaseMessaging.getToken()`을 사용하는 `firebase-messaging` 24.x를 기준으로 컴파일됩니다.

FID 등록은 `firebase-messaging` 25.1.2 이상이 필요한 `FirebaseMessaging.register()`를 사용합니다.

`firebase-messaging`을 업그레이드하려면 앱 모듈의 Gradle 파일에 다음을 추가합니다:

```kotlin app/build.gradle.kts theme={null}
implementation("com.google.firebase:firebase-messaging:[25.1.2, 25.99.99]")
```

```groovy app/build.gradle theme={null}
implementation 'com.google.firebase:firebase-messaging:[25.1.2, 25.99.99]'
```

#### firebase-messaging 26.x 사용 \\

`[25.1.2, 25.99.99]` 범위는 추가 요구 사항이 없는 25.x에 앱을 유지합니다. 앱 또는 다른 종속성이 `firebase-messaging` 26.x를 가져오면 Gradle은 26.x로 확인하며, 앱에는 다음도 필요합니다:

* `minSdk` 24 이상
* Kotlin 2.0.0 이상

앱이 확인하는 버전을 확인합니다:

```bash theme={null}
./gradlew :app:dependencies --configuration releaseRuntimeClasspath | grep firebase-messaging
```

### 3단계: Firebase 매니페스트 설정 추가 \\

`AndroidManifest.xml`의 `<application>` 태그 안에 다음을 추가합니다:

```xml AndroidManifest.xml theme={null}
<meta-data
    android:name="firebase_messaging_installation_id_enabled"
    android:value="true" />
```

Expo에서는 대신 `onesignal-expo-plugin` 구성(버전 `2.8.0` 이상)에서 `enableFirebaseInstallationId: true`를 설정한 다음 `expo prebuild`를 실행합니다.

### 4단계: FID 등록 확인 \\

기기에서 빌드하고 실행한 다음, 로그 또는 **Dashboard > Audience > Subscriptions**에서 **Push Token**을 확인합니다.

> [!TIP]
>
> OneSignal Subscription이 **Subscribed** 상태여야 하며, 푸시 토큰은 `dN8Ya5MTR2OO-0BXdqimCI:APA91bFw...`처럼 콜론이 포함된 긴 레거시 FCM 토큰이 아니라 `cXp9fY-TRFCLSy9kVTqorZ`처럼 짧은 Firebase Installation ID여야 합니다. 상태가 음수이면 [문제 해결](#troubleshooting)을 참조하세요.

***

## FID 등록 비활성화 \\

필요한 방법은 설정이 어디에서 왔는지에 따라 다릅니다.

> [tab] 직접 추가한 경우
>
> `AndroidManifest.xml`에서 `<meta-data>` 요소를 제거한 다음 다시 빌드합니다.

> [tab] 종속성이 추가한 경우
>
> 설정이 매니페스트 병합을 통해 들어오는 경우, 자체 항목이 없으므로 제거해도 아무 효과가 없습니다. 대신 병합된 값을 재정의합니다. `tools:replace`가 지정된 `false` 값이 병합에서 우선하므로 종속성의 `true`는 적용되지 않습니다:
>
> ```xml AndroidManifest.xml theme={null}
> <manifest xmlns:android="http://schemas.android.com/apk/res/android"
>     xmlns:tools="http://schemas.android.com/tools">
>
>     <application>
>         <meta-data
>             android:name="firebase_messaging_installation_id_enabled"
>             android:value="false"
>             tools:replace="android:value" />
>     </application>
> </manifest>
> ```
>
> 다시 빌드하고 병합된 매니페스트를 재확인하여 값이 이제 `false`인지 확인합니다.

> [!WARNING]
>
> FID 등록을 비활성화하면 OneSignal뿐만 아니라 앱의 모든 SDK에 영향을 줍니다. 다른 SDK가 FID 등록에 의존한다면 설정을 끄기 전에 해당 문서를 확인하세요.

기기는 다음 앱 실행 시 다시 등록됩니다. 기존 Subscription은 유지되며 새 토큰 값을 받습니다.

***

## 문제 해결 \\

**Dashboard > Audience > Subscriptions**에서 Subscription을 찾아 상태를 확인합니다. 아래 각 상태에는 하나의 원인과 하나의 해결책이 있습니다.

구성을 수정하고 새 빌드를 릴리스하면 **같은 Subscription이 이후 세션에서 복구됩니다**. 재설치가 필요 없으며 새 Subscription이 생성되지 않습니다.

| 상태 | 의미 | 해결책 |
| - | - | - |
| `-32` | FID 등록이 활성화되었지만 앱에 기본 `FirebaseApp`이 없음 | [Firebase 구성 추가](#32-no-default-firebase-app) |
| `-33` | FID 등록이 활성화되었지만 `FirebaseMessaging.register()`를 사용할 수 없음 | [firebase-messaging 업그레이드](#33-register-api-unavailable) |
| `-34` | FID 등록이 실패했거나 Google Play 서비스가 오래됨 | [Google Play 서비스 업데이트](#34-fid-registration-failed) |
| `-6` | 앱과 OneSignal 간 Sender ID 불일치 | [Firebase 프로젝트 일치시키기](#6-sender-id-mismatch) |

### -32: 기본 Firebase 앱 없음 \\

FID 등록에는 앱 자체의 기본 `FirebaseApp`이 필요합니다. OneSignal의 공유 Firebase 프로젝트로는 설치 ID를 생성할 수 없습니다.

가장 일반적인 원인(순서대로):

1. **`google-services.json`이 없습니다.** [Firebase 콘솔](https://console.firebase.google.com/)의 **Project settings > Your apps**에서 다운로드하여 앱에 추가하세요. 네이티브 Android 앱은 `app/` 디렉터리를 사용합니다. 다른 플랫폼은 다른 경로를 사용합니다. [Firebase 구성 파일 추가](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md#add-your-firebase-configuration-file)를 참조하세요.
2. **Google Services Gradle 플러그인이 적용되지 않았습니다.** 파일만으로는 아무 효과가 없습니다. 플러그인이 파일을 Firebase가 런타임에 읽는 리소스로 변환합니다. [Firebase 구성 파일 추가](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md#add-your-firebase-configuration-file)를 참조하세요.
3. **플러그인이 잘못된 Gradle 파일에 적용되었습니다.** `apply`는 프로젝트 수준 파일이 아니라 **앱 모듈의** `build.gradle`에 있어야 합니다.
4. **프로그래밍 방식 초기화가 너무 늦게 실행되었거나 실행되지 않았습니다.** (예: 사용자 동의 후 Firebase를 로드하기 때문에) 기본 앱을 직접 초기화하는 경우, OneSignal이 초기화되기 전에 완료되어야 합니다. [google-services.json 없이 Firebase 설정](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md#set-up-firebase-without-google-services-json)을 참조하세요.

FID 등록을 사용할 의도가 없었다면 대신 [비활성화](#disable-fid-registration)하세요.

### -33: register API를 사용할 수 없음 \\

앱이 확인한 `firebase-messaging` 버전에 `FirebaseMessaging.register()` API가 없거나, 릴리스 빌드에서 제거되었습니다.

1. **`firebase-messaging` 25.1.2 이상을 선언하세요.** `register()`는 25.1.0에서 처음 등장했고 OneSignal은 24.x를 기준으로 컴파일되므로, 앱에서 최신 라이브러리를 가져와야 합니다. 25.1.0이나 25.1.1이 아닌 25.1.2 이상을 사용하세요. [요구 사항](#requirements)을 참조하세요.

2. **확인된 버전을 점검하세요.** 다른 종속성이 이전 버전을 고정하고 있을 수 있습니다:

   ```bash theme={null}
   ./gradlew :app:dependencies --configuration releaseRuntimeClasspath | grep firebase-messaging
   ```

3. **릴리스 빌드에서만 발생한다면** R8이 메서드를 제거하거나 이름을 변경한 것입니다. OneSignal의 소비자 ProGuard 규칙이 적용되어 있고 이를 비활성화하지 않았는지 확인하세요.

### -34: FID 등록 실패 \\

이 상태는 재시도할 수 있습니다. SDK가 이후 세션에서 다시 시도합니다.

1. **Google Play 서비스가 오래되었습니다.** FID 등록에는 버전 `261200000` 이상이 필요합니다. 그보다 낮은 버전에서는 Firebase가 설치 ID를 등록하는 대신 레거시 토큰을 요청하며, 이 토큰은 앱에서 절대 사용할 수 없습니다. SDK는 푸시를 받을 수 없는 Subscription을 보고하는 대신 실패합니다. Play 스토어를 통해 기기의 Google Play 서비스를 업데이트하세요.
2. **일시적인 Firebase 오류.** 조치가 필요 없습니다. 이후 앱 실행 시 등록이 복구됩니다.

### -6: Sender ID 불일치 \\

대시보드에 `Invalid Google Project Number`로 표시됩니다. 앱의 Firebase 프로젝트와 OneSignal에 업로드한 FCM Service Account가 같은 프로젝트가 아닙니다.

프로젝트 불일치로 이 상태가 발생하는 것은 FID 등록이 켜져 있을 때뿐입니다. 레거시 토큰 경로에서는 같은 불일치가 있어도 실패하지 않으며, SDK가 대신 OneSignal의 공유 Firebase 프로젝트를 통해 등록합니다. 그래서 이전에는 푸시가 작동했더라도 FID 등록을 활성화한 직후 `-6`이 나타날 수 있습니다.

[Firebase 프로젝트 일치시키기](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md#match-your-firebase-projects)로 두 프로젝트를 비교하세요. 값이 다르면 올바른 Firebase 프로젝트의 Service Account를 업로드하거나, 업로드한 Service Account 프로젝트의 `google-services.json`을 앱에 포함하세요.

> [!WARNING]
>
> 다른 상태와 달리 `-6`은 기존 Subscription을 유효하지 않음으로 표시합니다. 구성을 수정하고 업데이트된 빌드를 릴리스하면 기기가 다음 실행 시 다시 등록되어 **Subscribed**로 돌아갑니다.

***

## FAQ

### FID를 사용하지 않아도 `google-services.json`이 필요한가요? \\

현재는 파일 없이도 푸시가 작동하지만, 추가하는 것이 좋습니다. 파일을 추가해도 매니페스트 설정이 켜지지는 않습니다. [google-services.json을 생략하면 어떻게 되나요?](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md#what-happens-if-i-skip-google-services-json)를 참조하세요.

### 기존 Subscription이 사라지나요? \\

아니요. 기기는 다음 앱 실행 시 다시 등록되며, 새 푸시 토큰 값으로 같은 Subscription을 유지합니다. 이는 활성화와 비활성화 모두에 적용됩니다. 예외는 Firebase 프로젝트 불일치로, 수정 사항을 릴리스할 때까지 기존 Subscription이 유효하지 않음으로 표시됩니다. [`-6`](#6-sender-id-mismatch)을 참조하세요.

### OneSignal에만 FID 등록을 활성화할 수 있나요? \\

아니요. 이 설정은 프로세스 전체에 적용되며 모든 SDK에서 `getToken()`을 비활성화합니다. 설치 ID 등록은 기본 `FirebaseApp`만 사용할 수 있습니다. OneSignal의 공유 앱으로는 해당 ID를 생성할 수 없습니다.

### 푸시 토큰 형식이 바뀐 이유는 무엇인가요? \\

앱이 이제 Firebase Installation ID로 등록하기 때문입니다. Installation ID는 `cXp9fY-TRFCLSy9kVTqorZ`처럼 짧고 콜론이 없습니다. 레거시 FCM 토큰은 `dN8Ya5MTR2OO-0BXdqimCI:APA91bFw...`처럼 길고 콜론이 포함됩니다.

***

## 관련 페이지

> [card] [Android Firebase 자격 증명](https://documentation.onesignal.com/docs/ko/android-firebase-credentials.md)
>
> FCM Service Account 비공개 키를 업로드하고 앱에 `google-services.json`을 추가합니다.

> [card] [Android SDK 설정](https://documentation.onesignal.com/docs/ko/android-sdk-setup.md)
>
> OneSignal Android SDK를 설치하고 초기화합니다.

> [card] [Subscriptions](https://documentation.onesignal.com/docs/ko/subscriptions.md)
>
> `-6` 및 FID 상태 `-32`\~`-34`를 포함한 Subscription 상태를 확인합니다.

> [card] [디버그 로그 캡처](https://documentation.onesignal.com/docs/ko/capturing-a-debug-log.md)
>
> 상세 SDK 로그를 수집하여 등록 오류를 확인합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.