تكامل RudderStack
RudderStack هي منصة بيانات عملاء تجمع الأحداث من تطبيقاتك ومواقعك الإلكترونية وخوادمك ومستودعات بياناتك وتعيد توجيهها إلى أدوات أخرى. مع وجهة Pushwoosh (destination) في RudderStack، تصل البيانات التي تجمعها هناك بالفعل إلى Pushwoosh دون كود إضافي في تطبيقك:
- تصبح أحداث track أحداثًا (Events) في Pushwoosh. استخدمها لإنشاء الشرائح ولبدء Customer Journey أو تفريعها.
- تصبح سمات identify (traits) وسومًا (Tags) خاصة بالمستخدم. استخدمها لاستهداف الإشعارات الفورية ورسائل In-App ورسائل البريد الإلكتروني وتخصيصها.
قبل أن تبدأ
Anchor link toتطابق الوجهة جميع البيانات حسب User ID، لذا تحقق من هذه المتطلبات المسبقة أولاً:
- تم دمج Pushwoosh SDK في تطبيقك.
- يستدعي تطبيقك
setUserIdبالقيمة نفسها التي يرسلها RudderStack كـuserId. يربط Pushwoosh الأحداث والسمات الواردة بالمستخدمين من خلال هذه القيمة. - يكون جهاز كل مستخدم مسجلاً بهذا User ID قبل أن يرسل RudderStack استدعاءات
identifyلهذا المستخدم. يتم تجاهل السمات الخاصة بـ User ID لا يعرفه Pushwoosh بعد. - لديك صلاحية الوصول إلى Settings → API Access في Pushwoosh لإنشاء رمز API.
- لديك مساحة عمل (workspace) في RudderStack تحتوي على مصدر واحد على الأقل يرسل استدعاءات
trackأوidentify.
إعداد وجهة Pushwoosh في RudderStack
Anchor link toيتكون الإعداد من جزأين: تحصل على قيمتين في Pushwoosh، ثم تنشئ الوجهة في RudderStack.
احصل على رمز التطبيق وDevice API token
Anchor link toيحتاج RudderStack إلى قيمتين لإرسال البيانات إلى تطبيقك: رمز التطبيق وDevice API token.
- في Pushwoosh، افتح التطبيق الذي تريد إرسال البيانات إليه.
- انسخ رمز التطبيق. يظهر أسفل اسم التطبيق في الزاوية العلوية اليسرى ويكون بالشكل
XXXXX-XXXXX. - انتقل إلى Settings → API Access وانقر على Generate New Token.
- في Token type، اختر
device. - في Name، أدخل اسمًا للرمز، على سبيل المثال
RudderStack. - انقر على Generate.
- في قائمة الرموز، انقر على قائمة النقاط الثلاث بجوار الرمز الجديد واختر Edit token….
- ضمن Applications، حدد التطبيق من الخطوة 1 وانقر على Save.
- انسخ قيمة الرمز من قائمة الرموز.
يكفي Device API token للوجهة. لا تحتاج إلى Server API token.
أضف الوجهة في RudderStack
Anchor link toتربط وجهة Pushwoosh مصادر RudderStack الخاصة بك بتطبيق Pushwoosh الخاص بك.
- في لوحة تحكم RudderStack، انتقل إلى Collect → Destinations.
- انقر على New destination.
- حدد Pushwoosh من القائمة.
- أدخل اسمًا للوجهة وانقر على Continue.
- حدد المصادر التي تريد إرسالها إلى Pushwoosh.
- في Application Code، الصق رمز التطبيق.
- في API Token، الصق Device API token.
- أكمل الإعداد لحفظ الوجهة.
يرسل RudderStack البيانات إلى Pushwoosh من خوادمه الخاصة (cloud mode)، لكل نوع مصدر تدعمه الوجهة.
للاطلاع على جانب RudderStack من الإعداد، راجع دليل وجهة Pushwoosh في وثائق RudderStack.
ما البيانات التي يرسلها RudderStack إلى Pushwoosh
Anchor link toتدعم الوجهة نوعين من الاستدعاءات، track وidentify. يرفض RudderStack أي نوع استدعاء آخر لهذه الوجهة، مثل page أو screen أو group أو alias.
يجب أن يحتوي كل استدعاء على userId. لا يرسل RudderStack الاستدعاءات التي لا تحتوي عليه، لأن Pushwoosh لا يمكنه نسب استدعاء مجهول إلى مستخدم.
تصبح استدعاءات track أحداثًا في Pushwoosh
Anchor link toيصبح كل استدعاء track حدثًا في Pushwoosh بالاسم نفسه الذي يحمله حدث RudderStack:
| حقل RudderStack | Pushwoosh |
|---|---|
event | اسم الحدث |
properties | سمات الحدث |
userId | User ID |
timestamp (أو originalTimestamp) | وقت الحدث |
context.device.id | Device ID، إن وُجد |
context.device.type أو context.os.name | المنصة: android؛ وios لأنظمة iOS وiPadOS وwatchOS وtvOS؛ وweb لأي قيمة أخرى أو عند عدم وجود قيمة |
إذا لم يكن الحدث أو إحدى السمات موجودًا في التطبيق بعد، ينشئه Pushwoosh تلقائيًا.
يتجاهل Pushwoosh الحدث بأكمله في الحالات التالية. لا يُرجع أي خطأ، لذا يعرض RudderStack الحدث على أنه تم تسليمه:
- يحتوي الاستدعاء على أكثر من 100 خاصية.
- يتجاوز طول قيمة إحدى الخصائص 10 KB.
- يتجاوز طول اسم الحدث 255 حرفًا.
- الحدث جديد، ويتجاوز طول اسمه 128 حرفًا أو يحتوي على أحرف تحكم.
يحتفظ الحدث بما يصل إلى 100 سمة. بمجرد أن يصبح للحدث 100 سمة معروفة، يواصل Pushwoosh تسجيل الاستدعاءات الجديدة، لكن لا تتم إضافة أسماء الخصائص الجديدة كسمات.
تصل الكائنات المتداخلة في properties كسلاسل JSON، ويتم تجاهل الخصائص ذات القيمة null.
تصبح استدعاءات identify وسومًا خاصة بالمستخدم
Anchor link toيعيّن كل استدعاء identify سماته كوسوم للمستخدم صاحب userId المحدد. تأتي السمات من traits، أو من context.traits عندما تكون traits فارغة.
- تتم كتابة الوسوم الخاصة بالمستخدم فقط. إذا كان الإنشاء التلقائي للوسوم مفعّلاً لحسابك، فإن السمة ذات الاسم الجديد تنشئ وسمًا خاصًا بالمستخدم. إذا كان هناك وسم General بالاسم نفسه بالفعل، يتخطى Pushwoosh تلك السمة دون خطأ.
- يجب أن تتطابق القيمة مع نوع الوسم. إذا كان الوسم موجودًا بالفعل ولم تتوافق قيمة السمة مع نوعه، مثل نص لوسم من نوع Integer، يتخطى Pushwoosh تلك السمة دون خطأ.
- يجب أن يكون المستخدم موجودًا بالفعل في Pushwoosh. تُطبق الوسوم فقط إذا كان Pushwoosh SDK قد سجّل جهازًا تم فيه تعيين
setUserIdعلىuserIdنفسه. يتم تجاهل سمات المستخدم غير المعروف دون خطأ. - لا يتم نسخ سمات الهوية وجهات الاتصال إلى الوسوم. لا يتم إرسال
emailوphoneوfirstNameوlastNameوnameوaddressوidوuserIdوanonymousIdكوسوم أبدًا. يفشل استدعاءidentifyالذي يحتوي على هذه السمات فقط مع الخطأNo traits left to send as Pushwoosh tags. - القيمة الفارغة تمسح الوسم. السمة ذات السلسلة الفارغة أو القائمة الفارغة تحذف القيمة الحالية لذلك الوسم لدى المستخدم.
- تصل الكائنات المتداخلة كسلاسل JSON. يتم تجاهل السمات ذات القيمة
null.
ما لا تقوم به الوجهة
Anchor link toترسل الوجهة بيانات track وidentify فقط. تبقى هذه المهام خارج نطاقها:
- لا تسجّل الأجهزة أو عناوين البريد الإلكتروني. تأتي الأجهزة من Pushwoosh SDK.
- لا تحذف المستخدمين. طلبات حذف المستخدمين من RudderStack غير مدعومة لهذه الوجهة.
تحقق من أن التكامل يعمل
Anchor link toبعد حفظ الوجهة، أرسل استدعاء track واستدعاء identify تجريبيين من مصدر يحتوي على userId لديه جهاز بالفعل في Pushwoosh.
- الأحداث: في Pushwoosh، انتقل إلى Audience → Events، وافتح الحدث، وتحقق من احتسابه.
- الوسوم: انتقل إلى Audience → User Explorer، وابحث عن المستخدم حسب User ID، وتحقق من قيم الوسوم.
تظهر أخطاء التسليم لكل استدعاء في عرض Live Events الخاص بالوجهة في RudderStack.
استكشاف الأخطاء وإصلاحها
Anchor link toابحث عن رسالة الخطأ التي يعرضها RudderStack للوجهة في Live Events لمعرفة سببها وطريقة إصلاحها.
تفشل استدعاءات track مع unauthorized
Anchor link toلا يتطابق رمز API مع رمز التطبيق. تحقق من أن الرمز ينتمي إلى حساب Pushwoosh نفسه الذي ينتمي إليه التطبيق.
لا تتحقق استدعاءات identify من الرمز، لذا تستمر في النجاح حتى مع رمز خاطئ. استخدم استدعاء track لاختبار الرمز.
تفشل الاستدعاءات مع application not found أو application code is not valid
Anchor link toرمز التطبيق خاطئ، أو الحساب غير مستضاف على app.pushwoosh.com. تفشل استدعاءات track مع application not found، وتفشل استدعاءات identify مع application code is not valid. تحقق من الرمز في Pushwoosh Control Panel. إذا كان الرمز صحيحًا، فتواصل مع Customer Success Manager الخاص بك أو مع الدعم.
تفشل الاستدعاءات مع Missing required value from userId
Anchor link toلا يحتوي الاستدعاء على userId. لا يتم إرسال الاستدعاءات المجهولة إلى Pushwoosh. استدعِ identify في مصدر RudderStack بعد تسجيل دخول المستخدم، حتى تحمل الاستدعاءات اللاحقة userId.
تفشل الاستدعاءات مع Invalid enum value
Anchor link toنوع الاستدعاء ليس track أو identify. يقبل Pushwoosh هذين النوعين فقط. إما ألا تربط المصادر التي ترسل استدعاءات page أو screen أو group أو alias فقط، أو تجاهل هذه الأخطاء.
تفشل استدعاءات identify مع No traits left to send as Pushwoosh tags
Anchor link toجميع السمات في الاستدعاء هي سمات هوية أو جهات اتصال، مثل email أو phone، ولا يتم نسخها إلى الوسوم أبدًا. أضف سمة أخرى واحدة على الأقل أو تخطَّ الاستدعاء.
تنجح استدعاءات identify لكن الوسوم لا تظهر
Anchor link toتحقق مما يلي بالترتيب:
- يوجد جهاز مسجل بهذا User ID في Pushwoosh. ابحث عن المستخدم في Audience → User Explorer.
- يستدعي التطبيق
setUserIdبالقيمة نفسها تمامًا التي يرسلها RudderStack كـuserId. - الوسم بهذا الاسم من نوع User-specific. يتم تخطي السمة الخاصة بوسم General موجود. غيّر نطاق الوسم أو أعد تسمية السمة.
- تتطابق قيمة السمة مع نوع الوسم الموجود.
- السمة ليست من سمات الهوية أو جهات الاتصال التي لا يتم نسخها أبدًا، مثل
emailأوphone.