Google sedang melakukan transisi penautan akun smart home pihak ketiga agar ditangani sepenuhnya dan secara independen dalam aplikasi Google Home. Pembaruan pada integrasi Anda mungkin diperlukan sebelum 30 Oktober 2026. Untuk mengetahui informasi selengkapnya, lihat Panduan migrasi penautan akun.

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

App Flip untuk iOS

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

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

Anda harus memiliki pernyataan otorisasi Google seperti "Setelah ditautkan, Google akan memiliki izin untuk mengontrol perangkat Anda."
Anda harus mengomunikasikan bahwa akun pengguna sedang ditautkan ke Google, bukan ke produk Google tertentu, seperti Google Home atau Asisten Google.
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.
Anda harus menyediakan cara bagi pengguna untuk kembali, menolak, atau membatalkan, jika mereka memilih untuk tidak menautkan. Gunakan kata "Batal" untuk tindakan pembatalan.
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:

Menampilkan Kebijakan Privasi Google. Sertakan link ke Kebijakan Privasi Google di layar izin.
Data yang akan dibagikan. Gunakan bahasa yang jelas dan ringkas untuk memberi tahu pengguna data apa yang diperlukan Google dari mereka dan alasannya.
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.
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.
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:

Siapkan server OAuth 2.0. Untuk mengetahui informasi selengkapnya tentang cara menyiapkan server OAuth, lihat Mengimplementasikan server OAuth 2.0.
Membuat integrasi Cloud ke cloud. Untuk membuat integrasi, ikuti petunjuk di Membuat integrasi Cloud-to-cloud.

Mengonfigurasi App Flip di Konsol Developer

Bagian berikut menjelaskan cara mengonfigurasi App Flip di Konsol Developer.

Isi semua kolom di bagian informasi klien OAuth. (Jika App Flip tidak didukung, OAuth reguler akan digunakan sebagai pengganti.)
Di bagian Gunakan aplikasi Anda untuk penautan akun(opsional), centang Aktifkan untuk iOS.
Isi kolom Link Universal. Untuk informasi selengkapnya tentang link universal, lihat Mengizinkan Aplikasi dan Situs Menautkan ke Konten Anda.
Jika Anda ingin mengonfigurasi klien secara opsional, tambahkan cakupan dan klik Add scope di bagian Configure your client (optional).
Klik Simpan.

Sekarang Anda dapat melanjutkan ke bagian berikutnya untuk menerapkan App Flip di aplikasi iOS 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) membuka aplikasi iOS Anda dari aplikasi Google untuk membantu pengguna aplikasi Google menautkan akun mereka dengan lebih mudah. Anda perlu membuat perubahan kode kecil pada aplikasi iOS untuk menerapkan fitur ini.

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

Mencoba contoh

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

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

Cara kerjanya

Berikut adalah langkah-langkah alur yang dilakukan aplikasi Google dan aplikasi Anda saat App Flip terjadi:

Aplikasi Google mencoba membuka link universal aplikasi Anda. Link ini dapat membuka aplikasi Anda jika aplikasi tersebut diinstal di perangkat pengguna dan dikaitkan dengan link universal. Lihat Mendukung Link Universal untuk mengetahui detailnya.
Aplikasi Anda akan memeriksa apakah parameter client_id dan redirect_uri yang dienkode dalam URL yang masuk cocok dengan link universal Google yang diharapkan.
Aplikasi Anda meminta kode otorisasi dari server OAuth2 Anda. Di akhir alur ini, aplikasi Anda akan menampilkan kode otorisasi atau error ke aplikasi Google. Untuk melakukannya, aplikasi Anda akan membuka link universal Google dengan parameter tambahan untuk kode otorisasi atau error.
Aplikasi Google akan menangani link universal Google yang masuk dan melanjutkan alur lainnya. Jika kode otorisasi diberikan, penautan akan segera diselesaikan. Pertukaran token terjadi dari server ke server, sama seperti dalam alur penautan OAuth berbasis browser. Jika kode error ditampilkan, alur penautan akan dilanjutkan dengan opsi alternatif.

Mengubah aplikasi iOS Anda untuk mendukung App Flip

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

Tangani NSUserActivityTypeBrowsingWeb di App Delegate Anda.
Ambil parameter redirect_uri dan state dari URL untuk digunakan nanti.

Pastikan redirect_uri cocok dengan format ini:

https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

Pastikan client ID cocok dengan nilai yang diharapkan. Gunakan contoh kode berikut:

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

Setelah otorisasi berhasil, panggil URI pengalihan dengan kode otorisasi. Gunakan contoh kode berikut:

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

Jika terjadi error, lampirkan hasil error ke URI pengalihan. Gunakan contoh kode berikut:

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

Parameter kueri untuk link universal aplikasi Anda

Saat dibuka oleh aplikasi Google, link universal aplikasi Anda menyertakan parameter kueri berikut:

client_id (String): Google client_id yang terdaftar di aplikasi Anda.
scope (List of String): Daftar cakupan yang dipisahkan spasi yang diminta.
state (String): Nonce yang digunakan oleh Google untuk memverifikasi bahwa hasil otorisasi merupakan respons terhadap permintaan keluar Google.
redirect_uri (String): Link universal Google. URI "flip" untuk membuka aplikasi Google dan meneruskan hasil.

Parameter kueri untuk link universal Google

Parameter yang digunakan saat hasil otorisasi berhasil ditampilkan:

code (String): Nilai kode otorisasi, jika tersedia.
state (String): Nilai persis yang diterima dari link universal yang masuk.

Parameter yang digunakan saat hasil otorisasi tidak berhasil ditampilkan:

error (String), dengan nilai berikut:
- cancelled: Error yang dapat dipulihkan. Aplikasi Google akan mencoba penautan akun menggunakan URL otorisasi. Beberapa contohnya adalah pengguna gagal login, perangkat offline, atau waktu koneksi habis.
- unrecoverable: Error yang tidak dapat dipulihkan. Misalnya, pengguna mencoba menautkan dengan akun yang dinonaktifkan.Aplikasi Google akan membatalkan penautan akun.
- invalid_request: Parameter permintaan tidak valid atau tidak ada. Error ini dapat dipulihkan. Aplikasi Google akan mencoba penautan akun menggunakan URL otorisasi.
- access_denied: Pengguna menolak permintaan izin. Error ini tidak dapat dipulihkan; aplikasi Google akan membatalkan penautan.
error_description (String, opsional): Pesan error yang mudah dipahami pengguna.

Catatan: Untuk mengetahui informasi selengkapnya tentang kemungkinan error dan konten opsional kolom error_description, lihat standar OAuth 2.0.

Untuk semua jenis error, Anda harus menampilkan data respons ke REDIRECT_URI yang ditentukan untuk memastikan penggantian yang sesuai dipicu.

Mengubah endpoint otorisasi Anda untuk mendukung App Flip

Konfigurasikan platform Anda untuk menerima permintaan menggunakan URL pengalihan App Flip Google:

Aplikasi 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

Aplikasi Asisten 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

Untuk Google Home app (GHA), penautan akun Smart Home menggunakan URL pengalihan com.google.Chromecast. Pastikan server otorisasi Anda mengizinkan URL pengalihan ini.

Pastikan client_id dan URL yang ditentukan oleh parameter redirect_uri cocok dengan nilai yang diharapkan saat permintaan diterima. Jika verifikasi klien gagal, tampilkan error invalid_request ke redirect_uri.

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:

Buka Konsol Developer, lalu pilih project Anda.
Buka Cloud-to-cloud > Test.
Memicu alur penautan akun dari aplikasi Home:

Buka Google Home app (GHA).
Klik tombol +.
Klik Siapkan perangkat.
Klik Ada yang sudah disiapkan?
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.
Pastikan aplikasi Anda diluncurkan dan mulai uji alur otorisasi Anda.

Sebelumnya

Android

Berikutnya

Identifikasi dan sinkronisasi