Приложение Флип для Android

Если у вас есть реализация OAuth 2.0, вы можете дополнительно настроить App Flip на основе OAuth, что позволит вашим пользователям Android быстрее связать свои учетные записи в вашей системе аутентификации со своими учетными записями Google. В следующих разделах описывается, как спроектировать и внедрить App Flip для вашего smart home .

Design guidelines

This section describes the design requirements and recommendations for the App Flip account linking consent screen. After Google calls your app, your app displays the consent screen to the user.

Requirements

  1. You must communicate that the user's account is being linked to Google, not to a specific Google product, such as Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

  1. Display Google's Privacy Policy. Include a link to Google's Privacy Policy on the consent screen.

  2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

  3. Clear call-to-action. State a clear call-to-action on your consent screen, such as "Agree and link." This is because users need to understand what data they're required to share with Google to link their accounts.

  4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

  5. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

  6. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

    • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.

  7. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

This figure shows an example consent screen with call-outs to the individual requirements and recommendations to be followed when you design a user consent screen.
Figure 1: Account linking consent screen design guidelines.

Настройка App Flip на основе OAuth

В следующих разделах описываются предварительные требования для App Flip на основе OAuth и способы настройки проекта App Flip в консоли действий.

Создайте действие «умный дом» и настройте сервер OAuth 2.0.

Прежде чем вы сможете настроить App Flip, вам необходимо сделать следующее:

Настройте App Flip в консоли действий.

В следующем разделе описывается, как настроить App Flip в консоли действий .

  1. Заполните все поля под информацией о клиенте OAuth. (Если App Flip не поддерживается, в качестве запасного варианта используется обычный OAuth.)
  2. В разделе Использовать приложение для привязки аккаунта (необязательно) установите флажок Включить для Android.
  3. Заполните следующие поля:
    • Идентификатор приложения. Идентификатор приложения — это уникальный идентификатор, который вы устанавливаете для своего приложения.
    • Подпись приложения. Приложения для Android должны быть «подписаны» сертификатом открытого ключа, прежде чем их можно будет установить. Сведения о получении подписи вашего приложения см. в разделе Аутентификация вашего клиента .
    • Цель авторизации. В этом поле введите строку, определяющую ваше намерение.
  4. Если вы хотите дополнительно настроить клиент, добавьте области и щелкните Добавить область в разделе Настроить клиент (необязательно).
  5. Щелкните Сохранить.

Реализуйте App Flip в своих приложениях для Android

Чтобы внедрить App Flip, вам нужно изменить код авторизации пользователя в вашем приложении, чтобы он принимал ссылку на контент от Google.

Связывание App Flip на основе OAuth (App Flip) вставляет ваше Android-приложение в процесс связывания аккаунта Google. Традиционный процесс привязки учетной записи требует, чтобы пользователь ввел свои учетные данные в браузере. Использование App Flip откладывает вход пользователя в ваше приложение для Android, что позволяет вам использовать существующие авторизации. Если пользователь вошел в ваше приложение, ему не нужно повторно вводить свои учетные данные, чтобы связать свою учетную запись. Для реализации App Flip в вашем приложении для Android требуется минимальное количество изменений кода.

В этом документе вы узнаете, как изменить приложение Android для поддержки App Flip.

Попробуйте образец

Пример приложения для связывания App Flip демонстрирует совместимую с App Flip интеграцию связывания учетных записей на Android. Вы можете использовать это приложение, чтобы проверить, как реагировать на входящие намерения App Flip из мобильных приложений Google.

Образец приложения предварительно настроен для интеграции с инструментом тестирования App Flip для Android , который можно использовать для проверки интеграции вашего приложения Android с App Flip перед настройкой привязки учетной записи к Google. Это приложение имитирует намерение, инициируемое мобильными приложениями Google, когда включен App Flip.

Как это работает

Для интеграции App Flip необходимы следующие шаги:

  1. Приложение Google проверяет, установлено ли ваше приложение на устройстве, используя имя пакета .
  2. Приложение Google использует проверку подписи пакета, чтобы убедиться, что установленное приложение является правильным приложением.
  3. Приложение Google формирует намерение начать определенное действие в вашем приложении. Это намерение включает дополнительные данные, необходимые для связывания. Он также проверяет, поддерживает ли ваше приложение App Flip, разрешая это намерение через инфраструктуру Android.
  4. Ваше приложение подтверждает, что запрос исходит от приложения Google. Для этого ваше приложение проверяет подпись пакета и предоставленный идентификатор клиента.
  5. Ваше приложение запрашивает код авторизации с вашего сервера OAuth 2.0. В конце этого потока он возвращает либо код авторизации, либо ошибку в приложение Google.
  6. Приложение Google получает результат и продолжает привязку аккаунта. Если предоставлен код авторизации, обмен токенами происходит между серверами так же, как и в процессе связывания OAuth на основе браузера.

Измените свое приложение для Android, чтобы оно поддерживало App Flip

Для поддержки 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. Извлеките идентификатор клиента из параметров намерения и убедитесь, что идентификатор клиента соответствует ожидаемому значению.

    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 , чтобы обеспечить запуск соответствующего отката.

Протестируйте приложение Flip на своем устройстве

Теперь, когда вы создали действие и настроили App Flip на консоли и в своем приложении, вы можете протестировать App Flip на своем мобильном устройстве. Вы можете использовать приложение Google Assistant или приложение Google Home, чтобы протестировать App Flip.

Чтобы протестировать App Flip из приложения Assistant, выполните следующие действия:

  1. Перейдите в консоль Actions и выберите свой проект.
  2. Нажмите «Тест» в верхней части навигации.
  3. Запустите процесс привязки учетной записи из приложения Assistant:
    1. Откройте приложение Google Ассистент .
    2. Щелкните Настройки .
    3. На вкладке «Помощник» нажмите «Управление домом».
    4. Нажмите Добавить(+) .
    5. Выберите действие из списка поставщиков. Он будет иметь префикс «[test]» в списке. Когда вы выбираете действие [test] из списка, оно должно открыть ваше приложение.
    6. Убедитесь, что ваше приложение запущено, и начните тестирование процесса авторизации.

Чтобы протестировать App Flip из приложения Home, выполните следующие действия:

  1. Перейдите в консоль Actions и выберите свой проект.
  2. Нажмите «Тест» в верхней части навигации.
  3. Запустите процесс привязки учетной записи из приложения Home:
    1. Откройте приложение Google Home .
    2. Нажмите кнопку + .
    3. Щелкните Настроить устройство .
    4. Нажмите Что-то уже настроено?
    5. Выберите действие вашего умного дома из списка провайдеров. Он будет иметь префикс «[test]» в списке. Когда вы выбираете действие [test] из списка, оно должно открыть ваше приложение.
    6. Убедитесь, что ваше приложение запущено, и начните тестирование процесса авторизации.
Назад
Создать проект действий
Далее
Определить и синхронизировать