Android için Intune Uygulama SDK'sı - MAM ile Çalışmaya Başlama

Android için Microsoft Intune Uygulama SDK'sı, yerel Java/Kotlin Android uygulamanıza Intune uygulama koruma ilkeleri eklemenizi sağlar. Bu ilkeler MAM ilkeleri olarak da bilinir. Intune yönetilen uygulama, Intune Uygulama SDK'sı ile tümleştirilmiş uygulamadır. Intune uygulamayı etkin bir şekilde yönettiğinde, Intune yöneticiler uygulama koruma ilkelerini Intune yönetilen uygulamanıza kolayca dağıtabilir.

Not

Bu kılavuz birkaç ayrı aşamaya ayrılmıştır. 1. Aşama: Tümleştirmeyi Planlama'ya bakarak başlayın.

3. Aşama: MAM'ı Kullanmaya Başlama

Aşama Hedefleri

• Intune Uygulama SDK'sını indirin.
• Intune Uygulama SDK'sında hangi dosyaların yer aldığı hakkında bilgi edinin.
• Uygulamanızdaki Intune Uygulama SDK'sı'na başvurun.
• Intune Uygulama Gradle Derleme Eklentisi'ni yapılandırın veya komut satırı derleme aracını kullanın.
• Intune Uygulama SDK'sının derlemenize düzgün şekilde eklendiğini onaylayın.

Arka plan

Uygulamanız MSAL'yi başarıyla tümleştirdiği için artık Intune Uygulama SDK'sını indirip uygulamanızın derleme işlemine eklemenin zamanı geldi.

Intune Uygulama SDK'sını tümleştirmenin büyük bir kısmı standart Android sınıflarını ve yöntem çağrılarını bu sınıfların ve yöntem çağrılarının Intune sürümleriyle değiştirmektir. SDK, bu değiştirmelerin çoğunu sizin için otomatik olarak yapan derleme araçlarını içerir. Bu değiştirme mantığı hakkında daha fazla bilgi edinmek isterseniz, ekinsınıf ve yöntem değiştirmeleri bölümüne bakın.

Intune Uygulama SDK'sını indirme

SDK'yı indirmek için bkz. SDK dosyalarını indirme.

SDK'da neler var?

Intune Uygulama SDK'sı aşağıdaki dosyalardan oluşur:

• Microsoft. Intune. MAM. SDK.aar: Destek Kitaplığı JAR dosyaları dışında SDK bileşenleri.
• com.microsoft.intune.mam.build.jar: SDK'yı tümleştirmeye yardımcı olan bir Gradle eklentisi.
• CHANGELOG.md: Her SDK sürümünde yapılan değişikliklerin kaydını sağlar.
• Microsoft. Intune. MAM. SDK. DownlevelStubs.aar: Bu Android Arşiv (AAR), yalnızca daha yeni cihazlarda bulunan ancak MAMActivity'deki yöntemlerle başvuruda bulunan Android sistem sınıfları için saplamalar içerir. Daha yeni cihazlar bu saplama sınıflarını yoksayar. Bu AAR yalnızca uygulamanız ' dan MAMActivitytüretilen sınıflarda yansıma gerçekleştiriyorsa ve çoğu uygulamanın bunu içermesi gerekmiyorsa gereklidir. AAR, tüm sınıflarını dışlamak için ProGuard kuralları içerir.

Intune Uygulama kitaplıklarına başvurma

Intune Uygulama SDK'sı, dış bağımlılıkları olmayan standart bir Android kitaplığıdır. Microsoft. Intune. MAM. SDK.aar, uygulama koruma ilkelerini etkinleştirmek için gereken arabirimleri içerir. Ayrıca Microsoft Intune Şirket Portalı uygulamasıyla birlikte çalışmak için gereken kodu içerir.

Android Studio

Microsoft. Intune. MAM. SDK.aar, Android kitaplık başvurusu olarak belirtilmelidir. Bu bağımlılığı derlemenize eklemek için Android belgelerinden AAR veya JAR'nizi bağımlılık olarak ekleme'yi izleyin.

Visual Studio

.NET MAUI için Intune Uygulama SDK'sı - Android NuGet paketi bağımlılık olarak eklenmelidir.

NuGet Paket Yöneticisi'ni kullanarak Visual Studio'da paketleri yükleme ve yönetme işlemini izleyin.

Microsoft.Intune. MAM. SDK.aar, ad alanı kapsamına Microsoft.Intune.Mam alınmış C# başvuruları oluşturmaya bağlıdır.

ProGuard

Uygulamanız derleme adımı olarak ProGuard 'ı (veya başka bir daraltma/karartma mekanizmasını) zaten kullanıyor olabilir. Intune Uygulama SDK'sı, bu derleme adımına eklenmesi gereken ProGuard yapılandırma kurallarına sahiptir. dahil. Daha önce açıklandığı gibi derlemenizdeki AAR, SDK'nın yapılandırmasını ProGuard adımıyla otomatik olarak tümleştirerek gerekli sınıf dosyalarının tutulmasını sağlar. öğesini eklediyseniz . AAR, başka değişiklik gerekmez.

Microsoft Kimlik Doğrulama Kitaplığı (MSAL) kendi ProGuard yapılandırmasıyla birlikte sağlanır. Uygulamanız MSAL'yi tümleştirirse daha fazla ayrıntı için MSAL belgelerine bakın.

Derleme araçları

SDK, MAM değiştirme işlemlerini otomatik olarak gerçekleştiren derleme araçları (Gradle derlemeleri için bir eklenti, .NET derlemeleri için hedefler ve komut satırı aracı) sağlar. Bu araçlar Java derlemesi tarafından oluşturulan sınıf dosyalarını dönüştürür; özgün kaynak kodunu değiştirmezler. Gradle eklentisini, .NET NuGet paketini veya komut satırı aracını kullanmanız gerekir.

Derleme araçları yalnızca uygulamanızı tam olarak tümleştirmek için yeterli değildir. Araçlar yalnızca sınıf ve yöntem değiştirme işlemleri gerçekleştirir. Çoklu Kimlik, Uygulama Koruma İlkesine Kaydolma, Uygulamalar ile cihaz veya bulut depolama konumları arasında veri aktarımını sınırlama ilkesi veyaMSAL yapılandırması gibi daha karmaşık SDK tümleştirmeleri gerçekleştirmez. Uygulamanız tam olarak Intune etkinleştirilmeden önce bu tümleştirmeleri tamamlamanız gerekir. Uygulamanızla ilgili tümleştirme noktaları için bu belgelerin geri kalanını dikkatle gözden geçirin.

Hata ayıklama

Derleme araçları derlemeden sonra değişiklik yapar. Bu değişiklikler bazı yöntem adlarını değiştirir. Sonuç olarak, yöntem adlarında ayarlanan hata ayıklama kesme noktaları etkilenebilir. Beklendiği gibi durmayabilirler. Satır numarası kesme noktaları etkilenmez.

Yığında MAM

Intune Uygulama SDK'sı tümleştirmesi, büyük ölçüde sınıf ve yöntem değiştirme işlemlerine dayanır. Bu bağımlılık nedeniyle, yığın izlemelerinizin tamamında görürsünüz mam . Uygulamanızın uygulama koruma ilkeleriyle hedeflenen bir hesabı olmadığında, tüm bu MAM kodu uykudadır. Örneğin, MAMActivity ile aynı ve onMAMCreate ile ActivityonCreateaynı şekilde çalışır. Bir yığında her gördüğünüzde mam , önce şunları denetleyin:

• Hesap uygulama koruma ilkeleriyle hedefleniyor mu?
• Intune Şirket Portalı yüklü mü?

Her ikisinin yanıtı "evet" değilse MAM kodu basit geçiş işlevi görür.

Hangi ara çubuğuna ihtiyacım var?

Uygulamanızı Gradle ile derlediyseniz bkz. Gradle Derleme Eklentisi ile Tümleştirme

Uygulamanızı .NET MAUI ile derlediyseniz bkz. .NET MAUI Hedefleri ile tümleştirme.

Uygulamanızı önceki araçlardan hiçbiri ile derlemezseniz bkz. Komut Satırı Aracı ile Tümleştirme.

Gradle Derleme Eklentisi ile tümleştirme

Intune Uygulama SDK'sı eklentisi, SDK'nın bir parçası olarak GradlePlugin/com.microsoft.intune.mam.build.jar olarak dağıtılır.

Eklentinin Gradle tarafından tanınması için sınıf yolu'na buildscript eklenmesi gerekir. Eklenti Javassist'e bağlıdır ve bu da eklenmelidir. Javassist bağımlılığı hakkında daha fazla bilgi için bkz. Bağımlılıklar.

Bunları classpath'e eklemek için köküne build.gradleaşağıdakileri ekleyin:

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")
    }
}

Ardından eklentiyi uygulamak için uygulamanızın ve dinamik özellik modüllerinin build.gradle dosyasına aşağıdakileri ekleyin:

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

Eklenti varsayılan olarak bağımlılıklar ve dış kitaplıklar üzerinde project çalışır. Test derlemesi etkilenmez.

Not

8.0 Intune Uygulama SDK'sı ile başlayarak kitaplıkları seçmeli olarak işlemek artık mümkün değildir. Tüm kitaplıklar işlenir.

Bağımlılık

Gradle eklentisinin Javassist bağımlılığı vardır ve bu bağımlılık Gradle'ın bağımlılık çözümlemesi için kullanılabilir hale getirilmelidir. Javassist yalnızca eklentiyi çalıştırırken derleme zamanında kullanılır ve uygulamanıza Javassist kodu eklenmez.

MAM SDK'sı	Javassist Sürümü
≥ 10.0.0	3.29.2-GA
≥ 7.0.0	3.27.0-GA
< 7.0.0	3.22.0-GA

Not

Javassist sürümleri geriye dönük olarak uyumlu olmayabilir. Genel olarak, Intune Uygulama SDK'sı tarafından beklenen tam sürümü kullanmanız gerekir.

Uyumluluk Matrisi

MAM SDK Derleme Eklentisi , Android derleme gereksinimleri ve uyumluluk tabloları ile uyumludur. Burada listelenmeyen sürümler çalışabilir veya çalışmayabilir.

MAM SDK'sı	Android Sürümü	Gradle	Android Gradle Eklentisi	Kotlin Sürümü	Java Sürümü
10.0.0	14	8.2	8.2.2	1.9.25	17
11.0.0	15	8.7	8.6.1	2.0.21	17
12.0.0	16	8.11.1	8.9.1	2.1.21	17

Dışlamalar

Uygulamanızdaki belirli bileşenleri yeniden yazmaların dışında tutmak için daha fazla yapılandırma sağlanabilir. Dışlamalar ağırlıklı olarak MAM ile ilgili olmayan bileşenler için yararlıdır (yani, şirket verilerini işlemez veya görüntülemez).

Dışlamalar çeşitli kapsamlar için yapılandırılabilir:

• excludeProjects Gradle projelerinin listesinin dışlanmasını sağlar. Bu dışlamalar, Android kitaplıklarıyla veya sistem API'leriyle arabirim oluşturmamış projeler için kullanışlıdır. Şirket verilerini işlemeyen projeler için de kullanışlıdır. Örneğin, yalnızca düşük düzeyli ağ işlemleri gerçekleştirmek için yerel kod içeren bir proje iyi bir aday olabilir. Bir proje, Android kitaplıkları veya sistem API'leri ile geniş bir arabirime sahipse, bu dışlamalardan kaçının.
• excludeClasses sınıfların listesinin dışlanmasını sağlar. Bu dışlamalar, kurumsal verileri işlemeyen veya sunmayan sınıflar için yararlıdır. Örneğin, giriş ekranları ve eklemeler Activityiyi adaylardır. Üst sınıflarından herhangi biri işlenirse sınıf dışlanamaz.
• excludeVariants proje varyantlarının dışlanmasını etkinleştirir. Bu dışlamalar tam bir değişken adına veya tek bir çeşite başvurabilir. Bunlar özellikle uygulamanızın MAM olmayan bir türünü oluşturmak istiyorsanız kullanışlıdır. Örneğin, uygulamanızın derleme türleri debug varsa ve {noMAM, MAM} ve release {mock, production} aromalarına sahipse şunları belirtebilirsiniz:
  • noMAM noMAM aromasına sahip tüm varyantları dışlamak için veya
  • noMAMMockDebug yalnızca tam değişkeni hariç tutmak için.

Dikkat

Dışlamalar hafife alınmamalıdır. Dışlamaların yanlış uygulanması, uygulamanızda ciddi veri sızıntılarına neden olabilir. Uyguladığınız dışlamanın etkisini her zaman doğrulayın.

Dışlamalarla örnek kısmi 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']
}

Bunun aşağıdaki etkileri olacaktır:

• :product:FooLib içinde bulunduğundan yeniden yazılmaz excludeProjects
• :product:foo-project , içinde olduğu için com.contoso.SplashActivityatlanan dışında yeniden yazılır excludeClasses
• com.microsoft.bar:baz.1.0.0 tüm dış kitaplıklar işlenmek üzere eklendiğinden yeniden yazılır.
• Bu aromaya noMAM sahip varyantlar yeniden yazılmaz.

Raporlama

Derleme eklentisi, yaptığı değişikliklerin html raporunu oluşturabilir. Bu raporun oluşturulmasını istemek için yapılandırma bloğunda intunemam belirtinreport = true. Oluşturulduysa, rapor derleme dizininde öğesine outputs/logs yazılır.

intunemam {
    report = true
}

Doğrulama

Derleme eklentisi, sınıf işlemedeki olası hataları aramak için daha fazla doğrulama çalıştırabilir. Bu denetimler, olası eklenti kaynaklı çalışma zamanı hatalarına karşı korunmaya yardımcı olur.

Derlemenizde doğrulama isteğinde bulunmak için yapılandırma bloğunda intunemam belirtinverify = true. Bu, eklentinin görevi tarafından geçen süreye birkaç saniye ekleyebilir.

intunemam {
    verify = true
}

Genellikle, doğrulama hatası derleme eklentisindeki bir hatayı temsil eder. Bir hatayla ilgili yardım için Sorunu Microsoft desteğiyle birlikte yükseltin. Microsoft destek sözleşmeniz yoksa bir GitHub sorunu açın.

Artımlı derlemeler

Artımlı olarak derleme desteğini etkinleştirmek için yapılandırma bloğunda intunemam belirtinincremental = true. Bu özellik yalnızca değişen giriş dosyalarını işleyerek derleme performansını artırır. için incremental varsayılan yapılandırma şeklindedir false.

intunemam {
    incremental = true
}

Dinamik Özellik Modülü yapılandırması

Dinamik Özellik Modülleri, uygulama projesinden ayrı olarak derler. Bu nedenle, Dinamik Özellik Modüllerinin de Gradle Derleme Eklentisi'ni uygulaması gerekir.

Gradle eklentisinin kullandığı API'lerde teknik sınırlamalar vardır. Bu sınırlamalar nedeniyle, dinamik özellik modülü sınıfları dönüştürülürken uygulama sınıflarının yeniden işlenmesi gerekir. Bu yeniden işlemenin yapılabilmesini sağlamak için tüm özellik modüllerini uygulamayla aynı ayarlarla yapılandırın.

Örneğin, bir uygulama bir sınıfı dışlarsa dinamik özellik modülü de bu sınıfı hariç tutmalıdır.

.NET MAUI Hedefleri ile Tümleştirme

Intune Uygulama SDK'sı hedefleri, SDK'nın bir parçası olarak Microsoft.Intune olarak dağıtılır. Maui.Essentials.android.targets.

.NET MAUI - Android NuGet paketi için Intune Uygulama SDK'sı eklendikten sonra hedefler derleme zamanında uygulamanıza otomatik olarak aktarılır.

Komut Satırı Derleme Aracı ile tümleştirme

Komut satırı derleme aracı SDK bırakma klasöründe bulunur BuildTool . Yukarıda ayrıntılarıyla belirtilen Gradle eklentisi ve .NET hedefleri ile aynı işlevi gerçekleştirir. Ancak komut satırı aracı özel derleme sistemleriyle tümleştirilebilir. Araç daha genel olduğundan çağırmak daha karmaşıktır. Mümkün olduğunda Gradle eklentisini veya .NET hedeflerini kullanın.

Command-Line Aracını Kullanma

Komut satırı aracı, dizinde BuildTool\bin bulunan sağlanan yardımcı betikler kullanılarak çağrılabilir.

Araç aşağıdaki parametreleri bekler.

Parametre	Gerekli	Açıklama
--input	Evet	Değiştireceğiniz JAR dosyalarının ve sınıf dosyalarının dizinlerinin noktalı virgülle ayrılmış listesi. Yeniden yazmak istediğiniz tüm JAR'leri ve dizinleri ekleyin.
--output	Evet	Değiştirilen sınıfları depolamak için JAR dosyalarının ve dizinlerinin noktalı virgülle ayrılmış listesi. Giriş girdisi başına aynı sırada listelenen bir çıkış girişi sağlayın.
--classpath	Evet	Derleme sınıf yolu. Bu hem JAR dosyalarını hem de sınıf dizinlerini içerebilir.
--processed	Hayır	Derleme aracının önceki bir çağrısıyla zaten işlenmiş olan sınıfları içeren JAR dosyalarının ve dizinlerinin noktalı virgülle ayrılmış listesi.
--excludeClasses	Hayır	Yeniden yazmanın dışında tutulması gereken sınıfların adlarını içeren noktalı virgülle ayrılmış liste.
--report	Hayır	Değiştirilen sınıflar hakkında html raporu yazacak dizin. Belirtilmezse rapor yazılmaz.

artımlı derlemeleri etkinleştirmek için isteğe bağlı --processed seçenek kullanılır. Burada listelenen dosya/dizin kümesi, giriş ve sınıf yolu listeleriyle kopuk olmalıdır.

İpucu

Unix benzeri sistemlerde noktalı virgül bir komut ayırıcıdır. Kabuğun komutları bölmesini önlemek için, her noktalı virgülden '' ile kaçtığınızdan veya tam parametreyi tırnak işaretleri içinde kaydırdığından emin olun.

Örnek Command-Line Aracı çağırma

> 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

Bunun aşağıdaki etkileri olacaktır:

• product-foo-project dizinine yeniden yazılırmam-build\product-foo-project
• bar.jar yeniden yazılır mam-build\libs\bar.jar
• zap.jar yeniden yazılmaz çünkü yalnızca --classpath
• sınıfı com.contoso.SplashActivity içinde olsa bile yeniden yazılmaz--input

Uyarı

Derleme aracı şu anda aar dosyalarını desteklemez. Derleme sisteminiz aar dosyalarıyla ilgilenirken ayıklamıyorsa classes.jar , derleme aracını çağırmadan önce ayıklayın.

MAMApplication'i ayarlama

Uygulamanız bir alt sınıfı android.app.Applicationoluşturursa derleme eklentisi veya komut satırı aracı uygulama sınıfınızı dönüştürür.

Uygulamanız alt sınıf android.app.Applicationdeğilse, AndroidManifest.xml <application> etiketinde özniteliği olarak "android:name" ayarlamanız "com.microsoft.intune.mam.client.app.MAMApplication"gerekir.

Önerilen Android en iyi yöntemleri

• En yeni Android SDK derleme araçlarını kullanın.
• Tüm gereksiz ve kullanılmayan kitaplıkları kaldırın (örneğin, android.support.v4).

Otomatik değiştirmeleri gerçekleştirdikten sonra Intune Uygulama SDK'sı, Android API tarafından sağlanan sözleşmeyi korumaya devam eder. Ancak, ilke zorlaması sonucunda hata koşulları daha sık tetiklenebilir. Bu Android en iyi uygulamaları hata olasılığını azaltır:

• Döndürebilen null Android SDK işlevleri artık daha yüksek bir döndürme nullolasılığına sahiptir. Denetimlerin bu işlev çağrılarını koruduğuna null emin olun.
• gibi clipboardManager.getPrimaryClipDescription()denetlenebilen özellikler, gibi MAMClipboard.getPrimaryClipDescription(clipboardManager)MAM değiştirme API'leri aracılığıyla denetlenmelidir.
• Türetilmiş işlevler, süper sınıf sürümlerine çağrılmalıdır.
• Herhangi bir API'yi belirsiz bir şekilde kullanmaktan kaçının. Örneğin, denetlemeden kullanmak Activity.startActivityForResult garip davranışlara requestCode neden olur.

Hizmetler

İlke uygulama, Android Hizmeti etkileşimlerini etkileyebilir. gibi Context.bindService bağlı bir hizmet bağlantısı kuran yöntemler, içindeki temel ilke zorlaması Service.onBind nedeniyle başarısız olabilir ve veya ServiceConnection.onServiceDisconnectedile ServiceConnection.onNullBinding sonuçlanabilir. Yerleşik bir bağlı hizmetle etkileşim kurmak, içinde Binder.onTransactilke zorlaması nedeniyle bir SecurityException oluşturabilir.

Bağlı hizmetlerin istemcilerinin hizmet tarafından oluşan özel durumları denetlemesi teşvik edilir. Özel durumların istemci uygulamasının geri kalanına yayılmasına izin vermeyin.

Çıkış Ölçütleri

Derleme eklentisini yapılandırdıktan veya komut satırı aracını derleme işleminizle tümleştirdikten sonra, başarıyla çalıştığını doğrulayın:

• Derlemenizin başarıyla derlendiğinden ve derlendiğinden emin olun.
• Bayrağı yapılandırın report , ardından rapor belgesini açın ve sınıf ve yöntem değiştirmelerinin gerçekleştiğini onaylayın:
  • Eklentiyi kullanıyorsanız Raporlama'daki adımları izleyin.
  • Komut satırı aracını kullanıyorsanız bayrağını --report ekleyin.
• Eklentiyi kullanıyorsanız bayrağını verify yapılandırın ve hata oluşturmadığından emin olun. Bkz . Doğrulama.
• build.gradle dosyasındaki tüm dışlamaları (excludeProjects, excludeClassesve excludeVariants) bir kez daha denetleyin. Her dışlamanın gerekli olduğunu ve korunan verilerle ilgilenmediğini onaylayın. Geçmişte çok sayıda veri sızıntısı hatası aşırı agresif dışlamalar nedeniyle oluşur.
• Intune Şirket Portalı yüklü olmadan derlenmiş uygulamanızı başlatın. Uygulama Koruma İlkesi ile hedeflenmemiş Microsoft Entra bir kullanıcıyla oturum açın. Uygulamanın beklendiği gibi çalıştığını onaylayın.
  • Oturumu kapatın ve Intune Şirket Portalı yüklü olarak bu testi tekrarlayın.

SSS

Uygulamam daha önce derleme eklentisi olmadan SDK'yi tümleştirmişti; derleme eklentisini nasıl kullanabilirim?

Intune Uygulama SDK'sının eski sürümleri, sınıf ve yöntem değiştirme işlemlerini gerçekleştirmek için herhangi bir otomatik yöntem içermiyordu. Geliştiricilerin bu değişiklikleri kaynak kodunda el ile gerçekleştirmesi gerekiyordu. Uygulamanız bu şekilde tümleştirilmişse, derleme eklentisini veya komut satırı derleme aracını uygulamak güvenlidir. Kaynak kodunda değişiklik yapmanız gerekmez. Projenizin MAM SDK'sını yine de bağımlılık olarak listelemesi gerekir.

Sonraki Adımlar

Tüm Çıkış Ölçütlerini tamamladıktan sonra 4. Aşama: MAM Integration Essentials'a geçin.