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

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

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

[إشعارات المطورين في الوقت الفعلي (RTDN)](https://developer.android.com/google/play/billing/rtdn-reference) هي خدمة من خادم إلى خادم من Google Play ترسل رسالة في الوقت الفعلي كلما تغيرت حالة الاشتراك.

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

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

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

**المصدر:** يتم إرسال إشعارات المطورين في الوقت الفعلي من 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.

<details>

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

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

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

</details>

### كيف يعمل

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

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

<Aside type="caution" title="هام">
يعتمد التطابق بين عملية شراء Google Play ومستخدم Pushwoosh على `obfuscatedAccountId`. إذا لم يقم تطبيقك بتعيين هذه القيمة في وقت الشراء، فإن Pushwoosh يتلقى الإشعار ولكن **لا يتم نشر أي حدث**. يتم تعيينه عند الشراء و**لا يمكن ملؤه بأثر رجعي** للاشتراكات الحالية. انظر [كيفية تعيين معرّف الحساب عند الشراء](#set-the-account-identifier-at-purchase).
</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`، فهذا يعني أن دفعة التجديد لم تنجح وأن الاشتراك في فترة السماح الخاصة به. اطلب من المستخدم تحديث طريقة الدفع الخاصة به قبل أن يفقد الوصول، وتابع مع `PW_SubscriptionRecovered` للتأكيد بمجرد حل المشكلة.

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

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

قبل أن تبدأ، تأكد من أن لديك تطبيق Pushwoosh مع [تكوين FCM](/ar/developer/pushwoosh-sdk/android-sdk/firebase-integration/integrate-pushwoosh-android-sdk/) (مطلوب بالفعل للإشعارات الفورية)، وتطبيق Google Play مع اشتراك، ووصول إداري إلى Play Console.

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

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

<Tabs>
<TabItem label="Kotlin">
```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)
```
</TabItem>
<TabItem label="Java">
```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);
```
</TabItem>
</Tabs>

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

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

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

1. في [Google Play Console](https://play.google.com/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](/ar/product/customer-journey/pushwoosh-journey-overview/) مع [دخول قائم على المشغل](/ar/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/) على أي حدث `PW_Subscription*`، على سبيل المثال `PW_SubscriptionCancel` للاستعادة أو `PW_SubscriptionStart` للتأهيل، وأضف الرسائل التي تريد إرسالها.

## الاختبار

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

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