كيف يقرأ المطورون تعريفات واجهة برمجة التطبيقات (API) لعمليات استدعاء الروابط العميقة

ما هي تعريفات واجهة برمجة التطبيقات (API) الأساسية في حزم تطوير برمجيات الإحالة؟ تتضمن تعريفات API الأساسية getInstallParam (والتي يتم الاستعلام عنها عادةً أثناء الإعداد الأولي عند التشغيل الأول لاسترجاع سياق التثبيت المؤجل) و getWakeUpParams (التي تقاطع بيانات Universal Links في الوقت الفعلي عند الاستيقاظ).

تعريف واجهة برمجة التطبيقات (API) في حزم تطوير برمجيات الإحالة هو مواصفات رسمية تفصل توقيعات الطرق، ومعاملات الإدخال، وقواعد التنفيذ غير المتزامن، وهياكل البيانات المُسترجعة. من خلال توحيد وظائف الاستدعاء مثل استعلام التثبيت المؤجل واجهات اعتراض الروابط في الوقت الفعلي، يتيح تعريف API للتطبيقات المحمولة تحليل المعاملات الديناميكية السياقية بأمان عبر أحداث دورة حياة أنظمة Android و iOS.

الفئات المعمارية الأساسية في تعريفات API لحزمة تطوير برمجيات الإحالة

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

تعرض مكتبات العميل لإحالة الأجهزة المحمولة والروابط العميقة واجهات برمجة تطبيقات (APIs) مصممة للتعامل مع مراحل مميزة من دورة حياة المستخدم. بدلاً من العمل كفئات خدمات أحادية، تقسم حزمة تطوير برمجيات الإحالة المسؤوليات البرمجية إلى ثلاث فئات وظائف رئيسية:

• واجهات برمجة تطبيقات استيعاب المعاملات المؤجلة: تعمل طرق مثل getInstallParam على نظام Android و getInstallParmsCompleted على نظام iOS بشكل أساسي أثناء عملية الإعداد الأولية للتطبيق بعد التثبيت. ونظراً لأن معاملات تصفح الويب العشوائية لا تتجاوز حدود تثبيت المتجر بشكل افتراضي، تستعلم واجهات برمجة التطبيقات المؤجلة عن ذاكرات التخزين المؤقت للعميل ونقاط نهاية الإحالة الخلفية لاستعادة البيانات الوصفية السياقية (مثل معرفات المُحيل، أو رموز الإحالة، أو معاملات الحملة) المرتبطة بالنقر الذي سبقه التثبيت.
• واجهات برمجة تطبيقات اعتراض الروابط في الوقت الفعلي: تعمل طرق مثل handleDeepLink على نظام Android و getWakeUpParams على نظام iOS عندما يكون التطبيق مثبتًا بالفعل على نظام التشغيل المُضيف. تتصل واجهات برمجة التطبيقات هذه ببروتوكولات النظام الأصلي - وتحديداً Apple Universal Links، و Android App Links، ومخططات عناوين URL المخصصة - لالتقاط معاملات URI في الوقت الفعلي عندما يؤدي رابط ويب خارجي أو تطبيق ثانوي إلى تشغيل التطبيق.
• واجهات برمجة تطبيقات إحالة أحداث ما بعد التثبيت: تتيح طرق الإبلاغ من جانب العميل - مثل saveEvent على نظام Android و reportEffectPoint على نظام iOS - للتطبيقات العميل الإبلاغ عن مراحل المستخدم اللاحقة إلى خوادم تجميع الإحالة. تتيح هذه الاستدعاءات تدقيق العائد على الإنفاق التسويقي (ROAS) بدقة، وتتبع الاحتفاظ بالشرائح، وتحليل الحلقات الفيروسية من خلال ربط إجراءات التحويل داخل التطبيق بمعاملات التثبيت السابقة.

دور الاستدعاءات غير المتزامنة في منع حظر خيط بدء التشغيل البارد للتطبيق

تفرض أنظمة تشغيل الأجهزة المحمولة عتبات أداء صارمة أثناء بدء تشغيل التطبيق. ففي نظام Android، يؤدي تنفيذ عمليات الشبكة المتزامنة على الخيط الرئيسي إلى طرح استثناء NetworkOnMainThreadException، بينما يمكن لأي عمل متزامن مطول - بما في ذلك حظر إدخال/إخراج القرص - تجميد خيط واجهة المستخدم والمساهمة في أخطاء عدم استجابة التطبيق (ANR). وفي نظام iOS، يقوم مؤقت مراقبة نظام التشغيل إنهاء العمليات التي تحظر الخيط الرئيسي لفترات طويلة أثناء التهيئة.

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

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

التمييز بين واجهات برمجة تطبيقات حزمة تطوير البرمجيات من جانب العميل واجهات التبادل من خادم إلى خادم

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

• واجهات برمجة تطبيقات حزمة تطوير البرمجيات من جانب العميل: يتم تجميدها مباشرة في الملف الثنائي للهاتف المحمول (على سبيل المثال، عبر أطر عمل CocoaPods أو تبعيات Maven AAR)، وتتفاعل هذه الواجهات مع إمكانيات الجهاز الأصلية. وهي تستمع إلى إشعارات دورة حياة التطبيق، وتحلل نوايا النظام الواردة، وتقرأ ملفات التكوين، وتوفر كائنات الذاكرة مباشرة لوحات تحكم عرض التطبيق للتوجيه الديناميكي.
• واجهات التبادل من خادم إلى خادم (S2S): تُنفذ بالكامل عبر البنية التحتية للخادم الخلفي، وتتكون واجهات S2S من نقاط نهاية HTTP REST التي تنقل تبادلات التحويل بين منصات الإحالة وشبكات التسويق. وبحسب المزود، قد تستخدم اتصالات S2S نقاط نهاية HTTPS مصادق عليها، أو رموز حمولة موقعة، أو شهادات متبادلة (mTLS)، أو ضوابط وصول الشبكة لضمان السلامة بشكل مستقل عن حالات تنفيذ جهاز العميل.

كيف تعمل ميكانيكا استعلام الروابط العميقة المؤجلة في getInstallParam؟

نافذة الإحالة المؤجلة: استرداد المعاملات المُخزنة مؤقتاً عند التشغيل الأول

تعالج الروابط العميقة المؤجلة فجوة معمارية أساسية في توزيع برمجيات الأجهزة المحمولة: إذ لا تحتفظ متاجر تطبيقات نظام التشغيل القياسية بسلاسل استعلام عناوين URL العشوائية عبر سير عمل التنزيل والتثبيت. وفي حين أن الآليات الخاصة بالمنصة مثل Google Play Install Referrer يمكنها تمرير سياق الحملة المدعومة من خلال تنزيلات المتجر، فإن معاملات استعلام الويب العامة (على سبيل المثال، https://example.com/invite?channelCode=affiliate_01&inviter_id=user_9876) لا تتجاوز تلقائياً حدود متجر التطبيقات.

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

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

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

تحليل getInstallParam: حمولة المعاملات، وكود القناة، واستجابة الحالة

يلخص كائن البيانات الذي يُرجعه استدعاء التثبيت المؤجل تدفقين مختلفين للبيانات إلى جانب علامات الحالة التشغيلية:

• المعاملات الديناميكية المخصصة (data): حاوية بيانات منظمة تحتوي على سلاسل الاستعلام المحددة بواسطة المطور والتي تم تمريرها إلى رابط الحملة الأصلي. يحمل هذا الحقل سياقاً تجارياً خاصاً بالحملة، مثل معرفات خصم الإحالة، أو لغات المستخدم المفضلة، أو معرفات محتوى محددة.
• معامل تحديد القناة (channelCode): عند توفره، يتم الكشف عن channelCode كمعرف قناة يشبه السلسلة يشير إلى المصدر التسويقي أو شريك شبكة الإعلانات. في عمليات التثبيت العضوية التي لم يتم فيها التعامل مع رابط قناة، قد يتم حل هذا المعامل كقيمة فارغة (null) أو فارغة اعتماداً على ربط حزمة تطوير البرمجيات للمنصة.
• النتيجة التشغيلية والأخطاء: بدلاً من الاعتماد على رموز أعداد صحيحة عامة صارمة، يتم توصيل الأخطاء ومهل الانتظار من خلال نماذج أخطاء خاصة بالمنصة (مثل OpoError على Android أو استدعاءات الأخطاء على iOS). يوفر الاستدعاء هياكل أخطاء وصفية عندما يفشل اتصال الشبكة أو تحدث عدم تطابقات في التكوين.

التعامل مع حالات انتهاء المهلة: فهم دورات الانتظار وعلامات إعادة المحاولة الديناميكية

غالباً ما تبدأ التطبيقات المحمولة في بيئات اتصال متدهورة، مثل شبكات النقل تحت الأرض أو نقاط وصول Wi-Fi العامة المزدحمة. وإذا تعذر على حزمة تطوير البرمجيات الوصول إلى عناقيد الإحالة الخلفية فوراً، فلا يجب أن يؤدي جلب المعاملات إلى تعليق منطق التطبيق.

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

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

إعادة توجيه الروابط العميقة في الوقت الفعلي وتحليل الاستدعاء في getWakeUpParams

اعتراض أحداث التشغيل البارد وفي الخلفية عبر بروتوكولات النظام

عندما يكون التطبيق موجوداً بالفعل على جهاز المستخدم، تتجاوز النقرات الخارجية عمليات تثبيت المتجر تماماً. تستخدم منصات الأجهزة المحمولة الحديثة معايير توجيه مخصصة - مثل Universal Links على نظام iOS و Android App Links على نظام Android - لنقل التنفيذ من المتصفحات الخارجية مباشرة إلى التطبيق الأصلي المثبت.

يرسل نظام التشغيل أحداث التشغيل هذه من خلال طرق مندوب التطبيق المحددة:

• دورات حياة iOS: بالنسبة للتطبيقات التي تستخدم بنى النوافذ الحديثة، تصل الروابط العالمية عبر scene:continueUserActivity: داخل SceneDelegate (أو scene:willConnectToSession:options: أثناء الاتصال الأولي بالمشهد). في التطبيقات التي لا تستخدم مناديب المشهد، يرسل نظام التشغيل عبر application:continueUserActivity:restorationHandler: داخل AppDelegate. تستدعي مخططات عناوين URL المخصصة application:openURL:options: أو scene:openURLContexts:. يجب تكييف طرق إعادة توجيه حزمة تطوير البرمجيات المعروضة في AppDelegate مع دورة حياة UIScene الفعلية للتطبيق عند تمكين المشاهد.
• دورات حياة Android: تستدعي النوايا الواردة onCreate(Bundle) إذا لم يكن النشاط المستهدف نشطاً في الذاكرة، أو onNewIntent(Intent) إذا كان النشاط يعمل تحت تكوين وضع تشغيل singleTask أو singleTop.

تعمل واجهة برمجة التطبيقات للاستدعاء getWakeUpParams (ونظيرتها في Android handleDeepLink) كمستمع مركزي يستقبل ويتحقق من ويفك تشكيل معاملات URI الديناميكية المسلمة عبر خطافات دورة حياة نظام التشغيل هذه.

تحليل حمولة getWakeUpParams أثناء إعادة توجيه الروابط العالمية ومخططات عناوين URL

عند اعتراض حدث تشغيل النظام، تستخرج حزمة تطوير البرمجيات سلسلة عنوان URL الواردة، وتفك تشفير مكونات الاستعلام المشفرة بـ URI، وتطبيع الحمولة إلى نموذج بيانات متسق.

يوفر توقيع الاستدعاء إمكانية الوصول إلى كل من channelCode و data. على سبيل المثال، إذا كان رابط حملة التجارة الإلكترونية مهيكلاً كـ https://app.example.com/shoes/running?promo_code=SUMMER20&item_id=sku_456 يطلق تشغيل التطبيق، فإن الاستدعاء يستخرج promo_code و item_id، ويقوم بتعبئتها في حمولة الاستدعاء ليستهلكها منطق عرض التطبيق.

استعادة المشهد الديناميكي داخل التطبيق: تعيين مفاتيح حمولة JSON إلى وحدات العرض / الأنشطة المستهدفة

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

يتطلب تحقيق استعادة موثوقة للمشهد إنشاء موجه حتمي داخل بنية التطبيق:

• الخطوة 1: استخراج مفتاح الحمولة: داخل مستمع الاستدعاء، يفحص التطبيق حمولة data بحثاً عن مفاتيح توجيه متفق عليها مسبقاً، مثل target_screen أو resource_id.
• الخطوة 2: التحقق من القيم الفارغة والنوع: يتحقق الموجه من وجود القيم، ومطابقتها للأنواع البدائية المتوقعة، وتوافقها مع ميزات التطبيق النشطة.
• الخطوة 3: تنفيذ وحدة تحكم التنقل: يحلس التطبيق التسلسل الهرمي للتنقل الجذر الحالي ويدفع أو يعرض وحدة تحكم العرض المستهدفة المناسبة أو نية النشاط (Activity).

ضمان التنفيذ الفعّال في حالات تشغيل دورة الحياة المكررة

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

ولمنع انتقالات العرض الزائدة أو تسجيل التحليلات المكررة، يجب أن تفرض موجهات التطبيق تنفيذاً مُتطابقاً (Idempotent). يجب على المطورين الاحتفاظ بسجل في الذاكرة لمعرفات الأحداث التي تمت معالجتها أو تجزئة حمولة مطبعة محددة بنطاق نافذة إزالة تكرار قصيرة، مع تجاهل الحمولات الواردة التي تتطابق توقيعاتها مع حدث تنقل مكتمل بالفعل.

توقيعات طرق المنصة المزدوجة لعمليات دمج Android و iOS

توقيعات طرق Android: واجهات ResultCallBack بلغة Kotlin وخطافات دورة حياة النشاط

في تطوير عملاء Android، تعرض حزمة تطوير برمجيات الإحالة واجهات غير متزامنة منظمة حول واجهات الاستدعاء. وبدلاً من حظر خيط الاستدعاء، تقبل استدعاءات الطرق تطبيقاً لـ ResultCallBack<T>.

يمكن للمطورين تنزيل حزمة تنزيل حزمة تطوير برمجيات OpoInstall للوصول إلى الملفات الثنائية للمكتبة الأصلية، وتوزيعات Maven، وتعريفات قواعد الاحتفاظ بـ ProGuard.

تتضمن توقيعات واجهة برمجة تطبيقات Android الأساسية:

• التهيئة: OpoInstall.initialize(Application application)
• بدء دورة الحياة: OpoInstall.getInstance().start(Activity activity)
• استرداد المعاملات المؤجلة: OpoInstall.getInstance().getInstallParam(ResultCallBack<OpoData> callBack)
• تحليل نية الرابط العميق: OpoInstall.getInstance().handleDeepLink(Intent intent, ResultCallBack<OpoData> callBack)
• إحالة الأحداث المخصصة: OpoInstall.getInstance().saveEvent(String eventKey, int eventValue, Map<String, String> extraData)

توقيعات طرق iOS: التوافق مع بروتوكول OpoInstallDelegate بلغة Swift و Objective-C

على منصات iOS، تستخدم بنية حزمة تطوير البرمجيات نمط تصميم التفويض (Delegation) إلى جانب إغلاق معالج الاكتمال. يتوافق مندوب التطبيق مع OpoInstallDelegate ويسجل نفسه أثناء تهيئة إطار العمل.

تتضمن توقيعات طرق iOS الأساسية:

• تهيئة حزمة تطوير البرمجيات: OpoInstallSDK.initWith(self)
• خطاف الاستيقاظ في الوقت الفعلي: func getWakeUpParams(_ appData: OpoinstallData?)
• استرداد معاملات التثبيت المؤجل: OpoInstallSDK.defaultManager()?.getInstallParmsCompleted { appData in ... }
• تتبع الأحداث المخصصة: OpoInstallSDK.defaultManager()?.reportEffectPoint("purchase", effectValue: 100, effectDictionary: ["currency": "USD"])
• تفويض توجيه الروابط العالمية: OpoInstallSDK.continue(userActivity)

ملاحظة توافق واجهة برمجة التطبيقات: تعكس هذه الأمثلة أنماط دمج OpoInstall المُوثّقة علناً. يسرد مركز تنزيل حزمة تطوير البرمجيات حالياً إصدارات Android و iOS v2.1.0. تحقق من أسماء الحزم الدقيقة، وتوقيعات الطرق، والأنواع القابلة للقيم الفارغة، واجهات الاستدعاء مقابل أرشيف حزمة تطوير البرمجيات الذي تم تنزيله قبل الاستخدام في الإنتاج. لم يتم اختبار تجميع الأمثلة بشكل مستقل مقابل هذا الأرشيف.

// Android - MainActivity.kt
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
import org.json.JSONObject

// أداة التطبيع المملوكة للتطبيق (أداة التطبيق المُضيف)
// تتحقق من كائنات بيانات SDK الخام بأمان إلى سلاسل JSON مطبعة
fun normalizePayload(rawData: Any?): String? = when (rawData) {
    is String -> rawData
    is JSONObject -> rawData.toString()
    is Map<*, *> -> runCatching {
        // فرض قيود المفاتيح المستندة إلى السلسلة قبل التفويض إلى JSONObject
        if (rawData.keys.any { it !is String }) {
            null
        } else {
            val sanitizedMap = mutableMapOf<String, Any?>()
            rawData.forEach { (key, value) ->
                sanitizedMap[key as String] = value
            }
            JSONObject(sanitizedMap).toString()
        }
    }.getOrNull()
    else -> null
}

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // يفترض أن OpoInstall.initialize(this) قد اكتمل بالفعل في Application.onCreate()
        OpoInstall.getInstance().start(this)

        // 1. الاستعلام عن معاملات التثبيت المؤجل
        OpoInstall.getInstance().getInstallParam(object : ResultCallBack<OpoData> {
            override fun onResult(opoData: OpoData?) {
                val customData: String? = normalizePayload(opoData?.data)
                val channel: String? = opoData?.channelCode
                
                // تسجيل الحالة منزوعة التحسس دون طباعة المستخدم الخام أو حمولة الإحالة
                Log.d("OpoInstall", "Install params received: hasData=${!customData.isNullOrBlank()}, channelPresent=${!channel.isNullOrBlank()}")

                // التأكد من إرسال العمليات الخاصة بواجهة المستخدم إلى خيط واجهة المستخدم الرئيسي
                runOnUiThread {
                    // توجيه واجهة المستخدم للتطبيق المُضيف أو منطق العرض
                }
            }

            override fun onError(error: OpoError?) {
                // تسجيل مؤشر الخطأ المطهر دون إخراج سلاسل النظام الحساسة
                Log.w("OpoInstall", "getInstallParam callback encountered an error status")
            }
        })

        // 2. معالجة الروابط العميقة الواردة في الوقت الفعلي
        handleIntent(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleIntent(intent)
    }

    private fun handleIntent(intent: Intent?) {
        intent?.let {
            OpoInstall.getInstance().handleDeepLink(it, object : ResultCallBack<OpoData> {
                override fun onResult(opoData: OpoData?) {
                    val customData: String? = normalizePayload(opoData?.data)
                    Log.d("OpoInstall", "DeepLink params received: hasData=${!customData.isNullOrBlank()}")
                    runOnUiThread {
                        // منطق توجيه الرابط العميق للتطبيق المُضيف
                    }
                }

                override fun onError(error: OpoError?) {
                    Log.w("OpoInstall", "handleDeepLink callback encountered an error status")
                }
            })
        }
    }
}

// iOS - AppDelegate.swift
import UIKit
import libOpoInstallSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        // 1. تهيئة حزمة تطوير برمجات OpoInstall مع مستمع المندوب
        OpoInstallSDK.initWith(self)

        // 2. الاستعلام عن معاملات التثبيت المؤجل
        OpoInstallSDK.defaultManager()?.getInstallParmsCompleted { appData in
            let customData = appData?.data
            let channel = appData?.channelCode
            
            // تسجيل الحالة منزوعة التحسس دون طباعة الحمولة المخصصة الخام
            print("OpoInstall: Deferred parameters received (hasData: \(customData != nil), channelPresent: \(channel != nil))")

            // إرسال عمليات واجهة المستخدم بشكل صريح إلى قائمة الانتظار الرئيسية
            DispatchQueue.main.async {
                // منطق عرض واجهة المستخدم للتطبيق المُضيف
            }
        }

        return true
    }

    // 3. استدعاء اعتراض معاملات الرابط العميق في الوقت الفعلي
    func getWakeUpParams(_ appData: OpoinstallData?) {
        let customData = appData?.data
        let channel = appData?.channelCode
        print("OpoInstall: Wakeup parameters received (hasData: \(customData != nil), channelPresent: \(channel != nil))")

        DispatchQueue.main.async {
            // منطق توجيه الرابط العميق للتطبيق المُضيف
        }
    }

    // ملاحظة: إذا كنت تستخدم دورات حياة قائمة على المشهد (UIScene)، فقم بإعادة توجيه الروابط العالمية والمخططات
    // من SceneDelegate عبر scene:continueUserActivity: و scene:openURLContexts:.
    // راجع العنوان العام لإصدار SDK الخاص بك للتحقق مما إذا كان continue/handLinkURL يُرجِع
    // قيمة منطقية تشير إلى ما إذا كان محرك الإحالة قد تعامل مع عنوان URL الوارد.
    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
    }
}

هياكل حمولة JSON وتعيين قاموس المعاملات

نموذج الحمولة المفاهيمية القانونية

على المستوى المفاهيمي، تطبيع استدعاءات الإحالة البيانات الوصفية التسويقية الواردة في هيكل مفتاح-قيمة يحتوي على إحالة القناة وحمولات الحملة المحددة من قبل المطور.

ملاحظة حدود المخطط: هذا مخطط تطبيع توضيحي ومملوك للتطبيق، وليس عقداً رسمياً لتنسيق أسلاك OpoInstall أو كائن إرجاع SDK.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ConceptualAttributionPayload",
  "type": "object",
  "properties": {
    "channelCode": {
      "type": ["string", "null"],
      "description": "معرف القناة التسويقية أو مصدر التوزيع؛ فارغ أو فارغ إذا كان عضوياً."
    },
    "data": {
      "type": ["object", "string", "null"],
      "description": "حمولة محددة بواسطة المطور تحتوي على معاملات توجيه ديناميكية، أو رموز إحالة، أو مفاتيح ترقية."
    }
  }
}

ربط البيانات الخاصة بالمنصة: سلسلة Android مقابل قاموس iOS

في حين تظل الحمولة المفاهيمية متسقة، تعرض ارتباطات حزمة تطوير البرمجيات الأصلية البيانات data بشكل مختلف وفقاً لاتفاقيات المنصة:

• ربط Android SDK: تُرجع خاصية OpoData.data كـ String? JSON مُسلسل قابل للقيم الفارغة (أو Any? اعتماداً على إصدار AAR). إذا تم كتابتها كـ سلسلة (على سبيل المثال، "{\"inviterId\":\"1024\",\"roomCode\":\"8899\"}")، يقوم المطور بتحليل هذه السلسلة إلى JSONObject أو تعيينها باستخدام أداة إلغاء تسلسل مثل Gson أو Moshi. وإذا أُرجعت كـ كائن غير مكتوب، فاستخدم مساعد تطبيع خاضع للتحكم قبل التحليل. يتم كشف channelCode مباشرة كـ String? قابل للقيم الفارغة.
• ربط iOS SDK: تظهر خاصية OpoinstallData.data كمجموعة قاموس أصلية (أو كائن خاص بالإصدار). يصل المطورون إلى القيم مباشرة باستخدام اشتراك مفتاح القاموس. يتم كشف channelCode كـ String? قابل للقيم الفارغة.

التسلسل الآمن: حماية منطق التنقل الديناميكي ضد استثناءات المؤشر الفارغ (Null Pointer Exceptions)

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

يتطلب استخراج المعاملات الدفاعي اتباع خط أنابيب تحقق صارم:

• القاعدة 1: الحراسة دائماً ضد القيم الفارغة: تحقق من وجود data و channelCode قبل تمريرهما إلى خدمات التطبيق اللاحقة.
• القاعدة 2: التقاط استثناءات تحليل JSON: في نظام Android، قم بلف عمليات إنشاء JSONObject(data) في كتل try-catch صريحة لالتقاط JSONException.
• القاعدة 3: فرض احتياطيات التوجيه الافتراضية: إذا نجح التحليل ولكن مفتاح توجيه معين (مثل target_sku) غائب، فارجع بأناقة إلى شاشة هبوط التطبيق الافتراضية بدلاً من إيقاف التنفيذ.

كيفية التعامل مع رموز حالة انتهاء المهلة ومنطق إعادة المحاولة غير المتزامن

التعامل مع استجابات انتهاء المهلة والأخطاء

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

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

تنفيذ إدارة حالة التطبيق المُضيف لتجنب الاستعلامات الزائدة

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

ملاحظة التنفيذ: المقتطف التالي هو جزء من التعليمات البرمجية الزائف للتطبيق المُضيف؛ يمثل processReferralPayload منطق الأعمال المحدد من قبل التطبيق. في نظام الإنتاج الذي يوزع المكافآت أو الحوافز المالية، اعتمد على الرموز المتطابقة المؤكدة من الخادم بدلاً من علامات الجهاز المحلية وحدها.

// Android - إدارة حالة تنفيذ الإحالة في SharedPreferences
val prefs = getSharedPreferences("app_prefs", Context.MODE_PRIVATE)
val isAttributionHandled = prefs.getBoolean("attribution_handled", false)

if (!isAttributionHandled) {
    OpoInstall.getInstance().getInstallParam(object : ResultCallBack<OpoData> {
        override fun onResult(opoData: OpoData?) {
            // تطبيع الحمولة بطريقة دفاعية باستخدام مساعد التطبيع المشترك
            val customData: String? = normalizePayload(opoData?.data)
            
            if (!customData.isNullOrEmpty()) {
                // تنفيذ التطبيق المُضيف: تحليل الحمولة المخصصة والتوجيه بشكل مناسب
                processReferralPayload(customData)
                
                // تسجيل معالجة الإحالة لمنع عمليات التنفيذ المكررة
                prefs.edit().putBoolean("attribution_handled", true).apply()
            }
        }
        override fun onError(error: OpoError?) {
            // التعامل مع انتهاء المهلة أو فشل الاتصال؛ تظل العلامة خطأ للسماح بإعادة المحاولة اللاحقة
            Log.w("OpoInstall", "Deferred retrieval error status observed")
        }
    })
}

سلامة الخيوط وقواعد تنفيذ واجهة المستخدم

يجب ألا يفترض المطورون تقارب خيط الاستدعاء ما لم يتم توثيقه صراحة لإصدار SDK المُشرّع. لضمان انتقالات واجهة مستخدم خالية من الأعطال وسلامة الخيوط، قم بإرسال التنقل في واجهة المستخدم أو تحديثات العرض صراحة إلى الخيط الرئيسي (باستخدام DispatchQueue.main.async على iOS أو runOnUiThread / Coroutine dispatchers على Android).

يضمن إرسال الخيوط الصريح تحديث مربعات حوار التنبيه، أو الأجزاء (Fragments)، أو وحدات تحكم العرض بأمان بغض النظر عن نموذج الترابط الداخلي الذي يستخدمه إصدار SDK.

تجنب ظروف سباق التهيئة في دورات حياة التطبيق

يجب على المطورين اتباع دورة حياة التهيئة المُوثّقة لـ SDK وتجنب استدعاء استعلامات المعاملات قبل اكتمال التهيئة أو قبل حدوث إعداد دورة الحياة المطلوبة.

يفرض نمط الدمج المُوصى به فصل دورة الحياة:

• مرحلة التهيئة: تنفيذ OpoInstall.initialize(this) داخل طريقة Application.onCreate() المخصصة على Android، أو OpoInstallSDK.initWith(self) داخل application(_:didFinishLaunchingWithOptions:) على iOS.
• مرحلة التنفيذ: استدعاء start(this) و getInstallParam(...) داخل النشاط المُشغِّل الأساسي Activity.onCreate() على Android.

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

تحليل مقارن لتعريفات API لحزمة تطوير برمجيات الإحالة الأساسية

الفروق المنهجية عبر واجهات حزمة تطوير برمجيات الإحالة

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

يقارن الجدول أدناه أنماط API الأساسية المدعومة بأمثلة الدمج المتاحة للعموم. تظل التوقيعات الدقيقة معتمدة على الإصدار:

ملاحظة اتفاقية الاستدعاء: توفر واجهات برمجة التطبيقات هذه إمكانيات روابط عميقة مقابلة، لكن Android يستخدم استدعاء طريقة SDK صريح (handleDeepLink) بينما يكشف iOS عن النتيجة من خلال استدعاء مندوب (getWakeUpParams).

قدرات SDK إضافية: قد يتم الكشف عن تقارير التسجيل وإحالة مشاركة الإحالة من خلال واجهات برمجة تطبيقات خاصة بالإاصدار. راجع الرؤوس العامة أو تعريفات واجهة SDK الموزعة مع إصدارك المُشرّع قبل استدعاء هذه الطرق.

الملخص وإطار القرار

يتيح إتقان تعريفات واجهة برمجة التطبيقات (API) لحزمة تطوير برمجيات الإحالة لفرق الهندسة المحمولة بناء رحلات إعداد موثوقة وتتبع تحليلات القناة. ومن خلال فهم الفرق بين استعلامات التثبيت المؤجل (getInstallParam / getInstallParmsCompleted) واعتراض الروابط في الوقت الفعلي (getWakeUpParams / handleDeepLink)، يمكن للمطورين تقليل فقدان المعاملات وتنفيذ توجيه الصفحات الديناميكي.

ومع قيام أنظمة تشغيل الأجهزة المحمولة بتحسين قيود مهام الخلفية ومربعات رمل خصوصية الشبكة، فإن الاعتماد على توقيعات API المُعرّفة جيداً لـ SDK يضمن التعامل مع البيانات بشكل متسق عبر إصدارات Android و iOS. الالتزام بإرشادات سلامة الخيوط، وإدارة استمرارية الحالة المحلية، ومعالجة شروط انتهاء المهلة غير المتزامنة يدعم عمليات إطلاق تطبيقات مستقرة.

يمكن للمطورين المستعدين لدمج تعريفات API هذه في مشروعهم التسجيل على وحدة تحكم مطوري OpoInstall أو الرجوع إلى مرجع تنفيذ إحالة الأجهزة المحمولة للحصول على إرشادات المنصة الكاملة.

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

• المفاهيم: تعريف API، الروابط العميقة المؤجلة، معاملات التتبع، تعيين حمولة JSON

• التقنيات: حزمة تطوير برمجيات Android، حزمة تطوير برمجيات iOS، الروابط العالمية (Universal Links)، مخططات عناوين URL، الاستدعاءات غير المتزامنة

• المعايير: مسودة مخطط JSON 2020-12، دورة حياة نشاط Android، دورة حياة UIScene في Apple

• واجهات برمجة التطبيقات: واجهة برمجة تطبيقات OpoInstall getInstallParam، واجهة برمجة تطبيقات OpoInstall getWakeUpParams، واجهة برمجة تطبيقات OpoInstall saveEvent

• التوثيق الرسمي المراجع &:

  • إرشادات مطوري Apple حول دعم الروابط العالمية في تطبيقك

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

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

  • مرجع مطوري Google Android حول دورة حياة النية (Intent)

  • وثائق دمج حزمة تطوير برمجيات OpoInstall

  • مركز تنزيل حزمة تطوير برمجيات OpoInstall