Intune App SDK for Android - 開始使用 MAM

發行項
10/14/2024

Microsoft Intune App SDK for Android 可讓您將 Intune 應用程式保護原則 (也稱為 應用程式 或 MAM 原則) 納入原生 Java/Kotlin Android 應用程式中。 Intune 受控應用程式是與 Intune App SDK 整合的應用程式。當 Intune 主動管理應用程式時，Intune 系統管理員可以輕鬆地將應用程式保護原則部署到受 Intune 管理的應用程式。

注意事項

本指南分成數個不同的階段。從檢閱階段 1：規劃整合開始。

階段3：開始使用MAM

階段目標

下載 Intune App SDK。
瞭解 Intune App SDK 中包含哪些檔案。
在您的應用程式中參考 Intune App SDK。
設定 Intune App Gradle 組建外掛程式或使用命令行建置工具。
確認 Intune App SDK 已正確包含在您的組建中。

Background

現在，您的應用程式已成功整合 MSAL，現在可以下載 Intune App SDK，並將其包含在應用程式的建置程式中。

整合 Intune App SDK 的很大一部分是以這些類別和方法呼叫的 Intune 版本取代標準 Android 類別和方法呼叫。 SDK 包含會自動為您取代大部分這些專案的建置工具。如果您想要深入瞭解此取代邏輯，請參閱附錄的類別和方法取代一節。

下載 Intune App SDK

若要下載 SDK，請參閱下載 SDK 檔案。

SDK 中有什麼功能？

Intune App SDK 包含下列檔案：

Microsoft.Intune.MAM.SDK.aar：SDK 元件，支持連結庫 JAR 檔案除外。
com.microsoft.intune.mam.build.jar：Gradle 外掛程式，可協助整合 SDK。
CHANGELOG.md：提供每個 SDK 版本中所做的變更記錄。
THIRDPARTYNOTICES.TXT：認可將編譯到應用程式中的第三方和/或 OSS 程式代碼的屬性通知。
Microsoft.Intune.MAM.SDK.DownlevelStubs.aar：此 AAR 包含僅存在於較新裝置上但 MAMActivity 中方法所參考之 Android 系統類別的存根。較新的裝置會忽略這些存根類別。只有當您的應用程式對衍生自 MAMActivity的類別執行反映，而且 大部分的應用程式都不需要包含它時，才需要此 AAR。 AAR 包含 ProGuard 規則，可排除其所有類別。

參考 Intune 應用程式連結庫

Intune App SDK 是標準 Android 連結庫，沒有外部相依性。 Microsoft.Intune.MAM.SDK.aar 包含啟用應用程式保護原則所需的介面，以及與 Microsoft Intune 公司入口網站應用程式互操作所需的程序代碼。

Android Studio

Microsoft.Intune.MAM.SDK.aar 必須指定為 Android 連結庫參考。若要將此相依性新增至您的組建，請遵循從 Android 檔將您的 AAR 或 JAR 新增為相依性。

Visual Studio

Intune App SDK for .NET MAUI - Android NuGet 套件必須新增為相依性。

遵循使用 NuGet 套件管理員在 Visual Studio 中安裝和管理套件的程式。

Microsoft.Intune.MAM.SDK.aar 會系結至建立範圍為命名空間的 Microsoft.Intune.Mam C# 參考。

ProGuard

您的應用程式可能已經使用 ProGuard (或任何其他壓縮/混淆機制) 作為建置步驟。 Intune App SDK 具有 ProGuard 設定規則，必須包含在該建置步驟中。包括。如上所述，組建中的 AAR 會自動將 SDK 的組態整合到 ProGuard 步驟中，因此會保留必要的類別檔案。如果您已正確包含 。AAR，不需要其他變更。

MICROSOFT驗證連結庫 (MSAL) 隨附自己的 ProGuard 設定。如果您的應用程式整合 MSAL，請參閱 MSAL 檔以取得詳細數據。

建置工具

SDK 提供建置工具 (Gradle 組建的外掛程式、.NET 組建的目標，以及自動執行 MAM 取代的命令行工具) 。這些工具會轉換 Java 編譯所產生的類別檔案;它們不會修改原始原始原始程式碼。 您必須使用 Gradle 外掛程式、.NET NuGet 套件或命令行工具。

單獨使用建置工具並不足以完全整合您的應用程式。 這些工具只會執行類別和方法取代。它們不會執行任何更複雜的 SDK 整合，例如多重身分識別、註冊應用程式保護原則、限制應用程式與裝置或雲端儲存位置之間數據傳輸的原則，或 MSAL 設定，必須在您的應用程式完全啟用 Intune 之前完成。請仔細檢閱本檔的其餘部分，以取得與您的應用程式相關的整合點。

對偵錯的影響

建置工具會在編譯之後執行取代，這會變更一些方法名稱。因此，在方法名稱上設定的偵錯斷點可能會受到影響，而且不會如預期般停止。行號斷點不受影響。

堆疊中的 MAM

因為 Intune App SDK 整合高度依賴類別和方法取代，所以您會開始看到 mam 整個堆疊追蹤。當您的應用程式沒有以應用程式保護原則為目標的帳戶時，這些 MAM 程式代碼全都處於休眠狀態： MAMActivity 運作方式與相同 Activity， onMAMCreate 運作方式會與等相同 onCreate。每當您在堆棧中看到 mam 時，請先檢查：

帳戶是否以應用程式保護原則為目標？
是否已安裝 Intune 公司入口網站？

除非兩者的答案都是「是」，否則 MAM 程式代碼會作為簡單的傳遞。

我需要什麼工具？

如果您使用 Gradle 建置應用程式，請參閱與 Gradle 組建外掛程式整合

如果您使用 .NET MAUI 建置應用程式，請參閱與 .NET MAUI 目標整合。

如果您使用上述任一項來建置應用程式，請參閱與命令行工具整合。

與 Gradle 組建外掛程式整合

Intune App SDK 外掛程式會以 GradlePlugin/com.microsoft.intune.mam.build.jar的方式散發為 SDK 的一部分。

若要讓 Gradle 辨識外掛程式，必須將其新增至 buildscript classpath。外掛程式相依於也必須新增的 Javassist。如需 Javassist 相依性的詳細資訊，請參閱相依性。

若要將這些新增至 classpath，請將下列內容新增至根目錄 build.gradle：

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath "org.javassist:javassist:3.29.2-GA"
        classpath files("$PATH_TO_MAM_SDK/GradlePlugin/com.microsoft.intune.mam.build.jar")
    }
}

然後，若要套用外掛程式，請將下列內容新增至 build.gradle 應用程式和動態功能模組的檔案：

apply plugin: 'com.microsoft.intune.mam'

根據預設，外掛程式會根據 project 相依性和外部連結庫運作。測試編譯不會受到影響。

注意事項

從 8.0 Intune App SDK 開始，就無法再選擇性地處理連結庫。所有連結庫都會進行處理。

相依性

注意事項

您必須使用 3.6.1 版或更新版本的 Android Gradle 外掛程式和 5.6.4 版或更新版本的 Gradle。

Gradle 外掛程式相依於 Javassist，其必須可供 Gradle 的相依性解析使用。 Javassist 只會在執行外掛程式時於建置時使用，而且不會將任何 Javassist 程式代碼新增至您的應用程式。

注意事項

Javassist 版本可能無法回溯相容。一般而言，您應該使用 Intune App SDK 預期的確切版本：

Intune App SDK ≥ 10.0.0 需要 Javassist 3.29.2-GA
Intune App SDK ≥ 7.0.0 需要 Javassist 3.27.0-GA
Intune App SDK < 7.0.0 需要 Javassist 3.22.0-GA

此外，使用 MAM SDK 8.0.0+ 時，您必須確定已在 Gradle 組態中設定下列專案：

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

排除項目

您可以提供其他設定，以排除應用程式中的特定元件免於重寫。排除範圍對於與 MAM (無關的元件而言非常有用，也就是不處理或顯示公司數據) 。

您可以針對不同的範圍設定排除專案：

excludeProjects 允許排除 Gradle 項目清單。這些排除專案適用於未與 Android 連結庫或系統 API 介面的專案，以及/或不處理公司數據的專案。例如，獨佔包含用來執行低階網路作業之原生程式代碼的專案，可能是不錯的候選專案。如果項目廣泛地與 Android 連結庫或系統 API 介面，則應避免這些排除專案。
excludeClasses 允許排除類別清單。這些排除專案對於不處理或呈現公司數據的類別很有用。例如，啟動顯示畫面和上線 Activity是不錯的候選專案。請注意，如果已處理類別的任何超級類別，則無法排除該類別。
excludeVariants 啟用排除項目變體。這些排除專案可以參考完整的變體名稱或單一類別。如果您想要建置應用程式的非 MAM 類別，它們特別有用。例如，如果您的應用程式具有組建類型debug，且release具有 {、 } 和 {mock、 MAM} 類別noMAM，production您可以指定下列專案：
- noMAM 排除具有 noMAM 類別的所有變體或
- noMAMMockDebug 表示只排除該確切的變體。

注意

排除專案不應輕舉。不正確套用排除專案可能會導致應用程式中的嚴重數據外洩。請一律驗證您所套用之任何排除範圍的影響。

包含排除專案的範例部分 build.gradle

apply plugin: 'com.microsoft.intune.mam'

dependencies {
    implementation project(':product:FooLib')
    implementation project(':product:foo-project')
    implementation "com.microsoft.bar:baz:1.0.0"

    // Include the MAM SDK
    implementation files("$PATH_TO_MAM_SDK/Microsoft.Intune.MAM.SDK.aar")
}
intunemam {
    excludeProjects = [':product:FooLib']
    excludeClasses = ['com.contoso.SplashActivity']
    excludeVariants = ['noMAM']
}

這會產生下列效果：

:product:FooLib 不會重寫，因為它包含在 excludeProjects
:product:foo-project 會重寫，但略過的除外 com.contoso.SplashActivity，因為它位於 excludeClasses
com.microsoft.bar:baz.1.0.0 會重寫，因為所有外部連結庫都包含在內以進行處理。
不會重寫具有類別的 noMAM 變體。

報告

組建外掛程式可以產生其所做變更的 html 報告。若要要求產生此報告，請在組態區塊中intunemam指定 report = true 。如果產生，報表會寫 outputs/logs 入組建目錄中的。

intunemam {
    report = true
}

驗證

組建外掛程式可以執行額外的驗證，以尋找處理類別中可能的錯誤。這些檢查有助於防範潛在的外掛程式引發的運行時間失敗。

若要要求在組建中執行驗證，請在組態區塊中intunemam指定 verify = true 。這可能會在外掛程式的工作所花費的時間增加幾秒鐘。

intunemam {
    verify = true
}

一般而言，驗證失敗代表組建外掛程式中的錯誤。如需失敗的協助，請向Microsoft支援呈報問題。如果您沒有Microsoft支援合約，請開啟 GitHub 問題。

累加組建

若要開啟以累加方式建置的支援，請在組態區塊中intunemam指定 incremental = true 。這項功能只會處理已變更的輸入檔，以提升建置效能。預設群組態為 incrementalfalse。

intunemam {
    incremental = true
}

動態功能模組設定

動態功能模組會與應用程式專案分開建置。因此，動態功能模組也需要套用 Gradle 組建外掛程式。

由於 Gradle 外掛程式所使用 API 的技術限制，在轉換動態功能模組類別時，必須重新處理應用程式類別。為了確保可以完成這項操作，所有功能模組都應該使用與其所設計應用程式相同的設定進行設定。

例如，如果應用程式排除類別，動態功能模組也應該排除該類別。

與 .NET MAUI 目標整合

Intune App SDK 目標會作為 SDK 的一部分散發為 Microsoft.Intune.Maui.Essentials.android.targets。

一旦新增適用於 .NET MAUI 的 Intune App SDK - Android NuGet 套件，系統就會在編譯時期自動將目標匯入您的應用程式。

與命令行建置工具整合

命令行建置工具可在 SDK 卸除的資料夾中 BuildTool 取得。其執行的功能與上面所述的 Gradle 外掛程式/.NET 目標相同，但可以整合到自定義組建系統中。由於其較為泛型，因此叫用更為複雜，因此應該盡可能使用 Gradle 外掛程式/.NET 目標。

使用 Command-Line 工具

您可以使用目錄中 BuildTool\bin 提供的協助程式腳本來叫用命令行工具。

此工具需要下列參數。

參數	必要	描述
`--input`	是	以分號分隔的 jar 檔案清單，以及要修改之類別檔案的目錄。這應該包含您想要重寫的所有 jar/目錄。
`--output`	是	以分號分隔的 jar 檔案和目錄清單，用來儲存修改過的類別。每個輸入項目應該會有一個輸出專案，而且應該依序列出。
`--classpath`	是	建置類別路徑。這可能同時包含 jar 和類別目錄。
`--processed`	否	jar 檔案和目錄的分號分隔清單，其中包含先前的建置工具調用已處理過的類別。
`--excludeClasses`	否	分號分隔清單，其中包含應該從重寫中排除的類別名稱。
`--report`	否	要寫入有關已修改類別之 HTML 報告的目錄。如果未指定，則不會寫入任何報表。

選擇性 --processed 選項可用來啟用增量組建。此處所列的一組檔案/目錄應該與輸入和類別路徑清單脫離。

提示

在類似 Unix 的系統上，分號是命令分隔符。若要避免殼層分割命令，請務必以 '' 逸出每個分號，或以引弧括住完整參數。

範例 Command-Line 工具調用

> BuildTool\bin\BuildTool.bat --input build\product-foo-project;libs\bar.jar --output mam-build\product-foo-project;mam-build\libs\bar.jar --classpath build\zap.jar;libs\Microsoft.Intune.MAM.SDK\classes.jar;%ANDROID_SDK_ROOT%\platforms\android-27\android.jar --excludeClasses com.contoso.SplashActivity

這會產生下列效果：

product-foo-project目錄會重寫為mam-build\product-foo-project
bar.jar 會重寫至 mam-build\libs\bar.jar
zap.jar 不會重寫，因為它只列在--classpath
com.contoso.SplashActivity即使類別位於中，也不會重寫該類別--input

警告

建置工具目前不支援 AAR 檔案。如果您的建置系統在處理 AAR 檔案時尚未擷取，您必須在叫用建置工具之前先擷取 classes.jar 。

設定 MAMApplication

如果您的應用程式建立的 android.app.Application子類別，則組建外掛程式/命令行工具會轉換您的應用程式類別。

如果您的應用程式沒有子類別 android.app.Application，則 您必須 將設定 "com.microsoft.intune.mam.client.app.MAMApplication" 為 "android:name" AndroidManifest.xml <application> 標籤中的屬性。

建議的 Android 最佳做法

使用最新的 Android SDK 建置工具。
拿掉所有不必要的和未使用的連結庫 (例如 android.support.v4) 。

執行自動取代之後，Intune App SDK 仍會維護 Android API 所提供的合約。不過，由於原則強制執行，可能會更頻繁地觸發失敗狀況。這些 Android 最佳做法可降低失敗的可能性：

可以傳回 null 的 Android SDK 函式現在傳回 null的可能性較高。請確定 null 檢查會保護這些函數調用。
可以檢查的功能，例如 clipboardManager.getPrimaryClipDescription()，必須透過其 MAM 取代 API 來檢查，例如 MAMClipboard.getPrimaryClipDescription(clipboardManager)。
任何衍生的函式都必須透過呼叫其超級類別版本。
避免以模棱兩可的方式使用任何 API。例如，在不檢查 requestCode 的情況下使用 Activity.startActivityForResult 會造成奇怪的行為。

服務

原則強制執行可能會影響Android 服務互動。建立系結服務連線的方法，例如 Context.bindService 可能會因為中的基礎原則強制執行 Service.onBind 而失敗，而且可能會導致 ServiceConnection.onNullBinding 或 ServiceConnection.onServiceDisconnected。與已建立的系結服務互動可能會因為中的原則強制執行Binder.onTransact而擲回 SecurityException 。

強烈建議系結服務的用戶端檢查服務擲回的例外狀況，而不是讓例外狀況傳播到用戶端應用程式的其餘部分。

結束準則

設定組建外掛程式或將命令行工具整合到建置程式之後，請驗證它是否已成功執行：

請確定您的組建已成功編譯和建置。
report設定旗標，然後開啟報表檔，並確認發生類別和方法取代：
- 如果使用外掛程式，請遵循報告中的步驟。
- 如果使用命令列工具，請包含 --report 旗標。
如果使用外掛程式，請設定 verify 旗標，並確定它不會產生錯誤。請參閱驗證。
在build.gradle 中 excludeProjects (、 excludeClasses和 excludeVariants) ，再次檢查所有排除專案。確認每個排除都是必要的，而且不會處理受保護的數據。在過去，因為過度積極排除，所以發生許多數據外洩錯誤。
若未安裝 Intune 公司入口網站，請啟動已編譯的應用程式、使用未以應用程式保護原則為目標的Microsoft Entra 使用者登入，並確認應用程式如預期般運作。
- 註銷並重複此測試，並安裝 Intune 公司入口網站。

常見問題集

我的應用程式先前已在沒有組建外掛程式的情況下整合 SDK;如何使用組建外掛程式？

舊版的 Intune App SDK 不包含任何執行類別和方法取代的自動化方式，而且開發人員需要在原始程式碼中手動執行這些取代。如果您的應用程式先前已以這種方式整合，則可以安全地將組建外掛程式套用 (或命令行建置工具) ，而不需要修改任何原始程式碼。您的專案仍然必須將 MAM SDK 列為相依性。

後續步驟

完成所有結束準則之後，請繼續進行第 4 階段：MAM 整合基本概要。

共用方式為

Intune App SDK for Android - 開始使用 MAM

階段3：開始使用MAM

階段目標

Background

下載 Intune App SDK

SDK 中有什麼功能？

參考 Intune 應用程式連結庫

Android Studio

Visual Studio

ProGuard

建置工具

對偵錯的影響

堆疊中的 MAM

我需要什麼工具？

與 Gradle 組建外掛程式整合

相依性

排除項目

包含排除專案的範例部分 build.gradle

報告

驗證

累加組建

動態功能模組設定

與 .NET MAUI 目標整合

與命令行建置工具整合

使用 Command-Line 工具

範例 Command-Line 工具調用

設定 MAMApplication

建議的 Android 最佳做法

服務

結束準則

常見問題集

我的應用程式先前已在沒有組建外掛程式的情況下整合 SDK;如何使用組建外掛程式？

後續步驟

意見反應

其他資源