این سند باید راهنمای اصلی شما برای استفاده از کیت توسعه نرمافزار AMAPI برای دریافت سیگنالهای اعتماد دستگاه باشد.
کیت توسعه نرمافزار AMAPI به برنامه شما امکان میدهد به نشانهای اعتماد دستگاه از برنامه Android Device Policy (ADP) دسترسی پیدا کند. سپس برنامه شما میتواند از این نشانها برای محاسبه وضعیت اعتماد دستگاه و اجرای منطق کسبوکار بهدلخواه استفاده کند.
پیشنیازها
- برنامه شما باید برای خواندن سیگنالهای اعتماد دستگاه مجاز باشد:
- برنامههای همراه در دستگاههای تحتمدیریت AMAPI: برنامههایی که نقش
COMPANION_APPدر خطمشی به آنها اختصاص داده شده است میتوانند به سیگنالهای اعتماد دستگاه دسترسی داشته باشند بدون اینکه در فهرست مجاز دستگاههای کاملاً مدیریتشده یا از داخل نمایه کاری باشند (با دسترسی محدود به سیگنالهای نمایه کاری). برای جزئیات بیشتر، به مدیریت نقشهای برنامه، پیکربندی خطمشی، و دسترسی به سیگنالها از برنامه همراه مراجعه کنید. - همه برنامهها و محیطهای دیگر: دسترسی به سیگنالهای اعتماد دستگاه
از داخل نمایه شخصی، در دستگاه مدیریتنشده، در دستگاه
مدیریتشده توسط DPC سفارشی، یا بدون نقش
COMPANION_APPمستلزم این است که برنامه شما در فهرست مجاز باشد. برای کسب اطلاعات درباره نحوه درخواست، به صفحه دسترسی به سیگنالهای اعتماد دستگاه بروید.
- برنامههای همراه در دستگاههای تحتمدیریت AMAPI: برنامههایی که نقش
- Android Enterprise توصیه میکند مجموعه Play Integrity از میاناهای برنامهسازی کاربردی را در برنامه کارخواه خود ادغام کنید و قبلاز خواندن و تکیه بر سیگنالهای اعتماد دستگاه، به نتیجه مراجعه کنید. دستگاههایی که در بررسیهای Play Integrity API مردود میشوند نباید قابلاعتماد تلقی شوند و هیچکدام از سیگنالهای برگرفته از دستگاه نباید برای تعیین وضعیت اعتماد استفاده شوند. برای جزئیات بیشتر میتوانید به اسناد Play Integrity مراجعه کنید.
ادغام کردن با AMAPI SDK در برنامه
برای دسترسی به سیگنالهای اعتماد دستگاه، برنامه شما باید با AMAPI SDK ادغام شود. در راهنمای ادغام AMAPI SDK میتوانید اطلاعات بیشتری درباره این کتابخانه و نحوه افزودن آن به برنامهتان پیدا کنید.
افزودن اجازههای لازم
برخیاز سیگنالهای برگشتی از Device Trust از Android Enterprise API مستلزم این است که برنامه همان اجازهای را اعلام کند که در وهله اول برای دسترسی به این اطلاعات لازم است، بهویژه:
| نشان | اجازه لازم است |
|---|---|
| وضعیت شبکه | ACCESS_NETWORK_STATE |
| پیچیدگی قفل صفحه | REQUEST_PASSWORD_COMPLEXITY |
اگر این اجازهها در AndroidManifest.xml برنامه گنجانده نشده باشد،
Device Trust از Android Enterprise 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) }
جاوا
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 ازقبل نصب شده باشد، میانای برنامهسازی کاربردی آن را بدون دخالت کاربر بهطور بیصدا بهروزرسانی خواهد کرد.
اگر برنامه ADP نصب نشده باشد، API از کاربر درخواست میکند تا نصب برنامه ADP را بپذیرد.
میتوانید برای نظارت بر انتخاب کاربر، یک فراخوانی برگشتی ثبت کنید. برای جزئیات بیشتر، ردیابی تعامل کاربر درطول نصب برنامه ADP را ببینید.
توصیه میکنیم که فراخوانی prepareEnvironment از فرایند پیشزمینه درطول جریان تجربه کاربری آمادهسازی انجام شود تا کاربر با کادر گفتگوی مدال نصب خطمشی دستگاه Android غافلگیر نشود.
اگر تماس گرفتن از فرایند پیشزمینه ممکن نباشد، چون این یک جریان وب است و مؤلفه Android واسط کاربر ندارد، تماس گرفتن از پسزمینه مجاز است، مشروط بر اینکه این اتفاق درطول جریان تجربه کاربری آمادهسازی رخ دهد.
وقتی محیط بهدرستی راهاندازی شد، میتوان به «سیگنالهای» اعتماد دستگاه دسترسی پیدا کرد. دسترسی به سیگنالهای اعتماد دستگاه را ببینید.
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()) }
جاوا
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) برقرار میکند
که بهطور خودکار هنگام غیرفعال بودن لغو اتصال میشود. چون نمونههای کارخواه روش خاموش کردن صریحی را نشان نمیدهند، ایجاد و دور انداختن چندین نمونه باعث میشود کانالهای یتیم برای جمعآوری زباله باقی بمانند.
برای بهینهسازی عملکرد و جلوگیری از کانالهای یتیم، یک نمونه واحد از
DeviceClient در محدوده برنامه بااستفاده از
DeviceClientFactory.create(context.applicationContext) ایجاد کنید و آن را برای استفاده مجدد در سراسر برنامه خود ذخیره کنید—برای مثال، بهعنوان یک سینگلتون با محدوده برنامه یا
بااستفاده از تزریق وابستگی.
برای دسترسی به سیگنالهای اعتماد دستگاه موردنظرتان، از نمونه ذخیرهشده در حافظه نهان
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) }
جاوا
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 به آن اختصاص داده شده است میتواند سیگنالهای اعتماد دستگاه را بدون
ثبت شدن در فهرست مجاز بخواند.
وقتی از داخل نمایه کاری (در دستگاه متعلق به شرکت یا دستگاه متعلق به شخص) فراخوانی میشود، برنامهتان باید در داخل نمایه کاری اجرا شود و دسترسی به سیگنالهای نمایه کاری محدود است (برای مثال، وضعیت مدیریت، پیچیدگی قفل صفحه، و برنامههای نصبشده فقط نمایه کاری را منعکس میکنند).
۱. اختصاص دادن نقش COMPANION_APP در خطمشی
خطمشی EMM خود را پیکربندی کنید تا roleType: "COMPANION_APP" را به
برنامه شما در فهرست خطمشی applications اعطا کند:
- برای پیکربندی مانیفست برنامه و گوش دادن اختیاری به واگذاریهای نقش، مدیریت نقشهای برنامه را ببینید.
- برای نحو پیکربندی خطمشی، پیکربندی خطمشی را ببینید.
۲. خواندن مستقیم نشانها با DeviceClient
یک نمونه deviceClient را در محدوده برنامه بااستفاده از
DeviceClientFactory.create ایجاد و ذخیره کنید (به
توصیه استفاده از 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" } }
جاوا
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- برنامه شما برای ارائه درخواست مجاز نیست (برای مثال، برنامه شما درصورت نیاز در فهرست مجاز ثبت نشده است، نقشCOMPANION_APPدر دستگاه تحت مدیریت AMAPI به آن اختصاص داده نشده است، یاprepareEnvironmentرا بهعنوان برنامه همراهی که در فهرست مجاز نیست فراخوانی کرده است). دسترسی به نشانهای اعتماد دستگاه و دسترسی به نشانها از برنامه همراه را ببینید.- زیرکلاس
AmapiSdkException- ADP وجود ندارد یا آماده نیست. این میتواند بهدلیل شرایط گذرا باشد و باید تماس را دوباره امتحان کنید.
امتحان کردن مجدد استراتژیها
برای استثناهای ناشی از شرایط گذرا، راهبرد تکرار مجدد را با عقبنشینی نمایی پیادهسازی کنید. پساز اولین شکست، با تأخیر اولیه ۵ ثانیهای شروع کنید و سپس دوباره امتحان کنید.
راهبرد امتحان مجدد را با حداکثر تعداد تلاش بهعنوان شرط خروج بااستفاده از تأخیر افزایشیافته نمایی در هر بار (۱۰ ثانیه، ۲۰ ثانیه، و غیره) پیادهسازی کنید.
ردیابی تعامل کاربر درطول نصب برنامه ADP
اگر دستگاه نیاز به نصب برنامه ADP درطول prepareEnvironment داشته باشد،
برنامه شما میتواند تعامل کاربر را با پیادهسازی
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 } }
جاوا
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"); } } }
مشکلات شناختهشده
درحالحاضر مشکل شناختهشدهای وجود ندارد.