Account Transfer API

Pengguna dapat menyalin data dan akun Google dari perangkat Android ke perangkat Android baru menggunakan Tap & Go. Gunakan Account Transfer API agar pengguna juga dapat menyalin kredensial untuk akun khusus yang diimplementasikan menggunakan AbstractAccountAuthenticator dan terintegrasi dengan AccountManager. Sistem memanggil Account Transfer API dari wizard penyiapan Tap & Go yang dijalankan di perangkat baru. Sistem juga memanggil Account Transfer API untuk mentransfer data dari ponsel Android ke Pixel menggunakan kabel.

Layar sambutan Tap & Go. Layar Tap & Go untuk memilih sumber data.

Gambar 1. Account Transfer API dipanggil dari wizard penyiapan Tap & Go yang dijalankan di perangkat baru.

Guna menambahkan dukungan untuk mentransfer akun kustom, integrasikan Account Transfer API di aplikasi Anda. Layanan Google Play kemudian dapat membuat saluran terenkripsi dua arah antara perangkat yang ada, yang juga dikenal sebagai perangkat sumber, dan perangkat baru, yang juga dikenal sebagai perangkat target, untuk mentransfer data akun, seperti yang diilustrasikan pada gambar 2. Saluran terenkripsi tidak bergantung pada koneksi ke server pihak ketiga untuk menyelesaikan transfer.

Pertimbangkan persyaratan berikut saat mengintegrasikan Account Transfer API ke dalam aplikasi Anda:

  • Perangkat sumber harus menjalankan Android 4.0.1 (API level 14) atau yang lebih tinggi.
  • Perangkat target harus menjalankan Android 8.0 (API level 26) atau yang lebih tinggi.
  • Perangkat sumber dan target harus menjalankan layanan Google Play versi 11.2.0 atau yang lebih tinggi.
  • Anda harus membuat aplikasi menggunakan SDK layanan Google Play versi 11.2.0 atau yang lebih tinggi.

Ilustrasi transfer akun dari perangkat sumber ke target.

Gambar 2. Transfer dilakukan melalui saluran terenkripsi yang dibuat layanan Google Play antara perangkat sumber dan target.

Menambahkan Account Transfer API ke project Anda

Untuk menggunakan Account Transfer API di project, Anda harus terlebih dahulu menyiapkan project dengan SDK layanan Google Play. Untuk petunjuk mendetail tentang cara menyiapkan SDK layanan Google Play, lihat Menyiapkan layanan Google Play.

Jika ingin secara selektif mengompilasi Account Transfer API Google ke dalam aplikasi Anda, tambahkan aturan build berikut ke blok dependencies dalam file build.gradle di dalam direktori modul aplikasi Anda:

Groovy

plugins {
  id 'com.android.application'
}
...
dependencies {
    // VERSION_NUMBER must be equal to or higher than 11.2.0.
    implementation 'com.google.android.gms:play-services-auth:<VERSION_NUMBER>'
}

Kotlin

plugins {
    id("com.android.application")
}
...
dependencies {
    // VERSION_NUMBER must be equal to or higher than 11.2.0.
    implementation("com.google.android.gms:play-services-auth:<VERSION_NUMBER>")
}

Guna menambahkan dukungan untuk mentransfer akun khusus, Anda harus mendeklarasikan penerima siaran START_ACCOUNT_EXPORT untuk layanan pengautentikasi dalam manifes aplikasi:

<receiver android:name=".MyBroadcastReceiver"  android:exported="true">
    <intent-filter>
        <action android:name="com.google.android.gms.auth.START_ACCOUNT_EXPORT"/>
        ...
    </intent-filter>
</receiver>

Jika aplikasi Anda tidak diinstal di image sistem OEM dan Anda tidak berencana untuk menginstal aplikasi di image sistem OEM, pastikan Anda mendaftar untuk memproses siaran ACTION_START_ACCOUNT_EXPORT di perangkat sumber untuk mengekspor data akun seperti yang dijelaskan di atas.

Jika Anda menginstal aplikasi pada image sistem OEM, Anda juga harus mendaftar untuk siaran berikut:

Mentransfer data akun

Setelah pengguna memilih untuk memulihkan konten dari perangkat yang ada, sistem akan mengirim siaran ACTION_START_ACCOUNT_EXPORT ke paket yang terkait dengan akun yang relevan pada perangkat sumber.

Mengirim data akun

Untuk mengirim data akun, mulai layanan pengautentikasi di perangkat sumber dan panggil sendData() setelah layanan menerima siaran ACTION_START_ACCOUNT_EXPORT. Anda dapat memperoleh referensi dari objek AccountTransferClient dengan memanggil getAccountTransferClient(Context) atau getAccountTransferClient(Activity). Cuplikan kode berikut mengilustrasikan cara mengirim data dari perangkat sumber:

Kotlin

val client: AccountTransferClient = AccountTransfer.getAccountTransferClient(this)
val exportTask: Task<Void> = client.sendData(ACCOUNT_TYPE, transferBytes)
try {
    // Wait for the task to either complete or provide the callback.
    Tasks.await(exportTask, TIMEOUT_API, TIME_UNIT)
} catch (e: Exception) {
    when(e) {
        is ExecutionException, is InterruptedException, is TimeoutException -> {
            client.notifyCompletion(ACCOUNT_TYPE,
                    AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE)
            return
        }
        else -> throw e
    }
}

Java

AccountTransferClient client = AccountTransfer.getAccountTransferClient(this);
Task<Void> exportTask = client.sendData(ACCOUNT_TYPE, transferBytes);
try {
  // Wait for the task to either complete or provide the callback.
  Tasks.await(exportTask, TIMEOUT_API, TIME_UNIT);
} catch (ExecutionException | InterruptedException | TimeoutException e) {
  client.notifyCompletion(ACCOUNT_TYPE,AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE);
  return;
}

Wizard penyiapan pada perangkat target menerima data akun.

Menerima data akun

Jika layanan pengautentikasi yang sama diinstal di perangkat ini dan telah mendaftarkan minatnya dengan memproses siaran ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, perangkat target akan mengirim siaran ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE ke paket yang sesuai.

Saat menerima siaran ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, mulai layanan dan panggil retrieveData() pada perangkat target untuk mengambil data yang dikirim dari perangkat sumber. Cuplikan kode berikut mengilustrasikan cara mengambil data di perangkat target:

Kotlin

val client: AccountTransferClient = AccountTransfer.getAccountTransferClient(this)
val transportTask: Task<Void> = client.retrieveData(ACCOUNT_TYPE)
try {
    val transferBytes: ByteArray = Tasks.await(transferTask, TIMEOUT_API, TIME_UNIT)
    // Add the transferred account(s) to AccountManager to register with the framework.
} catch (e: Exception) {
    when(e) {
        is ExecutionException, is InterruptedException, is TimeoutException -> {
            client.notifyCompletion(ACCOUNT_TYPE,
                    AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE)
            return
        }
        else -> throw e
    }
 }
client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_SUCCESS)

Java

AccountTransferClient client = AccountTransfer.getAccountTransferClient(this);
Task<Void> transferTask = client.retrieveData(ACCOUNT_TYPE);
try {
  byte[] transferBytes = Tasks.await(transferTask, TIMEOUT_API, TIME_UNIT);
  // Add the transferred account(s) to AccountManager to register with the framework.
} catch (ExecutionException | InterruptedException | TimeoutException e) {
  client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE);
  return;
}
client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_SUCCESS);

Menyelesaikan transfer

Jika diperlukan, layanan pengautentikasi pada perangkat target juga dapat mentransfer data kembali ke perangkat sumber dengan memanggil sendData().

Untuk menerima data di perangkat sumber, layanan pengautentikasi harus memproses file siaran ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE . Demikian pula, layanan pengautentikasi Anda pada perangkat sumber dapat mengirim pesan berikutnya ke perangkat target.

Saat proses transfer selesai, layanan pengautentikasi Anda harus memanggil notifyCompletion() dengan status penyelesaian yang sesuai.

Jika memerlukan keamanan lebih lanjut, Anda dapat menghadirkan tantangan yang dihadapi pengguna di perangkat sumber atau target. Pertama, periksa apakah tantangan dapat ditampilkan dengan memanggil getDeviceMetaData() dan memeriksa hasilnya. Jika layanan pengautentikasi pada perangkat target mendukung tantangan, panggil showUserChallenge() untuk menampilkan tantangan.

Jika layanan pengautentikasi yang diperlukan belum diinstal pada perangkat target saat melakukan transfer, sistem akan menyimpan data yang ditransfer di penyimpanan lokal sementara. Saat aplikasi pertama kali diinstal dan dibuka, aplikasi dapat memanggil retrieveData() untuk memeriksa apakah ada data yang tersedia di penyimpanan lokal sementara. Jika ada data yang tersedia, Account Transfer API akan menampilkan data tersebut; jika tidak, panggilan akan gagal. Jika tidak terdapat data yang tersedia di penyimpanan lokal sementara, semua upaya lebih lanjut untuk mengambil data mungkin akan gagal. Jangan panggil notifyCompletion(), karena dapat gagal.

Ilustrasi perangkat target yang menyimpan data yang ditransfer dalam penyimpanan lokal sementara.

Gambar 3. Jika layanan pengautentikasi yang diperlukan belum diinstal pada perangkat target, sistem akan menyimpan data yang ditransfer di penyimpanan lokal sementara.

Menguji transfer akun

Wizard penyiapan berjalan saat Anda menyiapkan perangkat baru. Melakukan reset ke setelan pabrik secara rutin pada perangkat untuk menguji penyiapan dan transfer akun akan melelahkan dan memakan waktu. Oleh karena itu, Anda dapat menjalankan subset alur wizard penyiapan untuk menguji mentransfer akun pengguna dari satu perangkat ke perangkat lainnya.

Pastikan untuk memiliki setidaknya satu akun khusus di perangkat sumber sebelum memulai pengujian. Pastikan juga bahwa perangkat target tidak di-login dengan akun khusus apa pun. Jika perangkat target telah di-login dengan akun khusus saat Anda menjalankan wizard penyiapan, percobaan untuk menambahkan akun yang sama akan gagal saat sistem memanggil metode AccountManager.addAccountExplicitly().

Untuk keperluan pengujian, Anda harus menggunakan perangkat yang menjalankan Android 8.0 (API level 26) atau yang lebih tinggi sebagai perangkat target.

Anda dapat menggunakan perangkat yang menjalankan Android 4.0.1 (API level 14) atau yang lebih tinggi, serta layanan Google Play versi 11.2.0 atau yang lebih tinggi, sebagai perangkat sumber. Untuk membuat APK yang Anda uji, Anda harus menggunakan SDK layanan Google Play versi 11.2.0 atau yang lebih tinggi.

Untuk menguji alur wizard penyiapan, jalankan perintah berikut pada perangkat target Anda:

$ adb shell am start -a android.intent.action.MAIN -n com.google.android.gms/.smartdevice.d2d.ui.TargetActivity

Perintah meluncurkan aktivitas dan menampilkan wizard penyiapan, siap menyambungkan perangkat pengujian dengan perangkat lain. Setelah perangkat membuat sambungan, Anda dapat memulai proses transfer akun.