اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تنفيذ شريحة eSIM

تتيح تكنولوجيا شريحة SIM المضمّنة (eSIM أو eUICC) لمستخدمي الأجهزة الجوّالة تنزيل ملف شخصي لمشغّل شبكة الجوّال وتفعيل خدمة المشغّل بدون الحاجة إلى شريحة SIM فعلية. وهي مواصفات عالمية وضعتها جمعية GSMA تتيح توفير شرائح SIM عن بُعد لأي جهاز جوّال. بدءًا من الإصدار 9 من نظام التشغيل Android، يوفّر إطار عمل Android واجهات برمجة تطبيقات عادية للوصول إلى شريحة eSIM وإدارة ملفات الاشتراك على شريحة eSIM. تتيح واجهات برمجة التطبيقات الخاصة بمنصة eUICC للجهات الخارجية تطوير تطبيقات مشغّلي شبكات الجوّال ومساعدي الملفات الشخصية المحلية (LPAs) على أجهزة Android المتوافقة مع شرائح eSIM.

إنّ LPA هو تطبيق نظام مستقل يجب تضمينه في صورة إصدار Android. تتولّى عادةً LPA إدارة الملفات الشخصية على شريحة eSIM، لأنّها تعمل كجسر بين SM-DP+ (خدمة عن بُعد تُعدّ حِزم الملفات الشخصية وتخزّنها وتسلّمها إلى الأجهزة) وشريحة eUICC. يمكن أن يتضمّن حِزمة APK الخاصة بـ LPA اختياريًا أحد مكونات واجهة المستخدم، يُطلق عليه اسم واجهة مستخدم LPA أو LUI، وذلك لتوفير مكان مركزي للمستخدم النهائي لإدارة جميع ملفات الاشتراك المضمّنة. يكتشف إطار عمل Android تلقائيًا أفضل تطبيق LPA متاح ويتصل به، كما يوجّه جميع عمليات eUICC من خلال مثيل LPA.

بنية Remote SIM Provisioning (RSP) المبسَّطة

الشكل 1. بنية RSP مبسطة

على مشغّلي شبكات الجوّال المهتمين بإنشاء تطبيق مشغّل شبكة الجوّال الاطّلاع على واجهات برمجة التطبيقات في EuiccManager، التي توفّر عمليات إدارة الملفات الشخصية ذات المستوى العالي، مثل downloadSubscription() وswitchToSubscription() وdeleteSubscription().

إذا كنت من مصنّعي الأجهزة الأصلية المهتمين بإنشاء تطبيق نظام LPA خاص بك، عليك توسيع EuiccService لنظام Android الأساسي من أجل الاتصال بخدمات LPA. بالإضافة إلى ذلك، يجب استخدام واجهات برمجة التطبيقات في EuiccCardManager، والتي توفّر وظائف ES10x استنادًا إلى GSMA RSP v2.0. تُستخدَم هذه الدوال لإصدار أوامر لشريحة eUICC، مثل prepareDownload() وloadBoundProfilePackage() وretrieveNotificationList() وresetMemory().

تتطلّب واجهات برمجة التطبيقات في EuiccManager تطبيق LPA تم تنفيذه بشكل صحيح لكي تعمل، ويجب أن يكون المتصل بواجهات برمجة التطبيقات EuiccCardManager هو تطبيق LPA. يتم فرض ذلك من خلال إطار عمل Android.

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

إنشاء تطبيق مشغّل شبكة جوّال

تتيح واجهات برمجة تطبيقات eUICC في Android 9 لمشغّلي شبكات الجوّال إنشاء تطبيقات تحمل العلامة التجارية للمشغّل لإدارة الملفات الشخصية مباشرةً. ويشمل ذلك تنزيل ملفات الاشتراك وحذفها التي يملكها مشغّل شبكة الجوّال، بالإضافة إلى التبديل إلى ملف يملكه مشغّل شبكة الجوّال.

EuiccManager

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

لاستخدام واجهات برمجة التطبيقات العامة، يجب أن يحصل تطبيق مشغّل شبكة الجوّال أولاً على مثيل EuiccManager من خلال Context#getSystemService:

EuiccManager mgr = (EuiccManager) context.getSystemService(Context.EUICC_SERVICE);

يجب التحقّق مما إذا كانت شريحة eSIM متوافقة مع الجهاز قبل إجراء أي عمليات متعلقة بشريحة eSIM. تعرض الدالة EuiccManager#isEnabled() عادةً القيمة true إذا كانت ميزة android.hardware.telephony.euicc محدّدة وكانت حزمة LPA متوفّرة.

if (mgr == null || !mgr.isEnabled()) {
    return;
}

للحصول على معلومات حول جهاز eUICC وإصدار نظام التشغيل لشريحة eSIM، اتّبِع الخطوات التالية:

EuiccInfo info = mgr.getEuiccInfo();
String osVer = info.getOsVersion();

تستخدم العديد من واجهات برمجة التطبيقات، مثل downloadSubscription() وswitchToSubscription()، عمليات معاودة الاتصال PendingIntent لأنّها قد تستغرق ثوانٍ أو حتى دقائق حتى تكتمل. يتم إرسال PendingIntent مع رمز نتيجة في المساحة EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_، ما يوفّر رموز خطأ محدّدة في إطار العمل، بالإضافة إلى رمز نتيجة تفصيلي عشوائي يتم نشره من LPA كـ EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE، ما يتيح لتطبيق مشغّل شبكة الجوّال تتبُّع الأخطاء لأغراض التسجيل/تصحيح الأخطاء. يجب أن يكون PendingIntent معرّف معاودة الاتصال BroadcastReceiver.

لتنزيل اشتراك قابل للتنزيل (تم إنشاؤه من خلال رمز تفعيل أو رمز استجابة سريعة):

// Register receiver.
static final String ACTION_DOWNLOAD_SUBSCRIPTION = "download_subscription";
static final String LPA_DECLARED_PERMISSION
    = "com.your.company.lpa.permission.BROADCAST";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);

                // If the result code is a resolvable error, call startResolutionActivity
                if (resultCode == EuiccManager.EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR) {
                    PendingIntent callbackIntent = PendingIntent.getBroadcast(
                        getContext(), 0 /* requestCode */, intent,
                        PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_MUTABLE);
                    mgr.startResolutionActivity(
                        activity,
                        0 /* requestCode */,
                        intent,
                        callbackIntent);
                }

                resultIntent = intent;
            }
        };
context.registerReceiver(receiver,
        new IntentFilter(ACTION_DOWNLOAD_SUBSCRIPTION),
        LPA_DECLARED_PERMISSION /* broadcastPermission*/,
        null /* handler */);

// Download subscription asynchronously.
DownloadableSubscription sub = DownloadableSubscription
        .forActivationCode(code /* encodedActivationCode*/);
Intent intent = new Intent(action).setPackage(context.getPackageName());
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent,
        PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_MUTABLE);
mgr.downloadSubscription(sub, true /* switchAfterDownload */,
        callbackIntent);

حدِّد الإذن واستخدِمه في AndroidManifest.xml:

    <permission android:protectionLevel="signature" android:name="com.your.company.lpa.permission.BROADCAST" />
    <uses-permission android:name="com.your.company.lpa.permission.BROADCAST"/>

للانتقال إلى اشتراك باستخدام رقم تعريف الاشتراك، اتّبِع الخطوات التالية:

// Register receiver.
static final String ACTION_SWITCH_TO_SUBSCRIPTION = "switch_to_subscription";
static final String LPA_DECLARED_PERMISSION
    = "com.your.company.lpa.permission.BROADCAST";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver,
        new IntentFilter(ACTION_SWITCH_TO_SUBSCRIPTION),
        LPA_DECLARED_PERMISSION /* broadcastPermission*/,
        null /* handler */);

// Switch to a subscription asynchronously.
Intent intent = new Intent(action).setPackage(context.getPackageName());
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent,
        PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_MUTABLE);
mgr.switchToSubscription(1 /* subscriptionId */, callbackIntent);

للاطّلاع على قائمة كاملة بواجهات برمجة التطبيقات EuiccManager وأمثلة على الرموز البرمجية، يُرجى الانتقال إلى واجهات برمجة تطبيقات eUICC.

الأخطاء القابلة للحل

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

في هذه الحالات، يتم استدعاء دالة معاودة الاتصال الخاصة بالمتصل مع EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR. يحتوي برنامج معالجة الردود Intent على بيانات إضافية داخلية، وبالتالي عندما يمرّر المتصل هذه البيانات إلى EuiccManager#startResolutionActivity، يمكن طلب حلّ المشكلة من خلال واجهة المستخدم المحلية (LUI). باستخدام رمز التأكيد كمثال مرة أخرى، يؤدي إدخال EuiccManager#startResolutionActivity إلى ظهور شاشة واجهة مستخدم محدودة، ما يتيح للمستخدم إدخال رمز التأكيد، وبعد إدخال الرمز، يتم استئناف عملية التنزيل. يمنح هذا الأسلوب تطبيق مشغّل شبكة الجوّال إمكانية التحكّم الكامل في وقت عرض واجهة المستخدم، ولكنّه يوفّر لواجهة برمجة التطبيقات LPA/LUI طريقة قابلة للتوسيع لإضافة معالجة جديدة للمشاكل التي يمكن للمستخدم حلّها في المستقبل بدون الحاجة إلى تغيير تطبيقات العميل.

يحدّد نظام التشغيل Android 9 الأخطاء القابلة للحل في EuiccService، التي يجب أن يتعامل معها واجهة المستخدم المحلية (LUI):

/**
 * Alert the user that this action will result in an active SIM being
 * deactivated. To implement the LUI triggered by the system, you need to define
 * this in AndroidManifest.xml.
 */
public static final String ACTION_RESOLVE_DEACTIVATE_SIM =
        "android.service.euicc.action.RESOLVE_DEACTIVATE_SIM";
/**
 * Alert the user about a download/switch being done for an app that doesn't
 * currently have carrier privileges.
 */
public static final String ACTION_RESOLVE_NO_PRIVILEGES =
        "android.service.euicc.action.RESOLVE_NO_PRIVILEGES";

/** Ask the user to resolve all the resolvable errors. */
public static final String ACTION_RESOLVE_RESOLVABLE_ERRORS =
        "android.service.euicc.action.RESOLVE_RESOLVABLE_ERRORS";

امتيازات مشغّل شبكة الجوّال

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

لضمان عدم إمكانية وصول أي شخص آخر إلى الملف الشخصي سوى مالكه، يستخدم نظام التشغيل Android آلية لمنح امتيازات خاصة لتطبيق مالك الملف الشخصي (أي تطبيق مشغّل شبكة الجوّال). يحمّل نظام التشغيل Android الشهادات المخزّنة في ملف قواعد الوصول (ARF) الخاص بالملف الشخصي ويمنح الإذن للتطبيقات الموقّعة بهذه الشهادات بإجراء طلبات إلى واجهات برمجة التطبيقات EuiccManager. في ما يلي وصف للعملية على مستوى عالٍ:

يوقّع المشغّل حِزمة APK لتطبيق مشغل شبكة الجوّال، وتُرفق أداة apksigner شهادة المفتاح العام بحِزمة APK.
يُعدّ المشغّل/SM-DP+ ملفًا شخصيًا وبياناته الوصفية، بما في ذلك ملف ARF يحتوي على:
1. توقيع (SHA-1 أو SHA-256) لشهادة المفتاح العام الخاصة بتطبيق مشغّل شبكة الجوّال (مطلوب)
2. اسم حزمة تطبيق مشغّل شبكة الجوّال (يُنصح بشدة بملء هذا الحقل)
يحاول تطبيق مشغّل شبكة الجوّال تنفيذ عملية eUICC باستخدام واجهة برمجة التطبيقات EuiccManager.
تتحقّق منصة Android من أنّ تجزئة SHA-1 أو SHA-256 لشهادة تطبيق المتصل تتطابق مع توقيع الشهادة التي تم الحصول عليها من ملف ARF الخاص بالملف الشخصي المستهدف. إذا كان اسم حزمة تطبيق مشغّل شبكة الجوّال مضمّنًا في ملف ARF، يجب أن يتطابق أيضًا مع اسم حزمة تطبيق المتصل.
بعد التحقّق من التوقيع واسم الحزمة (في حال تضمينهما)، يتم منح تطبيق المتصل امتيازات مشغّل شبكة الجوّال على الملف الشخصي المستهدف.

بما أنّ البيانات الوصفية للملف الشخصي يمكن أن تكون متاحة خارج الملف الشخصي نفسه (ليتمكّن LPA من استرداد البيانات الوصفية للملف الشخصي من SM-DP+ قبل تنزيل الملف الشخصي، أو من ISD-R عند إيقاف الملف الشخصي)، يجب أن تحتوي على قواعد امتيازات مشغّل شبكة الجوّال نفسها كما في الملف الشخصي.

يجب أن يتيح نظام التشغيل eUICC وSM-DP+ علامة خاصة BF76 في البيانات الوصفية للملف الشخصي. يجب أن يكون محتوى العلامة هو نفسه قواعد امتيازات مشغّل شبكة الجوّال التي تم عرضها من خلال تطبيق قاعدة الوصول (ARA) المحدّد في امتيازات مشغّل شبكة الجوّال في بطاقة UICC:

RefArDo ::= [PRIVATE 2] SEQUENCE {  -- Tag E2
    refDo [PRIVATE 1] SEQUENCE {  -- Tag E1
        deviceAppIdRefDo [PRIVATE 1] OCTET STRING (SIZE(20|32)),  -- Tag C1
        pkgRefDo [PRIVATE 10] OCTET STRING (SIZE(0..127)) OPTIONAL  -- Tag CA
    },
    arDo [PRIVATE 3] SEQUENCE {  -- Tag E3
        permArDo [PRIVATE 27] OCTET STRING (SIZE(8))  -- Tag DB
    }
}

لمزيد من التفاصيل حول توقيع التطبيق، يمكنك الاطّلاع على مقالة توقيع تطبيقك. ولمزيد من التفاصيل حول امتيازات مشغّل شبكة الجوّال، يمكنك الاطّلاع على مقالة امتيازات مشغّل شبكة الجوّال في بطاقة UICC.

إنشاء تطبيق مساعد للملفات الشخصية المحلية

يمكن لمصنّعي الأجهزة تنفيذ مساعد الملف الشخصي المحلي (LPA) الخاص بهم، والذي يجب ربطه بواجهات برمجة تطبيقات Euicc على Android. تقدّم الأقسام التالية نظرة عامة موجزة حول إنشاء تطبيق LPA ودمجه مع نظام Android.

متطلبات الأجهزة/المودم

يجب أن يتوافق تطبيق LPA ونظام تشغيل شريحة eSIM على شريحة eUICC مع الإصدار 2.0 أو 2.2 على الأقل من مواصفات GSMA RSP (توفير شرائح SIM عن بُعد). عليك أيضًا التخطيط لاستخدام خوادم SM-DP+‎ وSM-DS تتضمّن إصدارًا متوافقًا من RSP. للاطّلاع على بنية RSP التفصيلية، يُرجى الرجوع إلى مواصفات بنية RSP الصادرة عن جمعية GSMA‏ (SGP.21).

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

الإصدار 1.1 من طبقة تجريد الأجهزة (HAL) الخاصة بالراديو: setSimPower
IRadio HAL v1.2: getIccCardStatus

ملاحظة: يجب توفّر الإصدار 1.4 من IRadio HAL على الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android، ويُنصح بتوفّره على جميع إصدارات Android الأخرى.
‫IRadioConfig HAL الإصدار 1.0: getSimSlotsStatus

ملاحظة: يجب توفُّر الإصدار 1.2 من IRadioConfig HAL في الأجهزة التي تعمل بنظام التشغيل Android 10، ويُنصح باستخدامه في جميع إصدارات Android الأخرى.
‫IRadioConfig AIDL الإصدار 1.0: getAllowedCarriers

يحتاج تطبيق LPA من Google إلى معرفة حالة قفل مشغّل شبكة الجوّال حتى يتمكّن من السماح بتنزيل شريحة eSIM أو نقلها لمشغّل شبكة الجوّال المسموح به فقط. بخلاف ذلك، قد ينتهي الأمر بالمستخدمين إلى تنزيل شريحة SIM ونقلها ثم يدركون لاحقًا أنّ الجهاز مقفل على مشغّل شبكة جوّال مختلف.
- على المورّدين أو الشركات المصنّعة للمعدّات الأصلية تنفيذ واجهة برمجة التطبيقات IRadioSim.getAllowedCarriers() HAL.
  
  ملاحظة: يجب إجراء ذلك حتى إذا لم يكن المورّدون/مصنّعو المعدات الأصلية يستخدمون واجهة برمجة التطبيقات IRadioSim.setAllowedCarriers() HAL لحظر الجهاز.
- يجب أن يملأ RIL / Modem الخاص بالمورّد حالة القفل وcarrierId الخاص بمشغّل شبكة الجوّال الذي تم قفل الجهاز عليه كجزء من IRadioSimResponse.getAllowedCarriersResponse()HAL API.

يجب أن يتعرّف المودم على شريحة eSIM مع تفعيل ملف التشغيل التلقائي كشريحة SIM صالحة، وأن يبقي شريحة SIM مفعّلة.

بالنسبة إلى الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android، يجب تحديد مصفوفة أرقام تعريف لشرائح eUICC غير قابلة للإزالة. على سبيل المثال، اطّلِع على arrays.xml.

<resources>
   <!-- Device-specific array of SIM slot indexes which are are embedded eUICCs.
        e.g. If a device has two physical slots with indexes 0, 1, and slot 1 is an
        eUICC, then the value of this array should be:
            <integer-array name="non_removable_euicc_slots">
                <item>1</item>
            </integer-array>
        If a device has three physical slots and slot 1 and 2 are eUICCs, then the value of
        this array should be:
            <integer-array name="non_removable_euicc_slots">
               <item>1</item>
               <item>2</item>
            </integer-array>
        This is used to differentiate between removable eUICCs and built in eUICCs, and should
        be set by OEMs for devices which use eUICCs. -->

   <integer-array name="non_removable_euicc_slots">
       <item>1</item>
   </integer-array>
</resources>

للحصول على قائمة كاملة بمتطلبات المودم، يُرجى الاطّلاع على متطلبات المودم لاستخدام شريحة eSIM.

EuiccService

يتألف LPA من مكوّنَين منفصلَين (يمكن تنفيذ كليهما في حزمة APK نفسها): الخلفية الخاصة بـ LPA وواجهة المستخدم الخاصة بـ LPA أو LUI.

لتنفيذ الخلفية الخاصة بواجهة LPA، عليك توسيع EuiccService وتحديد هذه الخدمة في ملف البيان. يجب أن تتطلّب الخدمة إذن android.permission.BIND_EUICC_SERVICEالنظام لضمان عدم إمكانية ربطها إلا بالنظام. يجب أن تتضمّن الخدمة أيضًا فلتر أهداف يتضمّن الإجراء android.service.euicc.EuiccService. يجب ضبط أولوية فلتر الأهداف على قيمة غير صفرية في حال توفّر عمليات تنفيذ متعددة على الجهاز. مثلاً:

<service
    android:name=".EuiccServiceImpl"
    android:permission="android.permission.BIND_EUICC_SERVICE">
    <intent-filter android:priority="100">
        <action android:name="android.service.euicc.EuiccService" />
    </intent-filter>
</service>

داخليًا، يحدّد إطار عمل Android موفّر خدمة LPA النشط ويتفاعل معه حسب الحاجة لتوفير واجهات برمجة تطبيقات eUICC في Android. يتم البحث في PackageManager عن جميع التطبيقات التي لديها إذن android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS، والذي يحدّد خدمة لإجراء android.service.euicc.EuiccService. يتم اختيار الخدمة ذات الأولوية الأعلى. في حال عدم العثور على أي خدمة، سيتم إيقاف ميزة LPA.

لتنفيذ واجهة المستخدم المحلية، يجب توفير نشاط للإجراءات التالية:

android.service.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS
android.service.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION

وكما هو الحال مع الخدمة، يجب أن يتطلّب كل نشاط إذن النظام android.permission.BIND_EUICC_SERVICE. يجب أن يحتوي كل منهما على فلتر أهداف يتضمّن الإجراء المناسب والفئة android.service.euicc.category.EUICC_UI وأولوية غير صفرية. يتم استخدام منطق مشابه لاختيار عمليات التنفيذ لهذه الأنشطة كما هو الحال مع اختيار عملية تنفيذ EuiccService. مثلاً:

<activity android:name=".MyLuiActivity"
          android:exported="true"
          android:permission="android.permission.BIND_EUICC_SERVICE">
    <intent-filter android:priority="100">
        <action android:name="android.service.euicc.action.MANAGE_EMBEDDED_SUBSCRIPTIONS" />
        <action android:name="android.service.euicc.action.PROVISION_EMBEDDED_SUBSCRIPTION" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.service.euicc.category.EUICC_UI" />
    </intent-filter>
</activity>

يشير ذلك إلى أنّ واجهة المستخدم التي تنفّذ هذه الشاشات يمكن أن تأتي من حزمة APK مختلفة عن تلك التي تنفّذ EuiccService. يُعدّ تحديد ما إذا كان يجب توفير حزمة APK واحدة أو حِزم APK متعددة (على سبيل المثال، حزمة تنفِّذ EuiccService وحزمة توفّر أنشطة واجهة مستخدم محلية) خيارًا تصميميًا.

EuiccCardManager

EuiccCardManager هي الواجهة المخصّصة للتواصل مع شريحة eSIM. ويوفّر وظائف ES10 (كما هو موضح في مواصفات GSMA RSP) ويتعامل مع أوامر طلب/رد APDU المنخفضة المستوى بالإضافة إلى تحليل ASN.1. ‫EuiccCardManager هي واجهة برمجة تطبيقات خاصة بالنظام ولا يمكن طلبها إلا من خلال التطبيقات التي لديها امتيازات النظام.

تطبيقات مشغّل شبكة الجوّال وواجهات برمجة التطبيقات LPA وEuicc

الشكل 2. يستخدم كل من تطبيق مشغّل شبكة الجوّال وتطبيق LPA واجهات برمجة تطبيقات Euicc

تتطلّب واجهات برمجة التطبيقات الخاصة بعمليات الملف الشخصي من خلال EuiccCardManager أن يكون المتصل من مستخدمي LPA. يتم فرض ذلك من خلال إطار عمل Android. وهذا يعني أنّه يجب أن يوسّع المتصل EuiccService وأن يتم تعريفه في ملف البيان، كما هو موضّح في الأقسام السابقة.

على غرار EuiccManager، لاستخدام واجهات برمجة التطبيقات EuiccCardManager، يجب أن يحصل تطبيق LPA أولاً على مثيل EuiccCardManager من خلال Context#getSystemService:

EuiccCardManager cardMgr = (EuiccCardManager) context.getSystemService(Context.EUICC_CARD_SERVICE);

بعد ذلك، للحصول على جميع الملفات الشخصية على شريحة eUICC، اتّبِع الخطوات التالية:

ResultCallback<EuiccProfileInfo[]> callback =
       new ResultCallback<EuiccProfileInfo[]>() {
           @Override
           public void onComplete(int resultCode,
                   EuiccProfileInfo[] result) {
               if (resultCode == EuiccCardManagerReflector.RESULT_OK) {
                   // handle result
               } else {
                   // handle error
               }
           }
       };

cardMgr.requestAllProfiles(eid, AsyncTask.THREAD_POOL_EXECUTOR, callback);

داخليًا، يرتبط EuiccCardManager بـ EuiccCardController (الذي يتم تشغيله في عملية الهاتف) من خلال واجهة AIDL، ويتلقّى كلّ من طرق EuiccCardManager رد الاتصال من عملية الهاتف من خلال واجهة AIDL مختلفة ومخصّصة. عند استخدام واجهات برمجة التطبيقات EuiccCardManager، يجب أن يوفّر المتصل (LPA) كائن Executor يتم من خلاله استدعاء دالة رد الاتصال. يمكن تشغيل عنصر Executor هذا على سلسلة محادثات واحدة أو على مجموعة سلاسل محادثات من اختيارك.

تتّبع معظم واجهات برمجة التطبيقات EuiccCardManager نمط الاستخدام نفسه. على سبيل المثال، لتحميل حزمة ملف تعريف مرتبط على شريحة eUICC، اتّبِع الخطوات التالية:

...
cardMgr.loadBoundProfilePackage(eid, boundProfilePackage,
        AsyncTask.THREAD_POOL_EXECUTOR, callback);

للتبديل إلى ملف شخصي آخر باستخدام رقم ICCID معيّن، اتّبِع الخطوات التالية:

...
cardMgr.switchToProfile(eid, iccid, true /* refresh */,
        AsyncTask.THREAD_POOL_EXECUTOR, callback);

للحصول على عنوان SM-DP+‎ التلقائي من شريحة eUICC، اتّبِع الخطوات التالية:

...
cardMgr.requestDefaultSmdpAddress(eid, AsyncTask.THREAD_POOL_EXECUTOR,
        callback);

لاسترداد قائمة بالإشعارات الخاصة بأحداث الإشعارات المحدّدة، اتّبِع الخطوات التالية:

...
cardMgr.listNotifications(eid,
        EuiccNotification.Event.INSTALL
              | EuiccNotification.Event.DELETE /* events */,
        AsyncTask.THREAD_POOL_EXECUTOR, callback);

تفعيل ملف شخصي لشريحة eSIM من خلال تطبيق مشغّل شبكة الجوّال

على الأجهزة التي تعمل بالإصدار 9 من نظام التشغيل Android أو الإصدارات الأحدث، يمكنك استخدام تطبيق مشغّل شبكة الجوّال لتفعيل شريحة eSIM وتنزيل الملفات الشخصية. يمكن لتطبيق مشغّل شبكة الجوّال تنزيل الملفات الشخصية من خلال الاتصال downloadSubscription مباشرةً أو من خلال تقديم رمز تفعيل إلى LPA.

عندما ينزّل تطبيق مشغّل شبكة الجوّال ملفًا شخصيًا من خلال طلب downloadSubscription، يفرض الطلب أنّه يمكن للتطبيق إدارة الملف الشخصي من خلال BF76 علامة بيانات وصفية تشفّر قواعد امتيازات مشغّل شبكة الجوّال للملف الشخصي. إذا لم يتضمّن الملف الشخصي علامة BF76 أو إذا كانت علامة BF76 لا تتطابق مع توقيع تطبيق مشغّل شبكة الجوّال الذي يجري المكالمة، يتم رفض التنزيل.

يوضّح القسم أدناه كيفية تفعيل شريحة eSIM من خلال تطبيق مشغّل شبكة الجوّال باستخدام رمز تفعيل.

تفعيل شريحة eSIM باستخدام رمز تفعيل

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

تحديد خدمة توفير eUICC لمشغل شبكة الجوّال

يتواصل تطبيق LPA وتطبيق مشغّل شبكة الجوّال من خلال واجهتَي AIDL هما ICarrierEuiccProvisioningService وIGetActivationCodeCallback. يجب أن يتضمّن تطبيق مشغّل شبكة الجوّال واجهة ICarrierEuiccProvisioningService وأن يعرضها في تعريف البيان. يجب أن يرتبط LPA بـ ICarrierEuiccProvisioningService وأن ينفّذ IGetActivationCodeCallback. لمزيد من المعلومات حول كيفية تنفيذ واجهة AIDL وعرضها، يُرجى الاطّلاع على تعريف واجهة AIDL.

لتحديد واجهات AIDL، أنشئ ملفات AIDL التالية لكل من تطبيقات LPA ومشغّل شبكة الجوّال.

ICarrierEuiccProvisioningService.aidl

package android.service.euicc;

import android.service.euicc.IGetActivationCodeCallback;

oneway interface ICarrierEuiccProvisioningService {
    // The method to get the activation code from the carrier app. The caller needs to pass in
    // the implementation of IGetActivationCodeCallback as the parameter.
    void getActivationCode(in IGetActivationCodeCallback callback);

    // The method to get the activation code from the carrier app. The caller needs to pass in
    // the activation code string as the first parameter and the implementation of
    // IGetActivationCodeCallback as the second parameter. This method provides the carrier
    // app the device EID which allows a carrier to pre-bind a profile to the device's EID before
    // the download process begins.
    void getActivationCodeForEid(in String eid, in IGetActivationCodeCallback callback);
}

IGetActivationCodeCallback.aidl

package android.service.euicc;

oneway interface IGetActivationCodeCallback {
    // The call back method needs to be called when the carrier app gets the activation
    // code successfully. The caller needs to pass in the activation code string as the
    // parameter.
    void onSuccess(String activationCode);

    // The call back method needs to be called when the carrier app failed to get the
    // activation code.
    void onFailure();
}

مثال على تنفيذ LPA

لربط تطبيق LPA بتنفيذ ICarrierEuiccProvisioningService في تطبيق مشغّل شبكة الجوّال، يجب أن ينسخ تطبيق LPA كلاً من ICarrierEuiccProvisioningService.aidl وIGetActivationCodeCallback.aidl إلى مشروعك وينفّذ ServiceConnection.

@Override
public void onServiceConnected(ComponentName componentName, IBinder iBinder) {
    mCarrierProvisioningService = ICarrierEuiccProvisioningService.Stub.asInterface(iBinder);
}

بعد الربط بتنفيذ ICarrierEuiccProvisioningService في تطبيق مشغّل شبكة الجوّال، يستدعي LPA إما getActivationCode أو getActivationCodeForEid للحصول على رمز التفعيل من تطبيق مشغّل شبكة الجوّال من خلال تمرير تنفيذ فئة IGetActivationCodeCallback.

الفرق بين getActivationCode وgetActivationCodeForEid هو أنّ getActivationCodeForEid يتيح لمشغّل شبكة الجوّال ربط ملف شخصي مسبقًا بمعرّف EID الخاص بالجهاز قبل بدء عملية التنزيل.

void getActivationCodeFromCarrierApp() {
    IGetActivationCodeCallback.Stub callback =
            new IGetActivationCodeCallback.Stub() {
                @Override
                public void onSuccess(String activationCode) throws RemoteException {
                    // Handle the case LPA success to get activation code from a carrier app.
                }

                @Override
                public void onFailure() throws RemoteException {
                    // Handle the case LPA failed to get activation code from a carrier app.
                }
            };
    
    try {
        mCarrierProvisioningService.getActivationCode(callback);
    } catch (RemoteException e) {
        // Handle Remote Exception
    }
}

مثال على عملية التنفيذ لتطبيق مشغّل شبكة الجوّال

لكي يتم ربط LPA بتطبيق مشغّل شبكة الجوّال، يجب أن ينسخ تطبيق مشغّل شبكة الجوّال كلاً من ICarrierEuiccProvisioningService.aidl وIGetActivationCodeCallback.aidl إلى مشروعك ويحدّد خدمة ICarrierEuiccProvisioningService في ملف AndroidManifest.xml. يجب أن تتطلّب الخدمة إذن النظام android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS لضمان عدم إمكانية ربطها إلا بتطبيق LPA، وهو تطبيق يتمتع بامتيازات النظام. يجب أن تتضمّن الخدمة أيضًا فلتر أهداف مع الإجراء android.service.euicc.action.BIND_CARRIER_PROVISIONING_SERVICE.

AndroidManifest.xml

<application>
  ...
  <service
      android:name=".CarrierEuiccProvisioningService"
      android:exported="true"
      android:permission="android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS">
    <intent-filter>
      <action android:name="android.service.euicc.action.BIND_CARRIER_PROVISIONING_SERVICE"/>
    </intent-filter>
  </service>
  ...
</application>

لتنفيذ خدمة تطبيق مشغّل شبكة الجوّال المستندة إلى AIDL، أنشئ خدمة، ووسِّع الفئة Stub ونفِّذ الطريقتَين getActivationCode وgetActivationCodeForEid. يمكن بعد ذلك أن يستدعي تطبيق LPA أيًا من الطريقتين لجلب رمز تفعيل الملف الشخصي. يجب أن يستجيب تطبيق مشغّل شبكة الجوّال من خلال طلب IGetActivationCodeCallback#onSuccess باستخدام رمز التفعيل إذا تم جلب الرمز من خادم مشغّل شبكة الجوّال بنجاح. في حال عدم النجاح، يجب أن يستجيب تطبيق مشغّل شبكة الجوّال بالرمز IGetActivationCodeCallback#onFailure.

CarrierEuiccProvisioningService.java

import android.service.euicc.ICarrierEuiccProvisioningService;
import android.service.euicc.ICarrierEuiccProvisioningService.Stub;
import android.service.euicc.IGetActivationCodeCallback;

public class CarrierEuiccProvisioningService extends Service {
    private final ICarrierEuiccProvisioningService.Stub binder =
        new Stub() {
          @Override
          public void getActivationCode(IGetActivationCodeCallback callback) throws RemoteException {
            String activationCode = // do whatever work necessary to get an activation code (HTTP requests to carrier server, fetch from storage, etc.)
            callback.onSuccess(activationCode);
          }

          @Override
          public void getActivationCodeForEid(String eid, IGetActivationCodeCallback callback) throws RemoteException {
            String activationCode = // do whatever work necessary (HTTP requests, fetch from storage, etc.)
            callback.onSuccess(activationCode);
          }
      }
}

بدء واجهة مستخدم تطبيق مشغّل شبكة الجوَّال في عملية تفعيل LPA

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

في ما يلي خطوات بدء تشغيل واجهة مستخدم تطبيق مشغّل شبكة الجوّال في LPA:

يُطلق تطبيق LPA مسار تفعيل تطبيق مشغّل شبكة الجوّال من خلال إرسال الغرض android.service.euicc.action.START_CARRIER_ACTIVATION إلى حزمة تطبيق مشغّل شبكة الجوّال التي تتضمّن الإجراء. (يجب حماية أداة استقبال تطبيق مشغّل شبكة الجوّال في بيان التطبيق باستخدام android:permission="android.permission.WRITE_EMBEDDED_SUBSCRIPTIONS" لتجنُّب تلقّي الأهداف من التطبيقات غير المتوافقة مع LPA).
```
String packageName = // The carrier app's package name

Intent carrierAppIntent =
    new Intent(“android.service.euicc.action.START_CARRIER_ACTIVATION”)
        .setPackage(packageName);

ResolveInfo activity =
    context.getPackageManager().resolveActivity(carrierAppIntent, 0);

carrierAppIntent
    .setClassName(activity.activityInfo.packageName, activity.activityInfo.name);

startActivityForResult(carrierAppIntent, requestCode);
```
يؤدي تطبيق مشغّل شبكة الجوّال عمله باستخدام واجهة المستخدم الخاصة به. على سبيل المثال، تسجيل دخول المستخدم أو إرسال طلبات HTTP إلى الخلفية الخاصة بشركة الاتصالات.
يردّ تطبيق مشغّل شبكة الجوّال على LPA من خلال الاتصال بـ setResult(int, Intent) وfinish().
1. إذا ردّ تطبيق مشغّل شبكة الجوّال بالرمز RESULT_OK، ستواصل LPA عملية التفعيل. إذا حدّد تطبيق مشغّل شبكة الجوّال أنّه على المستخدم مسح رمز استجابة سريعة ضوئيًا بدلاً من السماح لـ LPA بربط خدمة تطبيق مشغّل شبكة الجوّال، سيردّ تطبيق مشغّل شبكة الجوّال على LPA باستخدام setResult(int, Intent) مع RESULT_OK ومثيل Intent يحتوي على القيمة المنطقية الإضافية android.telephony.euicc.extra.USE_QR_SCANNER التي تم ضبطها على true. بعد ذلك، يتحقّق LPA من البيانات الإضافية ويشغّل الماسح الضوئي لرمز الاستجابة السريعة بدلاً من ربط تنفيذ ICarrierEuiccProvisioningService لتطبيق مشغّل شبكة الجوّال.
2. إذا تعطّل تطبيق مشغّل شبكة الجوّال أو ردّ بالرمز RESULT_CANCELED (وهو رمز الردّ التلقائي)، ستلغي خدمة LPA عملية تفعيل شريحة eSIM.
3. إذا ردّ تطبيق مشغّل شبكة الجوّال بقيمة أخرى غير RESULT_OK أو RESULT_CANCELED، سيتعامل LPA معها على أنّها خطأ.
لأسباب تتعلّق بالأمان، يجب ألا يقبل LPA رمز التفعيل المقدَّم في نتيجة intent مباشرةً لضمان عدم تمكّن الجهات التي لا تستخدم LPA من الحصول على رمز تفعيل من تطبيق مشغّل شبكة الجوّال.

بدء عملية تفعيل LPA في تطبيق مشغّل شبكة جوّال

اعتبارًا من Android 11، يمكن لتطبيقات مشغّلي شبكة الجوّال استخدام واجهات برمجة تطبيقات eUICC لبدء واجهة مستخدم محلية لتفعيل شريحة eSIM. تعرض هذه الطريقة واجهة مستخدم عملية تفعيل شريحة eSIM الخاصة بتطبيق LPA لتفعيل الملف الشخصي لشريحة eSIM. بعد ذلك، يرسل LPA بثًا عند انتهاء عملية تفعيل ملف eSIM.

يجب أن يحدّد LPA نشاطًا يتضمّن فلتر أهداف مع الإجراء android.service.euicc.action.START_EUICC_ACTIVATION. يجب ضبط أولوية فلتر الأهداف على قيمة غير صفرية في حال توفُّر عمليات تنفيذ متعددة على الجهاز. مثلاً:

<application>
  ...
<activity
    android:name=".CarrierAppInitActivity"
    android:exported="true">

    <intent-filter android:priority="100">
        <action android:name="android.service.euicc.action.START_EUICC_ACTIVATION" />
    </intent-filter>
</activity>
  ...
</application>

يؤدي تطبيق مشغّل شبكة الجوّال عمله باستخدام واجهة المستخدم الخاصة به. على سبيل المثال، تسجيل دخول المستخدم أو إرسال طلبات HTTP إلى الخلفية الخاصة بشركة الاتصالات.
في هذه المرحلة، يجب أن يكون تطبيق مشغّل شبكة الجوّال جاهزًا لتقديم رمز تفعيل من خلال تنفيذ ICarrierEuiccProvisioningService. يُطلق تطبيق مشغّل شبكة الجوّال خدمة LPA من خلال استدعاء startActivityForResult(Intent, int) باستخدام الإجراء android.telephony.euicc.action.START_EUICC_ACTIVATION. يتحقّق LPA أيضًا من السمة الإضافية المنطقية android.telephony.euicc.extra.USE_QR_SCANNER. إذا كانت القيمة true، سيشغّل تطبيق LPA الماسح الضوئي لرمز الاستجابة السريعة ليتمكّن المستخدم من مسح رمز الاستجابة السريعة الخاص بالملف الشخصي ضوئيًا.
من جهة LPA، يرتبط LPA بتنفيذ ICarrierEuiccProvisioningService لتطبيق مشغّل شبكة الجوّال من أجل الحصول على رمز التفعيل وتنزيل الملف الشخصي المقابل. تعرض "حزمة التطبيق المحدودة" جميع عناصر واجهة المستخدم الضرورية أثناء عملية التنزيل، مثل شاشة التحميل.
عند اكتمال عملية تفعيل LPA، يستجيب LPA لتطبيق مشغّل شبكة الجوّال باستخدام رمز نتيجة، ويتعامل تطبيق مشغّل شبكة الجوّال مع هذا الرمز في onActivityResult(int, int, Intent).
1. إذا نجح تطبيق LPA في تنزيل ملف تعريف eSIM الجديد، سيردّ بالرمز RESULT_OK.
2. إذا ألغى المستخدم تفعيل الملف الشخصي لشريحة eSIM في LPA، سيتم الردّ بالرمز RESULT_CANCELED.
3. إذا ردّت LPA بقيمة أخرى غير RESULT_OK أو RESULT_CANCELED، سيتعامل تطبيق مشغّل شبكة الجوّال مع ذلك على أنّه خطأ.
لأسباب تتعلّق بالأمان، لا يقبل LPA رمز التفعيل مباشرةً في الغرض المقدَّم لضمان عدم تمكّن الجهات غير التابعة لـ LPA من الحصول على رمز التفعيل من تطبيق مشغّل شبكة الجوّال.

إتاحة استخدام شرائح eSIM متعددة

بالنسبة إلى الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android أو الإصدارات الأحدث، تتوافق الفئة EuiccManager مع الأجهزة التي تتضمّن شرائح eSIM متعددة. لا تتطلّب الأجهزة التي تحتوي على شريحة eSIM واحدة وتتم ترقيتها إلى Android 10 أي تعديل على عملية تنفيذ LPA، لأنّ النظام الأساسي يربط تلقائيًا مثيل EuiccManager بشريحة eUICC التلقائية. يتم تحديد شريحة eUICC التلقائية من خلال النظام الأساسي للأجهزة التي تعمل بالإصدار 1.2 أو الإصدارات الأحدث من طبقة تجريد الأجهزة اللاسلكية (HAL)، ومن خلال LPA للأجهزة التي تعمل بالإصدارات الأقدم من 1.2 من طبقة تجريد الأجهزة اللاسلكية.

المتطلبات

لاستخدام شرائح eSIM متعدّدة، يجب أن يحتوي الجهاز على أكثر من عنصر eUICC واحد، ويمكن أن يكون عنصر eUICC مدمجًا أو فتحة لشريحة SIM يمكن إدخال عناصر eUICC قابلة للإزالة فيها.

يجب توفُّر الإصدار 1.2 أو الإصدارات الأحدث من Radio HAL لاستخدام شرائح eSIM متعددة. يُنصح باستخدام الإصدار 1.4 من Radio HAL والإصدار 1.2 من RadioConfig HAL.

التنفيذ

لإتاحة استخدام شرائح eSIM متعددة (بما في ذلك شرائح eUICC القابلة للإزالة أو شرائح SIM القابلة للبرمجة)، يجب أن تنفّذ LPA EuiccService، التي تتلقّى رقم تعريف الخانة الذي يتوافق مع رقم تعريف البطاقة المقدَّم من المتصل.

المورد non_removable_euicc_slots المحدّد في arrays.xml هو مصفوفة من الأعداد الصحيحة التي تمثّل أرقام تعريف الشرائح المدمجة (eUICC) في الجهاز. يجب تحديد هذا المورد للسماح للنظام الأساسي بتحديد ما إذا كانت شريحة eUICC المُدرَجة قابلة للإزالة أم لا.

تطبيق مشغّل شبكة الجوّال لجهاز مزوّد بشرائح eSIM متعددة

عند إنشاء تطبيق مشغّل شبكة جوّال لجهاز يحتوي على شرائح eSIM متعددة، استخدِم طريقة createForCardId في EuiccManager لإنشاء عنصر EuiccManager يتم ربطه بمعرّف بطاقة معيّن. معرّف البطاقة هو قيمة عدد صحيح تحدّد بشكل فريد بطاقة UICC أو بطاقة eUICC على الجهاز.

للحصول على معرّف البطاقة لبطاقة eUICC التلقائية للجهاز، استخدِم طريقة getCardIdForDefaultEuicc في TelephonyManager. تعرض هذه الطريقة UNSUPPORTED_CARD_ID إذا كان إصدار HAL اللاسلكي أقل من 1.2، وتعرض UNINITIALIZED_CARD_ID إذا لم يقرأ الجهاز شريحة eUICC.

يمكنك أيضًا الحصول على معرّفات البطاقات من getUiccCardsInfo وgetUiccSlotsInfo (واجهة برمجة تطبيقات النظام) في TelephonyManager، ومن getCardId في SubscriptionInfo.

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

يمكنك استخدام نماذج الرموز البرمجية التالية لإنشاء تطبيق مشغّل شبكة جوّال.

المثال 1: الحصول على اشتراك نشط وإنشاء مثيل EuiccManager

// Get the active subscription and instantiate an EuiccManager for the eUICC which holds
// that subscription
SubscriptionManager subMan = (SubscriptionManager)
        mContext.getSystemService(Context.TELEPHONY_SUBSCRIPTION_SERVICE);
int cardId = subMan.getActiveSubscriptionInfo().getCardId();
EuiccManager euiccMan = (EuiccManager) mContext.getSystemService(Context.EUICC_SERVICE)
            .createForCardId(cardId);

المثال 2: التكرار خلال بطاقات UICC وإنشاء مثيل EuiccManager لبطاقة eUICC قابلة للإزالة

// On a device with a built-in eUICC and a removable eUICC, iterate through the UICC cards
// to instantiate an EuiccManager associated with a removable eUICC
TelephonyManager telMan = (TelephonyManager)
        mContext.getSystemService(Context.TELEPHONY_SERVICE);
List<UiccCardInfo> infos = telMan.getUiccCardsInfo();
int removableCardId = -1; // valid cardIds are 0 or greater
for (UiccCardInfo info : infos) {
    if (info.isRemovable()) {
        removableCardId = info.getCardId();
        break;
    }
}
if (removableCardId != -1) {
    EuiccManager euiccMan = (EuiccManager) mContext.getSystemService(Context.EUICC_SERVICE)
            .createForCardId(removableCardId);
}

التحقُّق

لا يتضمّن مشروع AOSP تنفيذًا لـ LPA، ولا يُتوقّع أن يتوفّر LPA على جميع إصدارات Android (لا تتوافق جميع الهواتف مع شريحة eSIM). لهذا السبب، لا تتوفّر حالات اختبار CTS للتشفير التام بين الأطراف. ومع ذلك، تتوفّر حالات اختبار أساسية في AOSP لضمان صلاحية واجهات برمجة التطبيقات eUICC المكشوفة في إصدارات Android.

عليك التأكّد من أنّ الإصدارات تجتاز حالات اختبار CTS التالية (بالنسبة إلى واجهات برمجة التطبيقات العامة): /platform/cts/tests/tests/telephony/current/src/android/telephony/euicc/cts.

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

إذا كنت بصدد إنشاء LPA، عليك إجراء اختبارات أكثر صرامة. عليك العمل مع مورّد المودم ومورّد شريحة eUICC أو نظام تشغيل شريحة eSIM ومورّدي SM-DP+ ومشغّلي شبكات الجوّال لحل المشاكل وضمان إمكانية التشغيل التفاعلي لتطبيق LPA ضمن بنية RSP. لا يمكن تجنُّب إجراء قدر كبير من الاختبارات اليدوية. للحصول على أفضل تغطية للاختبار، عليك اتّباع خطة اختبار GSMA SGP.23 RSP.

تنفيذ شريحة eSIM تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إنشاء تطبيق مشغّل شبكة جوّال

EuiccManager

الأخطاء القابلة للحل

امتيازات مشغّل شبكة الجوّال

إنشاء تطبيق مساعد للملفات الشخصية المحلية

متطلبات الأجهزة/المودم

EuiccService

EuiccCardManager

تفعيل ملف شخصي لشريحة eSIM من خلال تطبيق مشغّل شبكة الجوّال

تفعيل شريحة eSIM باستخدام رمز تفعيل

تحديد خدمة توفير eUICC لمشغل شبكة الجوّال

بدء واجهة مستخدم تطبيق مشغّل شبكة الجوَّال في عملية تفعيل LPA

بدء عملية تفعيل LPA في تطبيق مشغّل شبكة جوّال

إتاحة استخدام شرائح eSIM متعددة

المتطلبات

التنفيذ

تطبيق مشغّل شبكة الجوّال لجهاز مزوّد بشرائح eSIM متعددة

التحقُّق

تنفيذ شريحة eSIM