Install Realm - Android SDK¶

Overview¶

MongoDB Realm's Android SDK enables you to build apps for the following platforms:

• Android
• Wear OS
• Android Automotive OS
• Android TV
• Android Things

This page details how to install Realm in your project and get started.

Prerequisites¶

• Android Studio version 1.5.1 or higher.
• JDK version 7.0 or higher.
• An emulated or hardware Android device for testing.
• Android API Level 16 or higher (Android 4.1 and above).

Installation¶

MongoDB Realm only supports the Gradle build system. Follow these steps to add the MongoDB Realm Android SDK to your project.

1

Add the Realm Dependency to the Project-Level build.gradle File¶

Create or open your project in Android Studio. Select the "Project" view in the top-left panel:

Open the project-level build.gradle file:

First, add the following repositories to your project:

Paste the Realm classpath into the buildscript.dependencies block:

classpath "io.realm:realm-gradle-plugin:10.8.0"

When done, your project-level build.gradle should look something like this:

2

Add Realm to the Application-Level build.gradle File¶

Expand the app folder on the "Project" view in the top-left panel to reveal the application files. Open the application-level build.gradle file in this folder:

If your application uses the Kotlin programming language, you need to apply the kotlin-kapt plugin:

apply plugin: 'kotlin-kapt'

Apply the realm-android plugin near the top of your application level build.gradle file:

apply plugin: 'realm-android'

Note

Application Order Matters

Application order matters for android plugins. Because the realm-android plugin depends upon the kotlin-kapt plugin for applications written in Kotlin, you must apply the realm-android plugin after the kotlin-kapt plugin if your application uses the Kotlin programming language.

If your application uses sync, you must enable the sync features of the Android SDK here:

realm {
   syncEnabled = true
}

When done, your application-level build.gradle file should look something like this:

Note

Enabling Sync is Optional

The Realm Android SDK includes functionality that allows you to sync data between mobile applications and a MongoDB Realm backend. If your application only uses local Realm Database, you can omit the following snippet from your application level build.gradle file to disable that functionality at the SDK level:

realm {
   syncEnabled = true
}

Installation Size¶

Once your app is built for release and split for distribution, the SDK should only add about 800KB to your APK in most cases. The releases are significantly larger because they include support for more architectures, such as ARM7, ARMv7, ARM64, x86, and MIPS. The APK file contains all supported architectures, but the Android installer only installs native code for the device’s architecture. This means that the installed app is smaller than the size of the APK file.

You can reduce the size of the Android APK itself by splitting the APK into a version for each architecture. Use the Android Build Tool ABI Split support by adding the following to your build.gradle:

android {
    splits {
        abi {
            enable true
            reset()
            include 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        }
    }
}

Select the architectures that you’d like to include to build a separate APK for each.

If you don’t want to handle multiple APKs, you can restrict the number of architectures supported in a single APK. This is done by adding abiFilters to your build.gradle:

android {
    defaultConfig {
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a', 'mips', 'x86', 'x86_64'
        }
    }
}

Customize Dependecies Defined by the Realm Gradle Plugin¶

Realm uses a Gradle plugin because it makes it easier to set up a large number of dependencies. Unfortunately this also makes it a bit harder to ignore specific transitive dependencies.

If you want to customize Realm beyond what is exposed by the plugin, you can manually set up all the dependencies and ignore the Gradle plugin. The following example demonstrates how to set up the SDK for an Android application using Kotlin manually:

buildscript {
    ext.kotlin_version = '1.5.21'
    ext.realm_version = '10.8.0'
    repositories {
        jcenter()
        mavenCentral()
    }
    dependencies {
        classpath "io.realm:realm-transformer:$realm_version"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-kapt'
import io.realm.transformer.RealmTransformer
android.registerTransform(new RealmTransformer(project))
dependencies {
  api "io.realm:realm-annotations:$realm_version"
  api "io.realm:realm-android-library:$realm_version"
  api "io.realm:realm-android-kotlin-extensions:$realm_version"
  kapt "io.realm:realm-annotations-processor:$realm_version"
}