App Flip для Android

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

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

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

Требования

  1. Вам потребуется подтверждение авторизации от Google, например: «После установления соединения Google получит разрешение на управление вашими устройствами».
  2. Необходимо сообщить пользователю, что его учетная запись привязывается к Google, а не к конкретному продукту Google, такому как Google Home или Google Assistant.
  3. На экране согласия необходимо четко сформулировать призыв к действию и использовать формулировку «Согласен и связал» для обозначения действия по связыванию. Это необходимо, поскольку пользователи должны понимать, какие данные им необходимо предоставить Google для связывания своих учетных записей.
  4. Необходимо предоставить пользователям возможность вернуться назад, отклонить или отменить действие, если они решат не переходить по ссылке. Для отмены используйте словосочетание «Отмена».
  5. Необходимо реализовать следующий алгоритм действий: после нажатия кнопки «Согласиться и связать» необходимо отобразить сообщение об успешном связывании и автоматически перенаправить пользователя обратно в приложение Google Home. Теперь пользователь должен увидеть связанное устройство в приложении Google Home после выполнения вашего действия. После нажатия кнопки «Отмена» необходимо перенаправить пользователя обратно в приложение Google Home.

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

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

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

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

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

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

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

Попробуйте пример

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

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

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

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

  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, которое запускает ваше приложение, включает следующие поля:

  • 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. Убедитесь, что приложение запущено, и начните тестирование процесса авторизации.
Назад
Как создать интеграцию между облачными сервисами
Далее
iOS