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

استخدام شريحة eSIM

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

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

بنية مبسّطة لتوفير شريحة SIM عن بُعد (RSP)

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

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

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

تتطلّب واجهات برمجة التطبيقات في EuiccManager تطبيقًا مُنفَّذًا بشكلٍ سليم من أجل العمل، ويجب أن يكون المُرسِل لطلبات واجهة برمجة التطبيقات EuiccCardManager هو تطبيق LPA. ويفرض إطار عمل Android هذا الإجراء.

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

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

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

EuiccManager

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

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

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

يجب التحقّق مما إذا كانت شريحة 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 يتم عرض شاشة LUI تتيح للمستخدم إدخال رمز التأكيد، وبعد إدخال الرمز، تتم استعادة عملية التنزيل. ويوفّر هذا الأسلوب لتطبيق مشغّل شبكة الجوّال إمكانية التحكّم الكامل في وقت عرض واجهة المستخدم، ولكنّه يمنح "LPA" أو "LUI" طريقة قابلة للتوسُّع لإضافة معالجة جديدة للمشاكل التي يمكن للمستخدم إصلاحها في المستقبل بدون الحاجة إلى تغيير تطبيقات العميل.

يحدِّد نظام التشغيل Android 9 هذه الأخطاء القابلة للحل في EuiccService، التي من المفترض أن يعالجها واجهة المستخدم المتوافقة مع الأجهزة اللوحية:

/**
 * 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 (Remote SIM Provisioning) على الأقل. يجب أيضًا استخدام خادمَي SM-DP+‎ وSM-DS التي تتضمّن إصدارًا مطابقًا من RSP. للاطّلاع على بنية RSP التفصيلية، يُرجى الاطّلاع على مواصفات بنية RSP في معيار GSMA SGP.21.

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

IRadio HAL v1.1: setSimPower
IRadio HAL v1.2: getIccCardStatus

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

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

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

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

بالنسبة إلى الأجهزة التي تعمل بنظام التشغيل Android 10، يجب تحديد صفيف أرقام تعريف خانات 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

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

لتنفيذ الخلفية في 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 وحزمة تقدِّم أنشطة LUI) هو خيار تصميمي.

EuiccCardManager

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

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

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

تتطلّب واجهات برمجة التطبيقات الخاصة بعمليات الملف الشخصي من خلال EuiccCardManager أن يكون المُتصل موفِّر محتوى. ويفرض إطار عمل 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 طريقة callback من عملية الهاتف من خلال واجهة 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 من خلال تطبيق مشغل شبكة الجوال

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

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

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

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

عند استخدام رمز تفعيل لتفعيل ملف شخصي لشريحة eSIM، يُسترجع LPA رمز التفعيل من تطبيق مشغّل شبكة الجوّال وينزّل الملف الشخصي. يمكن أن يبدأ مسار التفاعل هذا من خلال 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

للربط بتنفيذ ICarrierEuiccProvisioningService في تطبيق مشغّل شبكة الجوّال، يجب أن ينسخ موفّر خدمات الجوّال كلّ من 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 يسمح لمشغّل شبكة الجوّال بربط ملف تعريف مسبقًا بملف تعريف العميل المتعلّق بالجهاز (getActivationCodeForEid) قبل بدء عملية التنزيل.

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);
          }
      }
}

بدء واجهة مستخدم تطبيق مشغّل شبكة الجوّال خلال مسار تفعيل "إعلانات الأنشطة التجارية المحلية"

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

في ما يلي خطوات بدء واجهة مستخدم لتطبيق مشغّل شبكة الجوّال في "إعلانات الأنشطة التجارية المحلية":

يطلق LPA عملية تفعيل تطبيق مشغّل شبكة الجوّال من خلال إرسال android.service.euicc.action.START_CARRIER_ACTIVATIONintent إلى حزمة تطبيق مشغّل شبكة الجوّال التي تحتوي على الإجراء. (يجب حماية مستلم تطبيق مشغّل شبكة الجوّال في بيان البيان باستخدام 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 بربط خدمة تطبيق مشغّل شبكة الجوّال، يستجيب تطبيق مشغّل شبكة الجوّال لهذا الإعلان باستخدام setResult(int, Intent) مع RESULT_OK والمثيل Intent الذي يحتوي على القيمة المنطقية الإضافية android.telephony.euicc.extra.USE_QR_SCANNER على true. بعد ذلك، يتحقق LPA من القيمة الإضافية ويشغّل الماسح الضوئي لرمز الاستجابة السريعة بدلاً من ربط تنفيذ ICarrierEuiccProvisioningService في تطبيق مشغّل شبكة الجوّال.
2. إذا تعطّل تطبيق مشغّل شبكة الجوّال أو أرسل الرمز RESULT_CANCELED (هذا هو رمز الردّ التلقائي)، تلغي وحدة التحكّم في حدود الجلسة عملية تفعيل سيم البريد الإلكتروني.
3. إذا استجاب تطبيق مشغّل شبكة الجوّال بشيء آخر غير RESULT_OK أو RESULT_CANCELED، يتعامل LPA مع ذلك على أنّه خطأ.
لأسباب تتعلق بالأمان، ينبغي ألا يقبل "إعلانات الأنشطة التجارية المحلية" رمز التفعيل المباشر الذي يظهر في النتيجة المقصودة لضمان عدم حصول المتصلين غير التابعين لـ LPA على رمز التفعيل من تطبيق مشغّل شبكة الجوّال.

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

اعتبارًا من Android 11، يمكن لتطبيقات مشغّلي شبكات الجوّال استخدام واجهات برمجة التطبيقات eUICC API لبدء LUI لتنشيط eSIM. تعرض هذه الطريقة واجهة مستخدم مسار تفعيل شريحة eSIM في LPA لتفعيل ملف eSIM الشخصي. بعد ذلك، يُرسِل موفِّر خدمات الجوّال الافتراضي رسالة بث عند اكتمال تفعيل ملف تعريف 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 بتنفيذ ICarrierEuiccProvisioningService تطبيق مشغّل شبكة الجوّال من أجل جلب رمز التفعيل وتنزيل الملف الشخصي المقابل. تعرِض واجهة المستخدم المخصّصة للتطبيقات أثناء التنزيل (LPA) جميع عناصر واجهة المستخدم اللازمة، مثل شاشة التحميل.
عند اكتمال عملية تفعيل LPA، يستجيب LPA لتطبيق carrier باستخدام رمز نتيجة يعالجه تطبيق carrier في onActivityResult(int, int, Intent).
1. إذا تمكّنت LPA من تنزيل الملف الشخصي الجديد لشريحة eSIM، ستجيب بالرسالة RESULT_OK.
2. إذا ألغى المستخدم تفعيل الملف الشخصي لشريحة eSIM من "إعلانات المنتجات المحلية"، سيتم إرسال الردّ إلى RESULT_CANCELED.
3. إذا استجاب "إعلانات الأنشطة التجارية المحلية" بعبارة أخرى غير RESULT_OK أو RESULT_CANCELED، سيتعامل تطبيق مشغّل شبكة الجوّال مع هذا الطلب على أنّه خطأ.
لأسباب تتعلق بالأمان، لا يقبل LPA رمز التفعيل مباشرةً في الطلب المقدَّم لضمان عدم تمكّن المتصلين غير التابعين لـ LPA من الحصول على رمز التفعيل من تطبيق مشغّل شبكة الجوّال.

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

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

المتطلبات

لتفعيل شرائح 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.