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

مطلوب مساعدة من المطور

ستحتاج إلى مساعدة من فريق التطوير الخاص بك لإعداد هذا التكامل. يرجى مشاركة هذا الدليل معهم.

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

إشعارات خادم App Store هي خدمة من خادم إلى خادم من Apple ترسل رسالة في الوقت الفعلي إلى الواجهة الخلفية الخاصة بك كلما تغيرت حالة الاشتراك.

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

ملاحظة

يدعم هذا التكامل اشتراكات iOS (إشعارات خادم App Store V2). لتتبع اشتراكات Android، راجع تتبع اشتراكات Google Play.

نوع التكامل

المصدر: يتم إرسال إشعارات خادم 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.

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

بالنسبة للمطورين الذين يتحققون من التكامل، يتوافق كل حدث 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

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

كيف يعمل

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

هام

تعتمد المطابقة بين معاملة App Store ومستخدم Pushwoosh على appAccountToken. إذا لم يقم تطبيقك بتعيين هذا الرمز في وقت الشراء، يتلقى Pushwoosh الإشعار ولكن لا يتم نشر أي حدث. راجع كيفية تعيين appAccountToken.

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

استعادة المشتركين المتسربين: لا يؤدي تعطيل التجديد التلقائي إلى إنهاء الوصول على الفور. يظل الاشتراك نشطًا حتى انتهاء الفترة المدفوعة، وهذه هي فرصتك لاستعادة المستخدم. عند حدوث PW_SubscriptionCancel، أطلق Customer Journey مع إشعار دفع للاحتفاظ بالعميل، أو بريد إلكتروني حول الميزات التي سيفقدونها، أو رسالة داخل التطبيق مع خصم على التجديد قبل انتهاء الوصول.

إعداد المشتركين الجدد: أطلق سلسلة ترحيب عند حدوث 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 أم لا.

StoreKit 2

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

StoreKit 1

// applicationUsername must be a UUID string to populate appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)

تنبيه

إذا كان تطبيقك يتجاوز HWID الخاص بـ Pushwoosh (على سبيل المثال، عبر وحدة HWID الدائمة PushwooshKeychain أو قيمة مخصصة)، فقم بتعيين appAccountToken إلى نفس HWID. يجب أن يتطابق الرمز مع HWID الخاص بالجهاز في Pushwoosh، وإلا لا يمكن إسناد الحدث.

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

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

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

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

1. في App Store Connect، انتقل إلى 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 برمز التطبيق من الخطوة السابقة. احتفظ بالشرطة المائلة في النهاية.

ملاحظة

إذا كان حسابك مستضافًا في مركز بيانات الولايات المتحدة، فاستخدم https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/ بدلاً من ذلك. إذا لم تكن متأكدًا من مركز البيانات الذي يستخدمه حسابك، فاتصل بمدير نجاح العملاء أو دعم Pushwoosh.

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

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

بناء حملتك

أنشئ Customer Journey مع دخول قائم على المشغل على أي حدث PW_Subscription*، على سبيل المثال PW_SubscriptionCancel للاستعادة أو PW_SubscriptionStart للإعداد، وأضف الرسائل التي تريد إرسالها.

الاختبار

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

1. قم بإجراء عملية شراء اشتراك في بيئة الاختبار مع تعيين appAccountToken كما هو موضح أعلاه. هذا يطلق PW_SubscriptionStart.
2. قم بتعطيل التجديد التلقائي من شاشة إدارة الاشتراكات في الجهاز. هذا يطلق PW_SubscriptionCancel.
3. في لوحة تحكم Pushwoosh، افتح ملف تعريف المستخدم وانتقل إلى سجل الأحداث.
4. تأكد من ظهور الأحداث في غضون لحظات قليلة.