המסמך הזה הוא המדריך הראשי לשימוש ב-AMAPI SDK כדי לקבל אותות מהימנות של מכשירים.
AMAPI SDK מאפשר לאפליקציה לגשת לאותות האמינות של המכשיר מאפליקציית Android Device Policy (ADP). לאחר מכן, האפליקציה יכולה להשתמש באותות האלה כדי לחשב את מצב האמינות של המכשיר ולהפעיל לוגיקה עסקית לפי הצורך.
דרישות מוקדמות
- לאפליקציה צריכה להיות הרשאה לקרוא אותות אמינות של המכשיר:
- אפליקציות נלוות במכשירים שמנוהלים באמצעות AMAPI: אפליקציות שהוקצה להן התפקיד
COMPANION_APPבמדיניות יכולות לגשת לאותות האמינות של המכשיר בלי להיות ברשימת ההיתרים במכשירים בניהול מלא או מתוך פרופיל עבודה (עם גישה מוגבלת לאותות מפרופיל העבודה). פרטים נוספים זמינים במאמרים ניהול תפקידי אפליקציה, הגדרת מדיניות וגישה לאותות מאפליקציה נלווית. - כל האפליקציות והסביבות האחרות: כדי לגשת לאותות האמינות של המכשיר מתוך פרופיל אישי, במכשיר לא מנוהל, במכשיר שמנוהל על ידי DPC בהתאמה אישית או בלי התפקיד
COMPANION_APP, האפליקציה צריכה להיות ברשימת ההיתרים. במאמר גישה לאותות האמינות של המכשיר מוסבר איך להגיש בקשה.
- אפליקציות נלוות במכשירים שמנוהלים באמצעות AMAPI: אפליקציות שהוקצה להן התפקיד
- ב-Android Enterprise מומלץ לשלב את חבילת ממשקי ה-API של Play Integrity באפליקציית הלקוח, ולהתייחס לתוצאה לפני שקוראים את אותות האמון של המכשיר ומסתמכים עליהם. מכשירים שלא עוברים את הבדיקות של Play Integrity API לא נחשבים מהימנים, וגם לא האותות שמתקבלים מהמכשיר ומשמשים לקביעת מצב המהימנות. פרטים נוספים זמינים במאמרי העזרה של Play Integrity.
שילוב עם AMAPI SDK באפליקציה
כדי לגשת לאותות האמינות של המכשיר, האפליקציה צריכה להשתלב עם AMAPI SDK. מידע נוסף על הספרייה הזו ועל הוספה שלה לאפליקציה זמין במדריך לשילוב AMAPI SDK.
הוספת ההרשאות הנדרשות
כדי לקבל חלק מהאותות שמוחזרים מ-Device Trust from Android Enterprise API, האפליקציה צריכה להצהיר על אותה הרשאה שנדרשת כדי לגשת למידע הזה מלכתחילה, ובמיוחד:
| אות | ההרשאה הנדרשת |
|---|---|
| מצב הרשת | ACCESS_NETWORK_STATE |
| רמת המורכבות של נעילת המסך | REQUEST_PASSWORD_COMPLEXITY |
אם ההרשאות האלה לא כלולות ב-AndroidManifest.xml של האפליקציה, Device Trust from 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) }
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.
אפשר לרשום קריאה חוזרת (callback) כדי לעקוב אחרי בחירת המשתמש. פרטים נוספים זמינים במאמר מעקב אחרי אינטראקציות של משתמשים במהלך ההתקנה של אפליקציית ADP.
מומלץ לבצע את הקריאה ל-prepareEnvironment מתהליך שפועל בחזית, במהלך תהליך ההצטרפות של חוויית המשתמש, כדי שהמשתמש לא יופתע מתיבת הדו-שיח המודאלית התקנת Android Device Policy.
אם אי אפשר לבצע קריאה מתהליך בחזית, כי מדובר בתהליך אינטרנט ולרכיב 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()) }
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) שמתנתק אוטומטית כשהוא לא פעיל. מכיוון שמופעי לקוח אינם חושפים שיטת כיבוי מפורשת, יצירה וסילוק של מופעים מרובים משאירים ערוצים יתומים שנאספים ב"זבל".
כדי לשפר את הביצועים ולמנוע ערוצים מיותרים, צרו מופע יחיד של DeviceClient ברמת האפליקציה באמצעות DeviceClientFactory.create(context.applicationContext) ושמרו אותו במטמון לשימוש חוזר בכל האפליקציה – לדוגמה, כ-singleton ברמת האפליקציה או באמצעות הזרקת תלויות (dependency injection).
כדי לגשת לאותות האמינות של המכשיר שמעניינים אתכם, צריך להשתמש במכונה של 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 כדי להעניק את ההרשאה roleType: "COMPANION_APP" לאפליקציה ברשימת כללי המדיניות של applications:
- כדי להגדיר את המניפסט של האפליקציה ולהאזין להקצאות תפקידים (אופציונלי), קראו את המאמר ניהול תפקידים באפליקציה.
- התחביר של הגדרת המדיניות מפורט במאמר הגדרת מדיניות.
2. קריאת אותות ישירות באמצעות 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" } }
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– לאפליקציה אין הרשאה לשלוח את הבקשה (לדוגמה, האפליקציה לא רשומה ברשימת ההיתרים כשנדרש, לא הוקצה לה התפקידCOMPANION_APPבמכשיר שמנוהל על ידי AMAPI, או שהיא קראה ל-prepareEnvironmentכאפליקציה נלווית שלא נמצאת ברשימת ההיתרים). אפשר לעיין במאמרים גישה לאותות אמון של מכשירים וגישה לאותות מאפליקציה נלווית. - מחלקה משנית של
AmapiSdkException– ADP לא קיימת או לא מוכנה. יכול להיות שהסיבה לכך היא מצב זמני, וכדאי לנסות שוב.
אסטרטגיות של ניסיון חוזר
אם החריגות נובעות ממצב זמני, צריך להטמיע אסטרטגיית ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). אחרי הכישלון הראשון, מתחילים בהשהיה ראשונית של 5 שניות לפני הניסיון החוזר.
מטמיעים אסטרטגיית ניסיון חוזר עם מספר ניסיונות מקסימלי כתנאי יציאה, באמצעות השהיה שגדלה באופן אקספוננציאלי בכל פעם (10 שניות, 20 שניות וכו').
מעקב אחרי האינטראקציה של המשתמשים במהלך ההתקנה של אפליקציית 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 } }
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"); } } }
בעיות מוכרות
אין כרגע בעיות ידועות.