Bundle a Realm - Kotlin SDK

Populate an Asset Realm with Seed Data

1. Create a new temporary project to create and populate an asset realm with seed data. This project uses the same Realm object schema as your production app.

2. Open an existing realm with the data you wish to seed, or create a new realm. Set a specific name for your asset realm so you can refer to it by name as the initial data source for your app.

3. Populate the asset realm with the seed data you want to include in your production application.

   You can get the path to the asset realm file using Realm.configuration.path.

// Open a local realm to use as the asset realm
val config = RealmConfiguration.Builder(schema = setOf(Item::class))
    .name("asset.realm")
    .build()
val assetRealm = Realm.open(config)
assetRealm.writeBlocking {
    // Add seed data to the asset realm
    copyToRealm(Item().apply {
        summary = "Write an awesome app"
        isComplete = false
    })
}
// Verify the data in the existing realm
// (this data should also be in the bundled realm we open later)
val originalItems: RealmResults<Item> = assetRealm.query<Item>().find()
for(item in originalItems) {
    Log.v("Item in the assetRealm: ${item.summary}")
}
// Get the path to the realm
Log.v("Realm location: ${config.path}")
assetRealm.close()

Now that you have an asset realm, you can move it into your production application and use it there.

Bundle and Open the Realm File in Your Production Application

1. Save the copy of the asset realm file to your production application. You must place this asset file in the appropriate location for your app's platform. For details, refer to Asset Realm Locations by Platform.

2. Create a Configuration that your production app can use to open the asset realm. Set the initialRealmFile property in this configuration to the name of your asset realm.

   You can optionally provide a sha256checkSum for the initialRealmFile to verify the integrity of the realm file when opening it. If you provide a checksum that does not match the computed checksum of the asset file when you open the seed realm, Realm.open() fails with an IllegalArgumentException.

3. With this configuration, you can open the bundled asset realm. It contains the data that was in the asset realm at the time you copied it.

// The config should list the bundled asset realm as the initialRealmFile
val bundledRealmConfig = RealmConfiguration.Builder(schema = setOf(Item::class))
    .initialRealmFile("asset.realm")
    .build()
// After moving the bundled realm to the appropriate location for your app's platform,
// open and use the bundled realm as usual.
val bundledRealm = Realm.open(bundledRealmConfig)
val bundledItems: RealmResults<Item> = bundledRealm.query<Item>().find()
for(item in bundledItems) {
    Log.v("Item in the bundledRealm: ${item.summary}")
}
bundledRealm.close()

Populate an Asset Realm with Seed Data

1. Create a new temporary project to create and populate the asset realm. This project uses the same Realm object schema as your production app.

2. Open the synced realm that you want to use as an asset realm.

3. Populate the asset realm with the seed data you want to include in your production application. You must wait for all local changes to synchronize with the Device Sync server. Use uploadAllLocalChanges() and downloadAllServerChanges() to ensure all sync processes are completed.

val app = App.create(yourFlexAppId)
// Login with user that has the server-side permissions to
// read and write the data you want in the asset realm
val user = app.login(credentials)
// Create a SyncConfiguration to open a synced realm to use as the asset realm
val assetRealmConfig = SyncConfiguration.Builder(user, setOf(Item::class))
    .name("asset.realm")
    // Add a subscription that matches the data being added
    // and your app's backend permissions
    .initialSubscriptions{ realm ->
        add(
            realm.query<Item>("isComplete == $0", false), "Incomplete Items")
    }
    .build()
val assetRealm = Realm.open(assetRealmConfig)
assetRealm.subscriptions.waitForSynchronization(10.seconds)
assertEquals(SubscriptionSetState.COMPLETE, assetRealm.subscriptions.state)
assetRealm.writeBlocking {
    // Add seed data to the synced realm
    copyToRealm(Item().apply {
        summary = "Make sure the app has the data it needs"
        isComplete = false
    })
}
// Verify the data in the existing realm
// (this data should also be in the bundled realm we open later)
val assetItems: RealmResults<Item> = assetRealm.query<Item>().find()
for(item in assetItems) {
    Log.v("Item in the assetRealm: ${item.summary}")
}
// IMPORTANT: Sync all changes with server before copying the synced realm
assetRealm.syncSession.uploadAllLocalChanges(30.seconds)
assetRealm.syncSession.downloadAllServerChanges(30.seconds)

Create a Copy of the Asset Realm

You must create a copy of the asset realm from the temporary project that you can bundle with your production application.

1. Create a SyncConfiguration that your app can use to open a copy of the asset realm. Set the initialRealmFile property in this configuration to the name of your asset realm.

   You can optionally provide a sha256checkSum for the initialRealmFile to verify the integrity of the realm file when opening it. If you provide a checksum that does not match the computed checksum of the seed realm when you open it, Realm.open() fails with an IllegalArgumentException.

   // Create a SyncConfiguration for the bundled copy.
   // The initialRealmFile value is the `name` property of the asset realm you're bundling.
   val copyConfig = SyncConfiguration.Builder(user, setOf(Item::class))
       .initialRealmFile("asset.realm")
       .build()

2. Create a new version of the synced realm using writeCopyTo() . You must use writeCopyTo() to bundle a synced realm. This method removes metadata that associates the realm with the user, which allows other users to open the realm file as well.

   Get the path to the copied realm file using Realm.configuration.path.

   // Copy the synced realm with writeCopyTo()
   assetRealm.writeCopyTo(copyConfig)
   // Get the path to the copy you just created.
   // You must move this file into the appropriate location for your app's platform.
   Log.v("Bundled realm location: ${copyConfig.path}")
   assetRealm.close()

Now that you have a copy of the asset realm, you can move it into your production application and use it there.

Bundle and Open a Synced Realm File in your Production Application

1. Save the copy of the asset realm file to your production application. You must place this asset file in the appropriate location for your app's platform. For details, refer to Asset Realm Locations by Platform.

2. Now that you have a copy of the asset realm bundled with your app, you can open it using the copied realm configuration you created. It contains the data that was in the asset realm at the time you copied it.

// After moving the bundled realm to the appropriate location for your app's platform,
// open and use the bundled realm as usual.
val copiedRealm = Realm.open(copyConfig)
// This should contain the same Items as in the asset realm
val copiedItems: RealmResults<Item> = copiedRealm.query<Item>().find()
for(item in copiedItems) {
    Log.v("Item in the copiedRealm: ${item.summary}")
}
copiedRealm.close()