App Flip для Android

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

Рекомендации по проектированию

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

Требования

  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, ознакомьтесь с разделом Логотипы и товарные знаки.

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

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

В следующих разделах описаны предварительные требования для переключения аккаунтов на основе OAuth и настройка проекта переключения аккаунтов в Google Home Developer Console.

Создайте интеграцию типа "облако – облако" и настройте сервер OAuth 2.0

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

Как настроить переключение аккаунтов в Developer Console

В этом разделе описывается, как настроить переключение аккаунтов в Developer Console.

  1. Заполните все обязательные(*) поля в разделе Связывание аккаунтов. Если переключение аккаунтов не поддерживается, используется стандартный протокол OAuth.
  2. Укажите URL в поле Cloud fulfillment URL (URL выполнения в облаке). URL выполнения в облаке используется для обработки намерений умного дома. Проверьте выполнение на локальном устройстве.
  3. В разделе App Flip (optional) (Переключение аккаунтов (необязательно)) установите флажок Android app (Приложение для Android).
  4. Заполните следующие поля:
    • Идентификатор приложения. Идентификатор приложения – это уникальный идентификатор, который вы задаете для своего приложения.
    • Подпись приложения. Прежде чем приложение для Android можно будет установить, оно должно быть подписано сертификатом открытого ключа. О том, как получить цифровую подпись приложения, можно прочитать в разделе об аутентификации клиентов.
    • Намерение авторизации. В этом поле укажите строку, которая определяет действие намерения.
  5. Если вы хотите настроить клиент, добавьте области действия и нажмите Добавить область действия в разделе Области действия (необязательно).
  6. Если это требуется клиенту, установите флажок Передавать идентификатор клиента и секретный код через заголовок базовой аутентификации HTTP.

Теперь вы можете перейти к следующему разделу, чтобы реализовать App Flip в приложении Android.

Как реализовать App Flip в нативных приложениях

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

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

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

Попробовать пример

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

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

Принцип работы

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

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

Как изменить приложение для Android, чтобы оно поддерживало переключение аккаунтов

Чтобы обеспечить поддержку переключения аккаунтов, внесите в код приложения для 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. Проверьте подпись вызывающего приложения.

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

    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): Google client_id, зарегистрированный в вашем приложении.
  • 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, необязательный): человекочитаемое сообщение о статусе, описывающее ошибку.

Если resultCode == Activity.RESULT_OK, необходимо указать значение для атрибута AUTHORIZATION_CODE. Во всех остальных случаях значение 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 на своем устройстве

Теперь, когда вы создали интеграцию Cloud-to-cloud и настроили переключение аккаунтов в консоли и в приложении, вы можете протестировать переключение аккаунтов на мобильном устройстве. Протестировать переключение аккаунтов можно в приложении Google Home.

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

  1. Откройте Developer Console и выберите проект.
  2. Перейдите в раздел Cloud-to-cloud > Test (Облако-облако > Тестирование).
  3. Запустите процесс связывания аккаунтов в приложении Google Home:
    1. Откройте Google Home app (GHA).
    2. Нажмите кнопку +.
    3. Нажмите Настроить устройство.
    4. Нажмите Ранее настроенные устройства.
    5. Выберите интеграцию в списке поставщиков. В списке перед его названием будет указано "[test]". Если вы выберете тестовую интеграцию из списка, должно открыться ваше приложение.
    6. Убедитесь, что приложение запущено, и начните тестирование процесса авторизации.