Account Transfer API

Stay organized with collections Save and categorize content based on your preferences.

Người dùng có thể sao chép dữ liệu và tài khoản Google qua một thiết bị chạy Android hiện có sang một thiết bị mới chạy hệ điều hành Android bằng tính năng Chạm và Chuyển. Sử dụng Account Transfer API để cho phép người dùng cũng sao chép được thông tin đăng nhập cho các tài khoản tuỳ chỉnh triển khai bằng cách sử dụng AbstractAccountAuthenticator và tích hợp với AccountManager. Hệ thống gọi Account Transfer API qua trình hướng dẫn thiết lập Chạm và Chuyển đang chạy trên thiết bị mới. Hệ thống cũng gọi Account Transfer API để chuyển dữ liệu từ điện thoại Android sang Pixel bằng cáp.

Màn hình chào mừng trong tính năng Chạm và Chuyển. Màn hình Chạm và Chuyển để chọn một nguồn dữ liệu.

Hình 1. Account Transfer API được gọi qua trình hướng dẫn thiết lập Chạm và Chuyển trên thiết bị mới.

Để hỗ trợ thêm tính năng chuyển tài khoản tuỳ chỉnh, hãy tích hợp Account Transfer API trong ứng dụng. Sau đó, Dịch vụ Google Play có thể thiết lập một kênh mã hoá hai chiều giữa thiết bị hiện có (còn được gọi là thiết bị nguồn) và thiết bị mới (còn được gọi là thiết bị mục tiêu) để chuyển dữ liệu tài khoản như minh hoạ trong hình 2. Kênh đã mã hoá không phụ thuộc vào việc kết nối với máy chủ của bên thứ ba để hoàn tất quá trình chuyển.

Hãy xem xét các yêu cầu sau đây khi tích hợp Account Transfer API vào ứng dụng:

  • Thiết bị nguồn phải chạy Android 4.0.1 (API cấp 14) trở lên.
  • Thiết bị đích phải chạy Android 8.0 (API cấp 26) trở lên.
  • Cả thiết bị nguồn và thiết bị đích đều phải chạy Dịch vụ Google Play phiên bản 11.2.0 trở lên.
  • Bạn phải xây dựng ứng dụng bằng cách sử dụng SDK Dịch vụ Google Play phiên bản 11.2.0 trở lên.

Hình minh hoạ quá trình chuyển tài khoản từ thiết bị nguồn sang thiết bị mục tiêu.

Hình 2. Quá trình chuyển diễn ra qua một kênh đã mã hoá mà Dịch vụ Google Play thiết lập giữa thiết bị nguồn và thiết bị mục tiêu.

Thêm Account Transfer API vào dự án

Để sử dụng Account Transfer API trong dự án, trước tiên bạn cần thiết lập dự án của mình bằng SDK Dịch vụ của Google Play. Để biết hướng dẫn chi tiết về cách thiết lập SDK Dịch vụ Google Play, hãy xem nội dùn Thiết lập Dịch vụ Google Play.

Nếu bạn muốn biên dịch chọn lọc Account Transfer API Google vào ứng dụng, hãy thêm quy tắc xây dựng sau vào tệp build.gradle bên trong thư mục mô-đun ứng dụng của bạn trong khối 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>")
}

Để hỗ trợ thêm việc chuyển tài khoản tuỳ chỉnh, bạn phải khai báo trình nhận thu phát (broadcast receiver) START_ACCOUNT_EXPORT cho dịch vụ trình xác thực của mình trong tệp kê khai của ứng dụng:

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

Nếu ứng dụng của bạn không được cài đặt trong hình ảnh hệ thống của OEM và bạn không có kế hoạch sau này đặt ứng dụng của mình vào hình ảnh hệ thống OEM, hãy đảm bảo bạn đăng ký nghe ACTION_START_ACCOUNT_EXPORT phát trên thiết bị nguồn để xuất dữ liệu tài khoản như mô tả ở trên.

Nếu cài đặt ứng dụng trên hình ảnh hệ thống OEM, bạn cũng phải đăng ký các trình thu phát sau:

Chuyển dữ liệu tài khoản

Sau khi người dùng chọn khôi phục nội dung từ thiết bị hiện có, hệ thống sẽ gửi ACTION_START_ACCOUNT_EXPORT phát đi thông báo đến các gói đã liên kết với các tài khoản liên quan trên thiết bị nguồn.

Gửi dữ liệu tài khoản

Để gửi dữ liệu tài khoản, hãy khởi động dịch vụ trình xác thực trên thiết bị nguồn rồi gọi sendData() sau khi dịch vụ nhận được ACTION_START_ACCOUNT_EXPORT phát đi thông báo. Bạn có thể tham chiếu đến đối tượng AccountTransferClient bằng cách gọi getAccountTransferClient(Context) hoặc getAccountTransferClient(Activity). Đoạn mã sau minh hoạ cách bạn có thể gửi dữ liệu từ thiết bị nguồn:

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

Trình hướng dẫn thiết lập trên thiết bị mục tiêu sẽ nhận dữ liệu tài khoản.

Nhận dữ liệu tài khoản

Nếu dịch vụ xác thực đó được cài đặt trên thiết bị này và người dùng đã đăng ký dịch vụ đó bằng cách lắng nghe trình thu phát ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, thì thiết bị mục tiêu gửi ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE sẽ phát đi thông báo đến các gói tương ứng.

Khi nhận được thông báo ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, hãy bắt đầu một dịch vụ rồi gọi retrieveData() trên thiết bị mục tiêu để truy xuất dữ liệu đã gửi từ thiết bị nguồn. Đoạn mã sau đây minh hoạ cách bạn có thể truy xuất dữ liệu trên thiết bị mục tiêu:

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

Hoàn tất quá trình chuyển

Nếu cần, dịch vụ trình xác thực trên thiết bị mục tiêu cũng có thể chuyển dữ liệu trở lại thiết bị nguồn bằng cách gọi sendData().

Để nhận dữ liệu trên thiết bị nguồn, dịch vụ trình xác thực của bạn phải theo dõi trình thu phát ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE. Tương tự, dịch vụ trình xác thực của bạn trên thiết bị nguồn có thể gửi thêm thông báo đến thiết bị mục tiêu.

Khi quá trình chuyển kết thúc, dịch vụ trình xác thực của bạn phải gọi notifyCompletion() kèm theo trạng thái hoàn thành thích hợp.

Nếu cần tăng cường bảo mật, bạn có thể đưa ra một thử thách mà người dùng nhìn thấy trên thiết bị nguồn hoặc thiết bị mục tiêu. Trước tiên, bạn phải kiểm tra xem các thử thách có thể xuất hiện hay không bằng cách gọi getDeviceMetaData() rồi kiểm tra kết quả. Nếu dịch vụ xác thực trên thiết bị mục tiêu hỗ trợ các thử thách, bạn có thể gọi showUserChallenge() để hiển thị thử thách xác thực.

Nếu dịch vụ trình xác thực bắt buộc không được cài đặt trên thiết bị mục tiêu tại thời điểm chuyển, hệ thống sẽ lưu trữ dữ liệu được chuyển trong bộ nhớ cục bộ tạm thời. Trong lần đầu cài đặt và mở, ứng dụng có thể gọi retrieveData() để kiểm tra xem có dữ liệu nào trong bộ nhớ cục bộ tạm thời hay không. Nếu có sẵn dữ liệu, Account Transfer API sẽ trả về dữ liệu; nếu không, lệnh gọi không hoạt động. Nếu không có dữ liệu trong bộ nhớ cục bộ tạm thời, thì hệ thống sẽ không thể truy xuất thêm dữ liệu. Đừng gọi notifyCompletion() vì thao tác này có thể không thực hiện được.

Hình minh hoạ thiết bị đích lưu trữ dữ liệu được chuyển trong bộ nhớ cục bộ tạm thời.

Hình 3. Nếu bạn không cài đặt dịch vụ trình xác thực bắt buộc trên thiết bị mục tiêu, thì hệ thống sẽ lưu trữ dữ liệu được chuyển trong bộ nhớ cục bộ tạm thời.

Thử nghiệm việc chuyển tài khoản

Trình hướng dẫn thiết lập sẽ chạy khi bạn thiết lập thiết bị mới. Việc thường xuyên đặt lại thiết bị về trạng thái ban đầu để kiểm tra việc thiết lập và chuyển tài khoản sẽ tốn thời gian và công sức. Thay vào đó, bạn có thể chạy một nhóm nhỏ quy trình thiết lập để thử nghiệm chuyển tài khoản của người dùng từ thiết bị này sang thiết bị khác.

Hãy nhớ có ít nhất một tài khoản tuỳ chỉnh trên thiết bị nguồn trước khi bắt đầu thử nghiệm. Ngoài ra, hãy đảm bảo rằng thiết bị mục tiêu chưa đăng nhập vào bất kỳ tài khoản tuỳ chỉnh nào. Nếu thiết bị đích đã đăng nhập vào một tài khoản tuỳ chỉnh khi bạn chạy trình hướng dẫn thiết lập, thì việc cố gắng thêm tài khoản tương tự sẽ không thành công khi hệ thống gọi AccountManager.addAccountExplicitly().

Đối với mục đích thử nghiệm, bạn phải sử dụng một thiết bị chạy Android 8.0 (API cấp 26) trở lên làm thiết bị mục tiêu.

Bạn có thể sử dụng một thiết bị chạy Android 4.0.1 (API cấp 14) trở lên, cũng như Dịch vụ của Google Play phiên bản 11.2.0 trở lên làm thiết bị nguồn. Để xây dựng tệp APK mà bạn đang thử nghiệm, bạn phải sử dụng SDK Dịch vụ Google Play phiên bản 11.2.0 trở lên.

Để kiểm tra quy trình hướng dẫn thiết lập, hãy chạy lệnh sau trên thiết bị mục tiêu:

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

Lệnh này sẽ chạy một hoạt động và hiện trình hướng dẫn thiết lập, sẵn sàng ghép nối thiết bị thử nghiệm với một thiết bị khác. Sau khi các thiết bị thiết lập kết nối, bạn có thể bắt đầu quá trình chuyển tài khoản.