# تتبع اشتراكات App Store

<Aside type="caution" icon="setting" title="مطلوب مساعدة من المطور">
ستحتاج إلى مساعدة من فريق التطوير الخاص بك لإعداد هذا التكامل. يرجى مشاركة هذا الدليل معهم.
</Aside>

## نظرة عامة على التكامل

[إشعارات خادم App Store](https://developer.apple.com/documentation/appstoreservernotifications) هي خدمة من خادم إلى خادم من Apple ترسل رسالة في الوقت الفعلي إلى الواجهة الخلفية الخاصة بك كلما تغيرت حالة الاشتراك.

من خلال ربط إشعارات خادم App Store بـ Pushwoosh، يمكنك التفاعل مع دورة حياة الاشتراك بأكملها، بما في ذلك عمليات الشراء والتجديد والإلغاء ومشاكل الفوترة وانتهاء الصلاحية واسترداد الأموال — دون بناء البنية التحتية الخلفية الخاصة بك. كلما تغيرت حالة الاشتراك في حساب App Store الخاص بالمستخدم، تقوم Apple بإشعار Pushwoosh، ويقوم Pushwoosh بإطلاق حدث [`PW_Subscription*`](#tracked-events) المطابق في ملف تعريف المستخدم.

<Aside type="note">
يدعم هذا التكامل **اشتراكات iOS** (إشعارات خادم App Store V2). لتتبع اشتراكات Android، راجع [تتبع اشتراكات Google Play](/ar/product/integrations/google-play-subscription-tracking/).
</Aside>

### نوع التكامل

**المصدر:** يتم إرسال إشعارات خادم App Store من Apple إلى Pushwoosh.

### الأحداث المتعقبة

يقوم Pushwoosh بربط كل إشعار مدعوم من App Store بمجموعة أحداث موحدة `PW_Subscription*`، حتى تتمكن من إطلاق الحملات في أي مرحلة من مراحل دورة حياة الاشتراك.

| الحدث | يتم إطلاقه عندما |
| ----- | ---------- |
| `PW_SubscriptionStart` | يشتري المستخدم الاشتراك لأول مرة. |
| `PW_SubscriptionRenew` | يتم تجديد الاشتراك تلقائيًا لفترة فوترة جديدة. |
| `PW_SubscriptionCancel` | يقوم المستخدم بإيقاف التجديد التلقائي. يظل الاشتراك نشطًا حتى انتهاء صلاحيته. |
| `PW_SubscriptionResume` | يقوم المستخدم بإعادة تمكين التجديد التلقائي، أو يعيد الاشتراك قبل انتهاء صلاحية الاشتراك. |
| `PW_SubscriptionBillingIssue` | تفشل دفعة التجديد ويدخل الاشتراك في فترة إعادة محاولة الفوترة من Apple. |
| `PW_SubscriptionRecovered` | يتم إتمام عملية تجديد فاشلة سابقًا ويصبح الاشتراك نشطًا مرة أخرى. |
| `PW_SubscriptionExpired` | انتهت صلاحية الاشتراك بالكامل ولم يعد نشطًا. |
| `PW_SubscriptionRefund` | تقوم Apple برد مبلغ الشراء أو إلغاء الوصول. |

يحمل كل حدث نفس السمات:

- **productID:** معرف منتج App Store للاشتراك.
- **expiresAt:** وقت انتهاء الفترة المدفوعة الحالية، كطابع زمني Unix بالثواني. يتم تضمينه عندما توفره Apple.

<details>

<summary>كيفية ربط الأحداث بإشعارات خادم App Store</summary>

بالنسبة للمطورين الذين يتحققون من التكامل، يتوافق كل حدث Pushwoosh مع قيم `notificationType` (و `subtype`) هذه من App Store:

| حدث Pushwoosh | `notificationType` / `subtype` |
| --------------- | ------------------------------ |
| `PW_SubscriptionStart` | `SUBSCRIBED` / `INITIAL_BUY` |
| `PW_SubscriptionRenew` | `DID_RENEW` |
| `PW_SubscriptionCancel` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_DISABLED` |
| `PW_SubscriptionResume` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_ENABLED`, `SUBSCRIBED` / `RESUBSCRIBE` |
| `PW_SubscriptionBillingIssue` | `DID_FAIL_TO_RENEW` |
| `PW_SubscriptionRecovered` | `DID_RENEW` / `BILLING_RECOVERY` |
| `PW_SubscriptionExpired` | `EXPIRED` |
| `PW_SubscriptionRefund` | `REFUND`, `REVOKE` |

يتم الإقرار بأنواع الإشعارات الأخرى، مثل زيادات الأسعار وتغييرات الخطط والطلبات المعلقة وطلبات الاستهلاك، ولكنها لا تنشر حدثًا.

</details>


### كيف يعمل

1. تتغير حالة الاشتراك في حساب App Store الخاص بالمستخدم (شراء، تجديد، إلغاء، وما إلى ذلك).
2. ترسل Apple إشعار خادم App Store (V2) إلى URL الإشعار الخاص بك في Pushwoosh.
3. يقوم Pushwoosh بفك تشفير الحمولة الموقعة وقراءة `appAccountToken` من المعاملة.
4. يبحث Pushwoosh عن الجهاز الذي يتطابق HWID الخاص به مع هذا الرمز، ويجد المستخدم المرتبط به، وينشر حدث `PW_Subscription*` المطابق لهذا المستخدم.

<Aside type="caution" title="هام">
تعتمد المطابقة بين معاملة App Store ومستخدم Pushwoosh على `appAccountToken`. إذا لم يقم تطبيقك بتعيين هذا الرمز في وقت الشراء، يتلقى Pushwoosh الإشعار ولكن **لا يتم نشر أي حدث**. راجع [كيفية تعيين `appAccountToken`](#set-appaccounttoken-to-the-devices-pushwoosh-hwid).
</Aside>

### حالات الاستخدام

**استعادة المشتركين المتسربين:** لا يؤدي تعطيل التجديد التلقائي إلى إنهاء الوصول على الفور. يظل الاشتراك نشطًا حتى انتهاء الفترة المدفوعة، وهذه هي فرصتك لاستعادة المستخدم. عند حدوث `PW_SubscriptionCancel`، أطلق [Customer Journey](/ar/product/customer-journey/pushwoosh-journey-overview/) مع إشعار دفع للاحتفاظ بالعميل، أو [بريد إلكتروني](/ar/product/messaging-channels/emails/) حول الميزات التي سيفقدونها، أو [رسالة داخل التطبيق](/ar/product/messaging-channels/in-apps/) مع خصم على التجديد قبل انتهاء الوصول.

**إعداد المشتركين الجدد:** أطلق سلسلة ترحيب عند حدوث `PW_SubscriptionStart` لمساعدة المستخدمين على الحصول على قيمة من خطتهم مبكرًا وتمهيد الطريق للتجديد.

**إنقاذ المدفوعات الفاشلة:** عندما يتم إطلاق `PW_SubscriptionBillingIssue`، فهذا يعني أن دفعة التجديد لم تتم وأن الاشتراك في نافذة إعادة المحاولة من Apple. اطلب من المستخدم تحديث طريقة الدفع الخاصة به قبل أن يفقد الوصول، وتابع مع `PW_SubscriptionRecovered` للتأكيد بمجرد حل المشكلة.

**إعادة إشراك المستخدمين الذين انتهت صلاحية اشتراكهم:** ابدأ حملة إعادة تنشيط عند حدوث `PW_SubscriptionExpired` مع عرض للعملاء العائدين للمشتركين الذين تسربوا بالكامل.


## إعداد التكامل

### تعيين `appAccountToken` إلى HWID الخاص بالجهاز في Pushwoosh

يحدد Pushwoosh المستخدم الصحيح من **HWID** الخاص بالجهاز، لذلك يجب على تطبيقك إرفاق HWID الخاص بالجهاز في Pushwoosh كـ `appAccountToken` عند شراء الاشتراك من خلال StoreKit.

بشكل افتراضي، يستخدم Pushwoosh iOS SDK `identifierForVendor` (IDFV) الخاص بالجهاز كـ HWID. IDFV هو بالفعل `UUID`، وهو التنسيق الذي تطلبه Apple بالضبط لـ `appAccountToken`. يقوم Pushwoosh بعد ذلك بحل المستخدم المرتبط حاليًا بهذا الجهاز تلقائيًا، لذلك يعمل هذا سواء قمت بتعيين User IDs الخاصة بك باستخدام `setUserId` أم لا.

<Tabs>
<TabItem label="StoreKit 2">
```swift
// Attach the device's Pushwoosh HWID (the default IDFV) as the appAccountToken
var options: Set<Product.PurchaseOption> = []
if let hwid = UIDevice.current.identifierForVendor {
    options.insert(.appAccountToken(hwid))
}

let result = try await product.purchase(options: options)
```
</TabItem>
<TabItem label="StoreKit 1">
```swift
// applicationUsername must be a UUID string to populate appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)
```
</TabItem>
</Tabs>

<Aside type="caution">
إذا كان تطبيقك يتجاوز HWID الخاص بـ Pushwoosh (على سبيل المثال، عبر وحدة HWID الدائمة [`PushwooshKeychain`](/ar/developer/pushwoosh-sdk/ios-sdk/ios-keychain/) أو قيمة مخصصة)، فقم بتعيين `appAccountToken` إلى نفس HWID. يجب أن يتطابق الرمز مع HWID الخاص بالجهاز في Pushwoosh، وإلا لا يمكن إسناد الحدث.
</Aside>

### العثور على رمز تطبيق Pushwoosh الخاص بك

افتح تطبيقك في لوحة تحكم Pushwoosh. يتم عرض **رمز التطبيق** الخاص بك (تنسيق `XXXXX-XXXXX`) أسفل اسم المشروع في الشريط الجانبي.

ستحتاج إلى رمز التطبيق لبناء URL الإشعار.

### إضافة URL الإشعار في App Store Connect

1. في [App Store Connect](https://appstoreconnect.apple.com/)، انتقل إلى **Apps → تطبيقك → App Information** (تحت *General*)، ومرر لأسفل إلى **App Store Server Notifications**.
2. حدد إشعارات **Version 2**.
3. قم بتعيين كل من **Production Server URL** و **Sandbox Server URL** إلى:

```
https://appstore-notifications.pushwoosh.com/appstore/YOUR_APPLICATION_CODE/
```

4. استبدل `YOUR_APPLICATION_CODE` برمز التطبيق من الخطوة السابقة. احتفظ بالشرطة المائلة في النهاية.

<Aside type="note">
إذا كان حسابك مستضافًا في **مركز بيانات الولايات المتحدة**، فاستخدم `https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/` بدلاً من ذلك. إذا لم تكن متأكدًا من مركز البيانات الذي يستخدمه حسابك، فاتصل بمدير نجاح العملاء أو [دعم Pushwoosh](https://www.pushwoosh.com/contact-us/).
</Aside>

### تأكيد الأحداث في Pushwoosh

يسجل Pushwoosh كل حدث `PW_Subscription*` في مشروعك في المرة الأولى التي يحدث فيها، مع سمات `productID` و `expiresAt`. بعد اختبار في بيئة الاختبار (sandbox)، افتح **Audience → Events** للتحقق من ظهور الأحداث. تكون بعد ذلك جاهزة للتقسيم والإحصاءات و Customer Journeys.

### بناء حملتك

أنشئ [Customer Journey](/ar/product/customer-journey/pushwoosh-journey-overview/) مع [دخول قائم على المشغل](/ar/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/) على أي حدث `PW_Subscription*`، على سبيل المثال `PW_SubscriptionCancel` للاستعادة أو `PW_SubscriptionStart` للإعداد، وأضف الرسائل التي تريد إرسالها.

## الاختبار

يمكن إطلاق إشعارات خادم App Store في بيئة **Sandbox** من Apple. للتحقق من التكامل:

1. قم بإجراء عملية شراء اشتراك في بيئة الاختبار مع تعيين `appAccountToken` كما هو موضح أعلاه. هذا يطلق `PW_SubscriptionStart`.
2. قم بتعطيل التجديد التلقائي من شاشة إدارة الاشتراكات في الجهاز. هذا يطلق `PW_SubscriptionCancel`.
3. في لوحة تحكم Pushwoosh، افتح ملف تعريف المستخدم وانتقل إلى [سجل الأحداث](/ar/product/audience-data-and-segmentation/user-explorer/#events-history-tab).
4. تأكد من ظهور الأحداث في غضون لحظات قليلة.