إعداد الاتصالات المبدئي لبيانات وشرائح المشتركين

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

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

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

• تطبيق في حساب Pushwoosh الخاص بك، مع دمج SDK أو تسجيل الأجهزة عبر API.
• رمز وصول API مع إذن لتعيين الوسوم.
• مساعدة مطور لمهمة التحديث من خادم إلى خادم.
• معرف مشترك يمكنك ربطه بـ Pushwoosh: إما User ID (عادةً ما يكون MSISDN، رقم هاتف المشترك بالتنسيق الدولي، أو معرف مشترك داخلي) أو HWID الخاص بالجهاز.

كيف يبدو ملف تعريف مشترك الاتصالات

يسرد الجدول أدناه الوسوم التي تغطي سيناريوهات الاتصالات القياسية. قم بإنشائها قبل تحميل البيانات الأول، وبهذه الأنواع بالضبط.

الوسم	النوع	قيمة مثال	ما الذي يقوده
msisdn	String	923001234567	الهوية واستهداف الرسائل القصيرة
tariff_plan	String	Gold Postpaid	عروض خاصة بالخطة
prepaid_postpaid	String	prepaid	تقسيم القاعدة حسب نموذج الفوترة
balance	Integer	50	تنبيهات انخفاض الرصيد
bundle_id	String	DATA_5GB_30D	عن أي باقة يدور التذكير
bundle_expiry_date	Date	2026-09-20 21:00:00	تذكيرات انتهاء صلاحية الباقة
roaming_status	Boolean	true	رسائل ترحيب التجوال وتحذيرات حول رسوم التجوال

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

• يجب أن يكون bundle_expiry_date وسمًا من نوع Date. فقط وسوم Date تحصل على العوامل النسبية، مثل بعد N إلى M يوم، التي تعبر عن “انتهاء صلاحية الباقة في غضون ثلاثة أيام” دون إعادة حساب الشريحة كل ليلة.
• يبقى bundle_id منفصلاً عن تاريخ انتهاء الصلاحية. يحتفظ وسم واحد بالتاريخ، وآخر بالباقة التي ينتمي إليها. تخزين كليهما في وسم واحد يتطلب تحليل سلسلة نصية داخل الشريحة، وهو ما لا يستطيع منشئ الشرائح القيام به.

لماذا يتم تحديد نوع الوسم قبل التحميل الأول

يتم إنشاء الوسوم تلقائيًا في المرة الأولى التي تصل فيها قيمة، ويتم استنتاج النوع من تلك القيمة الأولى. يصبح الرقم الصحيح Integer، والرقم الذي يحتوي على فاصلة عشرية يصبح Price، والسلسلة النصية تصبح String (أو Date، إذا تطابقت مع تنسيق تاريخ ووقت معترف به مثل 2024-10-02 22:11)، والمصفوفة تصبح List، و true/false تصبح Boolean.

يفشل الاستنتاج في بيانات الاتصالات، لأن تواريخ انتهاء الصلاحية تُرسل عادةً كطوابع زمنية Unix:

• ترسل bundle_expiry_date كرقم 1758393600. إنه رقم صحيح، لذا يتم إنشاء الوسم كوسم Integer. يتم تحميل القيم بشكل صحيح، ويبدو الوسم سليمًا، ولا يتم عرض أي عامل تاريخ له أبدًا.
• الوسم موجود بالفعل كـ Integer وتقوم لاحقًا بالتبديل إلى إرسال "2026-09-20". لم تعد القيمة تُحلل كرقم، لذا يتم تجاهلها دون أي خطأ. لا تزال واجهة برمجة التطبيقات API تستجيب بالنجاح، ويحتفظ الجهاز بقيمته القديمة أو لا شيء على الإطلاق.

تنتهي كلتا الحالتين بشريحة تُرجع صفرًا من المستخدمين ولا يوجد خطأ في أي مكان لشرح ذلك.

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

لمنع كلتا الحالتين، قم بتعيين الأنواع بنفسك:

1. افتح صفحة Tags في لوحة التحكم الخاصة بك.
2. انقر على إنشاء وسم.
3. أدخل اسم الوسم واختر نوعه من القائمة. كرر ذلك لكل وسم في الجدول أعلاه، قبل التحميل الأول.
4. في bulkSetTags، أرسل create_missing_tags: false. سيعيد الوسم المفقود خطأ بدلاً من إنشائه بنوع مُخمَّن.

كيفية تحديث الملف الشخصي من خادم إلى خادم

تتغير بيانات ملف تعريف الاتصالات يوميًا، لذا يتم تحميلها كمهمة دفعية بدلاً من SDK المحمول.

1. قم ببناء التغيير اليومي من جانبك: المشتركون الذين تغير رصيدهم أو باقتهم أو حالة التجوال لديهم منذ التشغيل الأخير. نادرًا ما تكون إعادة تحميل القاعدة الكاملة كل ليلة ضرورية وتكلفك حجم طلبات.
2. أرسل الدفعة إلى bulkSetTags، مع توجيه الأجهزة بواسطة user_id عندما يكون MSISDN هو User ID الخاص بك، أو بواسطة hwid خلاف ذلك. يحمل طلب واحد العديد من الأجهزة، وتتوقع الطريقة 50 جهازًا على الأقل. لمشترك واحد، استخدم setTags بدلاً من ذلك.
3. استعلم عن request_id المُرجع باستخدام bulkSetTags status حتى تنتهي المهمة. اطلبه مع ?detailed=true وسجل النتيجة، لأن المهمة المنتهية ليست مثل قبول كل قيمة.
4. أعد محاولة الدفعات الفاشلة بنفس الحمولة. تعيين وسم هو عملية متكررة: إرسال نفس القيمة مرتين يترك نفس الملف الشخصي.

تحديث الباقة اليومي

{
  "application": "XXXXX-XXXXX",
  "auth": "your API access token",
  "create_missing_tags": false,
  "devices": [{
    "user_id": "923001234567",
    "tags": {
      "bundle_id": "DATA_5GB_30D",
      "bundle_expiry_date": "2026-09-20 21:00:00",
      "balance": 50,
      "roaming_status": false
    }
  }]
}

ما هي تنسيقات التاريخ التي يقبلها وسم Date

يخزن وسم Date طابع زمني Unix epoch بالثواني. أرسل أحد هذه الخيارات:

• قيمة epoch بالثواني، كرقم: 1758393600.
• سلسلة تاريخ ووقت مع فواصل: 2026-09-20 21:00:00، 2026-09-20 21:00، أو 2026-09-20. التاريخ بدون وقت يعني منتصف الليل.
• سلسلة ISO 8601 مع إزاحة: 2026-09-20T21:00:00+05:00.

يتصرف تنسيقان بطريقة تفاجئ معظم عمليات التكامل:

• تُقرأ السلسلة النصية بدون منطقة زمنية على أنها UTC. لا تُقرأ في توقيتك المحلي. الباقة التي تنتهي صلاحيتها في الساعة 21:00 في كراتشي هي 2026-09-20T21:00:00+05:00، أو قيمة epoch المطابقة. 2026-09-20 21:00:00 أبكر بثلاث ساعات في الوقت الفعلي، مما ينقل المشتركين بين موجات التذكير اليومية.
• سلسلة من الأرقام هي قيمة epoch، وليست تاريخًا. "20260920" ليس 20 سبتمبر 2026، بل هو طابع زمني epoch يشير إلى عام 1970. أرسل إما قيمة epoch حقيقية أو سلسلة نصية مع فواصل.

يتم تجاهل القيمة التي لا تتطابق مع أي من التنسيقات المقبولة دون فشل الطلب. هذا هو السبب في أن الخطوة 3 أعلاه تتحقق من نتيجة المهمة بدلاً من حالة HTTP وحدها.

وصفات الشرائح

كل وصفة أدناه هي شريحة واحدة. افتح قسم Segments، انقر على إنشاء شريحة لفتح المنشئ، ثم أضف المرشحات المدرجة. للحصول على شرح كامل للمنشئ، راجع إنشاء شرائح حسب الوسوم.

انتهاء صلاحية الباقة في غضون ثلاثة أيام

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

• الوسم: bundle_expiry_date
• العامل: افتح قائمة العوامل، اذهب إلى قسم التواريخ النسبية، واختر بعد N إلى M يوم
• القيم: 3 و 3

غير كلتا القيمتين إلى 1 و 1 لتذكير اليوم الأخير. أضف مرشحًا ثانيًا على bundle_id عندما تذكر الرسالة الباقة المحددة.

لا تستخدم عوامل قسم الذكرى السنوية هنا

يقدم قسم الذكرى السنوية عامل بعد N أيام. يقارن هذا العامل اليوم والشهر فقط، لذا فهو يطابق كل مشترك انتهت صلاحية باقته في ذلك التاريخ في أي عام. استخدمه لأعياد الميلاد، وليس لصلاحية الباقة.

رصيد منخفض

يستهدف مشتركي الدفع المسبق الذين لم يعودوا قادرين على دفع ثمن التجديد التالي.

• الوسم: balance، العامل أصغر من أو يساوي، القيمة 50
• الوسم: prepaid_postpaid، العامل يساوي، القيمة prepaid

يتم وضع كلا الشرطين في نفس المجموعة، مع دمجهما بـ و.

دخول التجوال

يستهدف المشتركين الموجودين حاليًا في الخارج، لرسالة ترحيب بالأسعار المحلية.

• الوسم: roaming_status، العامل نعم

تعكس الشريحة القائمة على الوسم الحالة في وقت التجميع. عندما تحتاج إلى إرسال الرسالة في اللحظة التي يبدأ فيها التجوال، قم بتشغيل رحلة عميل من حدث تجوال بدلاً من الإرسال إلى هذه الشريحة.

تأكيد إعادة الشحن وردود الفعل الأخرى

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

الشريحة تُرجع صفرًا من المستخدمين

تحقق من هذه الأمور بالترتيب. تغطي الثلاثة الأولى معظم الحالات التي يتم الإبلاغ عنها للدعم.

1. تحقق من نوع الوسم في صفحة Tags. إذا كان bundle_expiry_date من نوع Integer، فلن يتم تطبيق أي عامل تاريخ أبدًا وقارنت الشريحة الأرقام. قم بإنشاء وسم Date وأعد تحميل القيم.
2. تحقق من أن القيم قد وصلت بالفعل. افتح User Explorer، وابحث عن مشترك تعرف أنه كان في الدفعة، وانظر إلى وسومه. الوسم الفارغ بعد مهمة ناجحة يعني أن القيم قد رُفضت بسبب التنسيق، غالبًا ما تكون سلاسل نصية من الأرقام فقط أو تاريخ لم يتطابق مع أي تخطيط.
3. تحقق من قسم العامل. بعد N أيام تحت الذكرى السنوية يتجاهل السنة. بعد N إلى M يوم تحت التواريخ النسبية لا يفعل ذلك.
4. تحقق من المنطقة الزمنية. تُقرأ طوابع انتهاء الصلاحية المرسلة بدون إزاحة على أنها UTC، مما قد ينقل المشترك إلى اليوم السابق أو التالي من جدول التذكير الخاص بك.
5. أعد حساب الشريحة قبل قراءة الرقم، حتى لا تنظر إلى حجم مخزن مؤقتًا. راجع حساب حجم الشريحة.

قيود يجب مراعاتها

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