تكامل Piano Analytics

تحتاج إلى مساعدة المطور

ستحتاج إلى مساعدة من فريق التطوير لديك لإعداد التكامل. يرجى مشاركة هذا الدليل معهم.

Piano Analytics هي أداة تساعد الشركات على فهم كيفية تفاعل الأشخاص مع مواقعهم الإلكترونية وتطبيقاتهم. تقوم بجمع البيانات حول سلوك المستخدم وتقدم رؤى من خلال التقارير والتصورات البيانية. تساعد هذه المعلومات الشركات على اتخاذ قرارات أفضل حول كيفية تحسين منتجاتها الرقمية وجهودها التسويقية.

يسمح تكامل Piano Analytics و Pushwoosh بالحصول على رؤى مفصلة لسلوك المستخدم لإنشاء شرائح دقيقة وإرسال إشعارات فورية ورسائل بريد إلكتروني ورسائل داخل التطبيق مستهدفة للغاية إلى المستخدمين المناسبين في الوقت المناسب.

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

نوع التكامل

• الوجهة: يتم إرسال البيانات من Piano Analytics إلى Pushwoosh.
• المصدر: يتم إرسال البيانات من Pushwoosh إلى Piano Analytics.

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

حسابات مدفوعة في كل من Pushwoosh و Piano Analytics

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

عند دمج Pushwoosh و Piano Analytics، قد تختلف بعض أسماء الكيانات بين المنصتين. فيما يلي المطابقات بين Pushwoosh و Piano Analytics:

Pushwoosh	Piano Analytics
UserID/hwid	visitorID
PostEvent.EventName	PianoEvent.Name
PostEvent.UserID	PianoEvent.PushwooshID
PostEvent.CampaignID	PianoEvent.SrcMedium
PostEvent.PlatformID	PianoEvent.DeviceType

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

المصدر

• الأحداث (Events)
• إحصائيات الإشعارات الفورية (Push Stats)
• العلامات (Tags) (كسمات للأحداث)

الوجهة

• الشرائح (Segments)

حالات الاستخدام

تحليلات موحدة

اجمع بيانات التفاعل من Pushwoosh مع Piano Analytics للحصول على رؤى شاملة للمستخدم. يتيح لك هذا الحصول على رؤية كلية لسلوك المستخدم وتفاعلاته عبر نقاط اتصال متعددة.

التقسيم

أنشئ شرائح مستخدمين مستهدفة في Pushwoosh بناءً على بيانات Piano Analytics. استخدم هذا التقسيم المحسن لتقديم حملات تسويقية مخصصة وفعالة.

مراقبة الأداء

تتبع فعالية الحملة وتفاعل المستخدم عبر المنصات.

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

نظرة عامة على التدفق

1. الإعداد: قم بتكوين إعدادات التكامل في حسابي Pushwoosh و Piano Analytics.
2. ربط الأحداث: قم بربط أحداث Pushwoosh بأحداث Piano (على سبيل المثال، PostEvent.EventName إلى PianoEvent.Name).
3. نقل البيانات: يرسل Pushwoosh الأحداث (أحداث النشر وأحداث سجل التتبع) إلى Piano Analytics.
4. استيراد الشرائح: يرسل Piano Analytics بيانات الشرائح إلى Pushwoosh لتقسيم الجمهور.

التدفق الفني

1. أحداث النشر (Post Events)
   • يرسل Pushwoosh بيانات الأحداث إلى Piano Analytics.
   • يتم ربط السمات على النحو التالي:
     • UserID (Pushwoosh) > PushwooshID (Piano)
     • CampaignID (Pushwoosh) > SrcMedium (Piano)
     • PlatformID (Pushwoosh) > DeviceType (Piano)
2. أحداث سجل التتبع (Tracking Log Events):
   • يرسل Pushwoosh بيانات التتبع (مثل، إشعار مرسل، إشعار تم تسليمه) إلى Piano Analytics.
   • تثري هذه البيانات Piano Analytics بمقاييس التسليم والتفاعل.
3. تكامل Piano VisitorID:
   • اختياريًا، قم بدمج Piano VisitorID مع Pushwoosh للحصول على تحليلات موحدة عبر حزم SDK.

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

لإعداد التكامل، انتقل إلى الإعدادات > تكاملات الجهات الخارجية (Settings > 3rd Party Integrations) في حساب Pushwoosh الخاص بك وحدد موقع Piano. انقر فوق تكوين (Configure).

في النافذة التي تفتح، قدم بيانات الاعتماد التالية:

1. معرف الموقع (Site ID)

لتحديد موقع معرف الموقع الخاص بك، قم بتسجيل الدخول إلى حساب Piano الخاص بك وانتقل إلى التحليلات > بوابة جمع البيانات > لوحة التحكم (Analytics > Data Collection Portal > Dashboard). ابحث عن موقع الويب ذي الصلة وانسخ معرفه.

2. نطاق الجمع (Collection Domain)

للعثور على نطاق الجمع، انتقل إلى الوسم > نطاقات الجمع (Tagging > Collection Domains). انسخ معرف نطاق الجمع. تأكد من إدخال نطاق الجمع بتنسيق ****.pa-cd.com بدون البادئة https://.

3. مفاتيح الوصول والسرية لواجهة برمجة تطبيقات Piano

للحصول على المفاتيح:

• في حساب Piano الخاص بك، انقر فوق عرض الملف الشخصي (See profile) أسفل اسم حسابك.

• انتقل إلى علامة التبويب مفاتيح API (API Keys) وأنشئ مفتاحًا جديدًا باسم ووصف واضحين. ثم انقر فوق موافق (OK).

• في النافذة التي تفتح، انسخ مفتاح الوصول (Access Key) والمفتاح السري (Secret Key).

تنبيه

لأسباب أمنية، سيتم عرض المفتاح السري (Secret Key) مرة واحدة فقط. يرجى التأكد من حفظ كلا المفتاحين في مكان آمن قبل المتابعة.

• في حقل مفتاح API (API key) في Pushwoosh، أدخل كلاً من مفتاح الوصول (Access Key) والمفتاح السري (Secret Key)، مفصولين بشرطة سفلية. على سبيل المثال: accesskey_secretkey.

إنشاء أحداث Piano لتطابق أحداث Pushwoosh

لتتبع الأحداث المرسلة من Pushwoosh في Piano، تحتاج إلى إنشاء أحداث مقابلة يدويًا داخل Piano.

إليك كيفية القيام بذلك في حساب Piano الخاص بك:

1. انتقل إلى الإعدادات > إدارة البيانات > نموذج البيانات (Settings > Data management > Data model).
2. حدد الأحداث (Events) وانقر على أيقونة الجمع لإنشاء حدث جديد.
3. في النافذة التي تفتح، قدم اسم الحدث ووصفه، على سبيل المثال، “pw_siteopened”.

ملاحظة

تسمية الأحداث ليست حساسة لحالة الأحرف. إذا قمت بإنشاء اسم بأحرف كبيرة لحدث في Pushwoosh، على سبيل المثال، PW_SiteOpened، فسوف يتطابق مع حدث pw_siteopened في Piano.

4. في حقل النوع (Type)، حدد On-site.
5. في حقل الفئات (Categories)، حدد الأحداث (Events).
6. انقر فوق حفظ (Save).

تعيين المنطقة الزمنية لموقع الويب الخاص بك في Piano

يعد تعيين المنطقة الزمنية الصحيحة لموقع الويب الخاص بك في Piano أمرًا بالغ الأهمية لتتبع البيانات وتحليلها بدقة. أفضل ممارسة هي مطابقة المنطقة الزمنية مع الموقع الذي ترسل منه الأحداث وتجري فيه التحليل. هذا يزيل التناقضات الزمنية.

لتعديل المنطقة الزمنية في Piano، انتقل إلى لوحة التحكم (Dashboard) وانقر على السطر الذي يحتوي على معلومات موقعك. في النافذة المنبثقة، انقر فوق تعديل (Edit) وحدد المنطقة الزمنية المطلوبة. ثم انقر فوق حفظ (Save).

إنشاء خاصية لتحديد الأحداث المرسلة من Pushwoosh في Piano

لتسهيل إدارة البيانات، قم بإنشاء خاصية في Piano يمكن ربطها بأحداث Pushwoosh. سيسمح لك هذا بتحديد الأحداث المرسلة من Pushwoosh بسهولة.

إليك كيفية إنشاء الخاصية:

1. في Piano، انتقل إلى الإعدادات > إدارة البيانات > الخصائص (Settings > Data Management > Properties).
2. انقر فوق إنشاء خاصية (Create Property).
3. في حقل الاسم (Name)، أدخل pushwooshid.
4. في حقل مفتاح الخاصية (Property Key)، أدخل pushwooshid.
5. اضبط النوع (Type) على String.
6. انقر فوق حفظ (Save).

التحقق مما إذا كانت أحداث Pushwoosh تُرسل إلى Piano

للتحقق من أن الأحداث التي تم إعدادها في Pushwoosh يتم إرسالها بنجاح إلى Piano، اتبع الخطوات التالية:

1. في حساب Piano الخاص بك، انتقل إلى المستكشف > الجمهور > إجمالي حركة المرور (Explorer > Audience > Overall Traffic).
2. أنشئ شريحة بناءً على الأحداث حيث لا تكون خاصية pushwooshid فارغة.

ستعرض العرض المصفى معلومات حركة المرور الإجمالية، بما في ذلك أي أحداث مرتبطة.

للحصول على عرض أكثر تفصيلاً للأحداث المرسلة من Pushwoosh، انتقل إلى المحتوى > الأحداث (Content > Events). يوفر هذا القسم تفصيلاً مفصلاً لجميع الأحداث المرسلة من Pushwoosh، بما في ذلك عدد مرات حدوث كل حدث.

إنشاء شرائح في Piano

بمجرد إكمال إعداد التكامل، يمكنك البدء في تحليل الأحداث المرسلة من Pushwoosh داخل Piano. للوصول إلى هذه الأحداث، انتقل إلى المستكشف > المحتوى > الأحداث (Explorer > Content > Events) في حساب Piano الخاص بك.

ثم أنشئ شرائح باستخدام هذه الأحداث. عند إنشاء الشرائح، حدد خاصية pushwooshid التي أنشأتها سابقًا لتصفية الأحداث.

تأكد من إعطاء شريحتك اسمًا واضحًا ووصفيًا. ستحتاج إلى مفتاح الشريحة (Segment Key)، وهو معرف فريد للشريحة المحفوظة، لاحقًا لإرسال الشرائح إلى Pushwoosh.

إرسال الشرائح من Piano إلى Pushwoosh

ملاحظة

يرجى ملاحظة أنه يمكن لمالكي الحسابات فقط استيراد الشرائح.

لتمكين Pushwoosh من استرداد الشرائح من Piano، قم بتزويد Pushwoosh بـ SegmentKey الذي أنشأته. للعثور على SegmentKey لشريحة ما، انتقل إلى التحليل > المكتبة > الشرائح (Analysis > Library > Segments). انقر على الشريحة التي تحتاجها وانسخ مفتاح الشريحة (Segment Key).

في قسم تكاملات Pushwoosh، حدد موقع Piano وانقر على استيراد شريحة (Import Segment). ثم أدخل مفتاح الشريحة الذي نسخته.

إذا كان الاستيراد ناجحًا، فسترى رسالة تأكيد.

يمكنك الوصول إلى الشرائح المستوردة في Pushwoosh. بمجرد اكتمال الاستيراد، سيتم إدراجها في قسم الجمهور > الشرائح (Audience > Segments) في حساب Pushwoosh الخاص بك.

ربط Piano VisitorID بـ Pushwoosh UserID/HWID للتحليلات المتراكمة عبر حزم SDK

إذا أراد العميل تجميع التحليلات من كل من Pushwoosh SDK و Piano Analytics SDK، فيجب على Pushwoosh ربط Piano VisitorID بـ Pushwoosh UserID/HWID. الحل هو إرسال علامة Piano VisitorID إلى Pushwoosh للمستخدم/الجهاز.

للقيام بذلك، قم بما يلي:

1. أنشئ علامة باسم ‘Piano Visitor ID’ على جانب Pushwoosh للتطبيق. ملاحظة: يجب أن يكون اسم العلامة تمامًا كما هو موصوف.
2. على جانب تطبيق العميل، احصل على Piano Visitor ID داخل Piano SDK باستخدام طريقة getVisitorId.
3. على جانب تطبيق العميل، استخدم Pushwoosh SDK لاستدعاء طلب setTags مع قيمة العلامة مرة واحدة.

إذا كانت قيمة العلامة (Piano Visitor ID) موجودة للمستخدم/الجهاز، فسيقوم Pushwoosh بتضمينها تلقائيًا كمعرف عميل (Client ID) في الطلبات إلى Piano Analytics. على جانب Piano Analytics، سيتم تحويلها إلى قيمة معرف زائر فريدة.

أمثلة على الكود

Web Push SDK (JavaScript)

Pushwoosh.push(function(api) {
// Set tags for a user
api.setTags({
'Piano Visitor ID': pa.getVisitorID(),
});

Android (Java)

String value1 = PianoAnalytics.getInstance().visitorId();
TagsBundle pianoTag = new TagsBundle.Builder()
    .putString("Piano Visitor ID", value1)
    .build();
Pushwoosh.getInstance().setTags(pianoTag);

iOS (Swift)

var pianoId: String = pa.getVisitorId(completionHandler: { visitorId in
Pushwoosh.sharedInstance().setTags([
 "Piano Visitor ID": visitorId
 ])
})

iOS (Objective-C)

__block NSString *pianoId;
[pa getVisitorIdWithCompletionHandler:^(NSString *visitorId) {
    Piano Visitor ID = visitorId;
    [[Pushwoosh sharedInstance] setTags:@{@"Piano Visitor ID": visitorId}];
}];

بشكل عام، يستخدم Pushwoosh علامات الجهاز لتوفير معلومات الجهاز وغيرها إلى Piano Analytics ضمن كل طلب. فيما يلي قائمة بالعلامات الشائعة المستخدمة:

• البلد (Country)
• طراز الجهاز (Device Model)
• إصدار نظام التشغيل (OS Version)
• نوع المتصفح (Browser Type) (في بعض الحالات)

كيفية التحقق من أن التكامل يعمل

المصدر: الكشف عن الأحداث المرسلة إلى Piano Analytics

هناك طريقتان سهلتان للكشف عن الأحداث التي تم إرسالها إلى Piano Analytics:

مفتش البث (Stream Inspector)

1. انتقل إلى حساب Piano Analytics الخاص بك.
2. انتقل إلى الإعدادات > بوابة جمع البيانات > الأدوات > مفتش البث (Settings > Data Collection Portal > Tools > Stream Inspector).
3. اختر الموقع المتصل الذي تريد التحقق منه.
4. حدد الأحداث التي تريد فحصها وابدأ جلسة.
5. تحقق من أن الأحداث قد تم استلامها بواسطة Piano Analytics.

تحقق من الأحداث في إجمالي حركة المرور (Overall Traffic)

1. انتقل إلى حساب Piano Analytics الخاص بك.
2. انتقل إلى الإعدادات > المستكشف > الجمهور > إجمالي حركة المرور (Settings > Explorer > Audience > Overall Traffic).
3. اختر الموقع والنطاق الزمني في القائمة أدناه.

الوجهة: استيراد شريحة Piano

للتحقق من التكامل من جانب الوجهة:

• استورد شريحة Piano.
• يجب أن ترى شريحة جديدة (مرشح) باسم تم إنشاؤه مثل segment_key (Piano Autogenerated).
• أعد حساب الشريحة للحصول على معلومات محدثة حول الأجهزة الحالية التي تتم معالجتها.

استكشاف الأخطاء وإصلاحها للأسئلة الشائعة: المشكلات الشائعة

كيف يمكنني التأكد من إرسال الأحداث بشكل صحيح من Pushwoosh إلى Piano Analytics؟

الحل: استخدم مفتش البث (Stream Inspector) الخاص بـ Piano أو تحقق من إجمالي حركة المرور (Overall Traffic) في Piano Analytics لمراقبة الأحداث الواردة من Pushwoosh.

ماذا أفعل إذا لم يتم استيراد بيانات الشريحة بشكل صحيح إلى Pushwoosh؟

الحل: تأكد من أن مفتاح الشريحة (Segment Key) من Piano يطابق الإعداد في Pushwoosh. تحقق من وجود أي أخطاء في حسابات حجم الشريحة أو استرداد البيانات.

هل يمكنني دمج Piano VisitorID مع Pushwoosh للحصول على تحليلات محسنة؟

الحل: نعم، عن طريق إعداد علامة محددة في Pushwoosh واستخدام SDK الخاص بـ Piano لجلب VisitorID، يمكنك مزامنة معرفات المستخدمين عبر المنصات.

ماذا أفعل إذا كانت هناك مشكلات في تكوينات مفتاح API؟

الحل: راجع سجلات طلبات API، وتأكد من صحة عناوين URL لنقاط النهاية ورموز المصادقة (مفاتيح API)، وتحقق من أي أخطاء من جانب الخادم تم الإبلاغ عنها بواسطة أي من الخدمتين.