# جمع بيانات اللاعبين

يحتاج Pushwoosh إلى معرفة من هم لاعبوك وماذا يفعلون في اللعبة. تسجّل الأحداث الإجراءات، وتحتفظ العلامات بالحالة الحالية لكل لاعب.

<Aside type="tip" title="دع AI Assistant ينشئ الأحداث والعلامات">
يمكن لـ [AI Assistant](/ar/product/pushwoosh-ai/ai-assistant/) إنشاء الأحداث والعلامات الواردة في هذه الصفحة داخل تطبيقك. أرسل إليه رابط الصفحة واطلب منه جعل العلامات User-specific. راجع كل تغيير قبل الموافقة عليه.
</Aside>

<span id="identify-players-by-user-id" />

## التعرّف على اللاعبين من خلال User ID

<Aside type="caution" icon="setting" title="مطلوب مساعدة المطور">
تعيين User ID هو تغيير في كود لعبتك. يُرجى مشاركة [جمع User ID](/ar/developer/first-steps/collecting-user-ids/#setuserid-sdk-method) مع المطورين لديك.
</Aside>

يربط Pushwoosh جميع أجهزة اللاعب بـ User ID واحد، لذا تتعامل الشرائح وJourney مع الشخص الواحد كلاعب واحد. تبقى الأحداث والعلامات من نوع User-specific التي سجّلها الجهاز قبل تسجيل دخول اللاعب مرتبطة بمعرّفه السابق. أما العلامات من نوع Device-specific فتنتقل مع الجهاز.

يستخدم Pushwoosh افتراضيًا معرّف الجهاز (HWID) لكل جهاز بوصفه User ID الخاص به. وبذلك يُحتسب اللاعب الذي يلعب على جهازين كلاعبَين اثنين. لتجنّب ذلك مع اللاعبين الذين يسجّلون الدخول، عيّن معرّف الحساب الخاص بك ليكون User ID لهم:

1. اختر المعرّف الذي ستستخدمه. استخدم معرّف الحساب الذي تخصّصه لعبتك بالفعل لكل لاعب.
2. اطلب من المطورين استدعاء `setUserId` بهذا المعرّف عند تسجيل دخول اللاعب.
3. تحقّق من النتيجة. سجّل الدخول إلى اللعبة على جهاز اختبار، ثم افتح **الجمهور** → **مستكشف المستخدمين**، وابحث حسب **معرّف المستخدم**، وأدخل معرّف الحساب. يُفتح الملف الشخصي للاعب.

يحتفظ اللاعبون الذين لا يسجّلون الدخول أبدًا بـ HWID بوصفه User ID الخاص بهم، ويعيّنه Pushwoosh لهم.

لمعرفة المزيد عن العلاقة بين User ID والأجهزة، راجع [المستخدمون (معرفات المستخدم)](/ar/product/pushwoosh-knowledge-hub/users-userids/).

<span id="set-up-the-events-to-track" />

## إعداد الأحداث المراد تتبّعها

الأحداث هي الطريقة التي يعرف بها Pushwoosh ما يفعله اللاعب. أنشئها أولًا: تجمع [الشرائح](/ar/tutorials/industry-playbooks/mobile-games/build-the-segments/) اللاعبين حسب الأحداث التي أطلقوها، وتبدأ [Journey](/ar/tutorials/industry-playbooks/mobile-games/build-the-journeys/) عند وقوع حدث ما.

خطّط للأحداث وسماتها معًا قبل أن تبني أي شيء. تسرد صفحة [الأحداث الموصى بها لتطبيقات الألعاب](/ar/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/) أحداث ألعاب جاهزة مع سماتها، وتشرح صفحة [الأحداث المخصصة](/ar/product/audience-data-and-segmentation/events/custom-events/) كيفية تعريف أحداثك الخاصة.

هناك نوعان من الأحداث:

* [الأحداث الافتراضية](#default-events): تسجيل الجهاز، وفتح التطبيق، والشراء، وغيرها القليل. يرسلها SDK، ولا تحتاج إلى إنشائها في لوحة التحكم.
* [الأحداث المخصصة](#custom-events): إكمال مستوى، والحصول على مكافأة، وفتح المتجر، وغيرها. يرسلها المطورون [من اللعبة](#send-the-events-from-the-game)، وينشئ Pushwoosh كل حدث منها عند وصوله لأول مرة. لاختيار أنواع السمات بنفسك، أنشئ الحدث أولًا في لوحة التحكم. راجع [الأحداث المخصصة](/ar/product/audience-data-and-segmentation/events/custom-events/) و[الأحداث المُنشأة تلقائيًا](/ar/product/audience-data-and-segmentation/events/#events-created-automatically).

<span id="default-events" />

### الأحداث الافتراضية

يرسل SDK هذه الأحداث نيابةً عنك. تحتاج إليها في معظم Journey في هذا الدليل العملي: التهيئة، واستعادة اللاعبين، وعروض الشراء.

* [`PW_DeviceRegistered`](/ar/product/audience-data-and-segmentation/events/default-events/#pw_deviceregistered): تلقّى جهاز أول رمز push له. لا يطلب SDK الرمز إلا عندما تستدعي اللعبة `registerForPushNotifications`، وهو ما يعرض أيضًا طلب الإذن على iOS، ويصل الرمز أيًّا كانت إجابة اللاعب. إذا طلبت اللعبة الإذن في وقت لاحق للتشغيل الأول، فسيُطلق الحدث في تلك اللحظة، وليس عند التثبيت. لرصد اللاعبين الجدد، استخدم حدث `Tutorial started` بدلًا منه.
* [`PW_ApplicationOpen`](/ar/product/audience-data-and-segmentation/events/default-events/#pw_applicationopen): فتح لاعب اللعبة. تحتاج إليه للعثور على اللاعبين الذين ما زالوا يلعبون واللاعبين الذين توقّفوا عن اللعب، حتى تتمكّن من استعادتهم.
* [`PW_InAppPurchase`](/ar/product/audience-data-and-segmentation/events/default-events/#pw_inapppurchase): اشترى لاعب شيئًا في اللعبة. تحتاج إليه للتمييز بين اللاعبين الدافعين وغير الدافعين، على سبيل المثال لتقديم عرض الشراء الأول فقط للاعبين الذين لم يدفعوا قط. يفعّل المطورون تتبّع المشتريات في iOS SDK أو يرسلون المشتريات من الكود، أما على Android فيرسلونها دائمًا من الكود. على iOS، يُطلق الحدث فقط للمنتجات المُعدّة في App Store Connect.
* اختياري: [`PW_UserIdle`](/ar/product/audience-data-and-segmentation/events/default-events/#pw_useridle): يُطلق عندما يتوقّف اللاعب عن لمس الشاشة لمدة تحدّدها أنت، لا تقلّ عن 30 ثانية. يبدأ Journey يعرض تلميحًا in-app عندما يتعثّر اللاعب. يفعّله المطورون في إعدادات SDK.
* اختياري: [`PW_ApplicationExit`](/ar/product/audience-data-and-segmentation/events/default-events/#pw_applicationexit): يُطلق عندما يغادر اللاعب اللعبة ولا يعود خلال 10 إلى 30 ثانية. يبدأ Journey استعادة للاعبين الذين يغادرون في منتصف التدفق. يفعّله المطورون في إعدادات SDK.

يظهر الحدث في **الجمهور** → **الأحداث** بعد أن يرسله SDK لأول مرة.

لإضافة أي حدث افتراضي آخر إلى القائمة مبكرًا، على سبيل المثال لإنشاء شريحة قبل إطلاق تحديث اللعبة:

1. افتح **الجمهور** → **الأحداث** وانقر على **إنشاء حدث**.
2. اختر **حدث افتراضي**.
3. حدّد الحدث وانقر على **تفعيل**.

لا تتضمّن القائمة في الخطوة 3 الحدثين `PW_UserIdle` و`PW_ApplicationExit`. فهما لا يظهران في **الجمهور** → **الأحداث** إلا بعد أن يرسلهما SDK لأول مرة.


للاطلاع على تفاصيل هذه الأحداث وغيرها من الأحداث الافتراضية، راجع [الأحداث الافتراضية](/ar/product/audience-data-and-segmentation/events/default-events/).

<span id="custom-events" />

### الأحداث المخصصة

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

<span id="choose-the-events-to-track" />

#### اختيار الأحداث المراد تتبّعها

اختر الأحداث التي تحتاج إليها لعبتك والسمات التي يحملها كل منها، على سبيل المثال `level_id` للحدث `Level completed`. يعرض الجدول أمثلة: استخدمها كما هي، أو أعد تسميتها، أو أضف أحداثك الخاصة. تتبّع فقط الأحداث التي تحتاج إليها Journey التي تطلقها.

| الحدث | متى يُطلق | السمات الرئيسية | ما الذي يشغّله |
| --- | --- | --- | --- |
| [New level](/ar/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#new-level) | يصل اللاعب إلى مستوى جديد | `level_id` (String) | اختياري: شرائحك الخاصة للمراحل المهمة |
| [Level completed](/ar/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#level-completed) | يُنهي اللاعب مستوى | `level_id` (String) | شريحتا المتفاعلين غير الدافعين واللاعبين العالقين، وJourney مساعدة اللاعبين العالقين |
| Level failed | يفشل اللاعب في مستوى | `level_id` (String) | شريحة اللاعبين العالقين وJourney الخاص بهم |
| Tutorial started | يبدأ اللاعب البرنامج التعليمي داخل اللعبة | `tutorial_name` (String) | Journey التهيئة، وشريحة المتوقفين عن البرنامج التعليمي |
| [Tutorial completed](/ar/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#tutorial-completed) | يُنهي اللاعب البرنامج التعليمي داخل اللعبة | `tutorial_name` (String), `completion` (Boolean) | Journey التهيئة، وتدفق إذن الإشعارات الفورية |
| [Virtual currency earned](/ar/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#virtual-currency-earned) | يزداد رصيد اللاعب من العملة داخل اللعبة | `currency_name` (String), `quantity` (Integer) | اختياري: شرائحك الخاصة المبنية على العملة |
| [Achievement unlocked](/ar/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#achievement-unlocked) | يحقّق اللاعب إنجازًا | `achievement_name` (String), `level` (Integer) | شريحة صائدي الإنجازات |
| Daily reward claimed | يحصل اللاعب على المكافأة اليومية | `day_number` (Integer) | Journey التذكير بالمكافأة اليومية |
| Live event joined | ينضم اللاعب إلى حدث مباشر | `event_id` (String) | هدف التحويل في Journey الحدث المباشر |
| Store opened | يفتح اللاعب المتجر داخل اللعبة | `section` (String) | Journey مغادرة المتجر دون شراء |

<Aside type="tip" title="لا يوجد برنامج تعليمي في لعبتك؟">
استخدم أحداثك الخاصة لأول إجراءين يقوم بهما كل لاعب جديد، مثل بدء المستوى الأول وإنهائه، بدلًا من `Tutorial started` و`Tutorial completed` أينما ذكرهما هذا الدليل العملي.

* يبدأ الحدث الأول Journey التهيئة، ويُعلمها الحدث الثاني بأن اللاعب قد انتهى. تجاوز الشرط `completion` المرتبط بـ `Tutorial completed`.
* لا ترسل حزم SDK أي حدث خاص بها للتشغيل الأول، لذا يجب أن يكون كلاهما حدثين مخصصين ترسلهما لعبتك.
</Aside>

<span id="send-the-events-from-the-game" />

#### إرسال الأحداث من اللعبة

<Aside type="caution" icon="setting" title="مطلوب مساعدة المطور">
إرسال الأحداث تغيير في كود لعبتك. يُرجى مشاركة [الأحداث للمطورين](/ar/developer/guides/audience-and-segmentation/events/) و[أمثلة أحداث الألعاب](/ar/developer/guides/audience-and-segmentation/events/custom-events-examples#gaming-apps) مع المطورين لديك. يرسلون كل حدث باستخدام `postEvent` في لحظة وقوع الإجراء. يجب أن تأتي المشتريات ومنح المكافآت من خادم اللعبة مع `userId` الخاص باللاعب.
</Aside>

اتّفق مع المطورين على الأحداث التي ترسلها اللعبة والسمات التي يحملها كل منها. يجب أن تتطابق أسماء الأحداث والسمات تمامًا.

على سبيل المثال، هكذا ترسل اللعبة `Level completed` مع السمة `level_id`:

<Tabs>
<TabItem label="Android">
```java
TagsBundle attributes = new TagsBundle.Builder()
    .putString("level_id", "12")
    .build();

InAppManager.getInstance().postEvent("Level completed", attributes);
```
</TabItem>
<TabItem label="iOS">
```swift
PWInAppManager.shared().postEvent("Level completed", withAttributes: ["level_id": "12"])
```
</TabItem>
</Tabs>

إذا وقع حدث على خادم يرسل بالفعل خطافات الويب الخاصة به، مثل الواجهة الخلفية للعبتك أو خدمة البطولات، فيمكن أن يصل إلى Pushwoosh عبر [خطاف ويب وارد](/ar/product/integrations/inbound-webhook/) بدلًا من `postEvent`. تربط الحقول التي يرسلها بحدث في Pushwoosh من لوحة التحكم، ويمكن للحدث أن يبدأ Journey مثل أي حدث آخر.

للتحقّق من وصول حدث ما، افتح **الجمهور** → **مستكشف المستخدمين**، وابحث عن لاعب اختبار، وافتح علامة التبويب **سجل الأحداث**.


<span id="track-revenue-as-pw_conversion" />

### تتبّع الإيرادات بوصفها PW_Conversion

يسجّل `PW_Conversion` مبلغ كل عملية شراء وعملتها بتنسيق واحد. تحتاج إليه لهدف الإيرادات في Journey ولفئات الإنفاق في [تجزئة RFM](/ar/product/audience-data-and-segmentation/segmentation/rfm-segmentation/)، التي تجمع اللاعبين حسب حداثة شرائهم ومعدّل تكراره وحجم إنفاقهم.

تصل المشتريات التي يتتبّعها iOS SDK إلى `PW_Conversion` تلقائيًا، لأنها تحمل السمتين `__amount` و`__currency`. أما مشتريات Android فتحتاج إلى أحد الخيارين التاليين:

* إذا كانت لعبتك تعمل على iOS وAndroid معًا، فاطلب من المطورين إرسال مشتريات Android بوصفها `PW_InAppPurchase` مع السمتين الرقميتين `__amount` و`__currency` عبر `postEvent`، بدلًا من طريقة الشراء في SDK. عندها يغطّي الربط التلقائي نفسه المنصّتين.
* إذا كانت لعبتك تعمل على Android فقط، فاربط المشتريات بنفسك، دون كود جديد. يحتفظ الحدث بربط واحد فقط، لذا في لعبة تحتوي على مشتريات iOS سيحلّ الربط اليدوي محلّ الربط التلقائي.

لربط المشتريات بنفسك:

1. افتح **الجمهور** → **الأحداث** وافتح إعدادات أحداث التحويل.
2. أضف `PW_InAppPurchase` بوصفه حدث تحويل.
3. حدّد السمات التي تحمل **السعر** و**العملة** الخاصين به.
4. انقر على **تطبيق**.

<Aside type="caution">
استخدم طريقة واحدة فقط لكل معاملة. إذا كان الكود الخاص بك يرسل أيضًا `PW_Conversion` لعملية الشراء نفسها، فسيسجّل Pushwoosh حدثَي تحويل منفصلين.
</Aside>

للاطلاع على جميع خيارات الإعداد، راجع [أحداث التحويل](/ar/product/audience-data-and-segmentation/events/conversion-events/).

<span id="track-subscriptions-from-the-stores" />

### تتبّع الاشتراكات من المتاجر

إذا كانت لعبتك تبيع اشتراكات، مثل بطاقة VIP أو Battle Pass، فإن Pushwoosh يتلقّى تغييرات حالتها من App Store وGoogle Play. يصل كل تغيير بوصفه حدث `PW_Subscription*`، على سبيل المثال:

* `PW_SubscriptionStart`: يشترك اللاعب.
* `PW_SubscriptionCancel`: يوقف اللاعب التجديد التلقائي.
* `PW_SubscriptionBillingIssue`: تفشل دفعة التجديد.

استخدم هذه الأحداث لبدء Journey، على سبيل المثال تذكير قبل انتهاء صلاحية اشتراك أُلغي.

<Aside type="caution" icon="setting" title="مطلوب مساعدة المطور">
يجب أن تمرّر اللعبة HWID الخاص باللاعب في Pushwoosh مع كل عملية شراء:

* على iOS، بوصفه `appAccountToken`.
* على Android، بوصفه `obfuscatedAccountId`. تمرّر اللعبة قيمة `getSubscriptionAccountId()` من SDK، وهي Application Code وHWID معًا، وليس HWID وحده.

بدون ذلك، يتلقّى Pushwoosh الإشعار لكنه لا يسجّل أي حدث، ولا يمكن مطابقة الاشتراكات التي اشتُريت سابقًا لاحقًا. يُرجى مشاركة [تتبع اشتراكات App Store](/ar/product/integrations/app-store-subscription-tracking/) و[تتبع اشتراكات Google Play](/ar/product/integrations/google-play-subscription-tracking/) مع المطورين لديك.
</Aside>

تغطّي هذه الأحداث الاشتراكات فقط. أما المشتريات لمرة واحدة، مثل حزمة عملات، فتظلّ تصل بوصفها `PW_InAppPurchase`.

<span id="store-player-data-in-tags" />

## تخزين بيانات اللاعبين في العلامات

[العلامة](/ar/product/audience-data-and-segmentation/user-data-tags/) قيمة يخزّنها Pushwoosh في الملف الشخصي للاعب، مثل مستوى اللاعب أو ما إذا كان قد دفع. يسجّل الحدث ما حدث، وتحتفظ العلامة بالحالة الحالية. تساعدك العلامات على:

* إرسال رسالة فقط إلى اللاعبين الذين لديهم قيمة معيّنة، على سبيل المثال عرض للاعبين الدافعين فقط.
* إدراج القيمة في نص الرسالة، على سبيل المثال مستوى اللاعب. راجع [إنشاء Journey](/ar/tutorials/industry-playbooks/mobile-games/build-the-journeys/).

العلامات اختيارية. تعمل Journey في هذا الدليل العملي على الأحداث وعلى العلامات الافتراضية التي يعيّنها Pushwoosh بنفسه، لذا يمكنك الاستغناء عن علاماتك الخاصة في البداية. أضفها عندما تريد طرقًا أكثر لتجميع اللاعبين. راجع [الشرائح حسب العلامات](/ar/tutorials/industry-playbooks/mobile-games/build-the-segments/#segments-by-tags).

### علاماتك الخاصة

يرسل المطورون قيم العلامات من اللعبة، أو يمكنك [استيرادها من ملف CSV](/ar/product/audience-data-and-segmentation/user-data-tags/update-tags-via-csv/). ينشئ Pushwoosh العلامة عندما يرسلها المطورون لأول مرة، بوصفها علامة User-specific. أنشئ العلامة أولًا في لوحة التحكم إذا أردت اختيار نوعها بنفسك. راجع [إدارة بيانات المستخدم باستخدام العلامات (Tags)](/ar/product/audience-data-and-segmentation/user-data-tags/tags/).

هذه العلامات أمثلة. أعد تسميتها لتناسب مفردات لعبتك، وأضف علاماتك الخاصة:

| العلامة | النوع | مثال | ما الذي تشغّله |
| --- | --- | --- | --- |
| `player_level` | Integer | `12` | تصفية الرسائل حسب مستوى التقدّم |
| `is_paying_user` | Boolean | `true` | الفصل بين رسائل اللاعبين الدافعين وغير الدافعين |
| `soft_currency_balance` | Integer | `1500` | تقديم حزمة عملة للاعبين ذوي الرصيد المنخفض |
| `vip_tier` | String | `gold` | منح لاعبي VIP عروضًا خاصة بهم ووصولًا مبكرًا |
| `favorite_mode` | String | `pvp` | الإعلان عن الأحداث المباشرة للوضع الذي يفضّله اللاعب |

عند إنشاء علامة في لوحة التحكم، أبقِ الخيار [**خاص بالمستخدم**](/ar/product/audience-data-and-segmentation/user-data-tags/tags/#tag-scope-general-vs-user-specific) مفعّلًا، كما هو افتراضيًا. عندها يحتفظ Pushwoosh بقيمة واحدة لكل User ID، فتنتمي القيمة إلى اللاعب وليس إلى أحد أجهزته. عند إيقاف **خاص بالمستخدم**، يحتفظ كل جهاز بقيمته الخاصة. راجع [التعرّف على اللاعبين من خلال User ID](/ar/tutorials/industry-playbooks/mobile-games/collect-player-data/#identify-players-by-user-id).

### العلامات الافتراضية

يخزّن Pushwoosh هذه [العلامات الافتراضية](/ar/product/audience-data-and-segmentation/user-data-tags/tags/#default-tags) لكل جهاز، لذا لا تحتاج إلى إنشائها:

* **Language**: لغة الجهاز. يستخدمها Pushwoosh لإرسال الرسالة إلى كل لاعب بلغته.
* **Last Application Open**: آخر مرة فُتحت فيها اللعبة على الجهاز. استخدمها للعثور على اللاعبين الذين توقّفوا عن اللعب.
* **Push Alerts Enabled**: ما إذا كانت الإشعارات مسموحًا بها في إعدادات الجهاز. استخدمها لعرض رسالة in-app فقط للاعبين الذين لم يسمحوا بها بعد.
* **First Install**: أول مرة ثُبّتت فيها اللعبة على الجهاز. استخدمها لذكرى التثبيت.
* **Country**: بلد الجهاز. استخدمها لإرسال عرض أو إعلان عن حدث مباشر فقط إلى اللاعبين في منطقة واحدة.