تخطّ إلى المحتوى الرئيسي

الحصول على بيانات اعتماد APNs (iOS)

يرسل Joryio إشعارات Push إلى أجهزة iOS عبر Apple Push Notification service (APNs). ولذلك يحتاج إلى بيانات اعتماد من حساب Apple Developer الخاص بك. تشرح هذه الصفحة خطوة بخطوة كيفية إنشائها في بوابة Apple وإدخالها في Joryio.

لكل تطبيق في Joryio بيانات اعتماد Push خاصة به، لذا تُجري هذه الخطوات مرة واحدة لكل تطبيق iOS. لمشروع React Native أو Unity تطبيق iOS منفصل في Joryio، وتُدخل بيانات اعتماد APNs الخاصة به هناك. راجع التتبع متعدد المنصات.

ما يطلبه Joryio​

يستخدم Joryio المصادقة المبنية على رمز مع مفتاح مصادقة APNs، وهو ملف .p8. تحتاج إلى أربعة أشياء:

الحقل في Joryioما هومصدره
Environmentالتطوير (Sandbox) أو الإنتاج - بيئة APNs التي تُسجَّل فيها إصدارات تطبيقكنوع الإصدار - راجع اختيار البيئة
Key IDمعرّف من 10 أحرف لمفتاح المصادقةحساب Apple Developer، Keys
Team IDمعرّف من 10 أحرف لفريق المطورين الخاص بك في Appleحساب Apple Developer، Membership details
Auth Key (.p8 Content)النص الكامل لملف .p8الملف الذي تنزّله مرة واحدة عند إنشاء المفتاح

تعرض إعدادات Push أيضًا طريقة المصادقة مبنية على شهادة (.p12). يغطي هذا الدليل مفتاح .p8 المبني على رمز فقط، وهو الطريقة الموصى بها: لا تنتهي صلاحية مفتاح المصادقة، ويمكن لمفتاح واحد الإرسال لكل التطبيقات في فريق المطورين الخاص بك في Apple.

قبل أن تبدأ​

  • عضوية في Apple Developer Program. تُنشأ مفاتيح APNs في حساب مطور مدفوع.
  • دور Account Holder أو Admin في فريق المطورين. لا تسمح Apple بإنشاء المفاتيح إلا لهذين الدورين. إذا كان لديك دور آخر، فاطلب من Account Holder أو من Admin إنشاء المفتاح وإرسال Key ID وTeam ID وملف .p8 إليك عبر قناة آمنة.
  • تفعيل إشعارات Push للتطبيق. في Xcode، أضف إمكانية Push Notifications إلى target التطبيق، وتأكد من تفعيل إشعارات Push لمعرّف App ID، أي bundle ID، في حساب المطور. يجب أن ينتمي المفتاح إلى فريق المطورين نفسه الذي ينتمي إليه التطبيق.
  • تطبيق iOS في Joryio مدمج فيه iOS SDK. لإنشاء تطبيق، راجع إنشاء التطبيقات.

الخطوة 1: إنشاء مفتاح مصادقة APNs​

  1. سجّل الدخول إلى حساب Apple Developer وافتح Certificates, Identifiers & Profiles.
  2. انقر Keys في الشريط الجانبي، ثم انقر زر الإضافة (+).
  3. في Key Name، أدخل اسمًا ستتعرف عليه لاحقًا، مثل «Joryio push».
  4. حدد مربع الاختيار بجوار Apple Push Notification service (APNs)، ثم انقر Configure بجواره.
  5. اختر بيئة المفتاح ونوع المفتاح:
    • البيئة - اختر البيئة المطابقة لما ستختاره في Joryio، راجع اختيار البيئة. المفتاح المقيّد بـ Sandbox لا يعمل لإرسال الإنتاج، والعكس صحيح.
    • نوع المفتاح - يعمل Team Scoped لكل تطبيق، أي كل bundle ID، في الفريق. أما Topic Specific فيقتصر على معرّفات bundle التي تحددها؛ إذا اخترته فأدرج bundle ID الخاص بتطبيقك.
  6. انقر Continue، وراجع إعداد المفتاح، ثم انقر Confirm.
  7. انقر Download. يُحفظ المفتاح كملف نصي بامتداد .p8.
  8. انقر Done.
يمكنك تنزيل المفتاح مرة واحدة فقط

لا تحتفظ Apple بنسخة من المفتاح الخاص. احفظ ملف .p8 في مكان آمن، مثل مدير كلمات المرور الخاص بفريقك. إذا كان زر Download معطلًا لاحقًا، فهذا يعني أن المفتاح نُزّل من قبل. إذا فُقد الملف، فأنشئ مفتاحًا جديدًا وألغِ المفتاح القديم.

الخطوة 2: تدوين Key ID وTeam ID​

  • Key ID - في Certificates, Identifiers & Profiles → Keys، انقر المفتاح الذي أنشأته. يظهر Key ID في تفاصيل المفتاح أسفل اسمه.
  • Team ID - في حساب Apple Developer، افتح Membership details. Team ID سلسلة من 10 أحرف.

الخطوة 3: اختيار البيئة​

لخدمة APNs بيئتان، ورمز الجهاز يعمل فقط في البيئة التي صدر لها:

  • التطوير (Sandbox) - للإصدارات الموقّعة بملف provisioning profile للتطوير، مثل تشغيل التطبيق من Xcode على جهازك.
  • الإنتاج - للإصدارات الموقّعة بملف provisioning profile للتوزيع: App Store وTestFlight.

يحدد Xcode بيئة Push للتطبيق من ملف provisioning profile، لذا فإن الإصدار هو الذي يحدد البيئة التي تُسجَّل فيها أجهزته. لكل تطبيق في Joryio إعداد بيئة واحد. إذا كنت تختبر بإصدارات تطوير وتنشر أيضًا على App Store، فأنشئ تطبيق iOS منفصلًا في Joryio لإصدارات التطوير، بمفتاح SDK خاص به، بدلًا من تبديل الإعداد ذهابًا وإيابًا.

الخطوة 4: إدخال بيانات الاعتماد في Joryio​

  1. في لوحة تحكم Joryio، انتقل إلى الإعدادات → التطبيقات.
  2. اعثر على تطبيق iOS في القائمة وانقر أيقونة إشعارات Push (الجرس) في صفه. تُفتح صفحة إشعارات Push - [اسم التطبيق].
  3. في بطاقة بيانات اعتماد APNS:
    • Environment - اختر التطوير (Sandbox) أو الإنتاج.
    • Authentication Method - اختر مبنية على رمز (.p8 Key).
    • Key ID - الصق Key ID من الخطوة 2.
    • Team ID - الصق Team ID من الخطوة 2.
    • Auth Key (.p8 Content) - افتح ملف .p8 في محرر نصوص والصق محتواه كاملًا، بما في ذلك السطرين -----BEGIN PRIVATE KEY----- و-----END PRIVATE KEY-----.
  4. انقر حفظ الإعداد.

تعرض قائمة التطبيقات الآن تم ضبط APNS أسفل اسم التطبيق. يُشفَّر مفتاح المصادقة عند التخزين ولا يُعرض مرة أخرى: عند إعادة فتح الصفحة يكون الحقل فارغًا مع الملاحظة «مضبوط - اتركه فارغًا للاحتفاظ بالقيمة الحالية، أو أدخل قيمة جديدة لاستبدالها.» اتركه فارغًا للاحتفاظ بالمفتاح المحفوظ.

الخطوة 5: إرسال Push تجريبي​

  1. ثبّت إصدارًا من تطبيقك تطابق بيئته البيئة التي اخترتها، وافتحه، واسمح بالإشعارات. يسجّل SDK رمز الجهاز في Joryio.
  2. أنشئ حملة Push، أو افتح مسودة، ترسل من هذا التطبيق.
  3. انقر إرسال Push تجريبي في المتغير، واختر المستخدم المسجّل الدخول على جهازك، ثم أرسل.

إذا فشل الاختبار، تتضمن رسالة الخطأ السبب الذي أعادته APNs؛ ابحث عنه في الجدول أدناه. لمسار الحملة الكامل، راجع إشعارات Push.

الأخطاء الشائعة وحلولها​

ما تراهالسبب المحتملالحل
BadDeviceTokenصدر رمز الجهاز للبيئة الأخرى - مثل إصدار TestFlight بينما Joryio مضبوط على التطوير (Sandbox).اضبط Environment ليطابق الإصدار، راجع الخطوة 3، ثم افتح التطبيق على الجهاز مرة أخرى ليسجّل رمزه من جديد.
DeviceTokenNotForTopicينتمي الرمز إلى تطبيق، أي bundle ID، غير الذي ترسل له بيانات الاعتماد.تحقق من أن الجهاز يشغّل التطبيق المرتبط بمفتاح SDK لتطبيق Joryio هذا، وأن المفتاح ينتمي إلى فريق المطورين المالك للتطبيق.
InvalidProviderTokenلا تتطابق قيم Key ID أو Team ID أو محتوى .p8 - مثل Key ID من مفتاح مع محتوى مفتاح آخر، أو مفتاح من فريق آخر.أعد إدخال القيم الثلاث من المفتاح والفريق نفسيهما. الصق ملف .p8 كاملًا، بما في ذلك سطري BEGIN وEND.
TopicDisallowedالمفتاح غير مسموح له بالإرسال إلى هذا التطبيق - مثل مفتاح Topic Specific لا يتضمن bundle ID الخاص بك، أو مفتاح مقيّد بالبيئة الأخرى.أنشئ مفتاحًا يغطي bundle ID والبيئة الخاصين بك، أو استخدم مفتاح Team Scoped.
Unregisteredأُزيل التطبيق أو لم يعد الرمز نشطًا.لا يلزم إصلاح بيانات الاعتماد. يتوقف Joryio عن الإرسال إلى هذا الرمز.
«no device accepted the notification»ليس لدى المستخدم جهاز iOS مسجّل لهذا التطبيق.افتح التطبيق المدمج فيه SDK على الجهاز، واسمح بالإشعارات، وتأكد من أنك تختبر بالمستخدم نفسه.
فُقد ملف المفتاحتسمح Apple بتنزيل واحد فقط.أنشئ مفتاحًا جديدًا، الخطوة 1، وأدخله في Joryio، ثم ألغِ المفتاح القديم.
أُلغي مفتاحيفشل كل إرسال بهذا المفتاح.أنشئ مفتاحًا جديدًا وأدخله في Joryio.

الأمان وتدوير المفاتيح​

  • تعامل مع ملف .p8 كسر: أي شخص يملكه، مع Key ID وTeam ID الخاصين بك، يمكنه إرسال إشعارات إلى مستخدميك. لا تضفه إلى نظام التحكم في الإصدارات ولا ترسله بالبريد الإلكتروني أو الدردشة.
  • إذا كنت تعتقد أن المفتاح تسرّب، فأنشئ مفتاحًا جديدًا، وأدخله في Joryio، ثم ألغِ القديم: في Certificates, Identifiers & Profiles → Keys، انقر المفتاح، ثم Revoke، وأكّد. يسري الإلغاء فورًا على كل خدمة تستخدم المفتاح.
  • لتدوير المفتاح دون انقطاع، اتبع الترتيب نفسه: المفتاح الجديد في Joryio أولًا، ثم إلغاء القديم. تحدّ Apple من عدد المفاتيح التي يمكن للفريق امتلاكها لكل بيئة، لذا قد تحتاج إلى إلغاء مفتاح غير مستخدم قبل إنشاء مفتاح جديد.