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 Tap & Go untuk memilih sumber data.

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

Untuk menambahkan dukungan untuk mentransfer akun khusus, integrasikan Account Transfer API di aplikasi Anda. Kemudian, layanan Google Play dapat menetapkan saluran terenkripsi bidireksional di antara perangkat yang ada, juga dikenal sebagai perangkat sumber, dan perangkat baru, juga dikenal sebagai perangkat target, untuk mentransfer data akun seperti yang diilustrasikan dalam 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 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 file build.gradle di dalam direktori modul aplikasi Anda di blok dependencies:

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 terinstal di image sistem OEM dan Anda tidak ingin menginstal aplikasi di image sistem OEM di masa mendatang, 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:

Pada perangkat sumber, daftar untuk memproses siaran ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE.
Pada perangkat target, daftar untuk memproses siaran ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE.

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 file 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 dikirimkan 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 it 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 it 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, Anda harus memeriksa apakah tantangan dapat ditampilkan dengan memanggil getDeviceMetaData() dan memeriksa hasilnya. Jika layanan pengautentikasi pada perangkat target mendukung tantangan, Anda dapat memanggil 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 terdapat 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 mungkin akan 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. Mereset perangkat untuk menguji penyiapan dan transfer akun secara berkala bisa melelahkan dan menghabiskan 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.