App Flip na Androida

Po wdrożeniu protokołu OAuth 2.0 możesz opcjonalnie skonfigurować App Flip oparty na protokole OAuth, który umożliwia użytkownikom Android 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 w Android.

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 wymagane(*) pola w sekcji Łączenie kont. (Jeśli funkcja Przejście do aplikacji nie jest obsługiwana, jako rozwiązanie zastępcze używany jest standardowy protokół OAuth).
  2. Podaj adres URL w polu Cloud fulfillment URL (Adres URL realizacji w chmurze). Adres URL realizacji w chmurze służy do przetwarzania intencji inteligentnego domu. Zaznacz Realizacja lokalna.
  3. W sekcji Przejście do aplikacji (opcjonalnie) zaznacz Aplikacja na Androida.
  4. Wypełnij następujące pola:
    • Identyfikator aplikacji. Identyfikator aplikacji to unikalny identyfikator, który ustawiasz dla swojej aplikacji.
    • Sygnatura aplikacji. Aby aplikacje na Androida można było zainstalować, muszą być „podpisane” certyfikatem klucza publicznego. Informacje o uzyskiwaniu podpisywania aplikacji znajdziesz w artykule Uwierzytelnianie klienta.
    • Intencja autoryzacji. W tym polu wpisz ciąg znaków, który określa działanie intencji.
  5. Jeśli chcesz opcjonalnie skonfigurować klienta, dodaj zakresy i kliknij Dodaj zakres w sekcji Zakresy (opcjonalnie).
  6. Jeśli klient tego wymaga, wybierz Google ma przesyłać identyfikator klienta i klucz w nagłówku uwierzytelniania podstawowego HTTP.

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

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) wstawia aplikację na Androida do procesu łączenia z kontem Google. Tradycyjny proces łączenia kont wymaga od użytkownika wpisania danych logowania w przeglądarce. Przejście do aplikacji przenosi logowanie użytkownika do aplikacji na Androida, co pozwala wykorzystać istniejące autoryzacje. Jeśli użytkownik jest zalogowany w Twojej aplikacji, nie musi ponownie wpisywać danych logowania, aby połączyć konto. Wdrożenie funkcji Przejście do aplikacji w aplikacji na Androida wymaga minimalnych zmian w kodzie.

Z tego dokumentu dowiesz się, jak zmodyfikować aplikację na Androida, aby obsługiwała funkcję Przejście do aplikacji.

Wypróbuj przykład

Przykładowa aplikacja do łączenia kont za pomocą funkcji Przejście do aplikacji pokazuje, jak zintegrować łączenie kont zgodne z tą funkcją na Androidzie. Możesz użyć tej aplikacji, aby sprawdzić, jak reagować na przychodzące intencje przełączenia do aplikacji z aplikacji mobilnych Google.

Przykładowa aplikacja jest wstępnie skonfigurowana do integracji z narzędziem do testowania przechodzenia do aplikacji na Androida, którego możesz użyć do sprawdzenia integracji aplikacji na Androida z funkcją przechodzenia do aplikacji przed skonfigurowaniem połączenia konta z Google. Ta aplikacja symuluje intencję wywoływaną przez aplikacje mobilne Google, gdy włączone jest przejście do aplikacji.

Jak to działa

Aby przeprowadzić integrację z przejściem do aplikacji, wykonaj te czynności:

  1. Aplikacja Google sprawdza, czy Twoja aplikacja jest zainstalowana na urządzeniu, używając jej nazwy pakietu.
  2. Aplikacja Google używa sprawdzania podpisu pakietu, aby potwierdzić, że zainstalowana aplikacja jest prawidłowa.
  3. Aplikacja Google tworzy intencję, aby rozpocząć wyznaczone działanie w Twojej aplikacji. Ta intencja zawiera dodatkowe dane wymagane do połączenia. Sprawdza też, czy aplikacja obsługuje funkcję przejścia do aplikacji, rozwiązując tę intencję za pomocą platformy Androida.
  4. Aplikacja sprawdza, czy żądanie pochodzi z aplikacji Google. W tym celu sprawdza podpis pakietu i podany identyfikator klienta.
  5. Aplikacja prosi serwer OAuth 2.0 o kod autoryzacji. Na końcu tego procesu zwraca do aplikacji Google kod autoryzacji lub błąd.
  6. Aplikacja Google pobiera wynik i kontynuuje łączenie kont. Jeśli podany jest kod autoryzacji, wymiana tokenów odbywa się między serwerami, tak samo jak w przypadku procesu łączenia OAuth w przeglądarce.

Zmodyfikuj aplikację na Androida, aby obsługiwała funkcję przejścia do aplikacji

Aby obsługiwać funkcję przejścia do aplikacji, wprowadź w aplikacji na Androida te zmiany w kodzie:

  1. Dodaj element <intent-filter> do pliku AndroidManifest.xml z ciągiem działania, który pasuje do wartości wpisanej w polu Intencja przejścia do aplikacji.

    <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. Sprawdź podpis aplikacji wywołującej.

    Musisz dopasować nazwę pakietu i podpis do wszystkich aplikacji Google, których użytkownicy mogą używać do łączenia kont. Aby na przykład połączyć się z aplikacjami Google Home i Wyszukiwarka, dodaj nazwy ich pakietów i podpisy:

    • Nazwa pakietu: com.google.android.apps.chromecast.app
    • Pierwotny certyfikat pochodzenia 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
    • Zastąpiony certyfikat SHA-256 podpisywania aplikacji przez 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

    i

    • Nazwa pakietu: com.google.android.googlequicksearchbox
    • Podpis: 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

    Prośby o połączenie z inteligentnym domem są inicjowane bezpośrednio przez Google Home app (GHA). Jeśli Twoja aplikacja ogranicza elementy wywołujące i wcześniej zezwalała tylko na aplikację wyszukiwarki Google, musisz dodać com.google.android.apps.chromecast.app i jej certyfikaty SHA-256 do listy dozwolonych, aby przejście do aplikacji nadal działało.

    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. Wyodrębnij identyfikator klienta z parametrów intencji i sprawdź, czy jest on zgodny z oczekiwaną wartością.

    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. Po pomyślnej autoryzacji zwróć do Google wynikowy kod autoryzacji.

    // Successful result
val data = Intent().apply {
    putExtra("AUTHORIZATION_CODE", authCode)
}
setResult(Activity.RESULT_OK, data)
finish()

  5. Jeśli wystąpił błąd, zwróć wynik błędu.

    // Error result
val error = Intent().apply {
    putExtra("ERROR_TYPE", 1)
    putExtra("ERROR_CODE", 1)
    putExtra("ERROR_DESCRIPTION", "Invalid Request")
}
setResult(-2, error)
finish()

Treść intencji uruchomienia

Intencja Androida, która uruchamia aplikację, zawiera te pola:

  • CLIENT_ID (String): Google client_id zarejestrowany w Twojej aplikacji.
  • SCOPE (String[]): lista żądanych zakresów.
  • REDIRECT_URI (String): adres URL przekierowania.

Treść danych odpowiedzi

Dane zwracane do aplikacji Google są ustawiane w aplikacji przez wywołanie setResult(). Są to m.in.:

  • AUTHORIZATION_CODE (String): wartość kodu autoryzacji.
  • resultCode (int): informuje o powodzeniu lub niepowodzeniu procesu i przyjmuje jedną z tych wartości:
    • Activity.RESULT_OK: oznacza powodzenie; zwracany jest kod autoryzacji.
    • Activity.RESULT_CANCELLED: błąd, który można naprawić. Sygnalizuje, że użytkownik anulował proces. W takim przypadku aplikacja Google spróbuje ponownie połączyć konto, używając adresu URL autoryzacji.
    • -2: wskazuje, że wystąpił błąd. Poniżej opisujemy różne typy błędów.
  • ERROR_TYPE (int): typ błędu, który może mieć jedną z tych wartości:
    • 1: błąd możliwy do naprawienia: aplikacja Google spróbuje połączyć konto, używając adresu URL autoryzacji.
    • 2: nieodwracalny błąd: aplikacja Google przerywa łączenie kont.
    • 3: nieprawidłowe lub brakujące parametry żądania.
  • ERROR_CODE (int): liczba całkowita określająca charakter błędu. Aby dowiedzieć się, co oznacza dany kod błędu, zapoznaj się z tabelą kodów błędów.

  • ERROR_DESCRIPTION (String, opcjonalny): zrozumiały dla człowieka komunikat o stanie opisujący błąd.

Wartość AUTHORIZATION_CODE jest oczekiwana, gdy resultCode == Activity.RESULT_OK. W pozostałych przypadkach wartość parametru AUTHORIZATION_CODE musi być pusta. Jeśli resultCode == -2, oczekiwana jest wartość ERROR_TYPE.

Tabela kodów błędów

W tabeli poniżej znajdziesz różne kody błędów i informacje o tym, czy dany błąd jest odwracalny czy nieodwracalny:

Kod błędu Znaczenie Możliwość odzyskania Nie do odzyskania
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 ✔

W przypadku wszystkich kodów błędów musisz zwrócić wynik błędu za pomocą setResult, aby zapewnić uruchomienie odpowiedniego działania zastępczego.

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
Tworzenie integracji z chmury do chmury
Dalej
iOS