如要使用 AMAPI SDK 接收裝置信任信號,請務必參考這份文件。
AMAPI SDK 可讓應用程式存取 Android Device Policy (ADP) 應用程式的裝置信任信號。應用程式接著可以使用這些信號,計算裝置的信任狀態,並執行所選的商業邏輯。
必要條件
- 應用程式必須獲得授權,才能讀取裝置信任信號:
- AMAPI 管理裝置上的隨附應用程式:在政策中獲派
COMPANION_APP角色的應用程式,不需加入全代管裝置或工作資料夾的許可清單,即可存取裝置信任信號 (僅限工作資料夾的信號)。詳情請參閱「管理應用程式角色」、「政策設定」和「從隨附應用程式存取信號」。 - 所有其他應用程式和環境:如要從個人資料夾、非受管理裝置、自訂 DPC 管理的裝置,或在沒有
COMPANION_APP角色時存取裝置信任信號,應用程式必須加入許可清單。如要瞭解如何申請,請前往裝置信任信號存取權頁面。
- AMAPI 管理裝置上的隨附應用程式:在政策中獲派
- Android Enterprise 建議您將 Play Integrity API 套件整合至用戶端應用程式,並在讀取及依賴裝置信任信號前,先參考結果。如果裝置未通過 Play Integrity API 檢查,則不應信任該裝置,也不應信任從該裝置取得的任何信號,用於判斷信任狀態。詳情請參閱 Play Integrity 說明文件。
在應用程式中整合 AMAPI SDK
如要存取裝置信任信號,應用程式必須與 AMAPI SDK 整合。如要進一步瞭解這個程式庫,以及如何將其新增至應用程式,請參閱 AMAPI SDK 整合指南。
新增必要權限
Android Enterprise 的 Device Trust 傳回的部分信號,需要應用程式宣告與一開始存取這項資訊時相同的權限,尤其是:
| 信號 | 必要權限 |
|---|---|
| 網路狀態 | ACCESS_NETWORK_STATE |
| 螢幕鎖定複雜度 | REQUEST_PASSWORD_COMPLEXITY |
如果應用程式的 AndroidManifest.xml 未包含這些權限,Android Enterprise 的 Device Trust API 會在相關信號的中繼資料中傳回 PERMISSION_ISSUE:
internalDeviceSettings=DeviceSettings{
screenLockComplexity=COMPLEXITY_UNSPECIFIED,
internalScreenLockComplexityMetadata=Metadata{
dataIssues=[
DataIssue{
issueType=PERMISSION_ISSUE,
issueLevel=WARNING,
issueDetails=IssueDetailsCase{none}
}
]
},
詳情請參閱可用的裝置信任信號清單。
存取裝置信任信號的步驟
許可清單中的應用程式 (包括在個人資料夾或非受管理裝置上執行的應用程式),必須先確認用戶端環境為最新狀態,並在必要時做好準備,才能要求信號。
如要讓許可清單中的應用程式存取裝置信任信號,請按照下列步驟操作:

驗證用戶端環境
下列程式碼範例說明如何使用 getEnvironment 讀取 ADP 應用程式的目前狀態。如果環境已準備就緒且為最新狀態,應用程式就能使用快取的 deviceClient 執行個體存取裝置信任信號 (請參閱「存取裝置信任信號」)。
Kotlin
import com.google.android.managementapi.common.model.Role import com.google.android.managementapi.device.DeviceClient import com.google.android.managementapi.device.DeviceClientFactory import com.google.android.managementapi.device.model.GetDeviceRequest import com.google.android.managementapi.environment.EnvironmentClient import com.google.android.managementapi.environment.EnvironmentClientFactory import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.INSTALLED import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.NOT_INSTALLED import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.READY import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.Version.UP_TO_DATE import com.google.android.managementapi.environment.model.GetEnvironmentRequest import com.google.android.managementapi.environment.model.PrepareEnvironmentRequest try { val context = applicationContext val roles = listOf(Role.builder().setRoleType(Role.RoleType.IDENTITY_PROVIDER).build()) val request = GetEnvironmentRequest.builder().setRoles(roles).build() val environmentClient = EnvironmentClientFactory.create(context) val environmentResponse = environmentClient.getEnvironment(request) if (environmentResponse.hasAndroidDevicePolicyEnvironment()) { val adpEnvironment = environmentResponse.androidDevicePolicyEnvironment if (adpEnvironment.state == READY && adpEnvironment.version == UP_TO_DATE) { // AMAPI Environment State OK, Version OK. Requesting Device signals.. checkDevice(deviceClient) } else if (adpEnvironment.state == INSTALLED) { // prepareEnvironment should be called, calling // prepareEnvironment won't show the UI prepareEnvironment(context, environmentClient) } else if (adpEnvironment.state == NOT_INSTALLED) { // prepareEnvironment should be called, calling // prepareEnvironment will show the UI prepareEnvironment(context, environmentClient) } } } catch (e: Exception) { Log.e(TAG, "Exception", e) }
Java
import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.INSTALLED; import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.NOT_INSTALLED; import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.State.READY; import static com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment.Version.UP_TO_DATE; import com.google.android.managementapi.common.model.Role; import com.google.android.managementapi.device.DeviceClient; import com.google.android.managementapi.device.DeviceClientFactory; import com.google.android.managementapi.device.model.Device; import com.google.android.managementapi.device.model.GetDeviceRequest; import com.google.android.managementapi.environment.EnvironmentClient; import com.google.android.managementapi.environment.EnvironmentClientFactory; import com.google.android.managementapi.environment.model.Environment; import com.google.android.managementapi.environment.model.Environment.AndroidDevicePolicyEnvironment; import com.google.android.managementapi.environment.model.GetEnvironmentRequest; import com.google.android.managementapi.environment.model.PrepareEnvironmentRequest; import com.google.android.managementapi.environment.model.PrepareEnvironmentResponse; try { Context context = getApplicationContext(); ImmutableListroles = new ImmutableList.Builder () .add(Role.builder() .setRoleType(Role.RoleType.IDENTITY_PROVIDER) .build()) .build(); EnvironmentClient environmentClient = EnvironmentClientFactory.create(context); GetEnvironmentRequest request = GetEnvironmentRequest.builder() .setRoles(roles) .build(); ListenableFuture getEnvironmentFuture = environmentClient.getEnvironmentAsync(request); Futures.addCallback(getEnvironmentFuture, new FutureCallback<>() { @Override public void onSuccess(Environment environment) { AndroidDevicePolicyEnvironment adpEnvironment = environment.getAndroidDevicePolicyEnvironment(); AndroidDevicePolicyEnvironment.State state = adpEnvironment.getState(); AndroidDevicePolicyEnvironment.Version version = adpEnvironment.getVersion(); if (state == READY && version == UP_TO_DATE) { // AMAPI Environment State OK, Version OK. Requesting Device signals.. checkDevice(deviceClient); } else if (state == INSTALLED) { // prepareEnvironment should be called, calling // prepareEnvironment won't show the UI prepareEnvironment(context, environmentClient); } else if (state == NOT_INSTALLED) { // prepareEnvironment should be called, calling // prepareEnvironment will show the UI prepareEnvironment(context, environmentClient); } } @Override public void onFailure(Throwable t) { Log.d(TAG, t.toString()); } }, MoreExecutors.directExecutor()); } catch (Exception e) { Log.d(TAG, e.toString()); }
如果已安裝 ADP 應用程式,但不是最新版本,您的應用程式應呼叫 prepareEnvironment,在不需使用者介入的情況下,自動更新 ADP 應用程式。
如果未安裝 ADP 應用程式,您的應用程式可以呼叫 prepareEnvironment,提示使用者安裝 ADP 應用程式。請參閱「準備用戶端環境」。
準備用戶端環境
如果已安裝 ADP 應用程式,API 會在背景更新,不需使用者介入。
如果未安裝 ADP 應用程式,API 會提示使用者接受安裝 ADP 應用程式。
您可以註冊回呼,監控使用者選擇。詳情請參閱「在 ADP 應用程式安裝期間追蹤使用者互動」。
建議您在新手上路使用者體驗流程中,從前景程序執行 prepareEnvironment 呼叫,以免使用者看到「安裝 Android Device Policy」強制回應對話方塊而感到意外。如果無法從前景程序呼叫 (因為這是網頁流程,且 Android 元件沒有 UI),則允許從背景呼叫,但必須在新進人員訓練使用者體驗流程中進行。
正確設定環境後,即可存取裝置信任信號。請參閱「存取裝置信任信號」。
Kotlin
try { val myNotificationReceiverService = ComponentName( context, MyNotificationReceiverService::class.java ) val roles = listOf(Role.builder().setRoleType(Role.RoleType.IDENTITY_PROVIDER).build()) val request = PrepareEnvironmentRequest.builder().setRoles(roles).build() val response = environmentClient.prepareEnvironment(request, myNotificationReceiverService) val environment = response.environment val adpEnvironment = environment.androidDevicePolicyEnvironment val state = adpEnvironment.state val version = adpEnvironment.version if (state == READY && version == UP_TO_DATE) { // Environment is prepared, access device posture signals using // DeviceClient. checkDevice(deviceClient) } else { // The prepareEnvironment call failed to prepare Log.w( TAG, "AMAPI environment was not ready: " + state + " - " + version ) } } catch (e: java.lang.Exception) { Log.d(TAG, e.toString()) }
Java
try { ComponentName myNotificationReceiverService = new ComponentName( context, MyNotificationReceiverService.class ); ImmutableListroles = new ImmutableList.Builder () .add(Role.builder() .setRoleType(Role.RoleType.IDENTITY_PROVIDER) .build()) .build(); PrepareEnvironmentRequest request = PrepareEnvironmentRequest.builder() .setRoles(roles) .build(); ListenableFuture environmentFuture = environmentClient.prepareEnvironmentAsync( request, myNotificationReceiverService ); Futures.addCallback(environmentFuture, new FutureCallback<>() { @Override public void onSuccess(PrepareEnvironmentResponse response) { Environment environment = response.getEnvironment(); AndroidDevicePolicyEnvironment adpEnvironment = environment.getAndroidDevicePolicyEnvironment(); AndroidDevicePolicyEnvironment.State state = adpEnvironment.getState(); AndroidDevicePolicyEnvironment.Version version = adpEnvironment.getVersion(); if (state == READY && version == UP_TO_DATE) { // AMAPI Environment State OK, Version OK. Requesting Device signals.. checkDevice(deviceClient); } else { // The prepareEnvironment call failed to prepare Log.w( TAG, "AMAPI environment was not ready: " + adpEnvironment.getState() + " - " + adpEnvironment.getVersion() ); } } @Override public void onFailure(@NonNull Throwable t) { // Handle the error Log.d(TAG, "AMAPI response did not contain an ADP environment"); } }, MoreExecutors.directExecutor()); } catch (Exception e) { Log.d(TAG, e.toString()); }
存取裝置信任信號
DeviceClient 使用建議
建立 deviceClient 執行個體 (或 EnvironmentClient 執行個體) 會與 Android 裝置政策 (ADP) 應用程式建立通訊管道,並在閒置時自動解除繫結。由於用戶端執行個體不會公開明確的關閉方法,因此建立及捨棄多個執行個體會留下孤立的管道,等待垃圾收集。
為提升效能並避免孤立管道,請使用 DeviceClientFactory.create(context.applicationContext) 在應用程式範圍建立單一 DeviceClient 執行個體,並快取該執行個體,以便在整個應用程式中重複使用,例如做為應用程式範圍的單例模式,或使用依附元件插入。
如要存取您感興趣的裝置信任信號,請使用快取的 deviceClient 執行個體要求 Device 物件:
Kotlin
runCatching { deviceClient.getDeviceAwait(GetDeviceRequest.getDefaultInstance()) }.onFailure { t -> Log.d(TAG, t.toString()) }.onSuccess { device -> // Access device posture signals available in device val deviceString = device.toString() Log.d(TAG, deviceString) }
Java
ListenableFuturedeviceFuture = deviceClient.getDevice(GetDeviceRequest.getDefaultInstance()); Futures.addCallback(deviceFuture, new FutureCallback () { @Override public void onSuccess(Device device) { // Access device posture signals available in device String deviceString = device.toString(); Log.d(TAG, deviceString); } @Override public void onFailure(Throwable t) { Log.d(TAG, t.toString()); } }, MoreExecutors.directExecutor());
從隨附應用程式存取信號
在全代管裝置上,或在透過 Android Management API (AMAPI) 管理的工作資料夾中,獲派 COMPANION_APP 角色的應用程式不需註冊許可清單,即可讀取裝置信任信號。
從工作資料夾 (無論是公司擁有或個人擁有的裝置) 內呼叫時,應用程式必須在工作資料夾內執行,且只能存取工作資料夾的信號 (例如管理狀態、螢幕鎖定複雜度和已安裝的應用程式,只會反映工作資料夾)。
1. 在政策中指派 COMPANION_APP 角色
設定 EMM 政策,在 applications 政策清單中將 roleType: "COMPANION_APP" 授予應用程式:
2. 直接使用 DeviceClient 讀取信號
使用 DeviceClientFactory.create 在應用程式範圍建立並快取單一 deviceClient 執行個體 (請參閱DeviceClient 使用建議),然後直接要求 Device 物件:
Kotlin
import android.content.Context import android.util.Log import com.google.android.managementapi.device.DeviceClient import com.google.android.managementapi.device.DeviceClientFactory import com.google.android.managementapi.device.model.GetDeviceRequest // Instantiate once at application scope (for example, using dependency injection) // to reuse a single DeviceClient instance across your app. class DeviceTrustRepository(context: Context) { private val deviceClient: DeviceClient = DeviceClientFactory.create(context.applicationContext) suspend fun readSignalsFromCompanionApp() { runCatching { deviceClient.getDeviceAwait(GetDeviceRequest.getDefaultInstance()) }.onSuccess { device -> Log.d(TAG, "Device signals: $device") }.onFailure { t -> Log.e(TAG, "Failed to read device signals", t) } } companion object { private const val TAG = "DeviceTrustRepository" } }
Java
import android.content.Context; import android.util.Log; import com.google.android.managementapi.device.DeviceClient; import com.google.android.managementapi.device.DeviceClientFactory; import com.google.android.managementapi.device.model.Device; import com.google.android.managementapi.device.model.GetDeviceRequest; import com.google.common.util.concurrent.FutureCallback; import com.google.common.util.concurrent.Futures; import com.google.common.util.concurrent.ListenableFuture; import com.google.common.util.concurrent.MoreExecutors; // Instantiate once at application scope (for example, using dependency injection) // to reuse a single DeviceClient instance across your app. public class DeviceTrustRepository { private static final String TAG = "DeviceTrustRepository"; private final DeviceClient deviceClient; public DeviceTrustRepository(Context context) { this.deviceClient = DeviceClientFactory.create(context.getApplicationContext()); } public void readSignalsFromCompanionApp() { ListenableFuturedeviceFuture = deviceClient.getDevice(GetDeviceRequest.getDefaultInstance()); Futures.addCallback(deviceFuture, new FutureCallback () { @Override public void onSuccess(Device device) { Log.d(TAG, "Device signals: " + device); } @Override public void onFailure(Throwable t) { Log.e(TAG, "Failed to read device signals", t); } }, MoreExecutors.directExecutor()); } }
處理錯誤
如果應用程式發出裝置信任要求,但呼叫失敗,應用程式會收到例外狀況。造成這類例外狀況的原因有很多,例如:
SecurityException:應用程式未獲授權,無法提出要求 (例如應用程式未在必要時註冊至許可清單、未在 AMAPI 管理的裝置上獲派COMPANION_APP角色,或呼叫prepareEnvironment做為未在許可清單中的隨附應用程式)。請參閱「裝置信任信號存取權」和「從隨附應用程式存取信號」。AmapiSdkException的子類別 - ADP 不存在或未就緒。這可能是暫時性狀況,請重試呼叫。
重試策略
如果例外狀況是由暫時性狀況造成,請採用指數輪詢重試策略。首次失敗後,請等待 5 秒的初始延遲時間,然後再重試。
實作重試策略,並以最大重試次數做為結束條件,每次重試的延遲時間依指數遞增 (10 秒、20 秒等)。
追蹤 ADP 應用程式安裝期間的使用者互動
如果裝置需要在prepareEnvironment期間安裝 ADP 應用程式,您的應用程式可以追蹤使用者互動,方法是實作 NotificationReceiverService 接收通知,並覆寫 getPrepareEnvironmentListener:
Kotlin
import android.util.Log import com.google.android.managementapi.environment.EnvironmentListener import com.google.android.managementapi.environment.model.EnvironmentEvent.EventCase.Kind.ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED import com.google.android.managementapi.environment.model.EnvironmentEvent import com.google.android.managementapi.notification.NotificationReceiverService class MyNotificationReceiverService : NotificationReceiverService() { override fun getPrepareEnvironmentListener(): EnvironmentListener { return MyEnvironmentListener() } } class MyEnvironmentListener : EnvironmentListener { override fun onEnvironmentEvent( event: EnvironmentEvent ) { if (event.event.kind == ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED) { Log.d(TAG, "User provided install consent") } else { Log.d(TAG, "User rejected install consent") } } companion object { private val TAG: String = MyEnvironmentListener::class.java.simpleName } }
Java
import static com.google.android.managementapi.environment.model.EnvironmentEvent.EventCase.Kind.ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED; import android.util.Log; import androidx.annotation.NonNull; import com.google.android.managementapi.environment.EnvironmentListener; import com.google.android.managementapi.environment.model.EnvironmentEvent; import com.google.android.managementapi.notification.NotificationReceiverService; class MyNotificationReceiverService extends NotificationReceiverService { @NonNull @Override protected EnvironmentListener getPrepareEnvironmentListener() { return new MyEnvironmentListener(); } } class MyEnvironmentListener implements EnvironmentListener { final private String TAG = MyEnvironmentListener.class.getSimpleName(); @Override public void onEnvironmentEvent(EnvironmentEvent event) { if (event.getEvent().getKind() == ANDROID_DEVICE_POLICY_INSTALL_CONSENT_ACCEPTED) { Log.d(TAG, "User provided install consent"); } else { Log.d(TAG, "User rejected install consent"); } } }
已知問題
目前沒有已知問題。