Android 版 Intune 應用程式 SDK - 開始使用 MAM

Microsoft Intune App SDK for Android 允許你將 Intune 應用程式保護政策整合到原生的 Java/Kotlin Android 應用程式中。 這些保單也被稱為MAM保單。 Intune 管理的應用程式是指與 Intune 應用程式 SDK 整合的應用程式。 當 Intune 主動管理該應用程式時，Intune 管理員可以輕鬆部署應用程式保護政策到您的 Intune 管理應用程式。

第三階段：使用者入門MAM

賽段目標

• 下載 Intune 應用程式 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 應用程式 SDK

要下載 SDK，請參見 下載 SDK 檔案。

SDK 裡面有什麼？

Intune 應用程式 SDK 包含以下檔案：

• Microsoft。Intune。媽。SDK.aar：SDK 元件，除了支援函式庫的 JAR 檔案。
• com.microsoft.intune.mam.build.jar：一個 Gradle 外掛， 協助整合 SDK。
• CHANGELOG.md：提供每個 SDK 版本變更的紀錄。
• Microsoft。Intune。媽。SDK。DownlevelStubs.aar：這個 Android 封存 (AAR) 包含僅在較新裝置上存在的 Android 系統類別的 stub，但透過 MAMActivity 的方法來引用。 較新的裝置會忽略這些存根類別。 只有當你的應用程式對從 MAMActivity衍生的類別進行反射時，這個 AAR 才是必要的，而 大多數應用程式不需要包含這個 AAR。 AAR 包含 ProGuard 規則，排除所有類別。

參考 Intune 應用程式函式庫

Intune App SDK 是一個標準的 Android 函式庫，沒有外部依賴。 Microsoft。Intune。媽。SDK.aar 包含啟用應用程式保護政策所需的介面。 它也包含與 Microsoft Intune 公司入口網站 應用程式互通所需的程式碼。

Android Studio

Microsoft。Intune。媽。SDK.aar 必須指定為 Android 函式庫參考。 要將此相依性加入你的建置，請依照 Android 文件中的 「新增你的 AAR 或 JAR 作為相依性 」。

Visual Studio

Intune App SDK for .NET MAUI - Android NuGet 套件必須作為相依套件加入。

請依照 Visual Studio 的 NuGet 套件管理器安裝與管理套件的流程。

Microsoft.Intune。媽。SDK.aar 必須建立 C# 參考，這些參考是對應命名Microsoft.Intune.Mam空間的範圍。

ProGuard

你的應用程式可能已經使用 ProGuard (或其他縮小/混淆機制) 作為建置步驟。 Intune App SDK 有 ProGuard 的設定規則，必須包含在建置步驟中。 包括 . 如前所述，你的建置中的 AAR 會自動將 SDK 的設定整合到 ProGuard 步驟中，因此必要的類別檔案會被保留。 如果你包含了 。AAR，不需要其他更改。

MSAL) (Microsoft 認證函式庫自有 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 外掛作為 SDK 的一部分以 GradlePlugin/com.microsoft.intune.mam.build.jar 名義發佈。

為了讓 Gradle 能辨識該外掛，必須將其加入 buildscript 類別路徑中。 這個外掛依賴 Javassist，而 Javassist 也必須加入。 欲了解更多關於Javassist依賴性的資訊，請參見 依賴關係。

要將這些加入類別路徑，請在根 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 性與外部函式庫。 測試編譯不會受影響。

相依性

Gradle 外掛依賴 Javassist，必須提供給 Gradle 的相依性解析。 Javassist 僅在編譯時執行外掛時使用，且不會在應用程式中加入 Javassist 程式碼。

相容矩陣

MAM SDK 建置外掛與 Android 建置需求及相容性表保持一致。 未在此列出的版本可能有效，也可能無效。

排除項目

可以提供更多設定，以排除應用程式中的特定元件不被重寫。 排除區主要適用於與 MAM (無關的元件，也就是不處理或顯示企業資料) 。

排除項目可針對不同範圍設定：

• excludeProjects 允許排除 Gradle 專案清單。 這些排除對於不與 Android 函式庫或系統 API 介面的專案非常有用。 它們對於不處理企業資料的專案也很有用。 例如，一個只包含用於執行低階網路操作的原生程式碼的專案，可能是個不錯的候選人。 如果專案廣泛介接 Android 函式庫或系統 API，請避免這些排除。
• excludeClasses 允許排除類別清單。 這些排除條款對於不處理或呈現企業資料的類別非常有用。 例如，啟動畫面和入職 ActivityS 就是很好的候選。 如果一個類別的任何超類別都被處理，該類別就無法被排除。
• excludeVariants 可排除專案變體。 這些排除可以指完整的變體名稱或單一口味。 如果你想打造非 MAM 風格的應用程式，這些特別有用。 例如，如果你的應用程式有建構類型 debug 和 release flavors {noMAM， MAM} 和 {mock， 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。 此功能透過只處理變更的輸入檔案，提升建置效能。 的 incremental 預設配置為 false。

intunemam {
    incremental = true
}

動態功能模組配置

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

Gradle 外掛在所使用的 API 上有技術限制。 由於這些限制，應用程式類別在轉換動態功能模組類別時需要重新處理。 為了確保能進行這種重新處理，請將所有功能模組設定與應用程式相同。

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

與 .NET MAUI 目標整合

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

一旦新增 Intune App SDK for .NET MAUI - Android NuGet 套件，目標會在編譯時自動匯入你的應用程式。

與命令列建置工具整合

命令列建置工具可在 SDK drop 的資料夾中找到 BuildTool 。 它執行與上述 Gradle 外掛及 .NET 目標相同的功能。 然而，命令列工具可以整合進自訂建置系統中。 因為這個工具比較通用，調用起來也比較複雜。 盡可能使用 Gradle 外掛或 .NET 目標。

使用 Command-Line 工具

命令列工具可透過目錄中提供的輔助腳本 BuildTool\bin 來呼叫。

該工具預期以下參數。

可選 --processed 選項用於啟用增量建置。 這裡列出的檔案/目錄集合應該與輸入和類別路徑清單不相交。

工具調用 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

設定MAMApplication

如果你的應用程式建立了 的 android.app.Application子類別，那麼建置插件或命令列工具會轉換你的應用程式類別。

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

推薦的 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。 例如，使用 Activity.startActivityForResult 時不檢查會導致 requestCode 奇怪的行為。

服務

政策執行可能會影響 Android 服務 的互動。 建立綁定服務連線的方法，例如Context.bindService可能因底層政策執行Service.onBind而失敗，且可能導致或ServiceConnection.onServiceDisconnected。ServiceConnection.onNullBinding 與既有的綁定服務互動可能會觸發 SecurityException 政策執行的 Binder.onTransact。

被綁定服務的客戶被鼓勵檢查服務拋出的異常情況。 不要讓例外程序傳播到客戶端應用程式的其他部分。

退出標準

在你設定建置外掛或將命令列工具整合進建置流程後，確認它是否順利執行：

• 確保你的建置能成功編譯和建置。
• 設定旗 report 標，然後打開報告文件確認類別與方法替換是否正在發生：
  • 如果使用外掛，請依照 報告中的步驟操作。
  • 如果使用命令列工具，請包含 --report 旗標。
• 如果使用插件，請設定 verify 旗標並確保不會產生錯誤。 請參見 驗證。
• 請再次確認 build.gradle 中所有排除事項 (excludeProjects、 、 excludeClasses) excludeVariants 。 確認每個排除是必要的，且不涉及受保護的資料。 歷史上，許多資料外洩錯誤是因為過度激進的排除所致。
• 在未安裝 Intune 公司入口網站的情況下，啟動已編譯好的應用程式。 使用未被應用程式保護政策鎖定的 Microsoft Entra 使用者登入。 確認該應用程式是否如預期運作。
  • 登出後，安裝 Intune 公司入口網站後重複此測試。

常見問題集

我的應用程式之前整合了 SDK 但沒有建置外掛;我該如何使用建置插件？

舊版 Intune App SDK 並未包含任何自動化的類別與方法替換功能。 開發者必須在原始碼中手動完成這些替換。 如果你的應用程式是以這種方式整合的，那麼套用建置外掛或命令列建置工具是安全的。 你不需要修改任何原始碼。 你的專案仍必須將 MAM SDK 列為相依。

後續步驟

完成所有 退出標準後，繼續進入 第四階段：MAM 整合基礎。