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

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

دع AI Assistant ينشئ الأحداث والعلامات

يمكن لـ AI Assistant إنشاء الأحداث والعلامات الواردة في هذه الصفحة داخل تطبيقك. أرسل إليه رابط الصفحة واطلب منه جعل العلامات User-specific. راجع كل تغيير قبل الموافقة عليه.

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

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

تعيين User ID هو تغيير في كود لعبتك. يُرجى مشاركة جمع User ID مع المطورين لديك.

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

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

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

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

لمعرفة المزيد عن العلاقة بين User ID والأجهزة، راجع المستخدمون (معرفات المستخدم).

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

الأحداث هي الطريقة التي يعرف بها Pushwoosh ما يفعله اللاعب. أنشئها أولًا: تجمع الشرائح اللاعبين حسب الأحداث التي أطلقوها، وتبدأ Journey عند وقوع حدث ما.

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

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

• الأحداث الافتراضية: تسجيل الجهاز، وفتح التطبيق، والشراء، وغيرها القليل. يرسلها SDK، ولا تحتاج إلى إنشائها في لوحة التحكم.
• الأحداث المخصصة: إكمال مستوى، والحصول على مكافأة، وفتح المتجر، وغيرها. يرسلها المطورون من اللعبة، وينشئ Pushwoosh كل حدث منها عند وصوله لأول مرة. لاختيار أنواع السمات بنفسك، أنشئ الحدث أولًا في لوحة التحكم. راجع الأحداث المخصصة والأحداث المُنشأة تلقائيًا.

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

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

• PW_DeviceRegistered: تلقّى جهاز أول رمز push له. لا يطلب SDK الرمز إلا عندما تستدعي اللعبة registerForPushNotifications، وهو ما يعرض أيضًا طلب الإذن على iOS، ويصل الرمز أيًّا كانت إجابة اللاعب. إذا طلبت اللعبة الإذن في وقت لاحق للتشغيل الأول، فسيُطلق الحدث في تلك اللحظة، وليس عند التثبيت. لرصد اللاعبين الجدد، استخدم حدث Tutorial started بدلًا منه.
• PW_ApplicationOpen: فتح لاعب اللعبة. تحتاج إليه للعثور على اللاعبين الذين ما زالوا يلعبون واللاعبين الذين توقّفوا عن اللعب، حتى تتمكّن من استعادتهم.
• PW_InAppPurchase: اشترى لاعب شيئًا في اللعبة. تحتاج إليه للتمييز بين اللاعبين الدافعين وغير الدافعين، على سبيل المثال لتقديم عرض الشراء الأول فقط للاعبين الذين لم يدفعوا قط. يفعّل المطورون تتبّع المشتريات في iOS SDK أو يرسلون المشتريات من الكود، أما على Android فيرسلونها دائمًا من الكود. على iOS، يُطلق الحدث فقط للمنتجات المُعدّة في App Store Connect.
• اختياري: PW_UserIdle: يُطلق عندما يتوقّف اللاعب عن لمس الشاشة لمدة تحدّدها أنت، لا تقلّ عن 30 ثانية. يبدأ Journey يعرض تلميحًا in-app عندما يتعثّر اللاعب. يفعّله المطورون في إعدادات SDK.
• اختياري: PW_ApplicationExit: يُطلق عندما يغادر اللاعب اللعبة ولا يعود خلال 10 إلى 30 ثانية. يبدأ Journey استعادة للاعبين الذين يغادرون في منتصف التدفق. يفعّله المطورون في إعدادات SDK.

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

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

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

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

للاطلاع على تفاصيل هذه الأحداث وغيرها من الأحداث الافتراضية، راجع الأحداث الافتراضية.

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

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

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

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

الحدث	متى يُطلق	السمات الرئيسية	ما الذي يشغّله
New level	يصل اللاعب إلى مستوى جديد	level_id (String)	اختياري: شرائحك الخاصة للمراحل المهمة
Level completed	يُنهي اللاعب مستوى	level_id (String)	شريحتا المتفاعلين غير الدافعين واللاعبين العالقين، وJourney مساعدة اللاعبين العالقين
Level failed	يفشل اللاعب في مستوى	level_id (String)	شريحة اللاعبين العالقين وJourney الخاص بهم
Tutorial started	يبدأ اللاعب البرنامج التعليمي داخل اللعبة	tutorial_name (String)	Journey التهيئة، وشريحة المتوقفين عن البرنامج التعليمي
Tutorial completed	يُنهي اللاعب البرنامج التعليمي داخل اللعبة	tutorial_name (String), completion (Boolean)	Journey التهيئة، وتدفق إذن الإشعارات الفورية
Virtual currency earned	يزداد رصيد اللاعب من العملة داخل اللعبة	currency_name (String), quantity (Integer)	اختياري: شرائحك الخاصة المبنية على العملة
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 مغادرة المتجر دون شراء

لا يوجد برنامج تعليمي في لعبتك؟

استخدم أحداثك الخاصة لأول إجراءين يقوم بهما كل لاعب جديد، مثل بدء المستوى الأول وإنهائه، بدلًا من Tutorial started وTutorial completed أينما ذكرهما هذا الدليل العملي.

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

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

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

إرسال الأحداث تغيير في كود لعبتك. يُرجى مشاركة الأحداث للمطورين وأمثلة أحداث الألعاب مع المطورين لديك. يرسلون كل حدث باستخدام postEvent في لحظة وقوع الإجراء. يجب أن تأتي المشتريات ومنح المكافآت من خادم اللعبة مع userId الخاص باللاعب.

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

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

Android

TagsBundle attributes = new TagsBundle.Builder()
    .putString("level_id", "12")
    .build();

InAppManager.getInstance().postEvent("Level completed", attributes);

iOS

PWInAppManager.shared().postEvent("Level completed", withAttributes: ["level_id": "12"])

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

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

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

يسجّل PW_Conversion مبلغ كل عملية شراء وعملتها بتنسيق واحد. تحتاج إليه لهدف الإيرادات في Journey ولفئات الإنفاق في تجزئة RFM، التي تجمع اللاعبين حسب حداثة شرائهم ومعدّل تكراره وحجم إنفاقهم.

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

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

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

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

تنبيه

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

للاطلاع على جميع خيارات الإعداد، راجع أحداث التحويل.

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

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

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

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

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

يجب أن تمرّر اللعبة HWID الخاص باللاعب في Pushwoosh مع كل عملية شراء:

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

بدون ذلك، يتلقّى Pushwoosh الإشعار لكنه لا يسجّل أي حدث، ولا يمكن مطابقة الاشتراكات التي اشتُريت سابقًا لاحقًا. يُرجى مشاركة تتبع اشتراكات App Store وتتبع اشتراكات Google Play مع المطورين لديك.

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

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

العلامة قيمة يخزّنها Pushwoosh في الملف الشخصي للاعب، مثل مستوى اللاعب أو ما إذا كان قد دفع. يسجّل الحدث ما حدث، وتحتفظ العلامة بالحالة الحالية. تساعدك العلامات على:

• إرسال رسالة فقط إلى اللاعبين الذين لديهم قيمة معيّنة، على سبيل المثال عرض للاعبين الدافعين فقط.
• إدراج القيمة في نص الرسالة، على سبيل المثال مستوى اللاعب. راجع إنشاء Journey.

العلامات اختيارية. تعمل Journey في هذا الدليل العملي على الأحداث وعلى العلامات الافتراضية التي يعيّنها Pushwoosh بنفسه، لذا يمكنك الاستغناء عن علاماتك الخاصة في البداية. أضفها عندما تريد طرقًا أكثر لتجميع اللاعبين. راجع الشرائح حسب العلامات.

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

يرسل المطورون قيم العلامات من اللعبة، أو يمكنك استيرادها من ملف CSV. ينشئ Pushwoosh العلامة عندما يرسلها المطورون لأول مرة، بوصفها علامة User-specific. أنشئ العلامة أولًا في لوحة التحكم إذا أردت اختيار نوعها بنفسك. راجع إدارة بيانات المستخدم باستخدام العلامات (Tags).

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

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

عند إنشاء علامة في لوحة التحكم، أبقِ الخيار خاص بالمستخدم مفعّلًا، كما هو افتراضيًا. عندها يحتفظ Pushwoosh بقيمة واحدة لكل User ID، فتنتمي القيمة إلى اللاعب وليس إلى أحد أجهزته. عند إيقاف خاص بالمستخدم، يحتفظ كل جهاز بقيمته الخاصة. راجع التعرّف على اللاعبين من خلال User ID.

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

يخزّن Pushwoosh هذه العلامات الافتراضية لكل جهاز، لذا لا تحتاج إلى إنشائها:

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