كيف تدعم حزم تطوير الصอฟتوير (SDKs) الإحالة والنمو في تطبيقات الهاتف المحمول

ما هي حزمة تطوير البرمجيات (SDK) وكيف تعمل؟ حزمة تطوير البرمجيات (SDK) هي مجموعة من المكتبات وواجهات برمجة التطبيقات والأدوات والوثائق المصممة لمساعدة المطورين على بناء أو توسيع نطاق تطبيقات البرمجيات. في تطوير تطبيقات الهاتف المحمول، تتضمن حزمة SDK عادةً مكتبات مدمجة داخل التطبيق الأصلي لتوفير وظائف خاصة بالمنصة مثل الروابط العميقة والإحالة. عندما تقيم فرق هندسة الهواتف المحمول كيفية انتقال بيانات اكتساب المستخدمين من الترويج عبر الويب إلى تطبيق مثبت حديثًا، فإنها تواجه حدًا أساسيًا لنظام التشغيل: لا يمكن لواجهات الويب البعيدة الوصول إلى دورات حياة التطبيقات الأصلية أو اجتياز بيئات الحماية (Sandboxes) الخاصة بمتجر التطبيقات بمفردها. توفر منصة OpoInstall، المتخصصة في إحالة الهواتف المحمول والروابط العميقة، مكتبات عميلة أصلية وscripts للويب لتنسيق العمل عبر هذه البيئات المعزولة لاستعادة معاملات الحملات وتوجيه المستخدمين إلى وجهات العرض المستهدفة داخل التطبيق.

حزمة تطوير البرمجيات (SDK) هي مجموعة معبأة مسبقًا من المكتبات، وواجهات برمجة تطبيقات البرمجيات (APIs)، وملفات الرأس، ووثائق المطورين، ونماذج التعليمات البرمجية المصممة لنظام تشغيل أو إطار عمل معين. على عكس واجهة برمجة تطبيقات الويب البعيدة المستقلة التي تحدد واجهة اتصال عديمة الحالة عبر HTTP، يتم تنفيذ حزمة SDK للهاتف المحمول مباشرةً داخل عملية وقت التشغيل (Runtime Process) للتطبيق العميل لإدارة الحالة المحلية، ونداءات استدعاء دورة حياة نظام التشغيل، والاتصالات غير المتزامنة.

ما هي حزمة SDK وكيف تختلف عن واجهة برمجة تطبيقات الويب القياسية

تفكيك المصطلحات: لماذا تحتوي كل حزمة SDK على واجهات برمجة تطبيقات، بينما لا تعد واجهة برمجة التطبيقات حزمة SDK

في هندسة البرمجيات، غالبًا ما يخلط المطورون الجدد على بنية نمو الهواتف المحمول بين واجهة برمجة التطبيقات (API) وحزمة تطوير البرمجيات (SDK). وبينما يعمل المفهومان معًا، إلا أنهما يشغلان طبقات متميزة في بنية البرمجيات.

واجهة برمجة التطبيقات (API) هي بمثابة مواصفات واجهة وعقد اتصال بحت. فهي تحدد توقيعات الطرق، هياكل البيانات، بناء جملة URI وفقًا لمعيار IETF RFC 3986، وتنسجات الاستجابة التي تسمح لمكون برمجيات بالتفاعل مع مكون آخر. تتواجد واجهات برمجة التطبيقات على مستويات متعددة: فقد تكون واجهات لنظام التشغيل المحلي، أو واجهات مكتبة داخل العملية، أو نقاط نهاية ويب بعيدة عديمة الحالة تحكمها دلالات بروتوكول HTTP وفقًا لمعيار IETF RFC 9110 (مثل GET وPOST). عند استدعاء واجهة REST API عن بُعد مباشرةً، يجب على مطور التطبيق بناء طلب الشبكة، وإدارة أمان النقل، وتحليل حمولة JSON المرتجعة، والتعامل مع شروط إعادة المحاولة يدويًا.

على العكس من ذلك، فإن حزمة SDK هي حزمة التنفيذ الكاملة التي تغلف واجهة برمجة تطبيقات محلية واحدة أو أكثر إلى جانب منطق وقت التشغيل، والوثائق، وأدوات المطورين. عندما يقوم المطور استيراد حزمة SDK للجوال في مشروع Android Studio أو Xcode، فإنه يربط كود المكتبة المعد مسبقًا مباشرةً بملف الثنائي (Binary) الخاص بتطبيقه. تعرض حزمة SDK واجهات برمجة تطبيقات برمجية محلية (مثل initialize() أو getInstallParam() أو handleDeepLink()) لتطبيق المضيف مع إدارة جدولة الخيوط، واستدعاءات دورة حياة نظام التشغيل، والاتصال بخادم بعيد داخليًا.

سياق التنفيذ: نقاط نهاية الخادم الخادم عديمة الحالة مقابل مكتبات وقت التشغيل من جهة العميل ذات الحالة

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

• إقامة العمليات والتغليف: يتم توفير واجهة برمجة تطبيقات الويب البعيدة من خلال البنية التحتية من جهة الخادم ويتم استدعاؤها عبر الشبكة؛ حيث يقوم تطبيق الخادم بتنفيذ نقطة النهاية، بينما ينفذ التطبيق العميل منطق معالجة الطلب. في المقابل، يتم تجميع حزمة SDK للجوال في ملف النشر الخاص بالتطبيق (مثل Android App Bundle .aab) أو حزمة التطبيق القابلة للتثبيت (.apk على أندرويد و.ipa على آي أو إس) وتعمل داخل مساحة الذاكرة المخصصة للتطبيق على جهاز المستخدم النهائي.
• الوعي بدورة الحياة الأصلية: تستجيب نقاط نهاية REST البعيدة فقط عندما يُرسل العميل طلب HTTP. تسجل حزمة SDK الأصلية للجوال مراقبين مع نظام تشغيل الهاتف المحمول، مما يسمح لها اكتشاف متى يتم تشغيل التطبيق، أو انتقاله بين حالات الواجهة الأمامية والخلفية، أو تلقي نية توجيه على مستوى النظام.
• الاستمرارية المحلية الاختيارية وقائمة الانتظار: اعتمادًا على تنفيذها، قد تقوم حزمة SDK للجوال بتخزين حالة التكوين أو وضع أحداث التحويل في قائمة انتظار داخل مساحة تخزين محلية آمنة (مثل SharedPreferences أو SQLite على أندرويد، وUserDefaults أو مساحة تخزين ملفات التطبيق على آي أو إس، مع حجز Keychain لبيانات الاعتماد الحساسة الصغيرة) بحيث يمكن نقل البيانات عن بُعد بشكل غير متزامن عندما يكون اتصال الشبكة متاحًا.

المقارنة المعمارية: واجهات برمجة تطبيقات الويب البعيدة مقابل حزم SDK الأصلية للجوال

يوضح الجدول أدناه التباين بين واجهات برمجة تطبيقات الويب عديمة الحالة وحزم SDK الأصلية للجوال عبر الأبعاد المعمارية الرئيسية:

المكونات الأساسية داخل حزمة تطوير برمجيات الجوال

المكتبات الثنائية المترجمة: حزم أرشيف أندرويد وإطارات عمل آي أو إس

في صميم أي حزمة SDK للجوال يوجد توزيع ثنائي مترجم منسق لأدوات بناء نظام التشغيل المستهدف:

أرشيف أندرويد (.aar)، JAR، وحزم التطبيقات (.aab): على أندرويد، توزع حزم SDK كحزم .aar أو مكتبات .jar. بينما يحتوي ملف .jar على بايت كود JVM مترجم، يمكن لحزمة .aar أيضًا تجميع موارد وإدخالات بيان خاصة بأندرويد تدمج في تطبيق المضيف أثناء بناء Gradle. عند بناء تطبيق المضيف للإصدار، يعمل حزمة Android App Bundle (.aab) كعنصر نشر بدلاً من حزمة تطبيق قابلة للتثبيت المباشر؛ يعالجها متجر Google Play إلى ملفات APK خاصة بالجهاز والتي تُسلم للمستخدمين.
مكتبات آي أو إس الثابتة (.a)، وإطارات العمل، وXCFrameworks: على آي أو إس، توزع حزم SDK كمكتبات ثابتة أو حزم .framework أو أرشيفات .xcframework. يستهدف بناء .framework القياسي عادةً متغير منصة معين وقد يحتوي على بنية معالجة واحدة أو أكثر مدعومة، بينما صُممت حزمة Apple XCFramework (.xcframework) لتغليف متغيرات منصات وبنى متعددة - مثل شرائح أجهزة ARM64 الفعلية لـ iOS إلى جانب شرائح محاكاة iOS - في عنصر واحد قابل للتوزيع.

ملفات الرأس العامة، وعقود الواجهات، وتعريفات الأنواع

تتطلب الثنائيات المترجمة عقود أنواع عامة حتى يتمكن مترجم تطبيق المضيف من التحقق من استدعاءات الطرق وقت البناء:

ملفات رأس آي أو إس (.h) وواجهات الجسر: توفر حزم SDK القائمة على Objective-C لـ iOS ملفات رأس عامة (مثل OpoInstallSDK.h) تعلن عن واجهات الفئات، بروتوكولات المندوبين (OpoInstallDelegate)، ونماذج البيانات (OpoinstallData). في مشاريع Swift، يتم الكشف عن هذه الإعلانات عبر رأس جسر Objective-C أو استيراد الوحدة النمطية.
توقيعات فئات أندرويد وواجهات الاستدعاء: تعرض حزم SDK الخاصة بأندرويد فئات نقاط الدخول العامة وواجهات الاستدعاء العامة (مثل ResultCallBack<OpoData>) ضمن مساحات أسماء الحزم الموثقة.

بيانات التهيئة، ومفاتيح التطبيقات (AppKeys)، وإعلانات الصلاحيات

تعتمد حزمة SDK للجوال على بيانات التعريف الخاصة بتكوين المضيف لتوثيق طلبات المستأجر وتسجيل خطاطيف توجيه نظام التشغيل:

معرف مستأجر التطبيق (AppKey): مُعلن عنه داخل علامة <meta-data> في ملف AndroidManifest.xml لأندرويد أو ملف Info.plist لـ iOS (com.opoinstall.APP_KEY)، ويقوم AppKey بتحديد مستأجر التطبيق أثناء تهيئة حزمة SDK.
إعلانات توجيه نظام التشغيل: لدعم تشغيل التطبيق بنقرة واحدة، يعلن مشروع المضيف عن مخططات عناوين URL مخصصة وربط النطاقات التي تم التحقق منها (نطاقات applinks: في تصاريح النطاقات المرتبطة بـ Xcode ومرشحات النوايا التي تم التحقق منها على أندرويد).

الوثائق ومشاريع النماذج: تحويل المكتبات المترجمة إلى واجهات مطورين قابلة للاستخدام

من الصعب تبني مكتبة مترجمة بدون مواصفات دمج واضحة. يجب أن توفر حزم SDK ذات الجودة الإنتاجية وثائق مطورين واضحة، وحيثما توفرت، مشاريع عينات قابلة للتشغيل:

وثائق المطورين: تحدد توافق الإصدار، ترتيب تهيئة دورة الحياة، الأذونات المطلوبة، تنسيقات حمولة الاستدعاء، ورموز الأخطاء حتى يتمكن المهندسون من دمج المكتبة بشكل متوقع.
مشاريع العينات والجسور عبر المنصات: تساعد مشاريع العينات التجريبية البادئة الفرق في التحقق من الروابط العميقة واستعادة المعلمات. بينما يقوم مركز تنزيل حزم SDK للهواتف المحمولة بتوزيع حزم SDK الأصلية الأساسية لأندرويد وiOS بشكل رئيسي (الإصدار الحالي v2.1.0)، تقوم الفرق التي تستخدم الأطر المتعددة المنصات (مثل Flutter أو Unity) بربط قدرات حزم SDK الأصلية هذه عبر المكونات الإضافية الوسيطة (Wrapper plugins) أو قنوات النظام الأساسي ويجب عليها التحقق من مستودعات الإضافات المتاحة مقابل الوثائق الرسمية.

لماذا لا تستطيع واجهات برمجة تطبيقات الويب وحدها حل إحالة تثبيت التطبيقات

صندوق متجر التطبيقات الأسود: كيف تؤدي عزلة الحماية إلى تعطيل تتبع ملفات تعريف ارتباط الويب التقليدية

في تطوير الويب القياسي، يعتمد تتبع رابط الإحالة إلى حدث التسجيل على التخزين المؤقت للمتصفح: عندما يزور المستخدم https://example.com/index.html?inviter_id=A102، يقرأ جافا سكريبت سلسلة الاستعلام ويخزن inviter_id=A102 في localStorage أو ملف تعريف ارتباط HTTP.

في مجال اكتساب تطبيقات الهاتف المحمول، ينكسر هذا الاتصال عند حدود متجر التطبيقات - وهو حاجز هيكلي يُعرف باسم صندوق متجر التطبيقات الأسود:

1. سياق الويب: ينقر المستخدم على رابط ترويجي داخل متصفح جوال أو تطبيق اجتماعي، مما يؤدي إلى تحميل صفحة هبوط H5 تحمل معلمات مخصصة (?ref=userA&channelCode=ch_01).
التسليم للمتجر: نظرًا لعدم تثبيت التطبيق الأصلي بعد، فإن النقر فوق زر التنزيل يعيد توجيه المستخدم خارج المتصفح وإلى متجر Apple App Store أو Google Play Store.
عزلة الحماية (Sandbox): عندما يقوم المستخدم بتثبيت وتشغيل التطبيق الأصلي، يقوم نظام تشغيل الهاتف المحمول بإنشاء العملية داخل نظام ملفات معزول وحماية للذاكرة. لا يمكن للتطبيق الأصلي قراءة ملفات تعريف الارتباط أو localStorage الخاصة بجلسة المتصفح التي بدأت التنزيل.

جسر الفجوة بين الويب والتطبيق: دور حزم Web JS SDKs وحزم العملاء الأصلية

يتضمن حل المعلمات عبر حدود متجر التطبيقات سير عمل منسق يفصل بين ثلاثة مفاهيم مترابطة - الروابط العميقة المؤجلة (توجيه مستخدم جديد إلى شاشة مستهدفة داخل التطبيق بعد التثبيت)، واستعادة معلمات التثبيت (استرداد أزواج المفتاح والقيمة المخصصة الم تمررة على رابط H5)، ومطابقة الإحالة (ربط التثبيت بقناة ترويجية محددة):

حزمة Web JS SDK السابقة للتثبيت (سكربت ويب OpoInstall): مدمجة في صفحة هبوط H5، تقوم حزمة Web JS SDK بتحليل معلمات الاستعلام الديناميكية من رابط المشاركة (مثل channelCode أو shareCode أو معرفات الغرف) وتحمل سياق جلسة ما قبل التثبيت إلى خادم الإحالة قبل تشغيل تنشيط التطبيق أو إعادة التوجيه للمتجر.
حزمة العميل الأصلية اللاحقة للتثبيت (حزمة SDK لأندرويد / آي أو إس): مدمجة في ثنائي تطبيق الجوال، تتم تهيئة حزمة SDK الأصلية عند التشغيل الأول، وتتواصل مع واجهات برمجة التطبيقات للمنصة وخادم الإحالة، وتعيد المعلمات المخصصة المستعادة إلى التطبيق العميل عبر استدعاء غير متزامن.

[متصفح الويب للجوال: صفحة هبوط H5]
                 |
                 | 1. حزمة Web JS SDK تحلل معاملات الويب (?ref=userA&channelCode=ch01)
                 |    وترفع سياق جلسة ما قبل التثبيت
                 v
     [خلفية خادم الإحالة]
                 |
                 | 2. المستخدم ينزل التطبيق من متجر التطبيقات / Google Play
                 |    (ملفات تعريف الارتباط للمتصفح لا يمكنها تجاوز حماية نظام التشغيل)
                 v
   [التشغيل الأول للتطبيق الأصلي: حزمة SDK للجوال]
                 |
                 | 3. حزمة SDK العميل تبدأ عند التشغيل وتسترد
                 |    المعلمات المخصصة المخزنة مؤقتًا + معرف القناة
                 v
  [التوجيه داخل التطبيق وإحالة القناة]

آليات الإحالة الخاصة بالمنصة: مرجع تثبيت Google Play مقابل تسوية سياق آي أو إس

نظرًا لأن أندرويد وiOS يحافظان على بنيتين مختلفتين لمتاجر التطبيقات، تعتمد إحالة الهواتف المحمول على آليات منصة مميزة:

نظام أندرويد البيئي واجهة برمجة تطبيقات مرجع تثبيت Google Play: بالنسبة للتطبيقات الموزعة من خلال Google Play، يمكن للتكامل الأصلي استخدام واجهة برمجة تطبيقات مرجع تثبيت Google Play الرسمية لاسترداد بيانات تعريف الإحالة (بما في ذلك عنوان URL للمرجع والطوابع الزمنية للنقر والتثبيت) التي يمررها متجر Play أثناء التثبيت. ونظرًا لأن واجهة برمجة تطبيقات مرجع تثبيت Google Play تنطبق بشكل خاص على تدفقات تثبيت متجر Google Play المؤهلة، فإن توزيعات أندرويد خارج Google Play تعتمد على مطابقة معلمات H5 من جهة الخادم أو حزم قنوات أندرويد المصدرة (ملفات APK التي تحمل معرفات channelCode المضمنة).
نظام آي أو إس البيئي وتسوية السياق: لا يوفر متجر التطبيقات الخاص بشركة Apple آليّة عامة لتمرير معلمات الاستعلام في عناوين URL تعادل مرجع التثبيت في Google Play. عندما يكون التطبيق مثبتًا بالفعل، يوجه آي أو إس المستخدمين مباشرةً إلى التطبيق عبر روابط Apple الشاملة (Universal Links)، والتي تتحقق من ملكية النطاق من خلال ملف apple-app-site-association (AASA). عندما لا يكون التطبيق مثبتًا، تعود الروابط الشاملة إلى موقع ويب ولا تضمن بشكل مستقل استعادة المعلمات بعد التثبيت؛ تتطلب استعادة المعلمات المؤجلة تسوية الجلسة من جهة الخادم عند التشغيل الأول.

احترام حدود خصوصية المنصة: إرشادات خصوصية مستخدم Apple وإشارات المطابقة المسموح بها

عند تقييم كيف تقوم حزم SDK للجوال بتسوية زيارات الويب السابقة للتثبيت مع عمليات الإطلاق اللاحقة للتثبيت، يجب على الفرق الهندسية التمييز بين الميزات الموثقة من قِبل المورد والامتثال لسياسة نظام التشغيل:

آلية موثقة من المورد: توثق وثائق المنتج العامة لـ OpoInstall قناة H5 وسير عمل تثبيت المعلمات حيث تجمع حزمة SDK للويب سمات بصمة الجهاز ومعرفات القنوات على صفحة H5، وتقوم حزمة SDK الأصلية لأندرويد/iOS بإعادة جمع سمات الجهاز عند التشغيل الأول لمطابقة مصدر التثبيت.
حدود سياسة منصة Apple: بموجب إرشادات خصوصية المستخدم واستخدام البيانات الخاصة بـ Apple، تحظر شركة Apple صراحةً استخلاص البيانات من الجهاز - مثل الجمع بين خصائص المتصفح، أو عناوين IP، أو تكوينات النظام - بغرض تحديد هوية المستخدم أو الجهاز بشكل فريد (أخذ بصمات الأجهزة / Fingerprinting). التطبيقات التي تشارك في أخذ البصمات المحظورة، أو تشير إلى حزم SDK لأطراف ثالثة تقوم بذلك، تواجه خطر الرفض أثناء مراجعة متجر التطبيقات. وبشكل منفصل، يُطلب إذن الشفافية لتتبع التطبيقات (ATT) عندما تمرر خدمات الروابط العميقة التابعة لأطراف ثالثة أو الروابط العميقة المؤجلة معرفات فريدة أو تنشئ هويات مستخدمين مشتركين عبر التطبيقات من شركات مختلفة لاستهداف الإعلانات، أو قياس الإعلانات، أو المشاركة مع وسطاء البيانات. ومع ذلك، فإن موافقة ATT لا تجعل أخذ بصمات الجهاز المحظور مسموحًا به.
تصعيد الامتثال ومتطلبات التحقق: إذا كان إصدار معين من حزمة SDK أو تكوينها يعتمد على أخذ بصمات الجهاز المحظورة، فلن يؤدي إجراء تدقيق داخلي للبيانات العامة ولا الحصول على موافقة المستخدم من خلال مطالبة ATT إلى جعل هذه الآلية متوافقة مع إرشادات Apple. إذا تعذر على المورد إثبات أن آلية المطابقة الخاصة بـ iOS تتجنب أخذ بصمات الجهاز المحظورة، فلا يجب على المطورين نشر آلية الإحالة هذه على iOS حتى يتم التحقق من بديل متوافق بشكل مستقل، وفقًا لممارسات الحوكمة الخاصة بـ أمان تطبيقات الأجهزة المحمولة من OWASP.
توقيت الشبكة والبدائل غير المنسوبة: على الرغم من أن iOS لا يعرض إذنًا عامًا يمنحه المستخدم للوصول العادي إلى الإنترنت (يجب على المطورين التمييز بين إمكانية الوصول العامة للإنترنت وإذن خصوصية الشبكة المحلية من Apple، والذي ينطبق على اكتشاف الأجهزة على الشبكة المحلية)، إلا أن تهيئة حزمة SDK واسترداد المعلمات يظل يعتمد على توفر الشبكة وتوقيت بدء التشغيل. ونظرًا لعدم ضمان المطابقة المؤجلة عبر جميع ظروف الشبكة أو عمليات الإطلاق الأولى المتأخرة، يجب على التطبيقات دائمًا تنفيذ تدفقات احتياطية سلسة عند إرجاع معلمات فارغة.

كيف تعمل حزمة SDK لإحالة الهواتف المحمولة عبر دورة حياة التطبيق

المرحلة الأولى: إدارة التبعيات والربط وقت البناء عبر Gradle وCocoaPods

تبدأ دورة حياة حزمة SDK في وقت الترجمة عندما يعلن المطور عن تبعية المكتبة عبر Gradle أو CocoaPods أو استيراد الأرشيف اليدوي. وأثناء تجميع البناء، يقوم مدير الحزم بحل عنصر المكتبة وربط رموزها الثنائية في حزمة التطبيق. تتطلب بعض حزم SDK للجوال اعتبارات توافق تقليص التعليمات البرمجية المحددة في إصدارات الإنتاج، وقد تتطلب عمليات دمج حزم SDK لـ iOS أيضًا إعلانات بيان الخصوصية الخاصة بالمنصة وتكوينات بناء متوافقة.

المرحلة الثانية: التهيئة على الخيط الرئيسي عند بدء تشغيل التطبيق

عندما يقوم المستخدم بتشغيل التطبيق، ينشئ نظام تشغيل الجوال عملية التطبيق ويستدعي خطاف دورة حياة نقطة الدخول الرئيسية - Application.onCreate() على أندرويد كما هو مفصل في دليل مطوري Google Android حول دورة حياة التطبيق، وapplication(_:didFinishLaunchingWithOptions:) على iOS كما هو مفصل في وثائق مطوري Apple حول UIApplicationDelegate. يجب أن تقلل حزمة SDK للجوال المصممة جيدًا من العمل أثناء بدء تشغيل التطبيق ونقل عمليات الشبكة إلى التنفيذ غير المتزامن. يجب على المطورين التحقق من سلوك التهيئة الفعلي وقياس أداء البدء على البارد في الإصدار المستهدف.

المرحلة الثالثة: اعتراض الروابط العميقة الأصلية عبر الروابط الشاملة ومرشحات النوايا

عندما يكون التطبيق مثبتًا بالفعل ويقوم المستخدم بالنقر فوق رابط H5، يقوم نظام التشغيل بتنبيه التطبيق وتسليم سياق التوجيه إلى حزمة SDK من خلال نقاط دخول خاصة بالمنصة:

مخططات أندرويد المخصصة مقابل روابط التطبيقات التي تم التحقق منها: توجيه مخططات عناوين URL المخصصة (scheme://) عبر مرشح نوايا أساسي BROWSABLE <intent-filter>. يتطلب دعم روابط تطبيقات أندرويد التي تم التحقق منها وجود <intent-filter android:autoVerify="true"> يعلن عن كلا المخططين http وhttps إلى جانب android:host المستهدف، مدعومًا بملف /.well-known/assetlinks.json Digital Asset Links يحتوي على اسم حزمة التطبيق بصمة شهادة التوقيع SHA-256.
توجيه AppDelegate و UISceneDelegate في آي أو إس: تسليم الروابط الشاملة لـ NSUserActivity إلى AppDelegate في تطبيقات دورة الحياة التقليدية، أو - لتطبيقات iOS 13+ التي تتبنى دورات الحياة القائمة على المشاهد عبر UISceneDelegate - إلى scene(_:willConnectTo:options:) عند التشغيل البارد وscene(_:continue:) عند استئناف التشغيل الدافئ.

المرحلة الرابعة: استعادة المعلمات بشكل غير متزامن وقائمة انتظار قياس الأحداث

عند التشغيل الأول - أو عند حدوث مراحل تحويل الأعمال - يقوم تطبيق المضيف باستدعاء طرق حزمة SDK غير المتزامن لاسترداد معلمات التثبيت المخزنة مؤقتًا (data وchannelCode) والإبلاغ عن أحداث التحويل اللاحقة (مثل تسجيل الحسابات أو نقاط التأثير المخصصة).

تنفيذ خطاطيف دورة حياة حزمة SDK الأصلية على أندرويد وiOS

تكوين معرفات التطبيقات والتحقق من إصدارات حزمة SDK

تتبع أنماط التكامل التوضيحية أدناه وثائق التكامل العامة لـ OpoInstall لإظهار كيف تقوم مشاريع أندرويد وiOS الأصلية بربط خطاطيف دورة الحياة الموضحة أعلاه. ونظرًا لأن مركز التنزيل يوزع أرشيفات SDK المحدثة (حاليًا v2.1.0، الصادر في 2026-09-20) بينما قد تشير أمثلة الوثائق إلى إحداثيات ثانوية أقدم، يجب على الفرق الهندسية تنزيل حزمة SDK المستهدفة v2.1.0، والتحقق من جميع مسارات الاستيراد وتوقيعات الطرق مقابل رؤوس المكتبة المضمنة، وتشغيل تحقق بناء نظيف في Android Studio وiOS قبل نشر الإنتاج. ارجع إلى وثائق OpoInstall التقنية للحصول على تعليمات التكامل الخاصة بالإصدار.

نمط تهيئة حزمة SDK لأندرويد واسترداد المعلمات

في ملف AndroidManifest.xml، أعلن عن أذونات الشبكة، ومعرف المستأجر AppKey، وكتل <intent-filter> منفصلة لتنبيه مخطط عنوان URL المخصص وروابط تطبيقات أندرويد التي تم التحقق منها (مع إعلان كلا المخططين http وhttps وفقًا لمتطلبات التحقق من روابط تطبيقات أندرويد، واستبدال links.example.com بنطاقك الذي تم التحقق منه):

<!-- File: app/src/main/AndroidManifest.xml (Illustrative Integration Pattern) -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app">

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    <application
        android:name=".CustomApplication"
        android:allowBackup="true">

        <meta-data
            android:name="com.opoinstall.APP_KEY"
            android:value="OPOINSTALL_APPKEY"/>

        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTask">

            <!-- 1. Custom URL Scheme wakeup filter -->
            <intent-filter>
                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <data android:scheme="OPOINSTALL_SCHEME"/>
            </intent-filter>

            <!-- 2. Verified Android App Links filter (requires /.well-known/assetlinks.json with SHA-256 cert fingerprint) -->
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <data android:scheme="http"/>
                <data android:scheme="https"/>
                <data android:host="links.example.com"/>
            </intent-filter>
        </activity>
    </application>
</manifest>

// File: app/src/main/java/com/example/app/CustomApplication.java
package com.example.app;

import android.app.Application;
import com.opoinstall.api.OpoInstall;

public class CustomApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        OpoInstall.initialize(this);
    }
}

// File: app/src/main/java/com/example/app/MainActivity.java
// Note: Verify exact package imports and callback signatures against your downloaded SDK v2.1.0 archive.
package com.example.app;

import android.content.Intent;
import android.os.Bundle;
import android.util.Log;
import androidx.appcompat.app.AppCompatActivity;
import com.opoinstall.api.OpoInstall;
import com.opoinstall.api.OpoData;
import com.opoinstall.api.OpoError;
import com.opoinstall.api.ResultCallBack;

public class MainActivity extends AppCompatActivity {
    private static final String TAG = "OpoInstallSDK";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        OpoInstall.getInstance().start(this);

        // Process wakeup intent if launched via custom scheme or verified App Link
        getWakeUpData(getIntent());

        // Retrieve deferred installation parameters when needed by onboarding logic
        OpoInstall.getInstance().getInstallParam(new ResultCallBack<OpoData>() {
            @Override
            public void onResult(OpoData opoData) {
                Log.d(TAG, "getInstallParam onResult : " + opoData);
            }

            @Override
            public void onError(OpoError opoError) {
                Log.e(TAG, "getInstallParam onError : " + opoError);
            }
        });
    }

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        getWakeUpData(intent);
    }

    private void getWakeUpData(Intent intent) {
        OpoInstall.getInstance().handleDeepLink(intent, new ResultCallBack<OpoData>() {
            @Override
            public void onResult(OpoData opoData) {
                Log.d(TAG, "handleDeepLink onResult : " + opoData);
            }

            @Override
            public void onError(OpoError opoError) {
                Log.d(TAG, "handleDeepLink onError : " + opoError);
            }
        });
    }
}

نمط تسجيل مندوب SDK لـ iOS وتنبيه SceneDelegate

على iOS، اعرض #import "OpoInstallSDK.h" في رأس جسر Objective-C الخاص بك، وقم بتكوين com.opoinstall.APP_KEY في Info.plist، ونفذ OpoInstallDelegate. استخدم طرق معالجة عنوان URL لـ AppDelegate للتطبيقات التي لا تتبنى إدارة دورة الحياة القائمة على المشاهد؛ بالنسبة للتطبيقات القائمة على المشاهد، قم بمعالجة الروابط الشاملة ومخططات عناوين URL للتشغيل البارد واستئناف التشغيل الدافئ من خلال طرق SceneDelegate المقابلة:

// File: AppDelegate.swift & SceneDelegate.swift (Illustrative Integration Pattern)
// Note: Verify exact Objective-C bridging headers and method signatures against your downloaded iOS SDK v2.1.0 archive.
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        OpoInstallSDK.initWith(self)
        return true
    }

    // For apps that do NOT adopt UISceneDelegate lifecycle management:
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        OpoInstallSDK.continue(userActivity)
        return true
    }

    func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey: Any] = [:]
    ) -> Bool {
        OpoInstallSDK.handLinkURL(url)
        return true
    }

    func getWakeUpParams(_ appData: OpoinstallData?) {
        print("Wakeup data: \(String(describing: appData?.data)), channelCode: \(String(describing: appData?.channelCode))")
    }

    func fetchInstallParameters() {
        OpoInstallSDK.defaultManager()?.getInstallParmsCompleted({ (appData: OpoinstallData?) in
            print("Install data: \(String(describing: appData?.data)), channelCode: \(String(describing: appData?.channelCode))")
        })
    }
}

// For iOS 13+ apps that adopt UISceneDelegate lifecycle management:
@available(iOS 13.0, *)
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        for userActivity in connectionOptions.userActivities {
            OpoInstallSDK.continue(userActivity)
        }
        for urlContext in connectionOptions.urlContexts {
            OpoInstallSDK.handLinkURL(urlContext.url)
        }
    }

    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        OpoInstallSDK.continue(userActivity)
    }

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        for urlContext in URLContexts {
            OpoInstallSDK.handLinkURL(urlContext.url)
        }
    }
}

متى يجب على الفرق الهندسية دمج حزمة SDK للجوال من جهة خارجية

السيناريوهات المناسبة لدمج حزمة SDK مخصصة للجوال

يعد دمج حزمة SDK مخصصة للإحالة والروابط العميقة أمرًا مناسبًا في الظروف التالية:

برامج الإحالة والتهيئة الخالية من الأكواد: التطبيقات التي تشغل برامج إحالة أو دعوات غرف متعددة اللاعبين حيث يجب استعادة المعلمات (مثل ?ref=userA أو room_id=402) بعد تثبيت المتجر دون إدخال كود يدوي.
حملات H5 ورموز الاستجابة السريعة (QR) متعددة القنوات: فرق التسويق التي توزع الروابط عبر شبكات التواصل الاجتماعي، رموز QR غير المتصلة، وحزم قنوات أندرويد التي تتطلب تتبعًا موحدًا للزيارات والنقرات والتثبيتات والتسجيلات.
التشغيل السلس من الويب إلى التطبيق بنقرة واحدة: المنتجات التي توجه مستخدمي التطبيق الحاليين مباشرة من متجر متصفحات الجوال إلى وجهات عرض محددة داخل التطبيق عبر الروابط الشاملة وروابط التطبيقات أثناء توجيه المستخدمين غير المثبتين إلى متجر التطبيقات المناسب.

السيناريوهات التي تكون فيها واجهة برمجة تطبيقات REST المباشرة كافية

على العكس من ذلك، تكون حزمة SDK للإحالة من جهة العميل غيرจำเป็นة عندما لا يتجاوز تدفق العمل بيئات حماية الجوال الأصلية:

المعاملات الخلفية الموثقة: عندما يقوم مستخدم موثق بالفعل بتجديد اشتراك أو تشغيل Webhook للفوترة الخلفية، فإن تسجيل هذا التحويل عبر واجهة برمجة تطبيقات REST مباشرة من خادم إلى خادم (S2S) يتجنب تحديثات تبعية العميل.
تبيقات الويب المقتصرة على المتصفح: تطبيقات الويب التقدمية (PWAs) ومواقع الجوال التي لا توزع ثنائيات أصلية من خلال متجر التطبيقات أو Google Play يمكنها تتبع الإحالات باستخدام ملفات تعريف ارتباط الويب الأساسية القياسية ومعلمات استعلام عناوين URL.

المفاهيم الخاطئة الشائعة هندسيًا حول حزم SDK للجوال

المفهوم الخاطئ 1: دمج حزمة SDK للجوال يعطل بدء تشغيل التطبيق على البارد تلقائيًا: تعمل حزمة SDK للجوال المصممة جيدًا على تقليل العمل أثناء Application.onCreate() أو didFinishLaunchingWithOptions: وتنقل عمليات الشبكة إلى التنفيذ غير المتزامن، على الرغم من أنه يجب على المطورين دائمًا قياس زمن انتقال بدء التشغيل على البارد في بناء الهدف.
المفهوم الخاطئ 2: حزم قنوات أندرويد تتجاوز معرفات قناة رابط H5: عندما يستخدم تطبيق أندرويد حزم APK للقنوات المصدرة وروابط قنوات H5 معًا، تتيح حزمة OpoInstall SDK استعادة المعلمات المخصصة ومعرفات القنوات معًا؛ وفقًا لوثائق منتج OpoInstall، إذا كان التثبيت ينشأ من رابط قناة H5 مع channelCode مميز، فإن معرف رابط قناة H5 يأخذ الأولوية على معرف حزمة القناة في التقارير الإحصائية.

الملخص وإطار اتخاذ القرارات المعمارية

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

عند تحديد كيفية هيكلة خط الإحالة الخاص بك، طبق هذه الإرشادات الهندسية:

نشر حزمة SDK أصلية للجوال: عندما تنتقل رحلات المستخدمين من صفحات هبوط H5، أو المشاركات الاجتماعية، أو رمز الاستجابة السريعة (QR) عبر متجر التطبيقات أو Google Play وتتطلب استعادة تلقائية للمعلمات أو توجيه رابط شامل / رابط تطبيق بنقرة واحدة.

استخدام واجهات برمجة تطبيقات HTTP من خادم إلى خادم: عند تصدير إحصائيات القنوات المجمعة إلى مستودع بيانات داخلي، أو عند تسجيل أحداث الواجهة الخلفية التي لا تعتمد على سياق التشغيل من جهة العميل.

التحقق من تجميع الثنائيات والامتثال لخصوصية المنصة: قم دائمًا باختبار تجميع أرشيف SDK المستهدف (مثل v2.1.0) في مشروع نظيف وتأكد مع المورد من أن أي آلية مطابقة لـ iOS تتجنب بصمات الأجهزة المحظورة قبل إصدار الإنتاج.

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

المواد ذات الصلة

المفاهيم: حزمة تطوير البرمجيات، واجهة برمجة تطبيقات البرمجيات، الروابط العميقة المؤجلة، عزلة بيئة حماية نظام التشغيل

التقنيات: أرشيف أندرويد (.aar)، إطار عمل آي أو إس XCFramework، مرجع تثبيت Google Play، روابط Apple الشاملة

المعايير: دلالات بروتوكول HTTP وفقًا لمعيار IETF RFC 9110، بناء جملة المعرفات العامة URI وفقًا لمعيار IETF RFC 3986، مشروع أمان تطبيقات الأجهزة المحمولة من OWASP

واجهات المنصة والتكامل: طريقة أندرويد Application.onCreate، واجهة UIApplicationDelegate في آي أو إس، UISceneDelegate، NSUserActivity

الوثائق الرسمية والمراجع:

• دليل مطوري Google Android حول دورة حياة التطبيق

• دليل مطوري Google Android حول روابط التطبيقات

• الدليل التقني لواجهة برمجة تطبيقات مرجع تثبيت Google Play

• وثائق مطوري Apple حول UIApplicationDelegate

• وثائق مطوري Apple حول UISceneDelegate

• وثائق مطوري Apple حول دعم الروابط الشاملة

• وثائق مطوري Apple حول إنشاء حزمة إطار عمل ثنائية متعددة المنصات (XCFramework)

• إرشادات خصوصية المستخدم واستخدام البيانات الخاصة بـ Apple