تطبيق App Flip لأجهزة Android

بعد تنفيذ OAuth 2.0، يمكنك اختياريًا ضبط App Flip المستند إلى OAuth، والذي يسمح لمستخدمي Android بربط حساباتهم في نظام المصادقة الخاص بك بحساباتهم على Google بسرعة أكبر. توضّح الأقسام التالية كيفية تصميم وتنفيذ App Flip لدمج Cloud-to-cloud على Android.

إرشادات التصميم

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

المتطلبات

1. يجب أن يتضمّن التطبيق بيانًا بشأن تخويل Google، مثل "بعد الربط، سيصبح بإمكان Google التحكّم في أجهزتك".
2. عليك توضيح أنّه سيتم ربط حساب المستخدم بحساب على Google، وليس بمنتج معيّن من Google، مثل Google Home أو "مساعد Google".
3. يجب تضمين عبارة واضحة تحثّ المستخدم على اتّخاذ إجراء في شاشة الموافقة، واستخدام عبارة "الموافقة والربط" لإجراء الربط. ويرجع ذلك إلى أنّ المستخدمين بحاجة إلى معرفة البيانات التي يُطلب منهم مشاركتها مع Google لربط حساباتهم.
4. يجب توفير طريقة للمستخدمين تتيح لهم الرجوع أو الرفض أو الإلغاء إذا اختاروا عدم الربط. استخدِم كلمة "إلغاء" للإشارة إلى إجراء الإلغاء.
5. يجب تنفيذ سير العمل التالي: بعد النقر على "الموافقة والربط"، يجب عرض رسالة تفيد بنجاح عملية الربط وإعادة توجيه المستخدم تلقائيًا إلى تطبيق Google Home. من المفترض أن يظهر للمستخدم الآن الجهاز المرتبط في تطبيق Google Home مع الإجراء الذي اتّخذته. بعد النقر على "إلغاء"، عليك إعادة توجيه المستخدم إلى تطبيق Google Home.

الاقتراحات

ننصحك باتّخاذ الإجراءات التالية:

1. عرض سياسة خصوصية Google تضمين رابط يؤدي إلى سياسة خصوصية Google في شاشة طلب الموافقة

2. البيانات التي ستتم مشاركتها استخدِم لغة واضحة وموجزة لتوضيح البيانات التي تطلبها Google من المستخدمين وسبب طلبها.

3. إمكانية إلغاء الربط: توفير آلية للمستخدمين لإلغاء الربط، مثل عنوان URL يؤدي إلى إعدادات حساباتهم على منصتك بدلاً من ذلك، يمكنك تضمين رابط يؤدي إلى حساب Google حيث يمكن للمستخدمين إدارة حساباتهم المرتبطة.

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

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

5. تضمين شعارك: عرض شعار شركتك على شاشة الموافقة استخدِم إرشادات الأسلوب لتحديد موضع شعارك. إذا كنت تريد عرض شعار Google أيضًا، يُرجى الاطّلاع على الشعارات والعلامات التجارية.

إعداد App Flip المستند إلى OAuth

توضّح الأقسام التالية المتطلبات الأساسية لميزة "ربط التطبيقات بسرعة" المستندة إلى بروتوكول OAuth وكيفية ضبط مشروع "ربط التطبيقات بسرعة" في Google Home Developer Console.

إنشاء عملية دمج من السحابة الإلكترونية إلى السحابة الإلكترونية وإعداد خادم OAuth 2.0

قبل أن تتمكّن من ضبط App Flip، عليك إجراء ما يلي:

• إعداد خادم OAuth 2.0 لمزيد من المعلومات حول إعداد خادم OAuth، يُرجى الاطّلاع على مقالة تنفيذ خادم OAuth 2.0.
• إنشاء عملية دمج من السحابة الإلكترونية إلى السحابة الإلكترونية لإنشاء عملية تكامل، اتّبِع التعليمات الواردة في إنشاء عملية تكامل من السحابة الإلكترونية إلى السحابة الإلكترونية.

ضبط ميزة "ربط التطبيقات بسرعة" في Developer Console

يوضّح القسم التالي كيفية ضبط ميزة "ربط التطبيقات بسرعة" في Developer Console.

1. املأ جميع الحقول المطلوبة(*) ضمن ربط الحساب. (إذا لم تكن ميزة ربط التطبيقات بسرعة متاحة، يتم استخدام بروتوكول OAuth العادي كخيار بديل).
2. أدخِل عنوان URL في حقل عنوان URL الخاص بالتنفيذ في السحابة الإلكترونية. يُستخدم عنوان URL لتنفيذ الطلبات في السحابة الإلكترونية لمعالجة طلبات المنزل المزوّد بأجهزة ذكية. اطّلِع على تنفيذ الطلبات المحلية.
3. ضمن ربط التطبيقات بسرعة (اختياري)، ضَع علامة في المربّع بجانب تطبيق Android.
4. املأ الحقول التالية:
• معرّف التطبيق: معرّف التطبيق هو معرّف فريد تضبطه لتطبيقك.
• توقيع التطبيق: يجب "توقيع" تطبيقات Android باستخدام شهادة مفتاح عام قبل أن يتم تثبيتها. للحصول على معلومات حول الحصول على توقيع تطبيقك، يُرجى الاطّلاع على مصادقة العميل.
• Authorization intent. في هذا الحقل، أدخِل سلسلة تحدّد إجراء intent.
5. إذا أردت ضبط عميلك اختياريًا، أضِف النطاقات وانقر على إضافة نطاق ضمن النطاقات (اختياري).
6. إذا كان العميل يتطلّب ذلك، اختَر السماح لـ Google بإرسال معرّف العميل والسرّ عبر عنوان المصادقة الأساسي لبروتوكول HTTP.

يمكنك الآن الانتقال إلى القسم التالي لتنفيذ App Flip في تطبيق Android.

تنفيذ App Flip في تطبيقاتك الأصلية

لتنفيذ App Flip، عليك تعديل رمز تفويض المستخدم في تطبيقك لقبول رابط عميق من Google.

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

في هذا المستند، ستتعرّف على كيفية تعديل تطبيق Android لإتاحة ميزة "ربط التطبيقات بسرعة".

تجربة النموذج

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

تم ضبط نموذج التطبيق مسبقًا ليتكامل مع أداة اختبار ميزة "ربط التطبيقات بسرعة" لنظام التشغيل Android، والتي يمكنك استخدامها للتحقّق من تكامل تطبيق Android مع ميزة "ربط التطبيقات بسرعة" قبل ضبط ربط الحساب مع Google. يحاكي هذا التطبيق الطلب الذي يتم تشغيله بواسطة تطبيقات Google للأجهزة الجوّالة عند تفعيل ميزة "ربط التطبيقات بسرعة".

آلية العمل

يجب اتّباع الخطوات التالية لتنفيذ عملية دمج ميزة "ربط التطبيقات بسرعة":

1. يتحقّق تطبيق Google مما إذا كان تطبيقك مثبّتًا على الجهاز باستخدام اسم الحزمة.
2. يستخدم تطبيق Google عملية التحقّق من توقيع الحزمة للتأكّد من أنّ التطبيق المثبّت هو التطبيق الصحيح.
3. ينشئ تطبيق Google نية لبدء نشاط محدّد في تطبيقك. تتضمّن هذه النية بيانات إضافية مطلوبة للربط. ويتحقّق أيضًا مما إذا كان تطبيقك يتيح ميزة "ربط التطبيقات بسرعة" من خلال حلّ هذا الغرض من خلال إطار عمل Android.
4. يتحقّق تطبيقك من أنّ الطلب وارد من تطبيق Google، وذلك من خلال التحقّق من توقيع الحزمة ومعرّف العميل المقدَّم.
5. يطلب تطبيقك رمز تفويض من خادم OAuth 2.0. في نهاية هذا المسار، يتم عرض رمز تفويض أو رسالة خطأ في تطبيق Google.
6. يستردّ تطبيق Google النتيجة ويواصل عملية ربط الحساب. في حال تقديم رمز تفويض، يتم تبادل الرموز المميزة بين الخوادم، بالطريقة نفسها التي يتم بها في مسار ربط OAuth المستند إلى المتصفّح.

تعديل تطبيق Android لإتاحة ميزة "ربط التطبيقات بسرعة"

لإتاحة ميزة ربط التطبيقات بسرعة، عليك إجراء التغييرات التالية على الرمز البرمجي لتطبيق Android:

1. أضِف <intent-filter> إلى ملف AndroidManifest.xml مع سلسلة إجراءات تتطابق مع القيمة التي أدخلتها في حقل ربط التطبيقات بسرعة Intent.

   <activity android:name="AuthActivity">
     <!-- Handle the app flip intent -->
     <intent-filter>
       <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
       <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
   </activity>
   

2. التحقّق من صحة توقيع تطبيق الاتصال

   يجب مطابقة اسم الحزمة وتوقيعها لأي تطبيقات Google قد يستخدمها المستخدمون لربط الحسابات. على سبيل المثال، للربط بتطبيقَي Google Home و"بحث Google"، أضِف أسماء الحزم والتوقيعات الخاصة بهما:

   • اسم الحزمة: com.google.android.apps.chromecast.app
   • شهادة التسلسل الأصلي لـ SHA-256: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
   • شهادة SHA-256 التي تم تدويرها لميزة "توقيع التطبيق" من Play: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

   و

   • اسم الحزمة: com.google.android.googlequicksearchbox
   • التوقيع: F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

   يتم إرسال طلبات ربط الأجهزة المنزلية المزوّدة بأجهزة ذكية مباشرةً من قِبل Google Home app (GHA). إذا كان تطبيقك يفرض قيودًا على المتصلين وكان يسمح في السابق بتطبيق "بحث Google" فقط، عليك إضافة com.google.android.apps.chromecast.app وشهادات SHA-256 الخاصة به إلى القائمة المسموح بها لكي تستمر ميزة "ربط التطبيقات بسرعة" في العمل بنجاح.

   private fun verifyFingerprint(
       expectedPackage: String,
       expectedFingerprints: List<String>
   ): Boolean {
       val callingPackage = callingActivity?.packageName ?: return false
       if (callingPackage != expectedPackage) return false
       return expectedFingerprints.any { hex ->
           val sha256Bytes =
               hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
           packageManager.hasSigningCertificate(
               callingPackage,
               sha256Bytes,
               PackageManager.CERT_INPUT_SHA256
           )
       }
   }
   

3. استخرِج معرِّف العميل من مَعلمات intent وتأكَّد من أنّ معرِّف العميل يتطابق مع القيمة المتوقّعة.

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
   // Original lineage certificate (3D:7A...) and active rotated
   // Play App Signing certificate (5A:AD...)
   private val EXPECTED_FINGERPRINTS = listOf(
       "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
       "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
   )
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {
   
           // ...authorize the user...
       }
   }
   

4. بعد الحصول على التفويض بنجاح، أرسِل رمز التفويض الناتج إلى Google.

   // Successful result
   val data = Intent().apply {
       putExtra("AUTHORIZATION_CODE", authCode)
   }
   setResult(Activity.RESULT_OK, data)
   finish()
   

5. في حال حدوث خطأ، يمكنك عرض نتيجة خطأ بدلاً من ذلك.

   // Error result
   val error = Intent().apply {
       putExtra("ERROR_TYPE", 1)
       putExtra("ERROR_CODE", 1)
       putExtra("ERROR_DESCRIPTION", "Invalid Request")
   }
   setResult(-2, error)
   finish()
   

محتوى نية التشغيل

يتضمّن Android intent الذي يشغّل تطبيقك الحقول التالية:

• ‫CLIENT_ID (String): تم تسجيل client_id Google ضمن تطبيقك.
• ‫SCOPE (String[]): قائمة بالنطاقات المطلوبة
• ‫REDIRECT_URI (String): عنوان URL لإعادة التوجيه

محتوى بيانات الاستجابة

يتم ضبط البيانات التي يتم عرضها في تطبيق Google في تطبيقك من خلال طلب setResult(). وتشمل هذه البيانات ما يلي:

• ‫AUTHORIZATION_CODE (String): قيمة رمز التفويض
• ‫resultCode (int): تشير إلى نجاح العملية أو فشلها، وتأخذ إحدى القيم التالية:
  • ‫Activity.RESULT_OK: يشير إلى النجاح، ويتم عرض رمز تفويض.
  • ‫Activity.RESULT_CANCELLED: خطأ يمكن إصلاحه يشير إلى أنّ المستخدم قد ألغى العملية. في هذه الحالة، سيحاول تطبيق Google ربط الحساب مرة أخرى باستخدام عنوان URL الخاص بالتفويض.
  • ‫-2: يشير إلى حدوث خطأ. يتم وصف أنواع مختلفة من الأخطاء أدناه.
• ‫ERROR_TYPE (int): نوع الخطأ، ويأخذ إحدى القيم التالية:
  • 1: خطأ يمكن إصلاحه: سيحاول تطبيق Google ربط الحساب باستخدام عنوان URL الخاص بالمصادقة.
  • ‫2: خطأ غير قابل للإصلاح: يوقف تطبيق Google عملية ربط الحساب.
  • ‫3: مَعلمات الطلب غير صالحة أو غير متوفّرة.
• ‫ERROR_CODE (int): عدد صحيح يمثّل طبيعة الخطأ. لمعرفة معنى كل رمز خطأ، يُرجى الرجوع إلى جدول رموز الأخطاء.

• ‫ERROR_DESCRIPTION (String، اختياري): رسالة حالة يمكن لشخص عادي قراءتها تصف الخطأ.

يجب إدخال قيمة للسمة AUTHORIZATION_CODE عندما تكون السمة resultCode == Activity.RESULT_OK. في جميع الحالات الأخرى، يجب أن تكون قيمة AUTHORIZATION_CODE فارغة. إذا كانت السمة resultCode == -2، من المتوقّع أن تتم تعبئة القيمة ERROR_TYPE.

جدول رموز الخطأ

يعرض الجدول أدناه رموز الأخطاء المختلفة وما إذا كان كل منها خطأ قابلاً للإصلاح أو خطأ غير قابل للإصلاح:

رمز الخطأ	المعنى	قابلة للاسترداد	غير قابل للاسترداد
1	INVALID_REQUEST	✔
2	NO_INTERNET_CONNECTION		✔
3	OFFLINE_MODE_ACTIVE	✔
4	CONNECTION_TIMEOUT	✔
5	INTERNAL_ERROR	✔
6	AUTHENTICATION_SERVICE_UNAVAILABLE		✔
8	CLIENT_VERIFICATION_FAILED	✔
9	INVALID_CLIENT	✔
10	INVALID_APP_ID	✔
11	INVALID_REQUEST	✔
12	AUTHENTICATION_SERVICE_UNKNOWN_ERROR		✔
13	AUTHENTICATION_DENIED_BY_USER		✔
14	CANCELLED_BY_USER		✔
15	FAILURE_OTHER		✔
16	USER_AUTHENTICATION_FAILED	✔

بالنسبة إلى جميع رموز الخطأ، يجب عرض نتيجة الخطأ من خلال setResult لضمان تفعيل الإجراء الاحتياطي المناسب.

اختبار App Flip على جهازك

بعد إنشاء عملية دمج من السحابة الإلكترونية إلى السحابة الإلكترونية وضبط ميزة "ربط التطبيقات بسرعة" في وحدة التحكّم وفي تطبيقك، يمكنك اختبار ميزة "ربط التطبيقات بسرعة" على جهازك الجوّال. يمكنك استخدام تطبيق Google Home لاختبار ميزة "ربط التطبيقات بسرعة".

لاختبار "App Flip" من تطبيق "Google Home"، يُرجى اتّباع الخطوات التالية:

1. انتقِل إلى Developer Console واختَر مشروعك.
2. انتقِل إلى من السحابة الإلكترونية إلى السحابة الإلكترونية > اختبار.
3. ابدأ عملية ربط الحساب من تطبيق Home:
1. افتح Google Home app (GHA).
2. انقر على الزر +.
3. انقر على إعداد الجهاز.
4. انقر على هل لديك أجهزة سبق وتمّ إعدادها؟
5. اختَر عملية الدمج من السحابة الإلكترونية إلى السحابة الإلكترونية من قائمة مقدّمي الخدمات. وسيتم إضافة بادئة "[اختبار]" في القائمة. عند اختيار عملية الدمج [الاختبارية] من القائمة، من المفترض أن يفتح تطبيقك.
6. تأكَّد من تشغيل تطبيقك وابدأ باختبار عملية التفويض.