مرحبًا بك في "مركز مطوّري Google Home"، الوجهة الجديدة لتعلّم كيفية تطوير المهام المنزلية الذكية. ملاحظة: ستواصل إنشاء إجراءات في "وحدة تحكّم المهام".

التطبيق العكسي لنظام التشغيل Android

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

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

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

المتطلّبات

  1. يجب إعلام المستخدم بأنّه تم ربط حساب Google، وليس بمنتج معيّن من منتجات Google، مثل Google Home أو "مساعد Google ".

الاقتراحات

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

  1. عرض سياسة خصوصية Google: أدرِج رابطًا يؤدي إلى سياسة خصوصية Google على شاشة الموافقة.

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

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

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

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

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

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

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

يعرض هذا الشكل مثالاً على شاشة الموافقة مع توفير وسائل شرح للمتطلبات والاقتراحات الفردية التي يجب اتّباعها عند تصميم شاشة موافقة المستخدم.
الشكل 1: إرشادات تصميم شاشة الموافقة لربط الحساب

إعداد ميزة "قلب التطبيقات" المستندة إلى بروتوكول OAuth

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

إنشاء إجراء منزلي ذكي وإعداد خادم OAuth 2.0

قبل ضبط تطبيق App Flip، عليك تنفيذ ما يلي:

ضبط عملية قلب التطبيق في وحدة تحكّم المهام

يوضّح القسم التالي كيفية ضبط ميزة "قلب التطبيقات" في وحدة تحكّم الإجراءات.

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

تنفيذ ميزة "قلب التطبيقات" في تطبيقات Android

لتطبيق ميزة "قلب التطبيقات"، يجب تعديل رمز تفويض المستخدم في تطبيقك لقبول رابط لصفحة في التطبيق من Google.

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

في هذا المستند، ستتعرّف على كيفية تعديل تطبيق Android المتوافق مع التطبيق Flip.

جرّب النموذج

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

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

آلية العمل

يجب اتّباع الخطوات التالية لتنفيذ عملية الدمج بين App Flip:

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

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

إذا أردت استخدام App Flip، عليك إجراء التغييرات التالية على الرمز في تطبيقك المتوافق مع Android:

  1. أضِف <intent-filter> إلى ملف AndroidManifest.xml باستخدام سلسلة إجراءات تطابق القيمة التي أدخلتها في الحقل App Flip 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. التحقّق من توقيع تطبيق الاتصال

    private fun verifyFingerprint(
        expectedPackage: String,
        expectedFingerprint: String,
        algorithm: String
): Boolean {

    callingActivity?.packageName?.let {
        if (expectedPackage == it) {
            val packageInfo =
                packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
            val signatures = packageInfo.signatures
            val input = ByteArrayInputStream(signatures[0].toByteArray())

            val certificateFactory = CertificateFactory.getInstance("X509")
            val certificate =
                certificateFactory.generateCertificate(input) as X509Certificate
            val md = MessageDigest.getInstance(algorithm)
            val publicKey = md.digest(certificate.encoded)
            val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }

            return (expectedFingerprint == fingerprint)
        }
    }
    return false
}

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

    private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
private const val EXPECTED_PACKAGE = "<google-app-package-name>"
private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
private const val ALGORITHM = "SHA-256"
...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {

        // ...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 الذي يشغِّل تطبيقك الحقول التالية:

  • 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 لضمان تشغيل الإجراء الاحتياطي المناسب.

اختبار قلب التطبيق على جهازك

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

لاختبار ميزة "قلب التطبيقات" من تطبيق "مساعد Google"، اتّبِع الخطوات التالية:

  1. انتقِل إلى وحدة تحكُّم الإجراءات واختَر مشروعك.
  2. انقر على اختبار في شريط التنقّل بأعلى الصفحة.
  3. يمكنك بدء مسار ربط الحساب من تطبيق "مساعد Google":
    1. افتح تطبيق "مساعد Google".
    2. انقر على الإعدادات.
    3. في علامة التبويب "مساعد Google"، انقر على إدارة آلية للمنزل.
    4. انقر على إضافة(+).
    5. اختَر "الإجراء" من قائمة مقدّمي الخدمة. وستتم إضافة البادئة [test] إلى القائمة في القائمة. عند اختيار الإجراء [test] من القائمة، من المفترض أن يفتح التطبيق.
    6. تحقّق من أنه تم إطلاق تطبيقك وابدأ في اختبار مسار التفويض.

لاختبار ميزة "قلب التطبيقات" من تطبيق Home، اتّبِع الخطوات التالية:

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