Добро пожаловать в Центр разработчиков Google Home, новое место, где можно научиться разрабатывать действия для умного дома. Примечание. Вы продолжите создавать действия в консоли действий.

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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Рекомендации по дизайну

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

Требования

  1. Вы должны сообщить, что учетная запись пользователя связана с Google, а не с конкретным продуктом Google, таким как Google Home или Google Assistant.

Рекомендации

Мы рекомендуем вам сделать следующее:

  1. Показать Политику конфиденциальности Google. Включите ссылку на Политику конфиденциальности Google на экране согласия.

  2. Данные для совместного использования. Используйте четкий и лаконичный язык, чтобы сообщить пользователю, какие данные требуются Google и почему.

  3. Четкий призыв к действию. Сформулируйте четкий призыв к действию на экране согласия, например «Согласиться и связать». Это связано с тем, что пользователи должны понимать, какими данными они должны делиться с Google, чтобы связать свои учетные записи.

  4. Возможность отмены. Предоставьте пользователям возможность вернуться или отменить, если они решат не связываться.

  5. Возможность отвязать. Предложите пользователям механизм отмены связи, например URL-адрес их настроек учетной записи на вашей платформе. Кроме того, вы можете включить ссылку на учетную запись Google , где пользователи могут управлять своей связанной учетной записью.

  6. Возможность смены учетной записи пользователя. Предложите пользователям способ переключения их учетных записей. Это особенно полезно, если пользователи склонны иметь несколько учетных записей.

    • Если пользователю необходимо закрыть экран согласия для переключения учетных записей, отправьте в Google устранимую ошибку, чтобы пользователь мог войти в нужную учетную запись с помощью привязки OAuth и неявного потока.
  7. Включите свой логотип. Отобразите логотип вашей компании на экране согласия. Используйте свои рекомендации по стилю, чтобы разместить свой логотип. Если вы хотите также отобразить логотип Google, см. раздел Логотипы и товарные знаки .

На этом рисунке показан пример экрана согласия с выносками отдельных требований и рекомендаций, которым необходимо следовать при разработке экрана согласия пользователя.
Рис. 1. Рекомендации по оформлению экрана согласия на привязку учетной записи.

Настройка 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. Убедитесь, что ваше приложение запущено, и начните тестирование процесса авторизации.