# Persistent Device ID (Keychain)

The `PushwooshKeychain` module provides persistent device identification (HWID) that survives app reinstallation. This is useful for testing and development scenarios where you need to maintain the same device identity even after reinstalling the app.

<Aside type="note">
Available starting from **SDK version 7.0.16**.
</Aside>

## How it works

By default, iOS generates a new `identifierForVendor` (IDFV) each time an app is reinstalled, which results in a new HWID being registered with Pushwoosh. The `PushwooshKeychain` module stores the HWID in the iOS Keychain, which persists across app reinstalls.

### Environment detection

The module automatically detects the app environment and behaves differently:

| Environment | Persistent HWID |
|-------------|-----------------|
| Simulator | Enabled |
| Debug/Development | Enabled |
| TestFlight | Enabled |
| App Store | **Disabled** |

<Aside type="caution" title="Important">
The module is **automatically disabled** in App Store builds for privacy compliance. This ensures that production users always get a fresh HWID when they reinstall your app.

If you prefer not to include this module in your production app at all, you can safely remove `PushwooshKeychain` from your release build configuration or use conditional linking for Debug/TestFlight builds only.
</Aside>

## Installation

### Swift Package Manager

Add `PushwooshKeychain` to your target when integrating the Pushwoosh SDK:

1. In Xcode, go to **File → Add Package Dependencies**
2. Enter the package URL: `https://github.com/Pushwoosh/Pushwoosh-XCFramework`
3. Select `PushwooshKeychain` in addition to the required frameworks

<Tabs>
<TabItem label="Required frameworks">
* `PushwooshFramework`
* `PushwooshCore`
* `PushwooshBridge`
</TabItem>
<TabItem label="Optional frameworks">
* `PushwooshKeychain` — Persistent device ID
* `PushwooshLiveActivities` — Live Activities support
* `PushwooshVoIP` — VoIP push notifications
* `PushwooshForegroundPush` — Custom foreground notifications
</TabItem>
</Tabs>

### CocoaPods

Add the Keychain subspec to your `Podfile`:

```ruby
target 'MyApp' do
  use_frameworks!

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

Then run:

```bash
pod install
```

## Usage

**No code changes required.** Once you add the `PushwooshKeychain` module to your project, it works automatically:

1. On first app launch, the module generates an HWID and stores it in the Keychain
2. On subsequent launches (including after reinstall), the module retrieves the stored HWID
3. The SDK uses this persistent HWID for device registration with Pushwoosh

## Use cases

The `PushwooshKeychain` module is particularly useful for:

- **QA testing** — Maintain the same device identity across multiple app installs during testing
- **Development** — Keep consistent device targeting while iterating on your app
- **TestFlight beta testing** — Track the same beta testers across app updates and reinstalls

<Aside type="tip">
Since the module is disabled in App Store builds, you don't need to conditionally include it — it's safe to ship with your production app.
</Aside>

## Troubleshooting

### Verifying the module is active

Check the Xcode console logs when your app launches. You should see a log message like:

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

or

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

### Clearing the stored HWID

If you need to reset the persistent HWID during development, you can call:

<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">
After clearing, the next app launch will generate and store a new HWID.
</Aside>