# تكامل Stripe

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

[Stripe](https://stripe.com/) هي منصة دفع تتيح لك قبول المدفوعات وإدارة الاشتراكات. يتيح لك تكامل Stripe مع Pushwoosh تتبع المدفوعات والاشتراكات في [الحملات](/ar/product/customer-journey/pushwoosh-journey-overview/)، وتحليل الإيرادات حسب الرحلة والمنتج، و[تقسيم المستخدمين](/ar/product/audience-data-and-segmentation/segmentation/) حسب أحداث الدفع، واستخدام [ManyMoney AI](/ar/product/pushwoosh-ai/ai-assistant/) للحصول على رؤى حول الإيرادات.

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

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

**المصدر:** يتم إرسال أحداث الدفع والاشتراك من Stripe إلى Pushwoosh.

### المتطلبات الأساسية

لإعداد تكامل Stripe مع Pushwoosh، تأكد مما يلي:

* لديك حساب Pushwoosh نشط.
* لديك حساب Stripe.


### مسرد المصطلحات (ربط أسماء الكيانات إذا كانت مختلفة)

يوضح الجدول أدناه كيفية ربط كيانات Stripe بـ Pushwoosh. يتم تحقيق هذا الربط عن طريق تمرير الحقول المقابلة كبيانات وصفية عند إنشاء جلسة Checkout (انظر [تكوين البيانات الوصفية](#metadata-configuration)).

| Stripe | Pushwoosh |
|--------|-----------|
| العميل | `user_id` (مطلوب)، `device_id` (اختياري) في البيانات الوصفية |
| الدفع / الشحن | حدث **StripePaymentSucceeded** (`charge.succeeded`) |
| الفاتورة (مدفوعة) | حدث **StripeInvoicePaid** (`invoice.paid`) |
| الاشتراك | **StripeSubscriptionCreated** + السمات في **StripeInvoicePaid** |
| المنتج / السعر | `product_id`، `product_name` في البيانات الوصفية وسمات الحدث |
| الحملة (الرحلة) | `journey_uuids` في البيانات الوصفية |

### الكيانات المتزامنة

* أحداث الدفع (المدفوعات لمرة واحدة، فواتير الاشتراك)
* أحداث الاشتراك (تم إنشاء الاشتراك، تم دفع فاتورة الاشتراك)


### كيف يعمل التكامل؟

بعد ربط حساب Stripe الخاص بك بـ Pushwoosh عبر **Stripe Connect**، يتلقى Pushwoosh بيانات الدفع والاشتراك من Stripe. يمكنك ربط كل معاملة بحملة ومستخدم أو جهاز عن طريق تمرير البيانات الوصفية عند إنشاء جلسة Checkout (انظر [تكوين البيانات الوصفية](#metadata-configuration)).

ينشئ Pushwoosh أحداثًا يمكنك استخدامها في [التقسيم](/ar/product/audience-data-and-segmentation/segmentation/) والتحليلات.

##### تدفق البيانات

1. تقوم بربط حساب Stripe الخاص بك بـ Pushwoosh مرة واحدة عبر **Stripe Connect** في **Settings** → **3rd-party integrations**.
2. عند إنشاء جلسة Checkout، تقوم بتمرير البيانات الوصفية حتى يمكن إسناد الدفع لاحقًا (انظر [تكوين البيانات الوصفية](#metadata-configuration)).
3. عند وقوع حدث دفع أو اشتراك في Stripe (على سبيل المثال `charge.succeeded` لمرة واحدة، `invoice.paid` للاشتراك)، يرسل Stripe البيانات إلى Pushwoosh.
4. ينشئ Pushwoosh الأحداث المقابلة ويستخدم البيانات الوصفية للإسناد. تظهر هذه البيانات في Finance Overview، و Audience → Events، و ManyMoney.


### حالات الاستخدام
##### تتبع المدفوعات
تلقي معلومات حول جميع المدفوعات والاشتراكات الناجحة تلقائيًا.

##### ربط المدفوعات بالحملات
ربط المعاملات بـ [رحلات العملاء](/ar/product/customer-journey/pushwoosh-journey-overview/) المحددة عن طريق تمرير البيانات الوصفية (انظر [تكوين البيانات الوصفية](#metadata-configuration)).

##### تحليل الإيرادات
عرض الدخل حسب الحملات والمنتجات والمستخدمين والأجهزة.

##### تقسيم جمهورك
[إنشاء شرائح](/ar/product/audience-data-and-segmentation/segmentation/create-segments/by-events/) بناءً على أحداث الدفع.

##### تحليلات الذكاء الاصطناعي
يتلقى مساعد [ManyMoney AI](/ar/product/pushwoosh-ai/ai-assistant/) تلقائيًا إحصائيات الدفع والاشتراك ويمكنه اتخاذ قرارات بناءً على هذه البيانات.

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

### ربط Stripe بـ Pushwoosh

1. افتح أي تطبيق Pushwoosh (يتم ربط حساب Stripe بحسابك بالكامل، وليس بتطبيق معين) وانتقل إلى **Settings** → **3rd-party integrations**.
2. ابحث عن بطاقة **Stripe** وانقر على زر **LOGIN PAGE**.

![صفحة الإعدادات مع قسم التكاملات مع الأطراف الثالثة وبطاقة Stripe مع زر LOGIN PAGE](/integrations-stripe-integration-1.webp)

3. سيتم إعادة توجيهك إلى صفحة تفويض Stripe.

![صفحة تفويض Stripe مع اختيار الحساب وزر Connect](/integrations-stripe-integration-2.webp)

4. في صفحة Stripe، أدخل بريدك الإلكتروني وانقر على **Continue**.
5. سجل الدخول إلى حساب Stripe الخاص بك (أو أنشئ حسابًا جديدًا). إذا كان لديك حسابات متعددة، فحدد الحساب الذي تريد ربطه.
6. انقر على **Connect** للتأكيد.
7. بعد التفويض الناجح، سيتم إعادة توجيهك مرة أخرى إلى Pushwoosh. ستتغير حالة التكامل إلى **Connected**.

![صفحة التكاملات مع الأطراف الثالثة تظهر بطاقة Stripe بحالة Connected](/integrations-stripe-integration-3.webp)

### فصل التكامل

##### الطريقة 1. عبر Pushwoosh

1. اذهب إلى **Settings** → **3rd-party integrations**.
2. ابحث عن بطاقة **Stripe** وانقر على زر **SETTINGS**.
3. في النافذة المنبثقة، انقر على زر **Disconnect**.

![نافذة منبثقة لإعدادات بطاقة Stripe مع زر Disconnect في التكاملات مع الأطراف الثالثة](/integrations-stripe-integration-4.webp)


##### الطريقة 2. عبر لوحة تحكم Stripe

1. سجل الدخول إلى [Stripe Dashboard](https://dashboard.stripe.com).
2. اذهب إلى **Settings** → **Team and security** → **Installed apps**.
3. ابحث عن التطبيق في قسم **Connect Extensions**.

![إعدادات لوحة تحكم Stripe، الفريق والأمان، التطبيقات المثبتة، قسم Connect Extensions](/integrations-stripe-integration-5.webp)

عندما تقوم بالفصل من خلال Stripe، يتلقى Pushwoosh إشعارًا تلقائيًا ويزيل التكامل.

## تكوين البيانات الوصفية

يرسل Stripe أحداث الدفع إلى Pushwoosh، ولكن بدون بيانات إضافية لا يمكن لـ Pushwoosh معرفة الحملة أو المستخدم الذي ينتمي إليه الدفع. عندما تقوم بتمرير البيانات الوصفية عند إنشاء جلسة Checkout (معرفات الحملة، معرف المستخدم أو الجهاز، المنتج)، يتم إسناد كل دفعة إلى الرحلة والمستخدم الصحيحين.

بعد ذلك، سترى الإيرادات حسب الحملة في Finance Overview، وتبني شرائح حسب الدافعين، وتستخدم ManyMoney مع إسناد صحيح.

### حقول البيانات الوصفية المتاحة

| الحقل | الوصف | مطلوب | مثال |
|-------|-------------|----------|---------|
| `journey_uuids` | معرفات الحملة (الرحلة) مفصولة بفواصل منقوطة | لا | `bfab4bc0-b0a5-414b-befc-4aaddc429b0e;a2bff710-6b49-44d1-96a7-3232feeca6e9` |
| `user_id` | معرف المستخدم. مطلوب لجمع الأحداث ولكي يتم تطبيق `device_id` | نعم | `user_12345` أو `email@example.com` |
| `device_id` | معرف الجهاز (HWID). | لا | `hwid_abc123` |
| `product_id` | معرف المنتج | لا | `prod_premium` |
| `product_name` | اسم المنتج | لا | `Premium Plan` |

<Aside type="caution" title="هام">

- بدون `user_id`، لا يتم جمع الأحداث ويتم تجاهل `device_id`. للحصول على تحليلات شاملة، قم أيضًا بتوفير `journey_uuids` و `device_id`.

- `journey_uuids` اختياري ولا يمكن تعيينه إلا عبر البيانات الوصفية. لا يوفر Stripe بيانات الحملة أو الرحلة، لذا قم بتمريرها عند إنشاء جلسة Checkout إذا كنت تريد إسناد الإيرادات إلى رحلة.

- `product_id` و `product_name` اختياريان. يستخدم Pushwoosh البيانات الوصفية أولاً. إذا كان أي منهما مفقودًا في البيانات الوصفية، يتم أخذه من Stripe عند توفره. إذا لم يكن لدى أي من المصدرين قيمة، فلن يتم تخزين الحقل.

</Aside>

### تمرير البيانات الوصفية عبر جلسة Checkout

يتم تمرير البيانات الوصفية عند إنشاء جلسة Checkout اعتمادًا على نوع الدفع:

| نوع الدفع | المعلمة | حدث Stripe |
|--------------|-----------|--------------|
| دفعة لمرة واحدة (`mode=payment`) | `payment_intent_data[metadata]` | `charge.succeeded` |
| اشتراك (`mode=subscription`) | `subscription_data[metadata]` | `invoice.paid` |

### أولوية البيانات الوصفية أثناء المعالجة

**للاشتراكات** (حدث `invoice.paid`):

```text
Invoice metadata → if empty → Subscription metadata
```

**للمدفوعات لمرة واحدة** (حدث `charge.succeeded`):

```text
Charge metadata (from payment_intent_data)
```

## إنشاء جلسة دفع عبر Stripe API (curl)

##### دفعة لمرة واحدة (`mode=payment`)

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_live_YOUR_SECRET_KEY: \
  -d "mode=payment" \
  -d "success_url=https://example.com/success" \
  -d "cancel_url=https://example.com/cancel" \
  -d "line_items[0][price]=price_1234567890" \
  -d "line_items[0][quantity]=1" \
  -d "payment_intent_data[metadata][journey_uuids]=bfab4bc0-b0a5-414b-befc-4aaddc429b0e" \
  -d "payment_intent_data[metadata][user_id]=user_12345" \
  -d "payment_intent_data[metadata][device_id]=hwid_abc123" \
  -d "payment_intent_data[metadata][product_id]=prod_premium" \
  -d "payment_intent_data[metadata][product_name]=Premium Plan"
```

##### اشتراك (`mode=subscription`)

```bash
curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_live_YOUR_SECRET_KEY: \
  -d "mode=subscription" \
  -d "success_url=https://example.com/success" \
  -d "cancel_url=https://example.com/cancel" \
  -d "line_items[0][price]=price_monthly_premium" \
  -d "line_items[0][quantity]=1" \
  -d "subscription_data[metadata][journey_uuids]=bfab4bc0-b0a5-414b-befc-4aaddc429b0e" \
  -d "subscription_data[metadata][user_id]=user_12345" \
  -d "subscription_data[metadata][device_id]=hwid_abc123" \
  -d "subscription_data[metadata][product_name]=Monthly Premium"
```

## عرض البيانات

بعد التكامل الناجح، تظهر لوحة تحكم **Finance Overview** جديدة في قسم [Dashboards](/ar/product/statistics-and-analytics/dashboards/). هناك يمكنك عرض إحصائيات إجمالي الإيرادات والاشتراكات الجديدة مقسمة حسب الحملات (الرحلة).

![لوحة تحكم Finance Overview في الإحصائيات مع إجمالي الإيرادات والاشتراكات الجديدة حسب الحملة](/integrations-stripe-integration-6.webp)

لمزيد من المعلومات التفصيلية، قم بزيارة لوحة تحكم Stripe الخاصة بك.

## إنشاء شرائح بناءً على المدفوعات

استخدم أحداث Stripe لإنشاء شرائح المستخدمين:

1. افتح **Audience** → **Segments**.
2. انقر على **Create Segment** → **Build Segment**.
3. في **Add filter by**، انقر على **Event**.
4. حدد حدث Stripe من القائمة المنسدلة (انظر الجدول أدناه للأحداث المتاحة).
<Aside type="note">
تظهر أحداث Stripe في القائمة بعد توصيل التكامل وتلقي بيانات الدفع.
</Aside>

5. قم بتعيين الشرط: كم مرة وقع الحدث والإطار الزمني (على سبيل المثال، خلال آخر 30 يومًا، بين تواريخ).
6. اختياريًا، قم بتضييق الشريحة حسب سمات الحدث. يسرد الجدول أدناه السمات المتاحة لكل حدث.

| الحدث | الوصف | السمات |
|-------|-------------|------------|
| `StripePaymentSucceeded` | دفعة ناجحة | __amount, __currency, invoice_id, journey_uuids, product_id, product_name, stripe_customer_id, subscription_id |
| `StripeInvoicePaid` | تم دفع فاتورة الاشتراك | __amount, __currency, journey_uuids, product_id, product_name, stripe_customer_id, transaction_id, transaction_type |
| `StripeSubscriptionCreated` | تم إنشاء الاشتراك | __amount, __currency, interval, journey_uuids, product_id, product_name, status, stripe_customer_id, subscription_id |

![صفحة شرائح الجمهور مع خيارات إنشاء شريحة وبناء شريحة](/integrations-stripe-integration-7.webp)

7. لإضافة المزيد من الأحداث، أضف مرشح حدث آخر واختر عامل تشغيل (AND أو OR) بين الشروط.

[تعرف على المزيد حول إنشاء الشرائح](/ar/product/audience-data-and-segmentation/segmentation/create-segments/by-events/).

<Aside type="tip">
يمكنك أيضًا ربط `StripePaymentSucceeded` (`__amount`، `__currency`، `product_id`) أو `StripeInvoicePaid` (`__amount`، `__currency`، `transaction_id`، `product_id`) كمصدر لـ [أحداث التحويل](/ar/product/audience-data-and-segmentation/events/conversion-events/)، لجلب إيرادات Stripe إلى تقسيم RFM، وإسناد الرحلة، و ManyMoney AI جنبًا إلى جنب مع مصادر إيراداتك الأخرى.
</Aside>

## مساعد ManyMoney AI

بعد التكامل الناجح مع Stripe، يحصل مساعد الذكاء الاصطناعي [**ManyMoney**](/ar/product/pushwoosh-ai/ai-assistant/) تلقائيًا على إمكانية الوصول إلى إحصائيات الدفع والاشتراك.

ManyMoney متاح في واجهة لوحة التحكم. بعد توصيل Stripe، تتوفر بيانات الدفع للتحليل تلقائيًا. لا يلزم تكوين إضافي.

### ما الذي يمكن لـ ManyMoney فعله

- **تحليل الإيرادات:** يجيب على الأسئلة المتعلقة بالدخل والتحويلات وفعالية الحملة.
- **مقارنة الفترات:** يعرض ديناميكيات الدفع والاشتراك عبر فترات زمنية مختلفة.
- **تحديد الاتجاهات:** يكتشف المنتجات وشرائح الجمهور المتنامية والمتراجعة.
- **تقديم توصيات:** يقترح تحسينات بناءً على بيانات الدفع.

<Aside type="tip" title="أمثلة على الأوامر">

- ما هي الإيرادات التي حققتها الحملة الشهر الماضي؟
- قارن معدلات تحويل الاشتراك بين يناير وفبراير
- عرض إحصائيات استرداد الأموال

</Aside>