Переключение аккаунтов для iOS

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

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

В этом разделе описаны требования к дизайну и рекомендации для окна запроса доступа на связывание аккаунтов 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. Если App Flip не поддерживается, используется обычный протокол OAuth.
  2. В разделе Использовать приложение для связывания аккаунтов(необязательно) установите флажок Включить для iOS.
  3. Заполните поле Универсальная ссылка. Подробнее об универсальных ссылках см. Разрешение приложениям и веб-сайтам ссылаться на ваш контент.
  4. Если вы хотите настроить клиент, добавьте области действия и нажмите Добавить область действия в разделе Настройте клиент (необязательно).
  5. Нажмите Сохранить.

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

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

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

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

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

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

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

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

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

Ниже описаны шаги, которые выполняют приложение Google и ваше приложение при переключении аккаунтов.

  1. Приложение Google пытается открыть универсальную ссылку вашего приложения. Если приложение установлено на устройстве пользователя и связано с универсальной ссылкой, то оно откроется. Подробнее о поддержке универсальных ссылок…

  2. Приложение проверяет, соответствуют ли параметры client_id и redirect_uri, закодированные во входящем URL, ожидаемой универсальной ссылке Google.

  3. Приложение запрашивает код авторизации у сервера OAuth2. В конце этого процесса ваше приложение возвращает приложению Google код авторизации или ошибку. Для этого оно открывает универсальную ссылку Google с добавленными параметрами для кода авторизации или ошибки.

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

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

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

  1. Обработайте NSUserActivityTypeBrowsingWeb в делегате приложения.
  2. Извлеките из URL параметры redirect_uri и state, чтобы использовать их в дальнейшем.
  3. Убедитесь, что redirect_uri соответствует этому формату:
    https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
    https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
  4. Убедитесь, что идентификатор клиента соответствует ожидаемому значению. Используйте следующий пример кода:

    func application(_ application: UIApplication,
                     continue userActivity: NSUserActivity,
                     restorationHandler: @escaping ([Any]?) -> Void) -> Bool
    {
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
            let incomingURL = userActivity.webpageURL,
            let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
            let params = components.queryItems else {
                return false
        }
    
        if let clientId = params.filter({$0.name == "client_id"}).first?.value,
            let state = params.filter({$0.name == "state"}).first?.value,
            let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {
    
            // Save the redirect_uri and state for later...
    
            // Verify the client id
            return (clientId == GOOGLE_CLIENT_ID)
        } else {
            // Missing required parameters
            return false
        }
    }
    
  5. После успешной авторизации вызовите URI перенаправления с кодом авторизации. Используйте следующий пример кода:

    func returnAuthCode(code: String, state: String, redirectUri: String) {
        var redirectURL = URL(string: redirectUri)
        var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)
    
        // Return the authorization code and original state
        let paramAuthCode = URLQueryItem(name: "code", value: code)
        let paramState = URLQueryItem(name: "state", value: state)
        components?.queryItems = [paramAuthCode, paramState]
        if let resultURL = components?.url {
            UIApplication.shared.open(
                resultURL,
                options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
                completionHandler: nil)
        }
    }
    
  6. Если произошла ошибка, прикрепите к URI перенаправления результат ошибки. Используйте следующий пример кода:

    func returnError(redirectUri: String) {
        var redirectURL = URL(string: redirectUri)
        var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)
    
        // Return the authorization code and original state
        let paramError = URLQueryItem(name: "error", value: "invalid_request")
        let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
        components?.queryItems = [paramError, paramDescription]
        if let resultURL = components?.url {
            UIApplication.shared.open(
                resultURL,
                options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
                completionHandler: nil)
        }
    }
    

Когда универсальная ссылка открывается в приложении Google, она содержит следующие параметры запроса:

  • client_id (String) – client_id Google, зарегистрированный в вашем приложении.
  • scope (List of String) – список запрошенных областей действия, разделенных пробелами.
  • state (String) – одноразовый код, используемый Google для проверки того, что результат авторизации является ответом на исходящий запрос Google.
  • redirect_uri (String) – универсальная ссылка Google. URI для открытия приложения Google и передачи результатов.

Параметры, используемые при успешном возврате результата авторизации:

  • code (String) – значение кода авторизации, если он доступен.
  • state (String) – точное значение, полученное из входящей универсальной ссылки.

Параметры, используемые при неудачном возврате результата авторизации:

  • error (String) со следующими значениями:

    • cancelled – устранимая ошибка. Приложение Google попытается связать аккаунты, используя URL авторизации. Например, пользователь не может войти в систему, устройство находится в автономном режиме или истекло время ожидания подключения.
    • unrecoverable – неустранимая ошибка. Например, пользователь пытается связать аккаунты с отключенным аккаунтом.Приложение Google прервет связывание аккаунтов.
    • invalid_request: параметры запроса недействительны или отсутствуют. Эту ошибку можно устранить. Приложение Google попытается связать аккаунты, используя URL авторизации.
    • access_denied – пользователь отклонил запрос согласия. Это неисправимая ошибка, и приложение Google прерывает связывание.
  • error_description (String, необязательно): удобное сообщение об ошибке.

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

Измените конечную точку авторизации, чтобы она поддерживала переключение аккаунтов

Настройте платформу так, чтобы она принимала запросы, в которых используются URL переадресации Google для переключения аккаунтов:

  • Приложение Google Home
    https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
    https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
    https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
    https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
    https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
    https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast
    
  • Приложение "Google Ассистент"
    https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
    https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
    https://oauth-redirect.googleusercontent.com/a/com.google.OPA
    https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
    https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
    https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA
    

Для Google Home app (GHA) при связывании аккаунтов умного дома используются URL переадресации com.google.Chromecast. Убедитесь, что ваш сервер авторизации разрешает эти URL.

Убедитесь, что при получении запроса client_id и URL, указанный в параметре redirect_uri, соответствуют ожидаемым значениям. Если проверка клиента не удалась, верните ошибку invalid_request в redirect_uri.

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