تتبع اشتراكات Google Play

تحتاج إلى مساعدة المطور

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

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

إشعارات المطورين في الوقت الفعلي (RTDN) هي خدمة من خادم إلى خادم من Google Play ترسل رسالة في الوقت الفعلي كلما تغيرت حالة الاشتراك.

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

ملاحظة

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

نوع التكامل

المصدر: يتم إرسال إشعارات المطورين في الوقت الفعلي من Google Play إلى Pushwoosh.

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

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

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

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

• productID: معرّف منتج Google Play للاشتراك.
• expiresAt: وقت انتهاء الفترة المدفوعة الحالية، كطابع زمني Unix بالثواني. يتم تضمينه عندما يوفره Google.

كيفية ربط الأحداث بإشعارات المطورين في الوقت الفعلي

بالنسبة للمطورين الذين يتحققون من التكامل، يتوافق كل حدث Pushwoosh مع قيم notificationType التالية من RTDN:

حدث Pushwoosh	notificationType من RTDN
PW_SubscriptionStart	SUBSCRIPTION_PURCHASED (4)
PW_SubscriptionRenew	SUBSCRIPTION_RENEWED (2)
PW_SubscriptionCancel	SUBSCRIPTION_CANCELED (3)
PW_SubscriptionResume	SUBSCRIPTION_RESTARTED (7)
PW_SubscriptionBillingIssue	SUBSCRIPTION_IN_GRACE_PERIOD (6)
PW_SubscriptionRecovered	SUBSCRIPTION_RECOVERED (1)
PW_SubscriptionExpired	SUBSCRIPTION_EXPIRED (13)
PW_SubscriptionRefund	SUBSCRIPTION_REVOKED (12)

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

كيف يعمل

لا يحمل إشعار Google Play أي معرّف Pushwoosh. يتضمن فقط رمز الشراء وpackageName الخاص بالتطبيق. لذا، يقوم تطبيقك بوضع علامة على كل عملية شراء بالمعرّف الذي يحتاجه Pushwoosh، ويقرأه Pushwoosh مرة أخرى من عملية الشراء كلما وصل إشعار.

1. تتغير حالة الاشتراك في حساب Google Play الخاص بالمستخدم (شراء، تجديد، إلغاء، وما إلى ذلك).
2. ينشر Google Play رسالة RTDN إلى الموضوع المشترك لـ Pushwoosh.
3. يقرأ Pushwoosh obfuscatedAccountId الخاص بالشراء، والذي قام تطبيقك بتعيينه إلى <AppCode>:<hwid> في وقت الشراء.
4. يحدد Pushwoosh الجهاز الذي يتطابق HWID الخاص به، ويجد المستخدم المرتبط به، وينشر حدث PW_Subscription* المطابق لذلك المستخدم.

هام

يعتمد التطابق بين عملية شراء Google Play ومستخدم Pushwoosh على obfuscatedAccountId. إذا لم يقم تطبيقك بتعيين هذه القيمة في وقت الشراء، فإن Pushwoosh يتلقى الإشعار ولكن لا يتم نشر أي حدث. يتم تعيينه عند الشراء ولا يمكن ملؤه بأثر رجعي للاشتراكات الحالية. انظر كيفية تعيين معرّف الحساب عند الشراء.

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

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

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

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

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

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

قبل أن تبدأ، تأكد من أن لديك تطبيق Pushwoosh مع تكوين FCM (مطلوب بالفعل للإشعارات الفورية)، وتطبيق Google Play مع اشتراك، ووصول إداري إلى Play Console.

تعيين معرّف الحساب عند الشراء

يحدد Pushwoosh المستخدم الصحيح من HWID الخاص بالجهاز، مع Application Code الخاص بك. يعرض Pushwoosh Android SDK مساعدًا، getSubscriptionAccountId()، الذي يعيد هذه القيمة منسقة بالفعل كـ <AppCode>:<hwid>. مررها إلى BillingFlowParams.setObfuscatedAccountId() عند إطلاق تدفق الفوترة في Google Play.

Kotlin

val billingParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    // Tag the purchase with the Pushwoosh account identifier "<AppCode>:<hwid>"
    .setObfuscatedAccountId(Pushwoosh.getInstance().subscriptionAccountId)
    .build()

billingClient.launchBillingFlow(activity, billingParams)

Java

BillingFlowParams billingParams = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        // Tag the purchase with the Pushwoosh account identifier "<AppCode>:<hwid>"
        .setObfuscatedAccountId(Pushwoosh.getInstance().getSubscriptionAccountId())
        .build();

billingClient.launchBillingFlow(activity, billingParams);

ملاحظة

استدعِ getSubscriptionAccountId() بعد تهيئة SDK. يعيد سلسلة فارغة إذا لم يكن Application Code أو HWID متاحًا بعد. يحدد Google معرّف الحساب المشفر بـ 64 حرفًا. تظل قيمة <AppCode>:<hwid> من Pushwoosh ضمن هذا الحد.

تنبيه

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

توجيه إشعارات المطورين في الوقت الفعلي إلى Pushwoosh

1. في Google Play Console، انتقل إلى تحقيق الدخل → إعداد تحقيق الدخل.
2. ابحث عن إشعارات المطورين في الوقت الفعلي وقم بتعيين اسم الموضوع إلى:

projects/pw-playstore-subscriptions/topics/play-rtdn

3. انقر على حفظ. تم منح إذن النشر بالفعل لخدمة إشعارات Google، لذلك لا يوجد شيء آخر لتكوينه هنا.

منح حساب خدمة Pushwoosh

1. في Google Play Console، انتقل إلى المستخدمون والأذونات → دعوة مستخدم جديد.
2. أدخل البريد الإلكتروني لحساب خدمة Pushwoosh:

play-api@pw-playstore-subscriptions.iam.gserviceaccount.com

3. تحت أذونات التطبيق، أضف تطبيقك وامنح عرض البيانات المالية والطلبات وردود استبيان الإلغاء (بالإضافة إلى إذن معلومات التطبيق للقراءة فقط).
4. انقر على حفظ. لا يحتاج حساب الخدمة إلى قبول الدعوة. يكون الوصول نشطًا على الفور.

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

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

بناء حملتك

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

الاختبار

للتحقق من التكامل من البداية إلى النهاية:

1. في Google Play Console، افتح إعداد تحقيق الدخل وانقر على إرسال إشعار اختبار. يجب أن يبلغ عن النجاح، مما يؤكد أن الموضوع متصل بشكل صحيح.
2. قم بإجراء عملية شراء اشتراك مع تعيين معرّف الحساب كما هو موضح أعلاه (هذا يطلق PW_SubscriptionStart)، ثم قم بإلغائه من متجر Play → الاشتراكات → إلغاء (هذا يطلق PW_SubscriptionCancel).
3. في لوحة تحكم Pushwoosh، افتح ملف تعريف المستخدم وانتقل إلى سجل الأحداث.
4. تأكد من ظهور الأحداث في غضون لحظات قليلة.