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

# Windows 앱 설정

> Windows Push Notification Service(WNS) 및 OneSignal의 REST API를 사용하여 Universal Windows Platform(UWP) 앱에 OneSignal 푸시 알림을 통합하는 완전한 가이드입니다

# Windows 앱 설정

## 요구 사항

Windows 앱에 대한 OneSignal을 설정하기 전에 다음을 확인하세요:

* **Universal Windows Platform (UWP) 앱** - OneSignal은 현재 UWP 앱만 지원합니다
* **Microsoft Store 앱 등록** - Package SID 및 Secret Key를 얻는 데 필요합니다
* **OneSignal 계정** - 구성된 앱 및 플랫폼 설정이 있는 무료 계정

<Info>OneSignal은 현재 Windows App SDK(WinUI 3)를 지원하지 않습니다. 앱이 UWP 대신 Windows App SDK를 사용하는 경우 [마이그레이션 옵션](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/notifications)에 대한 지침을 위해 `support@onesignal.com`에 문의하세요.</Info>

## OneSignal 앱 및 플랫폼 구성

### 1단계: OneSignal 계정 설정

팀에 이미 OneSignal 계정이 있는 경우 플랫폼 설정을 구성하려면 [관리자 액세스를 요청](./manage-team-members)하세요. 그렇지 않으면 [무료 계정을 만들어](https://onesignal.com) 시작하세요.

### 2단계: OneSignal 앱 생성 또는 구성

OneSignal을 사용하면 크로스 플랫폼 메시징을 위해 단일 앱 내에서 여러 플랫폼(iOS, Android, Huawei, Amazon, Windows)을 구성할 수 있습니다.

#### 새 앱 만들기

1. 대시보드에서 **New App/Website**를 클릭합니다
2. 인식 가능한 앱 이름과 조직 이름을 선택합니다
3. 플랫폼으로 \*\*Windows (UWP)\*\*를 선택합니다
4. **Next: Configure Your Platform**을 클릭합니다

<Frame caption="Windows 플랫폼으로 새 OneSignal 앱 만들기">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/13e619dc5fd638b4d9adf5505ddd645de431dc963dbeeac923462060c030ce7c-Screenshot_2025-04-07_at_3.48.57_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=77c331bb0aea78c3f5d96ed065e14d1f" width="2344" height="1544" data-path="images/docs/13e619dc5fd638b4d9adf5505ddd645de431dc963dbeeac923462060c030ce7c-Screenshot_2025-04-07_at_3.48.57_PM.png" />
</Frame>

#### 기존 앱에 플랫폼 추가

1. 기존 앱을 선택합니다
2. **설정 > 푸시 및 인앱**으로 이동합니다
3. **Add Platform**을 클릭하고 \*\*Windows (UWP)\*\*를 선택합니다

<Frame caption="OneSignal 앱 설정 및 Windows 플랫폼 선택">
  <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/5cfafd284e02ae310a7e2a973d58d858e36d59bd54a7c58c3dc5da5ff5946721-Screenshot_2025-04-07_at_3.51.19_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=2059055133014853ce9d5a62fb7c9bbc" width="2428" height="1960" data-path="images/docs/5cfafd284e02ae310a7e2a973d58d858e36d59bd54a7c58c3dc5da5ff5946721-Screenshot_2025-04-07_at_3.51.19_PM.png" />
</Frame>

### 3단계: 추가 플랫폼 구성 (선택 사항)

크로스 플랫폼 앱을 빌드하는 경우 지금 추가 플랫폼을 구성하세요:

* **Android**: [Firebase 자격 증명 설정](./android-firebase-credentials)
* **iOS**: [p8 토큰(권장)](./ios-p8-token-based-connection-to-apns) 또는 [p12 인증서](./ios-p12-generate-certificates)
* **Amazon**: [API 키 생성](./generate-an-amazon-api-key)
* **Huawei**: [OneSignal 권한 부여](./authorize-onesignal-to-send-huawei-push)

각 플랫폼에 대한 자격 증명을 입력한 후 **Save & Continue**를 클릭합니다.

### 4단계: 대상 SDK 선택

대상 SDK로 **Windows UWP**를 선택하고 **Save & Continue**를 클릭합니다.

<Frame caption="플랫폼별 문서에 액세스하려면 Windows UWP SDK 선택">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/13775481f708ed06086e4f6cfd4892a7e47970b669757212f62b2f508c0d1ab7-Screenshot_2025-04-07_at_3.57.27_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=2509168f647aef9dc29e59805d0cec21" width="3162" height="1886" data-path="images/docs/13775481f708ed06086e4f6cfd4892a7e47970b669757212f62b2f508c0d1ab7-Screenshot_2025-04-07_at_3.57.27_PM.png" />
</Frame>

### 5단계: 앱 ID 저장

**중요:** OneSignal 앱 ID를 복사하고 안전하게 저장하세요. API 호출 및 사용자 등록에 필요합니다.

<Frame caption="앱 ID를 저장하고 액세스가 필요한 팀 구성원 초대">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/45dc4f796e919a3da95ab0f3cba25be49091fe56c0a97b159dc12dd16702d734-Screenshot_2025-04-07_at_3.59.42_PM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=6c14c2a05be8a4474e22a52aaa7d76da" width="2710" height="1846" data-path="images/docs/45dc4f796e919a3da95ab0f3cba25be49091fe56c0a97b159dc12dd16702d734-Screenshot_2025-04-07_at_3.59.42_PM.png" />
</Frame>

선택적으로 **Invite**를 클릭하여 팀 구성원을 초대한 다음 **Done**을 클릭하여 계속합니다.

## Windows 플랫폼 구성

### Microsoft Store 자격 증명 가져오기

OneSignal은 Windows Push Notification Service(WNS)를 사용하므로 Microsoft Store의 자격 증명이 필요합니다:

1. **Microsoft Store에 게시** - 앱이 Microsoft Store에 등록되어 있어야 합니다(공개적으로 사용 가능하지 않더라도)
2. **Package SID 및 Secret Key 얻기** - 이러한 자격 증명을 검색하려면 [Microsoft의 상세 가이드](https://learn.microsoft.com/en-us/azure/notification-hubs/notification-hubs-windows-store-dotnet-get-started-wns-push-notification#create-an-app-in-windows-store)를 따르세요
3. **OneSignal 플랫폼 구성**:
   * OneSignal 대시보드에서 \*\*설정 > Windows (UWP)\*\*로 이동합니다
   * Package SID 및 Secret Key를 붙여넣습니다
   * **Save**를 클릭하여 플랫폼을 활성화합니다

<Frame caption="OneSignal 대시보드에서 Windows 플랫폼 자격 증명 구성">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b83d13b-Screenshot_2023-03-21_at_12.02.58_PM.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=aac1ef94751db6f307284a86a455b6cf" width="1842" height="940" data-path="images/docs/b83d13b-Screenshot_2023-03-21_at_12.02.58_PM.png" />
</Frame>

> **주의:** Package SID 및 Secret Key는 앱이 Microsoft Store에 등록된 후에만 사용할 수 있습니다. 이러한 자격 증명 없이는 로컬에서 푸시 알림을 테스트할 수 없습니다.

## SDK 통합

### 아키텍처 이해

OneSignal은 전용 UWP SDK를 제공하지 않습니다. 대신 다음을 사용하여 통합합니다:

1. **Windows Push Notification Service (WNS)** - Microsoft의 기본 푸시 서비스
2. **OneSignal REST API** - 사용자 관리 및 메시지 전송용
3. **Notification Channel URI** - 푸시 알림의 장치 토큰 역할

WNS에 대한 포괄적인 이해를 위해 [Microsoft의 WNS 문서](https://docs.microsoft.com/en-us/windows/uwp/design/shell/tiles-and-notifications/windows-push-notification-services--wns--overview)를 검토하세요.

### 푸시 알림을 위한 사용자 등록

#### 1단계: 알림 채널 요청

Microsoft의 가이드를 따라 [알림 채널을 생성](https://learn.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications/request-create-save-notification-channel)하세요. WNS에서 반환된 채널 URI가 장치 토큰 역할을 합니다.

```csharp theme={null}
// Example: Getting notification channel URI
var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
string channelUri = channel.Uri; // This is your token for OneSignal
```

#### 2단계: OneSignal 사용자 레코드 생성

장치를 등록하려면 OneSignal의 [사용자 생성](/reference/create-user) API를 호출합니다:

**필수 매개변수:**

* `subscription.type`: `"WindowsPush"`
* `subscription.token`: 1단계의 채널 URI

**권장 매개변수:**

* `identity.external_id`: 사용자의 고유 식별자(예: 시스템의 사용자 ID)
* `properties`: 타겟팅을 위한 모든 사용자 지정 사용자 속성

```json theme={null}
{
  "identity": {
    "external_id": "your-user-id-123"
  },
  "subscriptions": [
    {
      "type": "WindowsPush",
      "token": "https://cloud.notify.windows.com/?token=..."
    }
  ],
  "properties": {
    "tags": {
      "user_type": "premium",
      "app_version": "1.2.0"
    }
  }
}
```

> **주의:** 채널 URI는 만료되고 변경될 수 있습니다. 채널 URI를 주기적으로 새로 고치고 변경될 때 OneSignal 사용자 레코드를 업데이트하는 로직을 구현하세요.

### 채널 URI 변경 처리

WNS 채널 URI는 만료될 수 있습니다. 새로 고쳐야 하는 시기를 감지하려면 `PushNotificationReceived` 이벤트를 구현하세요:

```csharp theme={null}
channel.PushNotificationReceived += OnPushNotificationReceived;

// Check if channel URI has changed
if (channel.Uri != storedChannelUri) {
    // Update OneSignal user record with new URI
    await UpdateOneSignalUser(channel.Uri);
}
```

## 푸시 알림 전송

### OneSignal 대시보드 사용

1. OneSignal 대시보드에서 **메시지 > 푸시**로 이동합니다
2. 새 푸시 알림을 만듭니다
3. Windows 플랫폼을 선택합니다
4. 메시지 콘텐츠와 타겟팅을 구성합니다
5. 즉시 전송하거나 나중에 예약합니다

### OneSignal API 사용

[알림 생성](/reference/create-message) API를 사용하여 프로그래밍 방식으로 알림을 전송합니다:

```json theme={null}
{
  "app_id": "your-onesignal-app-id",
  "contents": {"en": "Your notification message"},
  "headings": {"en": "Notification Title"},
  "include_external_user_ids": ["your-user-id-123"],
  "channel_for_external_user_ids": "push"
}
```

상세한 메시징 옵션 및 고급 타겟팅에 대해서는 [푸시 메시지 전송](./push)을 참조하세요.

## 다음 단계 및 모범 사례

### 통합 테스트

1. **알림 채널 생성 테스트** - 앱이 WNS 채널을 성공적으로 생성하고 유지 관리하는지 확인합니다
2. **사용자 등록 확인** - 사용자가 OneSignal 대시보드에 올바르게 등록되었는지 확인합니다
3. **테스트 알림 전송** - OneSignal 대시보드를 사용하여 테스트 메시지를 전송합니다
4. **알림 이벤트 처리** - 알림 수신, 열림 및 해제 이벤트에 대한 적절한 처리를 구현합니다

### 일반적인 문제 및 해결 방법

**채널 URI가 작동하지 않음**

* Package SID 및 Secret Key가 올바르게 구성되었는지 확인합니다
* 앱이 Microsoft Store에 올바르게 등록되어 있는지 확인합니다
* 채널 URI가 만료되지 않았는지 확인합니다

**사용자가 알림을 받지 못함**

* OneSignal 사용자 레코드가 성공적으로 생성되었는지 확인합니다
* OneSignal에서 Windows 플랫폼이 올바르게 구성되었는지 확인합니다
* Windows 알림 설정에서 알림이 차단되지 않았는지 확인합니다

**API 통합 문제**

* OneSignal 앱 ID가 올바른지 확인합니다
* 올바른 API 엔드포인트와 인증을 사용하고 있는지 확인합니다
* 문제 해결을 위해 API 응답 코드 및 오류 메시지를 검토합니다

### 프로덕션 고려 사항

* 모든 OneSignal API 호출에 대한 적절한 오류 처리를 구현합니다
* 채널 URI 새로 고침 실패에 대한 모니터링을 설정합니다
* 네트워크 문제 중 API 호출을 위한 오프라인 큐잉 구현을 고려합니다
* 최대 앱 사용 기간 동안 사용자 등록 확장을 계획합니다

추가 지원 및 고급 구현 지침은 OneSignal 지원팀에 문의하거나 포괄적인 [API 문서](/reference/rest-api-overview)를 참조하세요.