# 영구 장치 ID (키체인)

`PushwooshKeychain` 모듈은 앱을 재설치해도 유지되는 영구 장치 식별(HWID)을 제공합니다. 이는 앱을 재설치한 후에도 동일한 장치 ID를 유지해야 하는 테스트 및 개발 시나리오에 유용합니다.

<Aside type="note">
**SDK 버전 7.0.16**부터 사용 가능합니다.
</Aside>

## 작동 방식

기본적으로 iOS는 앱이 재설치될 때마다 새로운 `identifierForVendor`(IDFV)를 생성하며, 이로 인해 새로운 HWID가 Pushwoosh에 등록됩니다. `PushwooshKeychain` 모듈은 HWID를 iOS 키체인에 저장하며, 이 키체인은 앱 재설치 시에도 유지됩니다.

### 환경 감지

이 모듈은 앱 환경을 자동으로 감지하고 다르게 동작합니다:

| 환경 | 영구 HWID |
|---|---|
| 시뮬레이터 | 활성화됨 |
| 디버그/개발 | 활성화됨 |
| TestFlight | 활성화됨 |
| App Store | **비활성화됨** |

<Aside type="caution" title="중요">
이 모듈은 개인 정보 보호 규정을 준수하기 위해 App Store 빌드에서는 **자동으로 비활성화됩니다**. 이를 통해 프로덕션 사용자는 앱을 재설치할 때 항상 새로운 HWID를 받게 됩니다.

프로덕션 앱에 이 모듈을 전혀 포함하지 않으려면 릴리스 빌드 구성에서 `PushwooshKeychain`을 안전하게 제거하거나 디버그/TestFlight 빌드에만 조건부 링크를 사용할 수 있습니다.
</Aside>

## 설치

### Swift Package Manager

Pushwoosh SDK를 통합할 때 타겟에 `PushwooshKeychain`을 추가하세요:

1. Xcode에서 **File → Add Package Dependencies**로 이동합니다.
2. 패키지 URL을 입력합니다: `https://github.com/Pushwoosh/Pushwoosh-XCFramework`
3. 필수 프레임워크 외에 `PushwooshKeychain`을 선택합니다.

<Tabs>
<TabItem label="필수 프레임워크">
* `PushwooshFramework`
* `PushwooshCore`
* `PushwooshBridge`
</TabItem>
<TabItem label="선택적 프레임워크">
* `PushwooshKeychain` — 영구 장치 ID
* `PushwooshLiveActivities` — Live Activities 지원
* `PushwooshVoIP` — VoIP 푸시 알림
* `PushwooshForegroundPush` — 사용자 지정 포그라운드 알림
</TabItem>
</Tabs>

### CocoaPods

Keychain 하위 스펙을 `Podfile`에 추가합니다:

```ruby
target 'MyApp' do
  use_frameworks!

  pod 'PushwooshXCFramework'
  pod 'PushwooshXCFramework/PushwooshKeychain'
end
```

그런 다음 실행합니다:

```bash
pod install
```

## 사용법

**코드 변경이 필요하지 않습니다.** `PushwooshKeychain` 모듈을 프로젝트에 추가하면 자동으로 작동합니다:

1. 첫 앱 실행 시, 모듈은 HWID를 생성하여 키체인에 저장합니다.
2. 이후 실행 시(재설치 후 포함), 모듈은 저장된 HWID를 검색합니다.
3. SDK는 이 영구 HWID를 사용하여 Pushwoosh에 장치를 등록합니다.

## 사용 사례

`PushwooshKeychain` 모듈은 다음과 같은 경우에 특히 유용합니다:

- **QA 테스트** — 테스트 중 여러 앱 설치에 걸쳐 동일한 장치 ID를 유지합니다.
- **개발** — 앱을 반복 개발하는 동안 일관된 장치 타겟팅을 유지합니다.
- **TestFlight 베타 테스트** — 앱 업데이트 및 재설치에 걸쳐 동일한 베타 테스터를 추적합니다.

<Aside type="tip">
이 모듈은 App Store 빌드에서 비활성화되므로 조건부로 포함할 필요가 없습니다. 프로덕션 앱과 함께 배포해도 안전합니다.
</Aside>

## 문제 해결

### 모듈 활성화 확인

앱이 실행될 때 Xcode 콘솔 로그를 확인하세요. 다음과 같은 로그 메시지가 표시되어야 합니다:

```
[Pushwoosh] Detected environment: Debug. Persistent HWID: ENABLED
```

또는

```
[Pushwoosh] Detected environment: App Store. Persistent HWID: DISABLED
```

### 저장된 HWID 지우기

개발 중에 영구 HWID를 재설정해야 하는 경우 다음을 호출할 수 있습니다:

<Tabs>
<TabItem label="Swift">
```swift
import PushwooshFramework

// Clear the stored HWID from Keychain
Pushwoosh.Keychain.clearPersistentHWID()
```
</TabItem>
<TabItem label="Objective-C">
```objective-c
@import PushwooshFramework;

// Clear the stored HWID from Keychain
[Pushwoosh.Keychain clearPersistentHWID];
```
</TabItem>
</Tabs>

<Aside type="note">
지운 후 다음 앱 실행 시 새로운 HWID가 생성되어 저장됩니다.
</Aside>