Intune适用于 Android 的应用 SDK - MAM 入门

Microsoft Intune Android 应用 SDK 允许将Intune应用保护策略合并到本机 Java/Kotlin Android 应用中。 这些策略也称为 MAM 策略。 Intune托管的应用程序是与 Intune App SDK 集成的应用程序。 Intune主动管理应用时，Intune管理员可以轻松地将应用保护策略部署到Intune托管的应用。

第 3 阶段：使用 MAM 入门

阶段目标

• 下载Intune应用 SDK。
• 了解 Intune App SDK 中包含的文件。
• 在应用程序中引用Intune应用 SDK。
• 配置 Intune App Gradle 生成插件或使用命令行生成工具。
• 确认Intune应用 SDK 已正确包含在生成中。

背景

现在，应用程序已成功集成 MSAL，接下来可以下载 Intune 应用 SDK 并将其包含在应用程序的生成过程中。

集成 Intune App SDK 的很大一部分是将标准 Android 类和方法调用替换为这些类和方法调用的Intune版本。 SDK 包含生成工具，可自动为你完成大部分替换。 若要了解有关此替换逻辑的详细信息，请参阅附录的类和方法替换部分。

下载 Intune 应用 SDK

若要下载 SDK，请参阅 下载 SDK 文件。

SDK 中有哪些内容？

Intune应用 SDK 包含以下文件：

• Microsoft。Intune。妈妈。SDK.aar：SDK 组件，支持库 JAR 文件除外。
• com.microsoft.intune.mam.build.jar：有助于 集成 SDK 的 Gradle 插件。
• CHANGELOG.md：提供在每个 SDK 版本中所做的更改的记录。
• Microsoft。Intune。妈妈。SDK。DownlevelStubs.aar：此 Android 存档 (AAR) 包含 Android 系统类的存根，这些类仅在较新的设备上存在，但由 MAMActivity 中的方法引用。 较新的设备忽略这些存根类。 仅当应用对派生自 MAMActivity的类执行反射，并且 大多数应用不需要包含它时，才需要此 AAR。 AAR 包含用于排除其所有类的 ProGuard 规则。

引用Intune应用库

Intune应用 SDK 是标准 Android 库，没有外部依赖项。 Microsoft。Intune。妈妈。SDK.aar 包含启用应用保护策略所需的接口。 它还包含与 Microsoft Intune 公司门户 应用互作所需的代码。

Android Studio

Microsoft。Intune。妈妈。SDK.aar 必须指定为 Android 库引用。 若要将此依赖项添加到生成，请按照从 Android 文档中 添加 AAR 或 JAR 作为依赖项 进行作。

Visual Studio

Intune应用 SDK for .NET MAUI - Android NuGet 包必须添加为依赖项。

按照 使用 NuGet 包管理器在 Visual Studio 中安装和管理包的过程进行作。

Microsoft.Intune。妈妈。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应用 SDK 集成在很大程度上依赖于类和方法替换。 由于这种依赖，你会看到 mam 整个堆栈跟踪。 如果你的应用没有针对应用保护策略的帐户，则所有这些 MAM 代码都处于休眠状态。 例如， 的工作方式与 相同Activity， MAMActivityonMAMCreate工作方式与 onCreate相同。 每当在mam堆栈中看到时，首先检查：

• 帐户是否面向应用保护策略？
• 是否安装了Intune 公司门户？

除非两者的回答均为“是”，否则 MAM 代码充当简单的直通。

我需要什么工具？

如果使用 Gradle 生成应用，请参阅 与 Gradle 生成插件集成

如果使用 .NET MAUI 生成应用，请参阅 与 .NET MAUI 目标集成。

如果构建应用时未使用上述两种工具，请参阅 与命令行工具集成。

与 Gradle 生成插件集成

Intune应用 SDK 插件作为 GradlePlugin/com.microsoft.intune.mam.build.jar 作为 SDK 的一部分分发。

为了使插件可由 Gradle 识别，必须将其添加到 buildscript 类路径。 插件依赖于 Javassist，还必须添加 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 依赖项和外部库进行作。 测试编译不受影响。

相关性

Gradle 插件依赖于 Javassist，它必须可用于 Gradle 的依赖项解析。 在运行插件时，Javassist 仅在生成时使用，并且不会向应用添加 Javassist 代码。

兼容性矩阵

MAM SDK 生成插件符合 Android 生成要求和兼容性表。 此处未列出的版本可能工作，也可能不起作用。

排除项

可以提供更多配置，以排除应用中的特定组件重写。 排除主要适用于与 MAM 无关的组件， (即不处理或显示公司数据) 。

可以为不同的范围配置排除项：

• excludeProjects 允许排除 Gradle 项目列表。 对于不与 Android 库或系统 API 交互的项目，这些排除项非常有用。 它们对于不处理公司数据的项目也很有用。 例如，仅包含用于执行低级网络作的本机代码的项目可能是一个很好的候选项。 如果项目与 Android 库或系统 API 广泛交互，请避免这些排除项。
• excludeClasses 允许排除类列表。 这些排除项对于不处理或显示公司数据的类非常有用。 例如，初始屏幕和载入 Activity是很好的候选项。 如果处理了类的任何超类，则无法排除该类。
• excludeVariants 启用排除项目变体。 这些排除项可以引用完整的变体名称或单个风格。 如果你想要构建非 MAM 风格的应用，它们特别有用。 例如，如果应用具有生成类型 debug ，并且 release 具有 {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 风格的变体不会重写。

Reporting

生成插件可以生成其所做更改的 HTML 报告。 若要请求生成此报表，请在配置块中intunemam指定report = true。 如果已生成，则报表将写入 outputs/logs 生成目录中。

intunemam {
    report = true
}

验证

生成插件可以运行更多验证，以查找处理类中可能存在的错误。 这些检查有助于防止潜在的插件引发的运行时故障。

若要请求在生成中执行验证，请在配置块中intunemam指定verify = true。 这可能会使插件的任务花费的时间增加几秒钟。

intunemam {
    verify = true
}

通常，验证失败表示生成插件中的 bug。 有关故障的帮助，请向Microsoft支持部门上报问题。 如果没有Microsoft支持合同， 请提交 GitHub 问题。

增量生成

若要启用对增量生成的支持，请在配置块中intunemam指定incremental = true。 此功能通过仅处理更改的输入文件来提高生成性能。 的默认配置 incremental 为 false。

intunemam {
    incremental = true
}

动态功能模块配置

动态功能模块独立于应用项目生成。 因此，动态功能模块还需要应用 Gradle 生成插件。

Gradle 插件在使用的 API 中存在技术限制。 由于这些限制，转换动态功能模块类时需要重新处理应用类。 若要确保可以完成此重新处理，请使用与应用相同的设置配置所有功能模块。

例如，如果应用排除某个类，动态功能模块也应排除该类。

与 .NET MAUI 目标集成

Intune应用 SDK 目标作为 Microsoft.Intune 作为 SDK 的一部分分发。Maui.Essentials.android.targets。

添加适用于 .NET MAUI 的 Intune 应用 SDK - Android NuGet 包后，目标会在编译时自动导入到应用程序中。

与命令行生成工具集成

命令行生成工具在 BuildTool SDK 放置的 文件夹中可用。 它执行与上面详述的 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应用 SDK 仍会维护 Android API 提供的合同。 但是，由于策略强制实施，可能会更频繁地触发失败条件。 以下 Android 最佳做法可降低失败的可能性：

• 现在可返回 null 的 Android SDK 函数返回 的可能性 null更高。 确保 null 检查保护这些函数调用。
• 必须通过其 MAM 替换 API（如 ）检查可检查 clipboardManager.getPrimaryClipDescription()的功能，例如 MAMClipboard.getPrimaryClipDescription(clipboardManager)。
• 任何派生函数都必须通过 调用其超级类版本。
• 避免以不明确的方式使用任何 API。 例如，使用 Activity.startActivityForResult 而不检查 会导致 requestCode 异常行为。

服务

策略强制实施可能会影响 Android 服务 交互。 建立绑定服务连接的方法（如 ） Context.bindService 可能会由于 中 Service.onBind 的基础策略强制实施而失败，并可能导致 ServiceConnection.onNullBinding 或 ServiceConnection.onServiceDisconnected。 与已建立的绑定服务交互可能会引发 ， SecurityException 因为 中 Binder.onTransact强制实施策略。

建议绑定服务的客户端检查服务引发的异常。 不要让异常传播到客户端应用程序的其余部分。

退出条件

配置生成插件或将命令行工具集成到生成过程中后，请验证它是否成功运行：

• 确保生成成功编译和生成。
• 配置 标志 report ，然后打开报表文档并确认发生类和方法替换：
  • 如果使用插件，请按照 报告中的步骤作。
  • 如果使用命令行工具，请 --report 包括 标志。
• 如果使用插件，请 verify 配置 标志并确保它不会产生错误。 请参阅 验证。
• double 检查 build.gradle 中所有排除项 (excludeProjects、 excludeClasses和 excludeVariants) 。 确认每个排除都是必要的，并且不处理受保护的数据。 从历史上看，许多数据泄漏错误都是由于过度攻击性排除而发生的。
• 如果不安装Intune 公司门户，请启动已编译的应用。 使用不是应用保护策略目标的Microsoft Entra用户登录。 确认应用按预期运行。
  • 注销并重复此测试，并安装Intune 公司门户。

常见问题

我的应用以前没有生成插件就集成了 SDK;如何使用生成插件？

旧版 Intune App SDK 不包含任何自动执行类和方法替换的方法。 开发人员需要在源代码中手动执行这些替换。 如果应用以这种方式集成，则可以安全地应用生成插件或命令行生成工具。 不需要任何源代码修改。 项目仍必须将 MAM SDK 列为依赖项。

后续步骤

完成所有 退出条件后，继续学习 阶段 4：MAM Integration Essentials。