# 持久化设备 ID (Keychain)

`PushwooshKeychain` 模块提供了持久化的设备标识 (HWID)，该标识在应用重装后依然存在。这对于测试和开发场景非常有用，因为在这些场景下，您需要在重新安装应用后仍保持相同的设备身份。

<Aside type="note">
从 **SDK 7.0.16** 版本开始提供。
</Aside>

## 工作原理

默认情况下，每次重装应用时，iOS 都会生成一个新的 `identifierForVendor` (IDFV)，这会导致一个新的 HWID 注册到 Pushwoosh。`PushwooshKeychain` 模块将 HWID 存储在 iOS Keychain 中，该 Keychain 在应用重装后仍然持久存在。

### 环境检测

该模块会自动检测应用环境并采取不同的行为：

| 环境 | 持久化 HWID |
|-------------|-----------------|
| 模拟器 | 已启用 |
| 调试/开发 | 已启用 |
| TestFlight | 已启用 |
| App Store | **已禁用** |

<Aside type="caution" title="重要提示">
为了符合隐私规定，该模块在 App Store 构建版本中会**自动禁用**。这确保了生产环境的用户在重新安装您的应用时，总会获得一个新的 HWID。

如果您完全不希望在生产应用中包含此模块，可以安全地从您的发布构建配置中移除 `PushwooshKeychain`，或者仅为调试/TestFlight 构建版本使用条件链接。
</Aside>

## 安装

### Swift Package Manager

在集成 Pushwoosh SDK 时，将 `PushwooshKeychain` 添加到您的 target 中：

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` — 实时活动支持
* `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 并将其存储在 Keychain 中
2. 在后续启动时（包括重装后），模块会检索已存储的 HWID
3. SDK 使用此持久化 HWID 向 Pushwoosh 注册设备

## 使用场景

`PushwooshKeychain` 模块在以下场景中特别有用：

- **QA 测试** — 在测试期间，跨多个应用安装维护相同的设备身份
- **开发** — 在迭代应用时保持一致的设备目标
- **TestFlight Beta 测试** — 跨应用更新和重装跟踪相同的 Beta 测试人员

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