Intune App SDK för Android – komma igång med MAM

Med Microsoft Intune App SDK för Android kan du införliva Intune appskyddsprinciper i din interna Java/Kotlin Android-app. Dessa principer kallas även MAM-principer. Ett Intune-hanterat program är ett program som är integrerat med Intune App SDK. När Intune aktivt hanterar appen kan Intune administratörer enkelt distribuera appskyddsprinciper till din Intune-hanterade app.

Steg 3: Komma igång med MAM

Etappmål

• Ladda ned Intune App SDK.
• Lär dig vilka filer som ingår i Intune App SDK.
• Referera till Intune App SDK i ditt program.
• Konfigurera plugin-programmet Intune App Gradle Build eller använd kommandoradsverktyget.
• Bekräfta att Intune App SDK ingår korrekt i din version.

Bakgrund

Nu när programmet har integrerat MSAL är det dags att ladda ned Intune App SDK och inkludera det i programmets byggprocess.

En stor del av integreringen av Intune App SDK ersätter standard Android-klasser och metodanrop med Intune versioner av dessa klasser och metodanrop. SDK:n innehåller byggverktyg som automatiskt gör de flesta av dessa ersättningar åt dig. Om du vill veta mer om den här ersättningslogiken kan du läsa avsnittet om klass- och metodersättningar i bilagan.

Ladda ned Intune App SDK

Information om hur du laddar ned SDK finns i Ladda ned SDK-filerna.

Vad ingår i SDK:et?

Intune App SDK består av följande filer:

• Microsoft. Intune. MAM. SDK.aar: SDK-komponenterna, förutom JAR-filerna för supportbiblioteket.
• com.microsoft.intune.mam.build.jar: Ett Gradle-plugin-program som hjälper dig att integrera SDK.
• CHANGELOG.md: Innehåller en post med ändringar som gjorts i varje SDK-version.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: Detta Android arkiv (AAR) innehåller stubbar för Android-systemklasser som endast finns på nyare enheter men refereras till av metoder i MAMActivity. Nyare enheter ignorerar dessa stub-klasser. Denna AAR är endast nödvändig om din app utför reflektion på klasser som härleds från MAMActivityoch de flesta appar behöver inte inkludera den. AAR innehåller ProGuard-regler för att undanta alla dess klasser.

Referera till Intune appbibliotek

Intune App SDK är ett standardbibliotek för Android utan externa beroenden. Microsoft. Intune. MAM. SDK.aar innehåller de gränssnitt som krävs för att aktivera appskyddsprinciper. Den innehåller också den kod som krävs för att samverka med Microsoft Intune Företagsportal-appen.

Android Studio

Microsoft. Intune. MAM. SDK.aar måste anges som en Android-biblioteksreferens. Om du vill lägga till det här beroendet i bygget följer du Lägg till din AAR eller JAR som ett beroende från Android-dokumentationen.

Visual Studio

Intune App SDK för .NET MAUI – Android NuGet-paketet måste läggas till som ett beroende.

Följ processen för att installera och hantera paket i Visual Studio med hjälp av NuGet Správca balíkov.

Microsoft.Intune. MAM. SDK.aar kommer att skapa C#-referenser som är begränsade till Microsoft.Intune.Mam namnområdet.

ProGuard

Ditt program kanske redan använder ProGuard (eller någon annan krympnings-/fördunklingsmekanism) som ett byggsteg. Intune App SDK har ProGuard-konfigurationsregler som måste ingå i det byggsteget. Inklusive . AAR i din version, som tidigare beskrivits, integrerar automatiskt SDK:s konfiguration i ProGuard-steget, så att nödvändiga klassfiler behålls. Om du inkluderade . AAR krävs ingen annan ändring.

MSAL (Microsofts autentiseringsbibliotek) levereras med en egen ProGuard-konfiguration. Om din app integrerar MSAL kan du läsa mer i MSAL-dokumentationen .

Byggverktyg

SDK:n innehåller byggverktyg (ett plugin-program för Gradle-versioner, mål för .NET-versioner och ett kommandoradsverktyg) som utför MAM-ersättningar automatiskt. Dessa verktyg omvandlar klassfilerna som genereras av Java-kompilering; De ändrar inte den ursprungliga källkoden. Du måste använda Gradle-plugin-programmet, .NET NuGet-paketet eller kommandoradsverktyget.

Enbart byggverktygen räcker inte för att helt integrera ditt program. Verktygen utför endast klass- och metodbyten . De utför inte några mer komplexa SDK-integreringar, till exempel multiidentitet, registrering för appskyddsprincip, princip för att begränsa dataöverföring mellan appar och enheter eller molnlagringsplatser eller MSAL-konfiguration. Du måste slutföra dessa integrationer innan din app är helt Intune aktiverad. Läs noga igenom resten av den här dokumentationen för att se om det finns integrationspunkter som är relevanta för din app.

Felsökning

Byggverktygen utför ersättningar efter kompileringen. Dessa ersättningar ändrar vissa metodnamn. Det innebär att felsökning av brytpunkter som angetts för metodnamn kan påverkas. De kanske inte stannar som förväntat. Brytpunkterna för radnummer påverkas inte.

MAM i högen

Intune App SDK-integreringen är starkt beroende av klass- och metodersättningar. På grund av det här beroendet ser mam du i hela stackspårningen. När din app inte har ett konto som är mål för appskyddsprinciper ligger all den här MAM-koden vilande. Fungerar till exempel MAMActivity identiskt med Activity och onMAMCreate fungerar identiskt med onCreate. När du ser mam i en stapel ska du först kontrollera:

• Omfattas kontot av appskyddsprinciper?
• Är Intune-företagsportalen installerad?

Om inte svaret på båda frågorna är "ja" fungerar MAM-koden som enkel genomströmning.

Vilket verktyg behöver jag?

Om du skapar din app med Gradle kan du läsa Integrera med plugin-programmet Gradle Build

Om du skapar din app med .NET MAUI, se Integrera med .NET MAUI-målen.

Om du skapar din app med inget av de tidigare verktygen kan du läsa Integrera med kommandoradsverktyget.

Integrera med plugin-programmet Gradle Build

Plugin-programmet Intune App SDK distribueras som en del av SDK:et som GradlePlugin/com.microsoft.intune.mam.build.jar.

För att plugin-programmet ska kännas igen av Gradle måste det läggas till i klassökvägen buildscript . Insticksprogrammet beror på Javassist, som också måste läggas till. Mer information om Javassist-beroendet finns i Beroenden.

Lägg till dessa i klassökvägen genom att lägga till följande i roten 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")
    }
}

Om du sedan vill tillämpa plugin-programmet lägger du till följande i build.gradle filen för din app och dynamiska funktionsmoduler:

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

Som standard fungerar plugin-programmet på project beroenden och externa bibliotek. Testkompileringen påverkas inte.

Beroenden

Gradle-plugin-programmet har ett beroende av Javassist, som måste göras tillgängligt för Gradles beroendematchning. Javassist används endast vid versionstillfället när plugin-programmet körs och ingen Javassist-kod läggs till i din app.

Matris för kompatibilitet

MAM SDK Build Plugin överensstämmer med Androids byggkrav och kompatibilitetstabeller. Versioner som inte visas här kanske inte fungerar.

Undantag

Fler konfigurationer kan tillhandahållas för att undanta specifika komponenter i din app från omskrivningar. Undantag är främst användbara för komponenter som inte är relevanta för MAM (d.v.s. inte hanterar eller visar företagsdata).

Undantag kan konfigureras för olika omfattningar:

• excludeProjects tillåter exkludering av en lista över Gradle-projekt. Dessa undantag är användbara för projekt som inte gränssnitt med Android-bibliotek eller system-API:er. De är också användbara för projekt som inte hanterar företagsdata. Ett projekt som uteslutande innehåller intern kod för nätverksåtgärder på låg nivå kan vara en bra kandidat. Om ett projekt i stort sett samverkar med Android-bibliotek eller system-API:er bör du undvika dessa undantag.
• excludeClasses tillåter exkludering av en lista över klasser. Dessa undantag är användbara för klasser som inte hanterar eller presenterar företagsdata. Välkomstskärmar och onboarding Activitys är till exempel bra kandidater. En klass kan inte uteslutas om någon av dess superklasser bearbetas.
• excludeVariants Gör det möjligt att utesluta projektvarianter. Dessa undantag kan referera till antingen ett fullständigt variantnamn eller en enda smak. De är särskilt användbara om du vill skapa en icke-MAM-smak av din app. Om din app till exempel har versionstyper debug och release med smakerna {noMAM, MAM} och {mock, production} kan du ange:
  • noMAM för att utesluta alla varianter med noMAM-smaken eller
  • noMAMMockDebug för att utesluta endast den exakta varianten.

Exempel på partiell build.gradle med undantag

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']
}

Detta skulle få följande effekter:

• :product:FooLib skrivs inte om eftersom det ingår i excludeProjects
• :product:foo-project skrivs om, förutom com.contoso.SplashActivity, som hoppas över eftersom den är i excludeClasses
• com.microsoft.bar:baz.1.0.0 skrivs om eftersom alla externa bibliotek ingår för bearbetning.
• Varianter med smaken noMAM skrivs inte om.

Rapportering

Byggpluginet kan generera en html-rapport över de ändringar det gör. Om du vill begära generering av den här rapporten anger du report = true i konfigurationsblocket intunemam . Om rapporten genereras skrivs den till outputs/logs i build-katalogen.

intunemam {
    report = true
}

Verifiering

Byggplugin-programmet kan köra fler verifieringar för att leta efter möjliga fel i bearbetningsklasser. Dessa kontroller hjälper till att skydda mot potentiella körningsfel som induceras av plugin-program.

Om du vill begära att verifiering utförs i versionen anger du verify = true det i konfigurationsblocket intunemam . Detta kan lägga till flera sekunder till den tid det tar för plugin-programmet.

intunemam {
    verify = true
}

I allmänhet representerar ett verifieringsfel ett fel i byggpluginet. Om du behöver hjälp med ett fel eskalerar du problemet med Microsofts support. Om du inte har ett Microsoft-supportavtal öppnar du ett GitHub-problem.

Inkrementella versioner

Om du vill aktivera stöd för att skapa inkrementellt anger du incremental = true i konfigurationsblocket intunemam . Den här funktionen ökar byggprestandan genom att endast bearbeta de indatafiler som ändras. Standardkonfigurationen för incremental är false.

intunemam {
    incremental = true
}

Konfiguration av dynamisk funktionsmodul

Dynamiska funktionsmoduler byggs separat från appprojektet. Därför måste dynamiska funktionsmoduler också tillämpa plugin-programmet Gradle Build.

Gradle-plugin-programmet har tekniska begränsningar i de API:er som används. På grund av dessa begränsningar måste appklasser bearbetas om vid transformering av dynamiska funktionsmodulklasser. För att säkerställa att den här bearbetningen kan utföras konfigurerar du alla funktionsmoduler med samma inställningar som appen.

Om en app till exempel exkluderar en klass ska den dynamiska funktionsmodulen även exkludera den klassen.

Integrera med .NET MAUI-målen

Intune App SDK-målen distribueras som en del av SDK som Microsoft.Intune. Maui.Essentials.android.targets.

Målen importeras automatiskt till programmet vid kompileringstillfället när Intune App SDK för .NET MAUI – Android NuGet-paketet har lagts till.

Integrera med verktyget Skapa kommandorad

Kommandoradsverktyget är tillgängligt i BuildTool mappen för SDK-släppet. Den utför samma funktion som Gradle-plugin-programmet och . NET-målen som beskrivs ovan. Kommandoradsverktyget kan dock integreras i anpassade byggsystem. Eftersom verktyget är mer allmänt är det mer komplext att anropa. Använd Gradle-plugin-programmet eller .NET-mål när det är möjligt.

Använda verktyget Command-Line

Kommandoradsverktyget kan anropas med hjälp av de angivna hjälpskripten som finns i katalogen BuildTool\bin .

Verktyget förväntar sig följande parametrar.

Det valfria --processed alternativet används för att aktivera inkrementella versioner. Den uppsättning filer/kataloger som anges här ska vara åtskilda från listorna för indata och klassökvägar.

Exempel Command-Line verktygsanrop

> 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

Detta skulle få följande effekter:

• katalogen product-foo-project skrivs om till mam-build\product-foo-project
• bar.jar skrivs om till mam-build\libs\bar.jar
• zap.jar skrivs inte om eftersom den bara visas i --classpath
• Klassen com.contoso.SplashActivity skrivs inte om även om den är i --input

Ställa in MAMApplication

Om din app skapar en underklass till android.app.Applicationomvandlar byggplugin-programmet eller kommandoradsverktyget din programklass.

Om din app inte har underklass android.app.Applicationmåste du ange"com.microsoft.intune.mam.client.app.MAMApplication" som "android:name" attribut i AndroidManifest.xml-taggen<application>.

Rekommenderade metodtips för Android

• Använd de senaste Android SDK-byggverktygen.
• Ta bort alla onödiga och oanvända bibliotek (till exempel android.support.v4).

När automatiska ersättningar har utförts behåller Intune App SDK fortfarande kontraktet som tillhandahålls av Android API. Feltillstånd kan dock utlösas oftare på grund av principtillämpning. De här metodtipsen för Android minskar risken för fel:

• Android SDK-funktioner som kan returneras har nu större sannolikhet att returneras nullnull. Se till att null kontroller skyddar dessa funktionsanrop.
• Funktioner som det går att kontrollera, t.ex clipboardManager.getPrimaryClipDescription(). , måste kontrolleras via MAM-ersättnings-API:erna, t.ex MAMClipboard.getPrimaryClipDescription(clipboardManager).
• Alla härledda funktioner måste anropa sina superklassversioner.
• Undvik att använda API:er på ett tvetydigt sätt. Till exempel att använda Activity.startActivityForResult utan att requestCode kontrollera orsakar konstigt beteende.

Tjänster

Principtillämpning kan påverka interaktioner med Android-tjänsten . Metoder som upprättar en bunden tjänstanslutning, t.ex Context.bindService . kan misslyckas på grund av underliggande principtillämpning i Service.onBind och kan resultera i ServiceConnection.onNullBinding eller ServiceConnection.onServiceDisconnected. Interaktion med en etablerad bunden tjänst kan utlösa en SecurityException på grund av principtillämpning i Binder.onTransact.

Klienter till bundna tjänster uppmanas att söka efter undantag som genereras av tjänsten. Låt inte undantag spridas till resten av klientprogrammet.

Villkor för att avsluta

När du antingen har konfigurerat plugin-programmet för bygget eller integrerat kommandoradsverktyget i byggprocessen kontrollerar du att det körs korrekt:

• Se till att bygget kompileras och byggs korrekt.
• Konfigurera flaggan report och öppna sedan rapportdokumentet och bekräfta att klass- och metodbyten sker:
  • Om du använder plugin-programmet följer du anvisningarna i Rapportering.
  • Om du använder kommandoradsverktyget tar du med flaggan --report .
• Om du använder plugin-programmet konfigurerar du flaggan verify och ser till att den inte skapar fel. Se Verifiering.
• Dubbelkolla alla undantag (excludeProjects, excludeClasses, och excludeVariants) i build.gradle. Bekräfta att varje undantag är nödvändigt och inte hanterar skyddade data. Tidigare inträffade många dataläckagefel på grund av alltför aggressiva undantag.
• Starta den kompilerade appen utan att Intune-företagsportalen är installerad. Logga in med en Microsoft Entra användare som inte är mål för appskyddsprincipen. Kontrollera att appen fungerar som förväntat.
  • Logga ut och upprepa testet med Intune-företagsportalen installerad.

Vanliga frågor och svar

Min app integrerade tidigare SDK utan byggplugin-programmet; hur kan jag använda byggpluginet?

Äldre versioner av Intune App SDK innehöll inget automatiserat sätt att utföra klass- och metodbyten. Utvecklare behövde utföra dessa ersättningar manuellt i källkoden. Om appen är integrerad på det här sättet är det säkert att använda plugin-programmet för bygg eller kommandoradsverktyget. Du behöver inte göra några ändringar i källkoden. Projektet måste fortfarande ange MAM SDK som ett beroende.

Nästa steg

När du har uppfyllt alla avslutningsvillkor fortsätter du till steg 4: MAM Integration Essentials.