Balik Aplikasi untuk Android

Setelah memiliki implementasi OAuth 2.0, Anda dapat secara opsional mengonfigurasi App Flip , which allows your Android users to more quickly link their accounts in your authentication system to their Google accounts. The following sections describe how to design and implement App Flip for your smart home Action. berbasis OAuth

Panduan desain

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

Persyaratan

1. Anda harus memberi tahu bahwa akun pengguna sedang ditautkan ke Google, bukan ke produk Google tertentu, seperti Google Home atau Asisten Google.

Rekomendasi

Sebaiknya lakukan hal berikut:

1. Tampilkan 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 dan alasannya.

3. Pesan ajakan (CTA) yang jelas. Nyatakan pesan ajakan (CTA) yang jelas di layar izin Anda, seperti "Setuju dan tautkan". Hal ini karena pengguna harus memahami data yang harus mereka bagikan kepada Google untuk menautkan akun mereka.

4. Kemampuan untuk membatalkan. Berikan cara bagi pengguna untuk kembali atau membatalkan, jika mereka memilih untuk tidak menautkan.

5. 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.

6. Kemampuan untuk mengubah akun pengguna. Menyarankan metode kepada pengguna untuk berganti akun. Hal ini sangat bermanfaat jika pengguna cenderung memiliki beberapa akun.

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

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

Menyiapkan App Flip berbasis OAuth

Bagian berikut menjelaskan prasyarat untuk App Flip berbasis OAuth dan cara mengonfigurasi project App Flip Anda di konsol Actions.

Membuat Action smart home dan menyiapkan server OAuth 2.0

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

• Siapkan server OAuth 2.0. Untuk mengetahui informasi selengkapnya tentang penyiapan server OAuth, lihat Mengimplementasikan server OAuth 2.0.
• Membuat Tindakan. Untuk membuat Action, ikuti petunjuk dalam Membuat project Actions.

Mengonfigurasi App Flip di konsol Actions

Bagian berikut menjelaskan cara mengonfigurasi App Flip di konsol Actions.

1. Isi semua kolom di bagian Informasi Klien OAuth. (Jika App Flip tidak didukung, OAuth biasa akan digunakan sebagai pengganti.)
2. Di bagian Gunakan aplikasi untuk penautan akun (opsional), centang Aktifkan untuk Android.
3. Isi kolom berikut:
• ID Aplikasi. ID Aplikasi adalah ID unik yang Anda tetapkan untuk aplikasi.
• Tanda tangan aplikasi. Aplikasi Android harus 'ditandatangani' dengan sertifikat kunci publik sebelum dapat diinstal. Untuk informasi tentang cara mendapatkan tanda tangan aplikasi, lihat Mengautentikasi Klien.
• Intent otorisasi. Dalam kolom ini, masukkan string yang menentukan tindakan intent Anda.
4. Jika Anda ingin mengonfigurasi klien secara opsional, tambahkan cakupan, lalu klik Tambahkan cakupan di bagian Konfigurasikan klien (opsional).
5. Klik Simpan.

Menerapkan App Flip di aplikasi Android Anda

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

Penautan App Flip berbasis OAuth (App Flip) memasukkan 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 sudah ada. Jika pengguna login ke aplikasi Anda, dia tidak perlu memasukkan kembali kredensialnya untuk menautkan akunnya. Perubahan kode dalam jumlah minimum diperlukan untuk menerapkan Flip Aplikasi di aplikasi Android Anda.

Dalam dokumen ini, Anda akan mempelajari cara memodifikasi aplikasi Android untuk mendukung Flip Aplikasi.

Mencoba contoh

Contoh aplikasi 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 Uji Balik Aplikasi untuk Android, yang dapat Anda gunakan untuk memverifikasi integrasi aplikasi Android dengan App Flip sebelum mengonfigurasi penautan akun dengan Google. Aplikasi ini menyimulasikan intent yang dipicu oleh aplikasi seluler Google saat App Flip diaktifkan.

Cara kerja

Langkah-langkah berikut diperlukan untuk menjalankan integrasi App Flip:

1. Aplikasi Google memeriksa apakah aplikasi Anda diinstal di perangkat menggunakan nama paket.
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 ditetapkan dalam aplikasi Anda. Intent ini mencakup data tambahan yang diperlukan untuk penautan. Pemeriksaan ini juga memeriksa apakah aplikasi Anda mendukung App Flip dengan menyelesaikan 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. Di akhir alur ini, metode ini akan menampilkan kode otorisasi atau error ke aplikasi Google.
6. Aplikasi Google akan mengambil hasil dan melanjutkan penautan akun. Jika kode otorisasi diberikan, pertukaran token akan dilakukan server ke server, dengan cara yang sama seperti dalam alur penautan OAuth berbasis browser.

Mengubah aplikasi Android Anda untuk mendukung App Flip

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

1. Tambahkan <intent-filter> ke file AndroidManifest.xml 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.

   private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprint: String,
           algorithm: String
   ): Boolean {
   
       callingActivity?.packageName?.let {
           if (expectedPackage == it) {
               val packageInfo =
                   packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
               val signatures = packageInfo.signatures
               val input = ByteArrayInputStream(signatures[0].toByteArray())
   
               val certificateFactory = CertificateFactory.getInstance("X509")
               val certificate =
                   certificateFactory.generateCertificate(input) as X509Certificate
               val md = MessageDigest.getInstance(algorithm)
               val publicKey = md.digest(certificate.encoded)
               val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }
   
               return (expectedFingerprint == fingerprint)
           }
       }
       return false
   }
   

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 = "<google-app-package-name>"
   private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
   private const val ALGORITHM = "SHA-256"
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {
   
           // ...authorize the user...
       }
   }
   

4. Setelah otorisasi berhasil, tampilkan kembali kode otorisasi yang dihasilkan 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 terdaftar di bawah aplikasi Anda.
• SCOPE (String[]): Daftar cakupan yang diminta.
• REDIRECT_URI (String): URL alihan.

Konten data respons

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

• AUTHORIZATION_CODE (String): Nilai kode otorisasi.
• resultCode (int): Menyampaikan keberhasilan atau kegagalan proses dan mengambil salah satu nilai berikut:
  • Activity.RESULT_OK: Menunjukkan keberhasilan; kode otorisasi ditampilkan.
  • Activity.RESULT_CANCELLED: Sinyal bahwa pengguna telah membatalkan proses. Dalam hal ini, aplikasi Google akan mencoba menautkan akun menggunakan URL otorisasi Anda.
  • -2: Menunjukkan bahwa telah terjadi error. Berbagai jenis error dijelaskan di bawah ini.
• ERROR_TYPE (int): Jenis error, yang mengambil salah satu nilai berikut:
  • 1: Error yang dapat dipulihkan: Aplikasi Google akan mencoba menautkan 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 merepresentasikan sifat error. Untuk mengetahui arti setiap kode error, lihat tabel kode error.

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

Diharapkan nilai untuk AUTHORIZATION_CODE saat resultCode == Activity.RESULT_OK. Dalam semua kasus lain, nilai untuk AUTHORIZATION_CODE harus kosong. Jika resultCode == -2, nilai ERROR_TYPE diharapkan terisi.

Tabel kode error

Tabel di bawah menunjukkan kode error yang berbeda-beda dan apakah masing-masing merupakan error yang dapat dipulihkan atau 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 Action dan mengonfigurasi App Flip di konsol dan di aplikasi, Anda dapat menguji App Flip di perangkat seluler. Anda dapat menggunakan aplikasi Asisten Google atau aplikasi Google Home untuk menguji App Flip.

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

1. Buka Konsol Actions dan pilih project Anda.
2. Klik Uji di navigasi atas.
3. Memicu alur penautan akun dari aplikasi Asisten:
1. Buka aplikasi Asisten Google.
2. Klik Setelan.
3. Di tab Asisten, klik Kontrol Rumah.
4. Klik Tambahkan(+).
5. Pilih Action Anda dari daftar penyedia. Nilai ini akan diawali dengan “[test]” di dalam daftar. Saat Anda memilih [test] Action dari daftar, tindakan tersebut akan membuka aplikasi Anda.
6. Pastikan bahwa aplikasi Anda telah diluncurkan dan mulai uji alur otorisasi Anda.

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

1. Buka Konsol Actions dan pilih project Anda.
2. Klik Uji di navigasi atas.
3. Memicu alur penautan akun dari aplikasi Home:
1. Buka aplikasi Google Home.
2. Klik tombol +.
3. Klik Siapkan perangkat.
4. Klik Sudah menyiapkan sesuatu?
5. Pilih Action smart home dari daftar penyedia. Nilai ini akan diawali dengan “[test]” di dalam daftar. Saat Anda memilih [test] Action dari daftar, tindakan tersebut akan membuka aplikasi Anda.
6. Pastikan bahwa aplikasi Anda telah diluncurkan dan mulai uji alur otorisasi Anda.