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

المصادقة على الأجهزة القابلة للارتداء: أداة إدارة بيانات الاعتماد

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

يقدّم هذا الدليل توجيهات حول طريقة المصادقة المقترَحة لتطبيقات Wear OS، وهي Credential Manager.

لمزيد من المعلومات حول كيفية تصميم تجربة تسجيل دخول جيدة، يُرجى الاطّلاع على دليل تجربة المستخدم لتسجيل الدخول.

اعتبارات أولية

قبل البدء في التنفيذ، يُرجى مراعاة النقاط التالية.

وضع الضيف

لا تطلب المصادقة لجميع الوظائف. بدلاً من ذلك، يمكنك توفير أكبر عدد ممكن من الميزات للمستخدم بدون أن تطلب منه تسجيل الدخول.

قد يكتشف المستخدمون تطبيق Wear OS ويثبّتونه بدون استخدام تطبيق الأجهزة الجوّالة، لذا قد لا يكون لديهم حساب وقد لا يعرفون الميزات التي يقدّمها. يُرجى التأكّد من أنّ وظيفة "وضع الضيف" تعرض ميزات تطبيقك بدقة.

قد تظل بعض الأجهزة مفتوحة لفترة أطول

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

إذا كان تطبيقك يتطلّب مستوى أعلى من الأمان، مثلاً عند عرض بيانات يُحتمل أن تكون حساسة أو خاصة، تحقَّق أولاً من تفعيل ميزة "التعرّف على المعصم":

fun isWristDetectionAutoLockingEnabled(context: Context): Boolean {
    // Use the keyguard manager to check for the presence of a lock mechanism
    val keyguardManager = context.getSystemService<KeyguardManager>()
    val isSecured = keyguardManager?.isDeviceSecure == true

    // Use OEM-specific system settings to verify that on-body autolock is enabled.
    val isWristDetectionOn = android.provider.Settings.Global.getInt(
        context.contentResolver, PIXEL_WRIST_AUTOLOCK_SETTING_STATE,
        0
    ) == 1

    return isSecured && isWristDetectionOn
}WristDetectionUtility.kt

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

مدير بيانات الاعتماد

‫Credential Manager هي واجهة برمجة التطبيقات المقترَحة للمصادقة على Wear OS. وتوفّر هذه الميزة بيئة أكثر أمانًا للمستخدمين لتسجيل الدخول إلى تطبيقات Wear OS في إعداد مستقل، بدون الحاجة إلى هاتف مقترن متصل وبدون الحاجة إلى تذكُّر كلمة المرور.

يحدّد هذا المستند المعلومات التي يحتاجها المطوّرون لتنفيذ حلّ Credential Manager باستخدام آليات المصادقة العادية التي يستضيفها، وهي:

مفاتيح المرور
كلمات المرور
الهويات الموحّدة (مثل ميزة "تسجيل الدخول باستخدام حساب Google")

يقدّم هذا الدليل أيضًا توجيهات حول كيفية نقل طرق المصادقة الأخرى المقبولة في Wear OS (مشاركة الرموز المميّزة لطبقة البيانات وOAuth) كنسخ احتياطية لـ Credential Manager، وتوجيهات خاصة للتعامل مع عملية الانتقال من زر "تسجيل الدخول باستخدام حساب Google" المستقل الذي تم إيقافه نهائيًا إلى إصدار Credential Manager المضمّن.

القيود والاختلافات في Wear OS

على المطوّرين مراعاة القيود والاختلافات التالية في Wear OS:

تتوفّر واجهة برمجة التطبيقات Credential Manager على الإصدار 3 من Wear OS والإصدارات الأحدث.
لا يمكن إنشاء بيانات الاعتماد على Wear OS
لا تتوفّر ميزة استعادة بيانات الاعتماد ولا مسارات تسجيل الدخول المختلطة.
يمكن إعادة استخدام "موفّري بيانات الاعتماد" (Credential Providers) من الأجهزة الجوّالة فقط إذا كانت تتكامل مع Wear OS.

مفاتيح المرور على Wear OS

ننصح المطوّرين بشدة باستخدام مفاتيح المرور في عمليات تنفيذ Credential Manager على Wear OS. مفاتيح المرور هي المعيار الجديد المتّبع في المجال لمصادقة المستخدمين النهائيين، وهي توفّر العديد من المزايا المهمة للمستخدمين.

مفاتيح المرور أسهل

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

مفاتيح المرور أكثر أمانًا

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

تنفيذ مفاتيح المرور

يتضمّن ذلك الإعداد والإرشادات لجميع أنواع التنفيذ.

الإعداد

اضبط مستوى واجهة برمجة التطبيقات المستهدَف على 35 في ملف build.gradle الخاص بوحدة التطبيق:
```
android {
    defaultConfig {
        targetSdk(35)
    }
}
```
أضِف الأسطر التالية إلى ملف build.gradle لتطبيقك أو وحدتك، باستخدام أحدث إصدار ثابت من مرجع إصدارات androidx.credentials.
```
androidx.credentials:credentials:1.6.0
androidx.credentials:credentials-play-services-auth:1.6.0
```

طرق المصادقة المدمَجة

بما أنّ Credential Manager هي واجهة برمجة تطبيقات موحّدة، فإنّ خطوات تنفيذها على Wear OS هي نفسها لأي نوع جهاز آخر.

استخدِم التعليمات المخصّصة للأجهزة الجوّالة للبدء وإتاحة استخدام مفاتيح المرور وكلمات المرور.

إنّ خطوات إضافة ميزة "تسجيل الدخول باستخدام حساب Google" إلى Credential Manager مخصّصة لتطوير التطبيقات المتوافقة مع الأجهزة الجوّالة، ولكنّها نفسها على Wear OS.

يُرجى العِلم أنّه لا يمكن إنشاء بيانات الاعتماد على Wear OS، لذا لست بحاجة إلى تنفيذ طرق إنشاء بيانات الاعتماد المذكورة في تعليمات الأجهزة الجوّالة.

طرق المصادقة الاحتياطية

هناك طريقتان أخريان مقبولتان للمصادقة في تطبيقات Wear OS: OAuth 2.0 (أيّ من الخيارَين) ومشاركة بيانات رمز المصادقة المميّز للأجهزة الجوّالة في طبقة البيانات. على الرغم من أنّ هذه الطرق لا تتضمّن نقاط تكامل في واجهة Credential Manager API، يمكن تضمينها في مسار تجربة المستخدم في Credential Manager كخيارات احتياطية في حال تجاهل المستخدمين شاشة Credential Manager.

للتعامل مع إجراء المستخدم المتمثّل في إغلاق شاشة Credential Manager، يمكنك رصد GetCredentialCancellationException كجزء من منطق GetCredential والانتقال إلى واجهة مستخدم المصادقة المخصّصة.

try {
    val getCredentialResponse: GetCredentialResponse =
        credentialManager.getCredential(activity, createGetCredentialRequest())
    return authenticate(getCredentialResponse.credential)
} catch (_: GetCredentialCancellationException) {
    navigateToSecondaryAuthentication()
}CredentialManager.kt

يمكن لواجهة مستخدم المصادقة المخصّصة بعد ذلك توفير أي من طرق المصادقة المقبولة الأخرى الموضّحة في دليل تجربة المستخدم لتسجيل الدخول.

مشاركة الرمز المميّز لطبقة البيانات

يمكن للتطبيق المصاحب على الهاتف نقل بيانات المصادقة بأمان إلى تطبيق Wear OS باستخدام واجهة Wearable Data Layer API. نقل بيانات الاعتماد كرسائل أو كعناصر بيانات

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

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

مرِّر الرموز المميّزة باستخدام طبقة البيانات من التطبيق على الأجهزة الجوّالة، كما هو موضّح في المثال التالي:

val token = "..." // Auth token to transmit to the Wear OS device.
val putDataReq: PutDataRequest = PutDataMapRequest.create("/auth").run {
    dataMap.putString("token", token)
    asPutDataRequest()
}
val putDataTask: Task<DataItem> = Wearable.getDataClient(this).putDataItem(putDataReq)DataLayerActivity.kt

رصد أحداث تغيير البيانات في تطبيق Wear OS، كما هو موضّح في المثال التالي:

class AuthDataListenerService : WearableListenerService() {
    override fun onDataChanged(dataEvents: DataEventBuffer) {
        dataEvents.forEach { event ->
            if (event.type == DataEvent.TYPE_CHANGED) {
                val dataItemPath = event.dataItem.uri.path ?: ""

                if (dataItemPath.startsWith("/auth")) {
                    val token = DataMapItem.fromDataItem(event.dataItem)
                        .dataMap
                        .getString("token")
                    // Display an interstitial screen to notify the user that they're being signed
                    // in. Then, store the token and use it in network requests.
                    handleSignInSequence(token)
                }
            }
        }
    }

    /** placeholder sign in handler. */
    fun handleSignInSequence(token: String?) {}
}DataLayerService.kt

لمزيد من المعلومات حول استخدام طبقة بيانات الأجهزة القابلة للارتداء، يُرجى الاطّلاع على مقالة إرسال البيانات ومزامنتها على Wear OS.

استخدام OAuth 2.0

يتيح Wear OS استخدام مسارَين يستندان إلى OAuth 2.0، وهما موضّحان في الأقسام التالية:

منح رمز التفويض باستخدام مفتاح الحماية لتبادل الرموز (PKCE)، كما هو محدّد في RFC 7636
منح تفويض الجهاز (DAG)، كما هو محدّد في RFC 8628

Proof Key for Code Exchange (PKCE)

لاستخدام PKCE بفعالية، استخدِم RemoteAuthClient. بعد ذلك، لإجراء طلب مصادقة من تطبيق Wear OS إلى موفِّر OAuth، أنشئ عنصر OAuthRequest. يتكوّن هذا العنصر من عنوان URL لنقطة نهاية OAuth للحصول على رمز مميّز وعنصر CodeChallenge.

يوضّح الرمز التالي مثالاً على إنشاء طلب مصادقة:

val oauthRequest = OAuthRequest.Builder(context)
    .setAuthProviderUrl(uri)
    .setCodeChallenge(codeChallenge)
    .setClientId(CLIENT_ID)
    .build()OAuthPKCE.kt

بعد إنشاء طلب المصادقة، أرسِله إلى التطبيق المصاحب باستخدام طريقة sendAuthorizationRequest():

RemoteAuthClient.create(context).sendAuthorizationRequest(
    request = oauthRequest,
    executor = { command -> command?.run() },
    clientCallback = object : RemoteAuthClient.Callback() {
        override fun onAuthorizationResponse(
            request: OAuthRequest,
            response: OAuthResponse
        ) {
            // Extract the token from the response, store it, and use it in requests.
            continuation.resume(parseCodeFromResponse(response))
        }
        override fun onAuthorizationError(request: OAuthRequest, errorCode: Int) {
            // Handle Errors
            continuation.resume(Result.failure(IOException("Authorization failed")))
        }
    }
)OAuthPKCE.kt

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

بعد نجاح التفويض أو تعذّره، يعيد خادم OAuth 2.0 التوجيه إلى عنوان URL المحدّد في الطلب. إذا وافق المستخدم على طلب الوصول، سيحتوي الردّ على رمز تفويض. إذا لم يوافق المستخدم على الطلب، سيتضمّن الردّ رسالة خطأ.

يكون الردّ على شكل سلسلة طلب بحث ويشبه أحد الأمثلة التالية:

  https://wear.googleapis.com/3p_auth/com.your.package.name?code=xyz
  https://wear.googleapis-cn.com/3p_auth/com.your.package.name?code=xyz

يؤدي ذلك إلى تحميل صفحة توجّه المستخدم إلى التطبيق المصاحب الذي يتحقّق من عنوان URL للاستجابة وينقل الاستجابة إلى تطبيق Wear OS باستخدام واجهة برمجة التطبيقات onAuthorizationResponse.

يمكن لتطبيق الساعة الذكية بعد ذلك استبدال رمز التفويض برمز وصول.

منح إذن الجهاز

عند استخدام "منح إذن الجهاز"، يفتح المستخدم معرّف الموارد المنتظم (URI) الخاص بالتحقّق على جهاز آخر. بعد ذلك، يطلب خادم التفويض من المستخدم الموافقة على الطلب أو رفضه.

لتسهيل هذه العملية، استخدِم RemoteActivityHelper لفتح صفحة ويب على الجهاز الجوّال المقترن الخاص بالمستخدم، كما هو موضّح في المثال التالي:

// Request access from the authorization server and receive Device Authorization Response.
private fun verifyDeviceAuthGrant(verificationUri: String) {
    RemoteActivityHelper(context).startRemoteActivity(
        Intent(Intent.ACTION_VIEW).apply {
            addCategory(Intent.CATEGORY_BROWSABLE)
            data = Uri.parse(verificationUri)
        },
        null
    )
}OAuthDAG.kt

إذا كان لديك تطبيق iOS، استخدِم الروابط العامة لاعتراض هذا الطلب في تطبيقك بدلاً من الاعتماد على المتصفّح لمنح الإذن للرمز المميّز.