# معرف الجهاز الدائم (Keychain)

توفر وحدة `PushwooshKeychain` تعريفًا دائمًا للجهاز (HWID) يبقى حتى بعد إعادة تثبيت التطبيق. هذا مفيد لسيناريوهات الاختبار والتطوير حيث تحتاج إلى الحفاظ على نفس هوية الجهاز حتى بعد إعادة تثبيت التطبيق.

<Aside type="note">
متاح بدءًا من **إصدار SDK 7.0.16**.
</Aside>

## كيف يعمل

بشكل افتراضي، يقوم iOS بإنشاء `identifierForVendor` (IDFV) جديد في كل مرة يتم فيها إعادة تثبيت التطبيق، مما يؤدي إلى تسجيل HWID جديد مع Pushwoosh. تقوم وحدة `PushwooshKeychain` بتخزين HWID في iOS Keychain، والذي يستمر عبر عمليات إعادة تثبيت التطبيق.

### كشف البيئة

تكشف الوحدة تلقائيًا عن بيئة التطبيق وتتصرف بشكل مختلف:

| البيئة | HWID دائم |
|---|---|
| المحاكي (Simulator) | مفعل |
| التصحيح/التطوير (Debug/Development) | مفعل |
| TestFlight | مفعل |
| متجر التطبيقات (App Store) | **معطل** |

<Aside type="caution" title="هام">
يتم **تعطيل الوحدة تلقائيًا** في إصدارات متجر التطبيقات (App Store) للامتثال للخصوصية. هذا يضمن أن المستخدمين في بيئة الإنتاج يحصلون دائمًا على HWID جديد عند إعادة تثبيت تطبيقك.

إذا كنت تفضل عدم تضمين هذه الوحدة في تطبيق الإنتاج الخاص بك على الإطلاق، يمكنك إزالة `PushwooshKeychain` بأمان من تكوين إصدار الإنتاج الخاص بك أو استخدام الربط الشرطي لإصدارات Debug/TestFlight فقط.
</Aside>

## التثبيت

### مدير حزم Swift (Swift Package Manager)

أضف `PushwooshKeychain` إلى هدفك عند دمج Pushwoosh SDK:

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` — معرف الجهاز الدائم
* `PushwooshLiveActivities` — دعم الأنشطة المباشرة (Live Activities)
* `PushwooshVoIP` — إشعارات VoIP push
* `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 التجريبي** — تتبع نفس مختبري النسخة التجريبية عبر تحديثات التطبيق وإعادة تثبيته.

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