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

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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

بعد تنفيذ بروتوكول OAuth 2.0، يمكنك اختياريًا إعداد الاستناد إلى OAuth App Flip , which allows your Android users to more quickly link their accounts in your authentication system to their Google accounts. The following sections describe how to design and implement App Flip for your smart home Action.

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

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

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

حتى تتمكّن من ضبط "قلب التطبيق"، عليك إجراء ما يلي:

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

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

  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 لاختبار "قلب التطبيق".

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

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

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

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