Odwracanie aplikacji na iOS

Po wdrożeniu protokołu OAuth 2.0 możesz opcjonalnie skonfigurować App Flip oparty na protokole OAuth, który umożliwia użytkownikom iOS szybsze łączenie kont w Twoim systemie uwierzytelniania z kontami Google. W sekcjach poniżej opisano, jak zaprojektować i wdrożyć App Flip na potrzeby integracji Cloud-to-cloud na iOS.

Wskazówki dotyczące wyglądu

W tej sekcji opisujemy wymagania i zalecenia dotyczące projektu ekranu zgody na połączenie konta w przypadku aplikacji App Flip. Gdy Google wywoła Twoją aplikację, wyświetli ona użytkownikowi ekran zgody.

Wymagania

  1. Musisz mieć oświadczenie o autoryzacji Google, np. „Po połączeniu Google będzie mieć uprawnienia do sterowania Twoimi urządzeniami”.
  2. Musisz poinformować użytkownika, że jego konto jest łączone z Google, a nie z konkretną usługą Google, np. Google Home czy Asystentem Google.
  3. Na ekranie zgody musisz umieścić jasne wezwanie do działania i użyć sformułowania „Zgadzam się i łączę” w przypadku działania polegającego na łączeniu. Dzieje się tak, ponieważ użytkownicy muszą wiedzieć, jakie dane muszą udostępnić Google, aby połączyć swoje konta.
  4. Musisz umożliwić użytkownikom powrót, odrzucenie lub anulowanie, jeśli nie chcą połączyć kont. W przypadku działania anulowania użyj słowa „Anuluj”.
  5. Musisz wdrożyć ten proces: po kliknięciu „Zgadzam się i łączę” musisz wyświetlić informację o udanym połączeniu i automatycznie przekierować użytkownika z powrotem do aplikacji Google Home. Użytkownik powinien teraz widzieć połączone urządzenie w aplikacji Google Home z Twoją czynnością. Po kliknięciu „Anuluj” przekieruj użytkownika z powrotem do aplikacji Google Home.

Rekomendacje

Zalecamy wykonanie tych czynności:

  1. Wyświetl Politykę prywatności Google. Na ekranie zgody umieść link do Polityki prywatności Google.

  2. Dane, które mają być udostępniane. Używaj jasnego i zwięzłego języka, aby poinformować użytkownika, jakich danych wymaga Google i dlaczego.

  3. Możliwość odłączenia Udostępniać użytkownikom mechanizm odłączania, np. adres URL do ustawień konta na Twojej platformie. Możesz też dodać link do konta Google, na którym użytkownicy mogą zarządzać połączonym kontem.

  4. Możliwość zmiany konta użytkownika. Zaproponuj użytkownikom metodę przełączania kont. Jest to szczególnie korzystne, jeśli użytkownicy mają zwykle kilka kont.

    • Jeśli użytkownik musi zamknąć ekran akceptacji, aby przełączyć konta, wyślij do Google błąd, który można naprawić, aby użytkownik mógł zalogować się na wybrane konto za pomocą połączenia OAuth i przepływu niejawnego.

  5. Dodaj logo. wyświetlać logo firmy na ekranie zgody; Umieść logo zgodnie z wytycznymi dotyczącymi stylu. Jeśli chcesz wyświetlać logo Google, zapoznaj się z sekcją Loga i znaki towarowe.

Ilustracja przedstawia przykładowy ekran akceptacji z objaśnieniami poszczególnych wymagań i rekomendacji, których należy przestrzegać podczas projektowania ekranu akceptacji użytkownika.
Rysunek 1. Wytyczne dotyczące projektowania ekranu zgody na połączenie kont.

Konfigurowanie App Flip opartego na protokole OAuth

W kolejnych sekcjach opisujemy wymagania wstępne dotyczące funkcji Przejście do aplikacji opartej na protokole OAuth oraz sposób konfigurowania projektu Przejście do aplikacji w Konsoli dewelopera Google Home.

Tworzenie integracji Cloud-to-cloud i konfigurowanie serwera OAuth 2.0

Zanim skonfigurujesz App Flip, musisz wykonać te czynności:

Konfigurowanie funkcji Przejście do aplikacji w Konsoli programisty

W sekcji poniżej opisano, jak skonfigurować Przejście do aplikacji w Konsoli programisty.

  1. Wypełnij wszystkie pola w sekcji Informacje o kliencie OAuth. (Jeśli App Flip nie jest obsługiwany, używany jest zwykły protokół OAuth).
  2. W sekcji Użyj aplikacji do łączenia kont(opcjonalnie) zaznacz Włącz na iOS.
  3. Wypełnij pole Uniwersalny link. Więcej informacji o uniwersalnych linkach znajdziesz w artykule Zezwalanie aplikacjom i witrynom na linkowanie do Twoich treści.
  4. Jeśli chcesz opcjonalnie skonfigurować klienta, dodaj zakresy i kliknij Dodaj zakres w sekcji Skonfiguruj klienta (opcjonalnie).
  5. Kliknij Zapisz.

Możesz teraz przejść do następnej sekcji, aby wdrożyć App Flip w aplikacji na iOS.

Wdrażanie App Flip w aplikacjach natywnych

Aby wdrożyć App Flip, musisz zmodyfikować kod autoryzacji użytkownika w aplikacji, aby akceptował precyzyjny link z Google.

Połączenie z przejściem do aplikacji oparte na protokole OAuth (przejście do aplikacji) otwiera aplikację na iOS z aplikacji Google, aby ułatwić użytkownikowi aplikacji Google połączenie konta. Aby wdrożyć tę funkcję, musisz wprowadzić niewielkie zmiany w kodzie aplikacji na iOS.

Z tego dokumentu dowiesz się, jak zmodyfikować aplikację na iOS, aby obsługiwała funkcję przejścia do aplikacji.

Wypróbuj przykład

Przykładowa aplikacja z funkcją przechodzenia do aplikacji pokazuje integrację połączenia konta na iOS, która jest zgodna z funkcją przechodzenia do aplikacji. Możesz użyć tej aplikacji, aby sprawdzić, jak reagować na przychodzące uniwersalne linki przełączenia do aplikacji z aplikacji mobilnych Google.

Przykładowa aplikacja jest wstępnie skonfigurowana do integracji z narzędziem do testowania przejścia do aplikacji na iOS, którego możesz użyć do sprawdzenia integracji aplikacji na iOS z przejściem do aplikacji przed skonfigurowaniem połączenia konta z Google. Ta aplikacja symuluje uniwersalny link wywoływany przez aplikacje mobilne Google, gdy włączona jest funkcja przejścia do aplikacji.

Jak to działa

Oto kroki, które wykonują aplikacja Google i Twoja aplikacja podczas przechodzenia do aplikacji:

  1. Aplikacja Google próbuje otworzyć uniwersalny link do Twojej aplikacji. Może otworzyć aplikację, jeśli jest ona zainstalowana na urządzeniu użytkownika i powiązana z uniwersalnym linkiem. Więcej informacji znajdziesz w artykule Obsługa uniwersalnych linków.

  2. Aplikacja sprawdza, czy parametry client_id i redirect_uri zakodowane w przychodzącym adresie URL są zgodne z oczekiwanym uniwersalnym linkiem Google.

  3. Aplikacja prosi serwer OAuth2 o kod autoryzacji. Na końcu tego procesu aplikacja zwraca do aplikacji Google kod autoryzacji lub błąd. W tym celu otwiera uniwersalny link Google z dołączonymi parametrami kodu autoryzacji lub błędu.

  4. Aplikacja Google obsługuje przychodzący uniwersalny link Google i kontynuuje proces. Jeśli podasz kod autoryzacji, połączenie zostanie nawiązane natychmiast. Wymiana tokenów odbywa się między serwerami, tak samo jak w przypadku połączenia OAuth opartego na przeglądarce. Jeśli zostanie zwrócony kod błędu, proces łączenia będzie kontynuowany z użyciem opcji alternatywnych.

Modyfikowanie aplikacji na iOS pod kątem obsługi funkcji przejścia do aplikacji

Aby obsługiwać funkcję Przejście do aplikacji, wprowadź w aplikacji na iOS te zmiany w kodzie:

  1. Obsługuj NSUserActivityTypeBrowsingWeb w delegacie aplikacji.
  2. Przechwyć parametry redirect_uri i state z adresu URL, aby użyć ich później.
  3. Sprawdź, czy redirect_uri jest zgodny z tym formatem: 
    https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

  4. Sprawdź, czy identyfikator klienta jest zgodny z oczekiwaną wartością. Użyj tego przykładowego kodu:

    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. Po pomyślnej autoryzacji wywołaj identyfikator URI przekierowania z kodem autoryzacji. Użyj tego przykładowego kodu:

    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. Jeśli wystąpił błąd, do identyfikatora URI przekierowania dołącz wynik błędu. Użyj tego przykładowego kodu:

    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)
    }
}

Gdy uniwersalny link do aplikacji jest otwierany przez aplikację Google, zawiera on te parametry zapytania:

  • client_id (String): client_id Google zarejestrowany w Twojej aplikacji.
  • scope (List of String): lista żądanych zakresów rozdzielonych spacjami.
  • state (String): liczba jednorazowa używana przez Google do weryfikacji, czy wynik autoryzacji jest odpowiedzią na żądanie wychodzące Google.
  • redirect_uri (String): uniwersalny link Google. Identyfikator URI „flip” do otwierania aplikacji Google i przekazywania wyników.

Parametry używane, gdy wynik autoryzacji jest zwracany pomyślnie:

  • code (String): wartość kodu autoryzacji, jeśli jest dostępna.
  • state (String): dokładna wartość otrzymana z przychodzącego uniwersalnego linku.

Parametry używane, gdy wynik autoryzacji jest nieudany:

  • error (String) z tymi wartościami:

    • cancelled: błąd, który można naprawić. Aplikacja Google spróbuje połączyć konta, używając adresu URL autoryzacji. Może to być na przykład nieudana próba zalogowania się użytkownika, urządzenie w trybie offline lub przekroczenie limitu czasu połączenia.
    • unrecoverable: nieodwracalny błąd. Na przykład użytkownik próbuje połączyć się z wyłączonym kontem.Aplikacja Google przerwie łączenie kont.
    • invalid_request: parametry żądania są nieprawidłowe lub ich brakuje. Ten błąd można naprawić. Aplikacja Google spróbuje połączyć konta, używając adresu URL autoryzacji.
    • access_denied: użytkownik odrzuca prośbę o zgodę. Jest to błąd, którego nie można naprawić. Aplikacja Google przerywa łączenie.

  • error_description (String, opcjonalny): przyjazny dla użytkownika komunikat o błędzie.

W przypadku wszystkich typów błędów musisz zwrócić dane odpowiedzi do określonego elementu REDIRECT_URI, aby zapewnić uruchomienie odpowiedniej kreacji zastępczej.

Zmodyfikuj punkt końcowy autoryzacji, aby obsługiwał funkcję przechodzenia do aplikacji

Skonfiguruj platformę tak, aby akceptowała żądania przy użyciu adresów URL przekierowań funkcji Przejście do aplikacji Google:

  • Aplikacja 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
  • Aplikacja Asystent 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

W przypadku Google Home app (GHA) łączenie konta inteligentnego domu korzysta z adresów URL przekierowania com.google.Chromecast. Upewnij się, że serwer autoryzacji zezwala na te adresy URL przekierowania.

Sprawdź, czy po otrzymaniu żądania client_id i adres URL określony przez parametr redirect_uri odpowiadają oczekiwanym wartościom. Jeśli weryfikacja klienta się nie powiedzie, zwróć błąd invalid_request do redirect_uri.

Testowanie aplikacji App Flip na urządzeniu

Po utworzeniu integracji Cloud-to-cloud i skonfigurowaniu funkcji Przejście do aplikacji w konsoli i w aplikacji możesz przetestować tę funkcję na urządzeniu mobilnym. Aby przetestować funkcję Przejście do aplikacji, możesz użyć aplikacji Google Home.

Aby przetestować App Flip w aplikacji Google Home, wykonaj te czynności:

  1. Otwórz Developer Console i wybierz swój projekt.
  2. Otwórz Cloud-to-cloud > Test.
  3. Uruchom proces łączenia konta w aplikacji Home:
    1. Otwórz Google Home app (GHA).
    2. Kliknij przycisk +.
    3. Kliknij Skonfiguruj urządzenie.
    4. Kliknij Masz już skonfigurowane urządzenia?.
    5. Wybierz integrację Cloud-to-cloud z listy dostawców. Na liście będzie on poprzedzony prefiksem „[test]”. Gdy wybierzesz z listy integrację [test], powinna otworzyć się aplikacja.
    6. Sprawdź, czy aplikacja została uruchomiona, i rozpocznij testowanie procesu autoryzacji.
Wstecz
Android
Dalej
Identyfikacja i synchronizacja