Android installation
The Nevis Mobile Authentication SDK binaries for Android are provided by Nevis in an archive file.
For convenience, Nevis also offers a public Maven repository where the debug flavor of the SDK is available.
To obtain the release flavor of the SDK, download it from our portal.
You will see a package called nevis-mobile-authentication-sdk-android-NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION.zip
where NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION
is the actual version of the Nevis Mobile Authentication Android SDK e.g.: 3.4.0.1466
.
Installation from Public Maven Repository
The nevis-mobile-authentication-sdk-android-package GitHub repository, contains the debug
flavor of the Nevis Mobile Authentication SDK. You can follow the following steps to integrate the SDK in your application using this repository.
The following steps assume that the NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION
contains the SDK version. Set the console environment variable as follows:
- Add the repositories containing the SDK aar in the
build.gradle
file of your application module:
buildscript {
repositories {
maven {
url "https://maven.pkg.github.com/nevissecurity/nevis-mobile-authentication-sdk-android-package"
credentials {
username = <GITHUB_USERNAME>
password = <GITHUB_PERSONAL_ACCESS_TOKEN>
}
}
}
}
Accessing GitHub packages requires you to have a GitHub account. You have to provide a Personal Access Token, as described here.
- In the
build.gradle
file of your application module, add the SDK dependency and its required dependencies:
dependencies {
debugImplementation "ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_SDK_ANDROID_VERSION}"
}
Installation Using Archive Provided by Nevis
The SDK is provided as compressed archive. After unpacking, you see the following structure:
debug
contains the binary files and POM files of thedebug
flavor.release
contains the binary files, that is, AAR library and finalization library, and the POM files of therelease
flavor.
For example the content of package version 3.4.0.1466
will look like:
├── debug
│ ├── nevis-mobile-authentication-sdk-android-debug-3.4.0.1466-javadoc.jar
│ ├── nevis-mobile-authentication-sdk-android-debug-3.4.0.1466.aar
│ └── nevis-mobile-authentication-sdk-android-debug-3.4.0.1466.pom
└── release
├── nevis-mobile-authentication-sdk-android-3.4.0.1466-javadoc.jar
├── nevis-mobile-authentication-sdk-android-3.4.0.1466.aar
├── nevis-mobile-authentication-sdk-android-3.4.0.1466.pom
├── nevis-mobile-authentication-sdk-android-finalizer-3.4.0.1466.jar
└── nevis-mobile-authentication-sdk-android-finalizer-3.4.0.1466.pom
- Declare Maven repository
You have to configure the Maven repository where the Android release SDK and the finalizer
Gradle plugin are available. There are multiple choices.
For more information about declaring Gradle repositories read the official guide.
- Local Maven repository
- Relative/file Maven repository
- Custom Maven repository
You may install the release version of the Android SDK and the finalizer
plugin into your local Maven repository. To do this execute the following commands in terminal:
export NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION=3.4.0.1466
mvn install:install-file -Dfile=release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar -DgroupId=ch.nevis -DartifactId=nevis-mobile-authentication-sdk-android -Dversion=${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION} -DpomFile=release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.pom
mvn install:install-file -Dfile=release/nevis-mobile-authentication-sdk-android-finalizer-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.jar -DgroupId=ch.nevis -DartifactId=nevis-mobile-authentication-sdk-android-finalizer -Dversion=${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION} -DpomFile=release/nevis-mobile-authentication-sdk-android-finalizer-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.pom
We assume that you are in the root directory of the unpacked SDK package.
Declare mavenLocal()
repository:
allprojects {
repositories {
mavenLocal()
}
}
You may decide to use the SDK package content from a relative/file Maven repository. Let's say you want to use the native-dependecies
folder in your Android project root. In this case you have to add the following repository declaration to allprojects
part of your build.gradle
.
allprojects {
...
repositories.maven ({
name = "Native-Dependencies"
url = new File(rootProject.rootDir, 'native-dependencies')
})
...
}
Now you have to install the package to this relative/file Maven repository. To do this run the following commands in terminal:
export NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION=3.4.0.1466
# Absolute path of the previosly created Android native dependencies directory. E.g.: /Users/username/projects/flutter_app/android/native-dependencies
export LOCAL_REPOSITORY=/Users/username/projects/flutter_app/android/native-dependencies
mvn install:install-file -Dfile=release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar -DgroupId=ch.nevis -DartifactId=nevis-mobile-authentication-sdk-android -Dversion=${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION} -DpomFile=release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.pom -DlocalRepositoryPath=${LOCAL_REPOSITORY}
mvn install:install-file -Dfile=release/nevis-mobile-authentication-sdk-android-finalizer-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.jar -DgroupId=ch.nevis -DartifactId=nevis-mobile-authentication-sdk-android-finalizer -Dversion=${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION} -DpomFile=release/nevis-mobile-authentication-sdk-android-finalizer-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.pom -DlocalRepositoryPath=${LOCAL_REPOSITORY}
mvn install:install-file -Dfile=debug/nevis-mobile-authentication-sdk-android-debug-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar -DgroupId=ch.nevis -DartifactId=nevis-mobile-authentication-sdk-android-debug -Dversion=${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION} -DpomFile=debug/nevis-mobile-authentication-sdk-android-debug-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.pom -DlocalRepositoryPath=${LOCAL_REPOSITORY}
for f in ${LOCAL_REPOSITORY}/**/maven-metadata-local.xml; do mv "$f" "$(dirname $f)/maven-metadata.xml"; done
We assume that you are in the root directory of the unpacked SDK package.
Add the following files to your custom Maven repository and declare that repository.
release/nevis-mobile-authentication-sdk-android-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.aar
release/nevis-mobile-authentication-sdk-android-finalizer-${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}.jar
We assume that you are in the root directory of the unpacked SDK package.
NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION
is the actual version of the Nevis Mobile Authentication Android SDK e.g.: 3.4.0.1466
.
Please check the related *.pom
file for groupId
, artifactId
and version
.
- Add release flavor dependency
In the build.gradle
file of your application module, add the SDK dependency and its required dependencies:
dependencies {
releaseImplementation "ch.nevis:nevis-mobile-authentication-sdk-android:${NEVIS_MOBILE_SDK_ANDROID_VERSION}"
}
Finalization
There are a number of protection mechanisms only included in the release
flavor that require a procedure during the building of the application called finalization.
The finalization updates the binaries of the library with information about your application to execute those protection mechanisms during runtime. If you use Gradle to build the application, the finalization can be done using a Gradle plugin.
The debug
flavor does not require finalization.
Update the build.gradle
File
To integrate the Nevis Mobile Authentication SDK for Android into your application, do as follows:
- Add the repository containing the SDK aar and the SDK finalizer to
buildscript
block in thebuild.gradle
file of your application module. Use the same repository that you declared in previous chapter. - In the same
buildscript
block, define the SDK finalizer dependency as well.
In the following snippet, it is assumed that the SDK aar dependency and the finalizer are published to the repo.mycompany.com/maven2
Maven repository.
For convenience, you can define the ${NEVIS_MOBILE_AUTHENTICATION_SDK_ANDROID_VERSION}
variable in the gradle.properties
file. The variable contains the version of the SDK.
buildscript {
repositories {
mavenLocal()
maven {
url "http://repo.mycompany.com/maven2"
}
}
dependencies {
classpath "ch.nevis:nevis-mobile-authentication-sdk-android-finalizer:${NEVIS_MOBILE_SDK_ANDROID_VERSION}"
}
}
- In the
build.gradle
file of your application module, the SDK finalization plugin is required when using therelease
flavor, that is, for production. This finalizes the hardening framework protection of the SDK as part of the gradle build of your application. Apply the plugin using therelease
flavor as follows:
apply plugin: 'finalize'
The finalization plugin has to be applied on app level.
You can apply the finalizer
plugin only for release Gradle tasks using the following code snippet:
if (project.gradle.startParameter.taskNames.find { name -> name.endsWith("Release") } != null) { apply plugin: 'finalize' }
Manifest placeholders
The plugin requires access to the AndroidManifest.xml
when executed. So, if you use manifest placeholders, they have to be resolved before the plugin runs. If you want to resolve the placeholders on a variant basis, and you use Android Gradle Plugin 7.0 or later, use androidComponent
as in the following example:
android {
androidComponents {
onVariants(selector().all(), variant -> {
variant.manifestPlaceholders = [attributeName : "$attributeValue"]
})
If you use an earlier version of the Android Gradle Plugin than 7.0, and use the merged flavor of the variant to resolve the placeholders, execute the plugin after project evaluation:
android { applicationVariants.all {
variant ->
variant.getMergedFlavor().manifestPlaceholders = [attributeName : "$attributeValue"]
}
}
[...]
project.afterEvaluate { apply plugin: 'finalize' }
android.enableJetifier
flag
Finalization can fail for instance when using Androidx libraries if third party libraries are not migrated automatically. If finalization fails, we recommend enabling library migration in gradle.properties
:
android.enableJetifier=true
Example - application module build.gradle
file using both release
and debug
SDK dependencies
In the following example, the two out-of-the box build types provided by the Android Gradle plugin are used: release
and debug
. It is assumed that the SDK dependencies are published to the local Maven repository, see installation chapter.
As only the release
flavor of the SDK requires finalization, the finalization plugin is only applied during assembly of the release
build type.
repositories {
// It is assumed that the Nevis SDK is deployed to the local Maven
// repository
mavenLocal()
// Maven Central and Google repositories have the transitive dependencies
// required by the Nevis SDK
mavenCentral()
google()
}
buildscript {
repositories {
// It is assumed that the Nevis SDK finalizer library is deployed
// to the local Maven repository
mavenLocal()
// The Android Gradle Plugin is accessible from the Google repository
// mavenCentral is required to get its transitive dependencies
google()
mavenCentral()
}
dependencies{
classpath "ch.nevis:nevis-mobile-authentication-sdk-android-finalizer:${NEVIS_MOBILE_SDK_ANDROID_VERSION}"
classpath 'com.android.tools.build:gradle:7.0.3'
}
}
apply plugin: 'com.android.application'
android {
compileSdkVersion 30
defaultConfig {
minSdkVersion 23
targetSdkVersion 30
}
defaultConfig {
applicationId "ch.nevis.doc.sdksampleapp"
versionCode 1
versionName "1.0"
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
// Apply the SDK finalization plugin if we are using a Nevis SDK
// flavor that requires it.
if (isNevisSdkFinalizationRequired()) {
apply plugin: 'finalize'
}
// Add the SDK dependency that corresponds to the build type that we
// are assembling.
addSDKDependency(project.gradle.startParameter.taskNames)
dependencies {
// Add the dependencies of your application. The Nevis SDK dependencies have
// been added in addSDKDependency
}
private boolean isNevisSdkFinalizationRequired() {
return project.gradle.startParameter.taskNames.find { name -> name.endsWith("assembleRelease") } != null
}
private void addSDKDependency(List<String> taskNames) {
if (taskNames.size() == 1) {
def taskName = taskNames.iterator().next()
if (taskName.endsWith('assembleDebug')) {
project.dependencies.add('implementation', "ch.nevis:nevis-mobile-authentication-sdk-android-debug:${NEVIS_MOBILE_SDK_ANDROID_VERSION}")
}
if (taskName.endsWith('assembleRelease')) {
project.dependencies.add('implementation', "ch.nevis:nevis-mobile-authentication-sdk-android:${NEVIS_MOBILE_SDK_ANDROID_VERSION}")
}
}
}
Disable minifyEnabled
minifyEnabled
must be set to false
for all gradle build types of your application.
The hardening framework used by the SDK requires this. If minifyEnabled
is set to true
, tamper guards that operate at application runtime (like checksum) would be disabled.
Enable Multidexing
If your Android Gradle plugin does not enable multidexing by default, set multiDexEnabled
to true
in the defaultConfig
section of your top level build.gradle
file. The finalization can cause the total number of methods to go beyond the Dalvik Executable specification limit of 64k. Therefore, multiDexing must be enabled for your application.
Backup Setup
The Android Mobile Authentication SDK does not support backing up and restoring its contents.
If your application does not require backing up any of its contents, disable the backup in the AndroidManifest.xml
of your application as described in the Android documentation:
<manifest ... >
...
<application android:allowBackup="false" ... >
...
</application>
</manifest>
If your application requires backing up contents, you must list them explicitly in AndroidManifest.xml
to avoid backing up the SDK contents.
If the contents of the Android Mobile Authentication SDK are backed up and then restored, the SDK can fail during initialization.