App Flip untuk Android

Setelah memiliki implementasi OAuth 2.0, Anda dapat mengonfigurasi App Flip berbasis OAuth, yang memungkinkan pengguna Android menautkan akun mereka di sistem autentikasi Anda ke Akun Google mereka dengan lebih cepat. Bagian berikut menjelaskan cara mendesain dan mengimplementasikan App Flip untuk integrasi Cloud-to-cloud Anda di Android.

Panduan desain

Bagian ini menjelaskan persyaratan dan rekomendasi desain untuk layar izin penautan akun App Flip. Setelah Google memanggil aplikasi Anda, aplikasi Anda akan menampilkan layar izin kepada pengguna.

Persyaratan

  1. Anda harus memiliki pernyataan otorisasi Google seperti "Setelah ditautkan, Google akan memiliki izin untuk mengontrol perangkat Anda."
  2. Anda harus mengomunikasikan bahwa akun pengguna sedang ditautkan ke Google, bukan ke produk Google tertentu, seperti Google Home atau Asisten Google.
  3. Anda harus menyatakan pesan ajakan (CTA) yang jelas di layar izin Anda dan menggunakan kata-kata "Setuju dan tautkan" untuk tindakan penautan. Hal ini karena pengguna perlu memahami data apa yang harus mereka bagikan kepada Google untuk menautkan akun mereka.
  4. Anda harus menyediakan cara bagi pengguna untuk kembali, menolak, atau membatalkan, jika mereka memilih untuk tidak menautkan. Gunakan kata "Batal" untuk tindakan pembatalan.
  5. Anda harus menerapkan alur kerja ini: Setelah mengklik "Setuju dan tautkan", Anda harus menampilkan keberhasilan penautan dan mengalihkan pengguna kembali ke aplikasi Google Home secara otomatis. Pengguna kini akan melihat perangkat tertaut di aplikasi Google Home dengan tindakan Anda. Setelah mengklik "Batal", Anda harus mengalihkan pengguna kembali ke aplikasi Google Home.

Rekomendasi

Sebaiknya Anda melakukan hal berikut:

  1. Menampilkan Kebijakan Privasi Google. Sertakan link ke Kebijakan Privasi Google di layar izin.

  2. Data yang akan dibagikan. Gunakan bahasa yang jelas dan ringkas untuk memberi tahu pengguna data apa yang diperlukan Google dari mereka dan alasannya.

  3. Kemampuan untuk membatalkan tautan. Menawarkan mekanisme bagi pengguna untuk membatalkan tautan, seperti URL ke setelan akun mereka di platform Anda. Atau, Anda dapat menyertakan link ke Akun Google tempat pengguna dapat mengelola akun tertaut mereka.

  4. Kemampuan untuk mengubah akun pengguna. Sarankan metode bagi pengguna untuk mengganti akun mereka. Hal ini sangat bermanfaat jika pengguna cenderung memiliki beberapa akun.

    • Jika pengguna harus menutup layar izin untuk beralih akun, kirimkan error yang dapat dipulihkan ke Google agar pengguna dapat login ke akun yang diinginkan dengan penautan OAuth dan alur implisit.

  5. Sertakan logo Anda. Menampilkan logo perusahaan Anda di layar izin. Gunakan panduan gaya Anda untuk menempatkan logo. Jika Anda ingin menampilkan logo Google juga, lihat Logo dan merek dagang.

Gambar ini menunjukkan contoh layar izin dengan penjelasan tentang persyaratan dan rekomendasi individual yang harus diikuti saat Anda mendesain layar izin pengguna.
Gambar 1: Panduan desain layar persetujuan penautan akun.

Menyiapkan App Flip berbasis OAuth

Bagian berikut menjelaskan prasyarat untuk App Flip berbasis OAuth dan cara mengonfigurasi project App Flip di Konsol Developer Google Home.

Membuat integrasi Cloud-to-cloud dan menyiapkan server OAuth 2.0

Sebelum dapat mengonfigurasi App Flip, Anda harus melakukan hal berikut:

Mengonfigurasi App Flip di Konsol Developer

Bagian berikut menjelaskan cara mengonfigurasi App Flip di Konsol Developer.

  1. Isi semua kolom wajib(*) di bagian Penautan Akun. (Jika App Flip tidak didukung, OAuth reguler akan digunakan sebagai pengganti.)
  2. Berikan URL untuk Cloud fulfillment URL. URL fulfillment Cloud digunakan untuk memproses intent smart home Anda. Centang Local fulfillment.
  3. Di bagian App Flip (opsional), centang Aplikasi Android.
  4. Isi kolom berikut:
    • ID Aplikasi. ID Aplikasi adalah ID unik yang Anda tetapkan untuk aplikasi Anda.
    • Tanda tangan aplikasi. Aplikasi Android harus ‘ditandatangani’ dengan sertifikat kunci publik sebelum dapat diinstal. Untuk mengetahui informasi tentang cara mendapatkan tanda tangan aplikasi, lihat Mengautentikasi Klien Anda.
    • Intent otorisasi. Di kolom ini, masukkan string yang menentukan tindakan intent Anda.
  5. Jika Anda ingin mengonfigurasi klien secara opsional, tambahkan cakupan dan klik Add scope di bagian Scopes(s) (optional).
  6. Jika klien Anda memerlukannya, pilih Have Google transmit Client ID and secret via HTTP basic auth header.

Sekarang Anda dapat melanjutkan ke bagian berikutnya untuk menerapkan App Flip di aplikasi Android Anda.

Menerapkan App Flip di aplikasi native Anda

Untuk menerapkan App Flip, Anda perlu mengubah kode otorisasi pengguna di aplikasi Anda untuk menerima deep link dari Google.

Penautan App Flip berbasis OAuth (App Flip) menyisipkan aplikasi Android Anda ke dalam alur Penautan Akun Google. Alur penautan akun tradisional mengharuskan pengguna memasukkan kredensial mereka di browser. Penggunaan App Flip menunda login pengguna ke aplikasi Android Anda, sehingga Anda dapat memanfaatkan otorisasi yang ada. Jika pengguna login ke aplikasi Anda, mereka tidak perlu memasukkan kembali kredensial untuk menautkan akun. Perubahan kode minimal diperlukan untuk menerapkan App Flip di aplikasi Android Anda.

Dalam dokumen ini, Anda akan mempelajari cara mengubah aplikasi Android untuk mendukung App Flip.

Mencoba contoh

Aplikasi contoh penautan App Flip menunjukkan integrasi penautan akun yang kompatibel dengan App Flip di Android. Anda dapat menggunakan aplikasi ini untuk memverifikasi cara merespons intent App Flip yang masuk dari aplikasi seluler Google.

Aplikasi contoh telah dikonfigurasi sebelumnya untuk diintegrasikan dengan Alat Pengujian App Flip untuk Android, yang dapat Anda gunakan untuk memverifikasi integrasi aplikasi Android Anda dengan App Flip sebelum mengonfigurasi penautan akun dengan Google. Aplikasi ini menyimulasikan intent yang dipicu oleh aplikasi seluler Google saat App Flip diaktifkan.

Cara kerjanya

Langkah-langkah berikut diperlukan untuk melakukan integrasi App Flip:

  1. Aplikasi Google memeriksa apakah aplikasi Anda diinstal di perangkat menggunakan nama paketnya.
  2. Aplikasi Google menggunakan pemeriksaan tanda tangan paket untuk memvalidasi bahwa aplikasi yang diinstal adalah aplikasi yang benar.
  3. Aplikasi Google membuat intent untuk memulai aktivitas yang ditentukan di aplikasi Anda. Intent ini menyertakan data tambahan yang diperlukan untuk penautan. Aplikasi Google juga memeriksa apakah aplikasi Anda mendukung App Flip dengan me-resolve intent ini melalui framework Android.
  4. Aplikasi Anda memvalidasi bahwa permintaan berasal dari aplikasi Google. Untuk melakukannya, aplikasi Anda memeriksa tanda tangan paket dan client ID yang diberikan.
  5. Aplikasi Anda meminta kode otorisasi dari server OAuth 2.0 Anda. Di akhir alur ini, kode otorisasi atau error akan ditampilkan ke aplikasi Google.
  6. Aplikasi Google mengambil hasilnya dan melanjutkan penautan akun. Jika kode otorisasi diberikan, pertukaran token akan terjadi server-ke-server, sama seperti dalam alur penautan OAuth berbasis browser.

Mengubah aplikasi Android Anda untuk mendukung App Flip

Untuk mendukung App Flip, lakukan perubahan kode berikut pada aplikasi Android Anda:

  1. Tambahkan <intent-filter> ke file AndroidManifest.xml Anda dengan string tindakan yang cocok dengan nilai yang Anda masukkan di kolom 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. Memvalidasi tanda tangan aplikasi panggilan.

    Anda harus mencocokkan nama paket dan tanda tangan untuk aplikasi Google apa pun yang mungkin digunakan pengguna untuk menautkan akun. Misalnya, untuk menautkan dengan aplikasi Google Home dan Penelusuran, tambahkan nama paket dan tanda tangannya:

    • Nama paket: com.google.android.apps.chromecast.app
    • Sertifikat silsilah SHA-256 asli: 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
    • Sertifikat SHA-256 Penandatanganan Aplikasi Play yang dirotasi: 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

    dan

    • Nama paket: com.google.android.googlequicksearchbox
    • Tanda tangan: 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

    Permintaan penautan smart home dimulai langsung oleh Google Home app (GHA). Jika aplikasi Anda membatasi pemanggil dan sebelumnya hanya mengizinkan aplikasi Google Penelusuran, Anda harus menambahkan com.google.android.apps.chromecast.app dan sertifikat SHA-256-nya ke daftar yang diizinkan agar App Flip terus berhasil.

    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. Ekstrak client ID dari parameter intent dan verifikasi bahwa client ID cocok dengan nilai yang diharapkan.

    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. Setelah otorisasi berhasil, tampilkan kode otorisasi yang dihasilkan kembali ke Google.

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

  5. Jika terjadi error, tampilkan hasil error.

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

Konten intent peluncuran

Intent Android yang meluncurkan aplikasi Anda menyertakan kolom berikut:

  • CLIENT_ID (String): Google client_id yang terdaftar di aplikasi Anda.
  • SCOPE (String[]): Daftar cakupan yang diminta.
  • REDIRECT_URI (String): URL pengalihan.

Konten data respons

Data yang ditampilkan ke aplikasi Google ditetapkan di aplikasi Anda dengan memanggil setResult(). Data ini mencakup hal berikut:

  • AUTHORIZATION_CODE (String): Nilai kode otorisasi.
  • resultCode (int): Mengomunikasikan keberhasilan atau kegagalan proses dan mengambil salah satu nilai berikut:
    • Activity.RESULT_OK: Menunjukkan keberhasilan; kode otorisasi ditampilkan.
    • Activity.RESULT_CANCELLED: Error yang dapat dipulihkan. Menandakan bahwa pengguna telah membatalkan proses. Dalam hal ini, aplikasi Google akan mencoba penautan akun lagi menggunakan URL otorisasi Anda.
    • -2: Menunjukkan bahwa telah terjadi error. Berbagai jenis error dijelaskan di bawah.
  • ERROR_TYPE (int): Jenis error, yang menggunakan salah satu nilai berikut:
    • 1: Error yang dapat dipulihkan: Aplikasi Google akan mencoba penautan akun menggunakan URL otorisasi.
    • 2: Error yang tidak dapat dipulihkan: Aplikasi Google membatalkan penautan akun.
    • 3: Parameter permintaan tidak valid atau tidak ada.
  • ERROR_CODE (int): Bilangan bulat yang mewakili sifat error. Untuk melihat arti setiap kode error, lihat tabel kode error.

  • ERROR_DESCRIPTION (String, opsional): Pesan status yang dapat dibaca manusia yang menjelaskan error.

Nilai untuk AUTHORIZATION_CODE diharapkan saat resultCode == Activity.RESULT_OK. Dalam semua kasus lainnya, nilai untuk AUTHORIZATION_CODE harus kosong. Jika resultCode == -2, nilai ERROR_TYPE diharapkan akan diisi.

Tabel kode error

Tabel di bawah menunjukkan berbagai kode error dan apakah setiap kode error tersebut dapat dipulihkan atau error yang tidak dapat dipulihkan:

Kode error Arti Dapat dipulihkan Tidak dapat dipulihkan
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 ✔

Untuk semua kode error, Anda harus menampilkan hasil error melalui setResult untuk memastikan penggantian yang sesuai dipicu.

Menguji App Flip di perangkat Anda

Setelah membuat integrasi Cloud-to-cloud dan mengonfigurasi App Flip di konsol dan di aplikasi, Anda dapat menguji App Flip di perangkat seluler. Anda dapat menggunakan aplikasi Google Home untuk menguji App Flip.

Untuk menguji App Flip dari aplikasi Google Home, ikuti langkah-langkah berikut:

  1. Buka Konsol Developer, lalu pilih project Anda.
  2. Buka Cloud-to-cloud > Test.
  3. Memicu alur penautan akun dari aplikasi Home:
    1. Buka Google Home app (GHA).
    2. Klik tombol +.
    3. Klik Siapkan perangkat.
    4. Klik Ada yang sudah disiapkan?
    5. Pilih integrasi Cloud-to-cloud Anda dari daftar penyedia. Iklan ini akan diawali dengan “[test]” dalam daftar. Saat Anda memilih integrasi [pengujian] dari daftar, aplikasi Anda akan terbuka.
    6. Pastikan aplikasi Anda diluncurkan dan mulai uji alur otorisasi Anda.
Sebelumnya
Membuat integrasi Cloud-ke-cloud
Berikutnya
iOS