> ## 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 Firebase 자격 증명

> OneSignal에서 Firebase Cloud Messaging(FCM) Service Account 자격 증명을 구성하여 Google Play 스토어의 앱에 Android 푸시 알림을 활성화하세요.

Google Play 스토어를 통해 Android 앱을 다운로드한 사용자에게 푸시 알림을 보내려면, Firebase Cloud Messaging(FCM) Service Account 비공개 키를 생성하여 OneSignal에 업로드해야 합니다.

<Note>
  이 안내는 다음에 적용되지 않습니다:

  * **웹 푸시.** Android 기기는 FCM Service Account 없이도 웹사이트나 PWA를 구독할 수 있습니다. [웹 푸시 설정](./web-push-setup)을 참조하세요.
  * **Huawei App Gallery를 통해 배포되는 Huawei 앱.** [Huawei 승인](./authorize-onesignal-to-send-huawei-push)을 참조하세요.
</Note>

***

## 요구 사항

* Google Play 스토어를 통해 배포된 Android 앱
* [OneSignal 계정](https://onesignal.com)
* [Firebase 계정(무료)](https://firebase.google.com)
* `cloudmessaging.messages.create` 및 `firebase.projects.get` 권한이 있는 Firebase Service Account 비공개 키
  * 없는 경우 아래 단계를 따라 [Firebase Service Account 비공개 키를 생성](#create-a-firebase-service-account-private-key)하세요
  * 이미 비공개 키가 있는 경우 [기존 권한을 확인](#how-do-i-check-my-service-account-permissions)하세요

***

<h2 id="create-a-firebase-service-account-private-key">
  Firebase Service Account 비공개 키 생성 \\
</h2>

<Steps>
  <Step title="Firebase 프로젝트 생성 또는 열기">
    [Firebase 콘솔](https://console.firebase.google.com/)로 이동하여 프로젝트를 생성하거나 선택하세요.

    <Frame caption="Firebase 내 프로젝트 페이지">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-projects.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=aca8614ec0e40fc63fd71f3160098778" alt="Firebase 콘솔에서 사용 가능한 프로젝트 목록을 표시" width="2656" height="1780" data-path="images/mobile/firebase-projects.png" />
    </Frame>
  </Step>

  <Step title="Firebase Cloud Messaging API V1 활성화">
    **프로젝트 설정**에서 **Cloud Messaging** 탭을 선택합니다.

    <Frame caption="Firebase 프로젝트 설정의 Cloud Messaging 탭">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-project-settings-cloud-messaging.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=e877c1d0ca51b85b1f2e80418e0195c4" alt="Cloud Messaging 탭을 표시하는 Firebase 프로젝트 설정, Firebase Cloud Messaging API (V1) 상태는 Enabled" width="2956" height="1140" data-path="images/mobile/firebase-project-settings-cloud-messaging.png" />
    </Frame>

    **Firebase Cloud Messaging API (V1)** 상태를 확인합니다:

    * **Enabled**(녹색 체크 표시)로 표시되면 다음 단계로 진행하세요.
    * **Disabled**로 표시되면 **3점 메뉴 > Google Cloud Console에서 API 관리**를 클릭합니다. Google Cloud Console에서 **Enable**을 클릭하고 녹색 체크 표시와 "API Enabled"가 나타날 때까지 기다립니다.

    <Frame caption="Google Cloud Console에서 활성화된 Firebase Cloud Messaging API">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-cloud-messaging-api-v1-enabled.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=9239c8baa0659152d8aed6fc6af810a7" alt="Google Cloud Console의 Firebase Cloud Messaging API 페이지에 녹색 체크 표시와 함께 API Enabled 상태가 표시됨" width="1616" height="750" data-path="images/mobile/firebase-cloud-messaging-api-v1-enabled.png" />
    </Frame>

    <Note>
      지금이 Firebase Service Account에 필요한 권한이 있는지 확인하기에 좋은 시점입니다:

      * `cloudmessaging.messages.create`
      * `firebase.projects.get`

      새로 생성된 Firebase 프로젝트는 보통 기본 Service Account에 이러한 권한을 가지고 있습니다. 확실하지 않거나 오래된 프로젝트로 작업하는 경우, 진행하기 전에 확인하세요. 자세한 내용은 [Service Account 권한은 어떻게 확인하나요?](#how-do-i-check-my-service-account-permissions)를 참조하세요.
    </Note>
  </Step>

  <Step title="새 비공개 키 생성">
    다시 **프로젝트 설정**으로 돌아가 **Service accounts** 탭을 선택하고 **새 비공개 키 생성**을 클릭합니다.

    <Frame caption="Firebase 내 Service Accounts 섹션">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-project-settings-service-accounts.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=d0b4a6d7c84cd1a639b6de79c3789363" alt="Firebase 프로젝트 설정의 Service accounts 탭에 새 비공개 키 생성 버튼이 표시됨" width="2978" height="1734" data-path="images/mobile/firebase-project-settings-service-accounts.png" />
    </Frame>

    팝업에서 **키 생성**을 클릭하여 확인합니다.

    <Frame caption="Service Account에 대한 비공개 키 생성.">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/firebase-generate-new-private-key.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=6b3ca4145c180400cf80a434adbbc216" alt="Service Account에 대한 새 비공개 키 생성을 위한 Firebase 확인 대화 상자" width="1432" height="572" data-path="images/mobile/firebase-generate-new-private-key.png" />
    </Frame>

    <Warning>
      다운로드된 비공개 키에는 민감한 자격 증명이 포함되어 있습니다. 공유하거나 버전 관리에 체크인하지 마세요.
    </Warning>

    `.json` 파일을 안전한 위치에 저장하세요. 다음 섹션에서 필요합니다.
  </Step>
</Steps>

***

## Service Account 비공개 키를 OneSignal에 업로드

OneSignal 대시보드에서:

<Steps>
  <Step title="Android 설정 열기">
    \*\*설정 > 푸시 및 인앱 > 플랫폼 > Google Android (FCM)\*\*으로 이동합니다.

    **활성화**(처음 설정 시) 또는 **설정**(Android가 이미 구성된 경우)을 클릭합니다.

    <Frame caption="OneSignal 앱 설정 내 플랫폼 화면">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/onesignal-push-platforms.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=9b8af64aae3dd5fdcb715731710785ca" alt="플랫폼 탭에 Google Android (FCM) 타일과 설정 버튼이 표시된 OneSignal 푸시 및 인앱 설정" width="2496" height="648" data-path="images/mobile/onesignal-push-platforms.png" />
    </Frame>
  </Step>

  <Step title="Service Account 비공개 키 업로드">
    **파일 선택**을 클릭하고 이전 섹션에서 저장한 `.json` 비공개 키를 선택합니다.

    <Frame caption="FCM 구성 화면">
      <img src="https://mintcdn.com/onesignal/uWz0BIZj_JUi1RGq/images/mobile/onesignal-fcm-configuration.png?fit=max&auto=format&n=uWz0BIZj_JUi1RGq&q=85&s=5fb6b977bf1517c453b1c0b0c9b57274" alt="Service Account JSON 파일 업로드 필드와 파일 선택 버튼이 있는 OneSignal Google Android (FCM) 구성 화면" width="1780" height="702" data-path="images/mobile/onesignal-fcm-configuration.png" />
    </Frame>
  </Step>

  <Step title="저장 및 계속">
    **Save & Continue**를 클릭합니다. OneSignal이 비공개 키를 검증하고 설정 흐름의 다음 단계로 이동하며, 여기에서 SDK를 선택합니다.

    <Warning>
      대시보드에 **Invalid request** 또는 기타 오류가 표시되면 Service Account에 하나 이상의 필수 역할이 누락되었을 가능성이 있습니다. [Service Account 권한은 어떻게 확인하나요?](#how-do-i-check-my-service-account-permissions)를 참조하세요.
    </Warning>
  </Step>
</Steps>

<Check>
  OneSignal 앱이 Firebase Cloud Messaging (V1)에 연결되었습니다. 다음으로 사용 중인 SDK에 맞는 [모바일 SDK 설정](./mobile-sdk-setup)을 따라 앱에서 OneSignal을 설치하고 초기화하세요.
</Check>

***

## FAQ

<h3 id="how-do-i-check-my-service-account-permissions">
  Service Account 권한은 어떻게 확인하나요? \\
</h3>

Service Account 권한은 Firebase 콘솔이 아닌 **Google Cloud Console**에서 관리됩니다. OneSignal에 업로드한 비공개 키의 Service Account는 다음 두 가지를 모두 가지고 있어야 합니다:

* `cloudmessaging.messages.create` — **Firebase Cloud Messaging API Admin**(`roles/firebasecloudmessaging.admin`)에 의해 부여됨.
* `firebase.projects.get` — **Firebase Viewer**(`roles/firebase.viewer`)에 의해 부여됨.

**Firebase Admin**(`roles/firebase.admin`), **Editor** 또는 **Owner**와 같은 더 광범위한 역할도 두 권한을 모두 포함하므로 요구 사항을 충족합니다. OneSignal 전용 Service Account의 경우, 비공개 키가 노출되었을 때의 영향을 제한하기 위해 위의 좁은 쌍을 선호하세요.

Service Account 비공개 키를 업로드한 후 OneSignal 대시보드에 **Invalid request**가 표시되면, 누락된 역할이 가장 일반적인 원인입니다.

<Steps>
  <Step title="Google Cloud Console에서 IAM 열기">
    [Google Cloud Console](https://console.cloud.google.com/)에 로그인하고 Firebase 앱과 연결된 프로젝트를 선택한 후 **IAM 및 관리 > IAM**으로 이동합니다.
  </Step>

  <Step title="Service Account 찾기">
    주체 이메일을 업로드한 비공개 키의 `client_email` 필드와 일치시킵니다.
  </Step>

  <Step title="누락된 역할 추가">
    연필(편집) 아이콘을 클릭한 다음 **다른 역할 추가**를 클릭하여 아직 할당되지 않은 역할을 추가합니다.
  </Step>

  <Step title="저장">
    **저장**을 클릭합니다. IAM 변경 사항이 적용되는 데 몇 분이 걸릴 수 있습니다.
  </Step>
</Steps>

### "This configuration is for a different Firebase Project"가 표시되는 이유는 무엇인가요?

이 오류는 업로드한 비공개 키가 다른 Firebase 프로젝트(다른 Sender ID)에 속할 때 발생합니다.

**해결책**: 원래 Firebase 프로젝트의 비공개 키를 사용하세요. 사용할 수 없는 경우 앱 ID와 함께 `support@onesignal.com`에 문의하세요. 프로젝트를 전환하면 푸시 토큰이 재설정됩니다. 사용자는 푸시를 다시 받으려면 앱을 다시 열어야 합니다.

### Sender ID를 변경할 수 있나요?

예, 하지만 기존 사용자에게 영향을 미칩니다.

기기 토큰은 원래 Sender ID에 묶여 있습니다. 이를 변경하면 기존 토큰이 무효화됩니다.

<Warning>
  사용자가 앱을 다시 열고 새 토큰을 생성할 때까지 푸시 알림 수신이 중단됩니다.
</Warning>

도움이 필요한 경우 앱 ID와 함께 `support@onesignal.com`에 문의하세요.

### OneSignal에서 Sender ID가 보이지 않는 이유는 무엇인가요?

Firebase 서버 키가 `AIz...`처럼 보이면 오래된 Google Cloud Messaging(GCM) 설정을 사용 중일 가능성이 큽니다. 새 Firebase 프로젝트를 만들고 Service Account 비공개 키를 업로드하세요.

### FCM V1로 전환할 때 코드를 업데이트해야 하나요?

앱 또는 SDK 변경은 필요하지 않습니다. 이는 대시보드만 업데이트하는 것입니다.

### FCM V1로 전환하는 마감일은 언제인가요?

Google의 레거시 FCM API는 이제 완전히 사용 중단되었습니다. 여전히 레거시 API를 사용하고 있다면, **즉시 FCM V1로 마이그레이션해야 합니다**.

### 어떤 앱이 여전히 레거시 API를 사용하고 있는지 어떻게 확인할 수 있나요?

각 앱에 대해 [View an app](/reference/view-an-app) API를 호출하고 응답의 `fcm_v1_service_account_json` 필드를 확인하세요:

* **존재하고 비어있지 않음**: 앱이 FCM V1을 사용 중입니다.
* **누락되었거나 비어있음**: 앱이 FCM V1로 구성되지 않았습니다. 해당 앱이 Android 푸시를 전송하는 경우, 여전히 레거시 API를 사용 중이며 마이그레이션이 필요합니다.

앱과 앱 ID를 먼저 나열하려면 [View apps](/reference/view-apps) API를 사용하세요.

<h3 id="what-is-firebase-cloud-messaging-and-why-does-onesignal-need-a-service-account-private-key">
  Firebase Cloud Messaging이란 무엇이며, OneSignal에는 왜 Service Account 비공개 키가 필요한가요? \\
</h3>

\*\*Firebase Cloud Messaging (FCM)\*\*은 Android 기기에 푸시 알림을 전달하는 Google의 서비스입니다. **Service Account**는 OneSignal이 Firebase 프로젝트에 인증하기 위해 사용하는 Google 신원이며, **비공개 키**는 신원을 증명하는 JSON 파일입니다. 비공개 키를 업로드하면 OneSignal이 Firebase를 통해 사용자를 대신해 푸시를 전송할 권한을 부여받게 됩니다. 자세한 내용은 [Google의 Service Account 문서](https://cloud.google.com/iam/docs/service-account-overview)를 참조하세요.

***

## 관련 페이지

<Columns cols={2}>
  <Card title="모바일 SDK 설정" icon="mobile-screen" href="./mobile-sdk-setup">
    Android 앱에서 OneSignal SDK를 설치하고 초기화합니다.
  </Card>

  <Card title="모바일 푸시 설정" icon="bell" href="./mobile-push-setup">
    Android, iOS 및 기타 모바일 플랫폼별 설정 단계.
  </Card>

  <Card title="Huawei 푸시 설정" icon="mobile" href="./authorize-onesignal-to-send-huawei-push">
    Huawei App Gallery를 통해 배포되는 Huawei 앱에 OneSignal이 푸시를 보낼 수 있도록 승인합니다.
  </Card>

  <Card title="웹 푸시 설정" icon="globe" href="./web-push-setup">
    웹사이트용 푸시 알림을 구성합니다.
  </Card>
</Columns>