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

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

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

يقدّم هذا الدليل تعليمات حول طريقة المصادقة المقترَحة لتطبيقات Wear OS، وهي "إدارة بيانات الاعتماد".

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

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

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

وضع الضيف

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

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

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

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

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

val wristDetectionEnabled =
        isWristDetectionAutoLockingEnabled(applicationContext)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ضبط إعدادات الميزة

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

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

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

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

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

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

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

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

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

yourCoroutineScope.launch {
    try {
      val response = credentialManager.getCredential(activity, request)
      signInWithCredential(response.credential)
    } catch (e: GetCredentialCancellationException) {
      navigateToFallbackAuthMethods()
    }
}

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

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

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

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

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

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

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

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

val dataClient: DataClient = Wearable.getDataClient(context)
dataClient.addListener{ dataEvents ->
    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.
            }
        }
    }
}

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

استخدام بروتوكول OAuth 2.0

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

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

مفتاح الحماية لتبادل الرموز (PKCE)

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

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

val request = OAuthRequest.Builder(this.applicationContext)
    .setAuthProviderUrl(Uri.parse("https://...."))
    .setClientId(clientId)
    .setCodeChallenge(codeChallenge)
    .build()

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

val client = RemoteAuthClient.create(this)
client.sendAuthorizationRequest(request,
    { command -> command?.run() },
    object : RemoteAuthClient.Callback() {
        override fun onAuthorizationResponse(
            request: OAuthRequest,
            response: OAuthResponse
        ) {
            // Extract the token from the response, store it, and use it in
            // network requests.
        }

        override fun onAuthorizationError(errorCode: Int) {
            // Handle any errors.
        }
    }
)

يؤدي هذا الطلب إلى بدء مكالمة مع التطبيق المصاحب، الذي يعرض بعد ذلك واجهة مستخدم خاصة بالتفويض في متصفّح الويب على هاتف المستخدم الجوّال. يصادق موفّر 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.

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

منح إذن الوصول إلى الجهاز

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

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

// Request access from the authorization server and receive Device Authorization
// Response.
val verificationUri = "..." // Extracted from the Device Authorization Response.
RemoteActivityHelper.startRemoteActivity(
    this,
    Intent(Intent.ACTION_VIEW)
        .addCategory(Intent.CATEGORY_BROWSABLE)
        .setData(Uri.parse(verificationUri)),
    null
)
// Poll the authorization server to find out if the user completed the user
// authorization step on their mobile device.

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

التوقّف عن استخدام ميزة "تسجيل الدخول باستخدام حساب Google" القديمة

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

ملاحظة: إنّ إصدار واجهة برمجة التطبيقات Credential Manager من ميزة "تسجيل الدخول باستخدام حساب Google" غير متاح مؤقتًا على أجهزة Wear OS التي تعمل بالإصدار Wear OS 3 (المستوى 30 من واجهة برمجة التطبيقات). إذا طلب تطبيق استخدام واجهة برمجة التطبيقات Credential Manager على جهاز لا يتوافق معها، سيؤدي ذلك إلى ظهور الخطأ NoCredentialException في عملية GetCredential، ما يشير عادةً إلى عدم توفّر بيانات اعتماد على جهاز المستخدم للتطبيق الذي يطلب استخدام واجهة برمجة التطبيقات.

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

// Define a basic SDK check.
fun isCredentialManagerAvailable(): Boolean {
 return android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.VANILLA_ICE_CREAM
}

// Elsewhere in the code, use it to selectively disable the legacy option.
Button(
  onClick = {
    if (isCredentialManagerAvailable()) {
      Log.w(TAG, "Devices on API level 35 or higher should use
                  Credential Manager for Sign in with Google")
    } else {
      navigateToSignInWithGoogle()
    }},
  enabled = !isCredentialManagerAvailable(),
  label = { Text(text = stringResource(R.string.sign_in_with_google)) },
  secondaryLabel = { Text(text = "Disabled on API level 35+")
  }
)