Diego Freniche

# Adding Realm as a Dependency to an iOS Framework


## Introduction

In this post we’ll review how we can add RealmSwift as a dependency to our libraries, using two different methods: Xcode assistants and the Swift Package Manager.


## The Problem 

I have a little, nice Binary Tree library. I know that I will use it for a later project, and that it'll be used at least in a macOS and iOS app. Maybe also a Vapor web app. So I decided to create a Framework to hold this code. But some of my model classes there need to be persisted in some way locally in the phone later. The Realm Mobile library is perfect for this, as I can start working with regular objects and store them locally and, later, if I need a ~~no code~~ really simple & quick to implement backend solution I can use Realm Sync.

But the problem is, how do we add Realm as a dependency in our Frameworks?


## Solution 1: Use Xcode to Create the Framework and Add Realm with SPM

The first way to create the Framework is just to create a new Xcode Project. Start Xcode and select `File > New > Project`. In this case I’ll change to the iOS tab, scroll down to the Framework & Library section, then select Framework. This way I can share this Framework between my iOS app and its extensions, for instance.

![Choosing a template for the project](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_3_38b52507fe.png)

Now we have a new project that holds our code. This project has two targets, one to build the Framework itself and a second one to run our Unit Tests. Every time we write code we should test it, but this is especially important for reusable code, as one bug can propagate to multiple places.

To add Realm/Swift as a dependency, open your project file in the File Navigator. Then click on the Project Name and change to the Swift Packages tab. Finally click on the + button to add a new package. 

![Adding Realm as a Package to the Project, step by step](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/add_realm_swift_framework_c6525c705c.gif)

In this case, we’ll add Realm Cocoa, a package that contains two libraries. We’re interested in  Realm Swift: [https://github.com/realm/realm-cocoa](https://github.com/realm/realm-cocoa). We want one of the latest versions, so we’ll choose “Up to major version” 10.0.0. Once the resolution process is done, we can select RealmSwift.

Nice! Now that the package is added to our Framework we can compile our code containing Realm Objects without any problems!


## Solution 2: create the Framework using SPM and add the dependency directly in Package.swift

The other way to author a framework is to create it using the Swift Package Manager. We need to add a Package Manifest (the Package.swift file), and follow a certain folder [structure](https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode). We have two options here to create the package:



*   Use the Terminal
*   Use Xcode


### Creating the Package from Terminal



*   Open Terminal / CLI
*   Create a folder with `mkdir yourframeworkname`
*   Enter that folder with `cd yourframeworkname`
*   Run `swift package init`
*   Once created, you can open the package with `open Package.swift`

    
![Terminal showing the results of running above commands](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_2_b01503b34b.png)


### Creating the Package using Xcode

You can also use Xcode to do all this for you. Just go to `File > New > Swift Package`, give it a name and you’ll get your package with the same structure.


![Xcode showing the newly created Package.swift](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_1_146e545d92.png)



### Adding Realm as a dependency

So we have our Framework, with our library code and we can distribute it easily using Swift Package Manager. Now, we need to add Realm Swift. We don’t have the nice assistant that Xcode shows when you create the Framework using Xcode, so we need to add it manually to `Package.swift`

The complete `Package.swift` file


```swift
let package = Package(
    name: "BinaryTree",
    platforms: [
        .iOS(.v14)
    ],
    products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "BinaryTree",
            targets: ["BinaryTree"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(name: "Realm", url: "https://github.com/realm/realm-cocoa", from: "10.7.0")
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "BinaryTree",
            dependencies: [.product(name: "RealmSwift", package: "Realm")]),
        .testTarget(
            name: "BinaryTreeTests",
            dependencies: ["BinaryTree"]),
    ]
)
```


Here, we declare a package named “BinaryTree”, supporting iOS 14


```swift
let package = Package(
    name: "BinaryTree",
    platforms: [
        .iOS(.v14)
    ],
```


As this is a library, we declare the products we’re going to build, in this case it’s just one target called `BinaryTree`.


```swift
products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "BinaryTree",
            targets: ["BinaryTree"]),
    ],
```


Now, the important part: we declare Realm as a dependency in our library. We’re giving this dependency the short name “Realm” so we can refer to it in the next step.


```swift
dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(name: "Realm", url: "https://github.com/realm/realm-cocoa", from: "10.7.0")
    ],
```


In our target, we use the previously defined `Realm` dependency.


```swift
.target(
            name: "BinaryTree",
            dependencies: [.product(name: "RealmSwift", package: "Realm")]),
```


And that’s all! Now our library can be used as a Swift Package normally, and it will include automatically Realm.


## Recap

In this post we’ve seen different ways to create a Framework, directly from Xcode or as a Swift Package, and how to add `Realm` as a dependency to that Framework. This way, we can write code that uses Realm and distribute it quickly using SPM. 

In our next post in this series we’ll document this library using the new Documentation Compiler (DocC) from Apple. Stay tuned and thanks for reading!

If you have questions, please head to our [developer community website](https://developer.mongodb.com/) where the Realm engineers and the Realm/MongoDB community will help you build your next big idea with Realm and MongoDB.


Adding Realm to a Project is how we usually work. But sometimes we want to create a Framework (could be the data layer of a bigger project) that uses Realm. So... how do we add Realm as a dependency to said Framework? 

Adding Realm as a dependency to an iOS Framework

Andrew Morgan

## Introduction
Embedding Apple Maps and location functionality in SwiftUI apps used to be a bit of a pain. It required writing your own SwiftUI wrapper around UIKit code—see these examples from the [O-FISH app](https://github.com/WildAid/o-fish-ios):

* [Location helper](https://github.com/WildAid/o-fish-ios/blob/main/o-fish-ios/Helpers/LocationHelper.swift)
* [Map views](https://github.com/WildAid/o-fish-ios/tree/main/o-fish-ios/Views/Components/Maps)

If you only need to support iOS14 and later, then you can **forget most of that messy code 😊**. If you need to support iOS13—sorry, you need to go the O-FISH route!

iOS14 introduced the [Map](https://developer.apple.com/documentation/mapkit/map) SwiftUI view (part of [Mapkit](https://developer.apple.com/documentation/mapkit/map)) allowing you to embed maps directly into your SwiftUI apps without messy wrapper code.

This article shows you how to embed Apple Maps into your app views using Mapkit's Map view. We'll then look at how you can fetch the user's current location—with their permission, of course!

Finally, we'll see how to store the location data in Realm in a format that lets MongoDB Realm sync it to MongoDB Atlas. Once in Atlas, you can add a [geospatial index](https://docs.mongodb.com/manual/core/2dsphere/) and use [MongoDB Charts](https://www.mongodb.com/products/charts) to plot the data on a map—we'll look at that too.

Most of the code snippets have been extracted from the [RChat app](https://github.com/realm/RChat). That app is a good place to see maps and location data in action. [Building a Mobile Chat App Using Realm – The New and Easier Way](https://developer.mongodb.com/how-to/building-a-mobile-chat-app-using-realm-new-way/) is a good place to learn more about the RChat app—including how to enable [MongoDB Realm Sync](https://docs.mongodb.com/realm/sync/).

## Prerequisites

* [Realm-Cocoa 10.8.0](https://github.com/realm/realm-cocoa/releases)+ (may work with some 10.7.X versions)
* iOS 14.5+ ([Mapkit](https://developer.apple.com/documentation/mapkit/map) was introduced in iOS 14.0 and so most features should work with earlier iOS 14.X versions)
* [XCode12+](https://developer.apple.com/xcode/)

## How to Add an Apple Map to Your SwiftUI App

To begin, let's create a simple view that displays a map, the coordinates of the center of that map, and the zoom level:

![Gif of scrolling around an embedded Apple Map and seeing the reported coordinates changing](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_map1_7ea7ecbf15.gif)

With Mapkit and SwiftUI, this only takes a few lines of code:

``` swift
import MapKit
import SwiftUI

struct MyMapView: View {
    @State private var region: MKCoordinateRegion = MKCoordinateRegion(
        center: CLLocationCoordinate2D(latitude: MapDefaults.latitude, longitude: MapDefaults.longitude),
        span: MKCoordinateSpan(latitudeDelta: MapDefaults.zoom, longitudeDelta: MapDefaults.zoom))
        
    private enum MapDefaults {
        static let latitude = 45.872
        static let longitude = -1.248
        static let zoom = 0.5
    }

    var body: some View {
        VStack {
            Text("lat: \(region.center.latitude), long: \(region.center.longitude). Zoom: \(region.span.latitudeDelta)")
            .font(.caption)
            .padding()
            Map(coordinateRegion: $region,
                interactionModes: .all,
                showsUserLocation: true)
        }
    }
}
```

Note that `showsUserLocation` won't work unless the user has already given the app permission to use their location—we'll get to that.

`region` is initialized to a starting location, but it's updated by the `Map` view as the user scrolls and zooms in and out.

### Adding Bells and Whistles to Your Maps (Pins at Least)

Pins can be added to a map in the form of "annotations." Let's start with a single pin:

![Embedded Apple Map showing a red pin](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_map2_3812086195.png)

Annotations are provided as an array of structs where each instance must contain the coordinates of the pin. The struct must also conform to the [Identifiable](https://developer.apple.com/documentation/swift/identifiable) protocol:

``` swift
struct MyAnnotationItem: Identifiable {
    var coordinate: CLLocationCoordinate2D
    let id = UUID()
}
```

We can now create an array of `MyAnnotationItem` structs:

``` swift
let annotationItems = [
    MyAnnotationItem(coordinate: CLLocationCoordinate2D(
        latitude: MapDefaults.latitude,
        longitude: MapDefaults.longitude))]
```

We then pass `annotationItems` to the `MapView` and indicate that we want a `MapMarker` at the contained coordinates:

``` swift
Map(coordinateRegion: $region,
    interactionModes: .all,
    showsUserLocation: true,
    annotationItems: annotationItems) { item in
        MapMarker(coordinate: item.coordinate)
    }
```

That gives us the result we wanted.

What if we want multiple pins? Not a problem. Just add more `MyAnnotationItem` instances to the array.

All of the pins will be the same default color. But, what if we want different colored pins? It's simple to extend our code to produce this:

![Embedded Apple Map showing red, yellow, and plue pins at different locations](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_map3_669f6ec179.png)

Firstly, we need to extend `MyAnnotationItem` to include an optional `color` and a `tint` that returns `color` if it's been defined and "red" if not:

``` swift
struct MyAnnotationItem: Identifiable {
    var coordinate: CLLocationCoordinate2D
    var color: Color?
    var tint: Color { color ?? .red }
    let id = UUID()
}
```

In our sample data, we can now choose to provide a color for each annotation:

``` swift
let annotationItems = [
    MyAnnotationItem(
        coordinate: CLLocationCoordinate2D(
            latitude: MapDefaults.latitude,
            longitude: MapDefaults.longitude)),
    MyAnnotationItem(
        coordinate: CLLocationCoordinate2D(
            latitude: 45.8827419,
            longitude: -1.1932383),
        color: .yellow),
    MyAnnotationItem(
        coordinate: CLLocationCoordinate2D(
            latitude: 45.915737,
            longitude: -1.3300991),
        color: .blue)
]
```

The `MapView` can then use the `tint`:

``` swift
Map(coordinateRegion: $region,
    interactionModes: .all,
    showsUserLocation: true,
    annotationItems: annotationItems) { item in
    MapMarker(
        coordinate: item.coordinate,
        tint: item.tint)
}
```

If you get bored of pins, you can use `MapAnnotation` to use any view you like for your annotations:

``` swift
Map(coordinateRegion: $region,
    interactionModes: .all,
    showsUserLocation: true,
    annotationItems: annotationItems) { item in
    MapAnnotation(coordinate: item.coordinate) {
        Image(systemName: "gamecontroller.fill")
            .foregroundColor(item.tint)
    }
}
```

This is the result:

![Apple Map showing red, yellow and blue game controller icons at different locations on the map](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_map5_8509602cd7.png)

You could also include the name of the system image to use with each annotation.

This [gist](https://gist.github.com/am-MongoDB/3073226a84bf6deb6b2df7afcb21ca92) contains the final code for the view.

## Finding Your User's Location

### Asking for Permission

Apple is pretty vocal about respecting the privacy of their users, and so it shouldn't be a shock that your app will have to request permission before being able to access a user's location.

The first step is to add a key-value pair to your Xcode project to indicate that the app may request permission to access the user's location, and what text should be displayed in the alert. You can add the pair to the "Info.plist" file:

```
Privacy - Location When In Use Usage Description : We'll only use your location when you ask to include it in a message
```

![Screenshot from Xcode showing the key-value pair for requesting permission for the app to access the user's location](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Info_plist_1500a15e11.png)

Once that setting has been added, the user should see an alert the first time that the app attempts to access their current location:

![iPhone screenshot – app is requesting permission to access the user's location](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/request_access_to_location_08d1be66d1.png)

### Accessing Current Location

While Mapkit has made maps simple and native in SwiftUI, the same can't be said for location data.

You need to create a SwiftUI wrapper for Apple's [Core Location](https://developer.apple.com/documentation/corelocation) functionality. There's not a lot of value in explaining this boilerplate code—just copy this code from RChat's [LocationHelper.swift](https://github.com/realm/RChat/blob/main/RChat-iOS/RChat/Helpers/LocationHelper.swift) file, and paste it into your app:

``` swift
import CoreLocation

class LocationHelper: NSObject, ObservableObject {

    static let shared = LocationHelper()
    static let DefaultLocation = CLLocationCoordinate2D(latitude: 45.8827419, longitude: -1.1932383)

    static var currentLocation: CLLocationCoordinate2D {
        guard let location = shared.locationManager.location else {
            return DefaultLocation
        }
        return location.coordinate
    }

    private let locationManager = CLLocationManager()

    private override init() {
        super.init()
        locationManager.delegate = self
        locationManager.desiredAccuracy = kCLLocationAccuracyBest
        locationManager.requestWhenInUseAuthorization()
        locationManager.startUpdatingLocation()
    }
}

extension LocationHelper: CLLocationManagerDelegate {
    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) { }

    public func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
        print("Location manager failed with error: \(error.localizedDescription)")
    }

    public func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
        print("Location manager changed the status: \(status)")
    }
}
```

Once added, you can access the user's location with this simple call:

``` swift
let location = LocationHelper.currentLocation
```

### Store Location Data in Your Realm Database

#### The Location Format Expected by MongoDB

Realm doesn't have a native type for a geographic location, and so it's up to us how we choose to store it in a Realm Object. That is, unless we want to synchronize the data to MongoDB Atlas using MongoDB Realm Sync, and go on to use MongoDB's geospatial functionality.

To make the best use of the location data in Atlas, we need to add a [geospatial index](https://docs.mongodb.com/manual/geospatial-queries/#geospatial-indexes) to the field (which we’ll see how to do soon.) That means storing the location in a [supported format](https://docs.mongodb.com/manual/geospatial-queries/#geospatial-data). Not all options will work with Realm Sync (e.g., it's not guaranteed that attributes will appear in the same order in your Realm Object and the synced Atlas document). The most robust approach is to use an array where the first element is longitude and the second is latitude:

``` json
location: [<longitude>, <latitude>]
```

#### Your Realm Object

The RChat app gives users the option to include their location in a chat message—this means that we need to include the location in the [ChatMessage](https://github.com/realm/RChat/blob/main/RChat-iOS/RChat/Model/ChatMessage.swift) Object:

``` swift
class ChatMessage: Object, ObjectKeyIdentifiable {
  …
    @Persisted let location = List<Double>()
  …
    convenience init(author: String, text: String, image: Photo?, location: [Double] = []) {
        ...
	location.forEach { coord in
            self.location.append(coord)
      }
        ...
        }
    }
   ….
}
```

The `location` array that's passed to that initializer is formed like this:

``` swift
let location = LocationHelper.currentLocation
self.location = [location.longitude, location.latitude]
```

## Location Data in Your Backend MongoDB Realm App

The easiest way to create your backend MongoDB Realm schema is to enable [Development Mode](https://docs.mongodb.com/realm/sync/enable-development-mode/)—that way, the schema is automatically generated from your Swift Realm Objects.

This is the generated [schema](https://github.com/realm/RChat/blob/main/RChat-Realm/RChat/services/mongodb-atlas/rules/RChat.ChatMessage.json) for our "ChatMessage" collection:

``` swift
{
    "bsonType": "object",
    "properties": {
      "_id": {
        "bsonType": "string"
      },
      ...
      "location": {
        "bsonType": "array",
        "items": {
          "bsonType": "double"
        }
      }
    },
    "required": [
      "_id",
      ...
    ],
    "title": "ChatMessage"
}
```

This is a document that's been created from a synced Realm `ChatMessage` object:

![Screen capture of an Atlas document, which includes an array named location](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/atlas_document_d09cb3be1d.png)

### Adding a Geospatial Index in Atlas

Now that you have location data stored in Atlas, it would be nice to be able to work with it—e.g., running [geospatial queries](https://docs.mongodb.com/manual/geospatial-queries/). To enable this, you need to add a [geospatial index](https://docs.mongodb.com/manual/geospatial-queries/#geospatial-indexes) to the `location` field.

From the Atlas UI, select the "Indexes" tab for your collection and click "CREATE INDEX":

![Atlas screen capture of creating a new index](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/geo_index1_604fcbcd13.png)

You should then configure a `2dsphere` index:

![Atlas screen capture of creating a new 2dsphere index](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/geo_index2_8878556cfc.png)

Most chat messages won't include the user's location and so I set the `sparse` option for efficiency.

Note that you'll get an error message if your ChatMessage collection contains any documents where the value in the location attribute isn't in a valid geospatial format.

Atlas will then build the index. This will be very quick, unless you already have a huge number of documents containing the location field. Once complete, you can move onto the next section.

### Plotting Your Location Data in MongoDB Charts

[MongoDB Charts](https://www.mongodb.com/products/charts) is a simple way to visualize MongoDB data. You can access it through the same UI as Realm and Atlas. Just click on the "Charts" button:

![Atlas screen capture of MongoDB Charts button](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/select_charts_9c8caa71c0.png)

The first step is to click the "Add Data Source" button:

![Charts screen capture of adding a new data source](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/charts_data_source_4cbf88fea5.png)

Select your Atlas cluster:

![Charts screen capture of adding Atlas cluster as a data source](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/charts_select_cluster_b6d35ea00e.png)

Select the `RChat.ChatMessage` collection:

![Charts screen capture of selecting the ChatMessage collection in the RChat database](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/charts_select_collections_4f0dc0577d.png)

Click “Finish.” You’ll be taken to the default Dashboards view, which is empty for now. Click "Add Dashboard":

![Charts screen capture of adding a new dashboard](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/charts_dashboard1_b25eb3e015.png)

In your new dashboard, click "ADD CHART":

![Charts screen capture of adding a new chart](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/charts_add_chart_f00639d1a1.png)

Configure your chart as shown here by:
- Setting the chart type to "Geospatial" and the sub-type to "Scatter."
- Dragging the "location" attribute to the coordinates box.
- Dragging the "author" field to the "Color" box.

![Charts screen capture of configuring a new chart](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/charts_create_chart_81189874ac.png)

Once you've created your chart, you can [embed it](https://docs.mongodb.com/charts/saas/embed-chart-anon-auth/#std-label-anon-embedding-charts) in web apps, etc. That's beyond the scope of this article, but check out the [MongoDB Charts docs](https://docs.mongodb.com/charts/saas/) if you're interested.

## Conclusion

SwiftUI makes it easy to embed Apple Maps in your SwiftUI apps. As with most Apple frameworks, there are extra maps features available if you break out from SwiftUI, but I'd suggest that the simplicity of working with SwiftUI is enough incentive for you to avoid that unless you have a compelling reason.

Accessing location information from within SwiftUI still feels a bit of a hack, but in reality, you cut and paste the helper code once, and then you're good to go.

By storing the location as a `[longitude, latitude]` array (`List`) in your Realm database, it's simple to sync it with MongoDB Atlas. Once in Atlas, you have the full power of MongoDB's geospatial functionality to work your location data.

If you have questions, please head to our [developer community website](https://community.mongodb.com/) where the MongoDB engineers and the MongoDB community will help you build your next big idea with MongoDB.

Learn how to use the new Map view from iOS Map Kit in your SwiftUI/Realm apps. Also see how to use iOS location in Realm, Atlas, and Charts.

Using Maps and Location Data in Your SwiftUI (+Realm) App

## Introduction

[Murphy's law](https://en.wikipedia.org/wiki/Murphy%27s_law) dictates that as soon as your mobile app goes live, you'll receive a request to add a new feature. Then another. Then another.

This is fine if these features don't require any changes to your data schema. But, that isn't always the case.

Fortunately, Realm has built-in functionality to make schema migration easier.

This tutorial will step you through updating an existing mobile app to add some new features that require changes to the schema. In particular, we'll look at the Realm migration code that ensures that no existing data is lost when the new app versions are rolled out to your production users.

We'll use the [Scrumdinger app that I modified in a previous post to show how Apple's sample Swift app could be ported to Realm](https://www.mongodb.com/developer/how-to/realm-swiftui-scrumdinger-migration/). The starting point for the app can be found in [this branch of our Scrumdinger repo](https://github.com/realm/Scrumdinger/tree/realm) and the final version is in [this branch](https://github.com/realm/Scrumdinger/tree/new-schema).

Note that the app we're using for this post doesn't use [MongoDB Realm Sync](https://docs.mongodb.com/realm/sync/). If it did, then the schema migration process would be very different—that's covered in [Migrating Your iOS App's **Synced** Realm Schema in Production](https://www.mongodb.com/developer/how-to/realm-sync-migration/).

## Prerequisites

This tutorial has a dependency on [Realm-Cocoa 10.13.0+](https://github.com/realm/realm-cocoa/releases).

## Baseline App/Realm Schema

As a reminder, the starting point for this tutorial is the ["realm" branch of the Scrumdinger repo](https://github.com/realm/scrumdinger/tree/realm).

![Animated gif of the original Scrumdinger app in action](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/scrumdinger_original_b6a15f10ea.gif)

There are two Realm model classes that we'll extend to add new features to Scrumdinger. The first, [DailyScrum](https://github.com/realm/Scrumdinger/blob/realm/Scrumdinger/Models/DailyScrum.swift), represents one scrum:

``` swift
class DailyScrum: Object, ObjectKeyIdentifiable {
   @Persisted var title = ""
   @Persisted var attendeeList = RealmSwift.List<String>()
   @Persisted var lengthInMinutes = 0
   @Persisted var colorComponents: Components?
   @Persisted var historyList = RealmSwift.List<History>()


   var color: Color { Color(colorComponents ?? Components()) }
   var attendees: [String] { Array(attendeeList) }
   var history: [History] { Array(historyList) }
   ...
}
```

The second, [History](https://github.com/realm/Scrumdinger/blob/realm/Scrumdinger/Models/History.swift), represents the minutes of a meeting from one of the user's scrums:

``` swift
class History: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var date: Date?
   @Persisted var attendeeList = List<String>()
   @Persisted var lengthInMinutes: Int = 0
   @Persisted var transcript: String?
   var attendees: [String] { Array(attendeeList) }
   ...
}
```

We can use [Realm Studio](https://docs.mongodb.com/realm/studio/) to examine the contents of our Realm database after the `DailyScrum` and `History` objects have been created:

![DailyScrum data shown in RealmStudio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Daily_Scrum_original_117e226072.png)

![History data shown in RealmStudio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/History_original_fcc4e0b78d.png)

[Accessing Realm Data on iOS Using Realm Studio](https://www.mongodb.com/developer/how-to/realm-ios-database-access-using-realm-studio/) explains how to locate and open the Realm files from your iOS simulator.

## Schema Change #1—Mark Scrums as Public/Private

The first new feature we've been asked to add is a flag to indicate whether each scrum is public or private:

![Screen capture highlighting the new status - set to "Private"](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_show_privacy_00eb2f407b.png)

![Screen capture showing the user setting the meeting status to "Public"](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_edit_privacy_8df1447d57.png)

This feature requires the addition of a new `Bool` named `isPublic` to [DailyScrum](https://github.com/realm/Scrumdinger/blob/new-schema/Scrumdinger/Models/DailyScrum.swift):

``` swift
class DailyScrum: Object, ObjectKeyIdentifiable {
   @Persisted var title = ""
   @Persisted var attendeeList = RealmSwift.List<String>()
   @Persisted var lengthInMinutes = 0
   @Persisted var isPublic = false
   @Persisted var colorComponents: Components?
   @Persisted var historyList = RealmSwift.List<History>()


   var color: Color { Color(colorComponents ?? Components()) }
   var attendees: [String] { Array(attendeeList) }
   var history: [History] { Array(historyList) }
   ...
}
```

Remember that our original version of Scrumdinger is already in production, and the embedded Realm database is storing instances of `DailyScrum`. We don't want to lose that data, and so we must migrate those objects to the new schema when the app is upgraded.

Fortunately, Realm has built-in functionality to automatically handle the addition and deletion of fields. When adding a field, Realm will use a default value (e.g., `0` for an `Int`, and `false` for a `Bool`).

If we simply upgrade the installed app with the one using the new schema, then we'll get a fatal error. That's because we need to tell Realm that we've updated the schema. We do that by setting the schema version to 1 (the version defaulted to 0 for the original schema):

``` swift
@main
struct ScrumdingerApp: SwiftUI.App {
   var body: some Scene {
       WindowGroup {
           NavigationView {
               ScrumsView()
                   .environment(\.realmConfiguration,
                       Realm.Configuration(schemaVersion: 1))
           }
       }
   }
}
```

After upgrading the app, we can use [Realm Studio](https://docs.mongodb.com/realm/studio/) to confirm that our `DailyScrum` object has been updated to initialize `isPublic` to `false`:

![RealmStudio showing that the new, isPublic field has been initialised to false](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Daily_Scrum_updated_19c30fabd6.png)

## Schema Change #2—Store The Number of Attendees at Each Meeting

The second feature request is to show the number of attendees in the history from each meeting:

![Screen capture showing that the number of attendees is now displayed in the meeting minutes](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_History_Change_5218655494.png)

We could calculate the count every time that it's needed, but we've decided to calculate it just once and then store it in our [History](https://github.com/realm/Scrumdinger/blob/new-schema/Scrumdinger/Models/History.swift) object in a new field named `numberOfAttendees`:

``` swift
class History: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var date: Date?
   @Persisted var attendeeList = List<String>()
   @Persisted var numberOfAttendees = 0
   @Persisted var lengthInMinutes: Int = 0
   @Persisted var transcript: String?
   var attendees: [String] { Array(attendeeList) }
   ...
}
```

We increment the schema version to 2. Note that the schema version applies to all Realm objects, and so we have to set the version to 2 even though this is the first time that we've changed the schema for `History`.

If we leave it to Realm to initialize `numberOfAttendees`, then it will set it to 0—which is not what we want. Instead, we provide a `migrationBlock` which initializes new fields based on the old schema version:

``` swift
@main
struct ScrumdingerApp: SwiftUI.App {
   var body: some Scene {
       WindowGroup {
           NavigationView {
               ScrumsView()
                   .environment(\.realmConfiguration, Realm.Configuration(
                       schemaVersion: 2,
                       migrationBlock: { migration, oldSchemaVersion in
                            if oldSchemaVersion < 1 {
                                // Could init the `DailyScrum.isPublic` field here, but the default behavior of setting
                                // it to `false` is what we want.
                            }
                            if oldSchemaVersion < 2 {
                                migration.enumerateObjects(ofType: History.className()) { oldObject, newObject in
                                    let attendees = oldObject!["attendeeList"] as? RealmSwift.List<DynamicObject>
                                    newObject!["numberOfAttendees"] = attendees?.count ?? 0
                                }
                            }
                            if oldSchemaVersion < 3 {
                                // TODO: This is where you'd add you're migration code to go from version
                                // to version 3 when you next modify the schema
                            }
                        }
                   ))
           }
       }
   }
}
```

Note that all other fields are migrated automatically.

It's up to you how you use data from the previous schema to populate fields in the new schema. E.g., if you wanted to combine `firstName` and `lastName` from the previous schema to populate a `fullName` field in the new schema, then you could do so like this:

``` swift
migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
   let firstName = oldObject!["firstName"] as! String
   let lastName = oldObject!["lastName"] as! String
   newObject!["fullName"] = "\(firstName) \(lastName)"
}
```

We can't know what "old version" of the schema will be already installed on a user's device when it's upgraded to the latest version (some users may skip some versions,) and so the `migrationBlock` must handle all previous versions. Best practice is to process the incremental schema changes sequentially:

* `oldSchemaVersion < 1` : Process the delta between v0 and v1
* `oldSchemaVersion < 2` : Process the delta between v1 and v2
* `oldSchemaVersion < 3` : Process the delta between v2 and v3
* ...

Realm Studio shows that our code has correctly initialized `numberOfAttendees`:

![Realm Studio showing that the numberOfAttendees field has been set to 2 – matching the number of attendees in the meeting history](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/History_new_11564ec4b0.png)

## Conclusion

It's almost inevitable that any successful mobile app will need some schema changes after it's gone into production. Realm makes adapting to those changes simple, ensuring that users don't lose any of their existing data when upgrading to new versions of the app.

For changes such as adding or removing fields, all you need to do as a developer is to increment the version with each new deployed schema. For more complex changes, you provide code that computes the values for fields in the new schema using data from the old schema.

This tutorial stepped you through adding two new features that both required schema changes. You can view the final app in the [new-schema branch of the Scrumdinger repo](https://github.com/realm/Scrumdinger/tree/new-schema).

## Next Steps

This post focussed on schema migration for an iOS app. You can find some [more complex examples in the repo](https://github.com/realm/realm-cocoa/tree/master/examples/ios/swift/Migration).

If you're working with an app for a different platform, then you can find instructions in the docs:

* [Node.js](https://docs.mongodb.com/realm/sdk/node/examples/modify-an-object-schema/)
* [Android](https://docs.mongodb.com/realm/sdk/android/examples/modify-an-object-schema/)
* [iOS](https://docs.mongodb.com/realm/sdk/android/examples/modify-an-object-schema/)
* [.NET](https://docs.mongodb.com/realm/sdk/dotnet/examples/modify-an-object-schema/)
* [React Native](https://docs.mongodb.com/realm/sdk/react-native/examples/modify-an-object-schema/)

If you've any questions about schema migration, or anything else related to Realm, then please post them to our [community forum](https://www.mongodb.com/community/forums/c/realm-sdks/58).

Learn how to safely update your iOS app's Realm schema to support new functionality—without losing any existing data

Migrating Your iOS App's Realm Schema in Production

Rachelle Palmer

<h2>Introduction</h2>

This Summer, MongoDB hosted 112 interns, spread across departments such as MongoDB Cloud, Atlas, and Realm. These interns have worked on a vast array of projects using the MongoDB platform and technologies. One such project was created by two Software Engineering interns, José Pedro Martins and Linnea Jansson, on the MongoDB Realm team. 

Using MongoDB Realm and React Native, they built an app to log and display the location and movement of a user’s devices in real-time on a map. Users can watch as their device’s position on the map updates in response to how its physical location changes in real life. Additionally, users can join groups and view the live location of devices owned by other group members. 

In this article, I look forward to demonstrating the app’s features, discussing how it uses MongoDB Realm, and reviewing some noteworthy scenarios which arose during its development.


<h2>App overview</h2>

The project, called *Find Our Devices*, is an app for iOS and Android which allows users to view the live location of their devices on a map. The demo video above demonstrates some key features and shows off the intuitive UI. Users can track multiple devices by installing the app, logging in with their email, and adding the current device to their account. 

For each device, a new pin is added to the map to indicate the device’s location. This feature is perfect if one of your devices has been lost or stolen, as you can easily track the location of your iOS and Android devices from one app. Instead of using multiple apps to track devices on android and iOS, the user can focus on retrieving their device. Indeed, if you’re only interested in the location of one device, you can instantly find its location by selecting it from a dropdown menu. 

Additionally, users can create groups with other users. In these groups, users can see both the location of their devices and the location of other group members' devices. Group members can also invite other users by inputting their email. If a user accepts an invitation, their devices' locations begin to sync to the map. They can also view the live location of other members’ devices on the group map. 

This feature is fantastic for families or groups of friends travelling abroad. If somebody gets lost, their location is still visible to everyone in the group, provided they have network connectivity. Alternatively, logistics companies could use the app to track their fleets. If each driver installs the app, HQ could quickly find the location of any vehicle in the fleet and predict delays or suggest alternative routes to drivers. If users want privacy, they can disable location sharing at any time, or leave the group.

<h2>Uses of Realm</h2>

This app was built using the [MongoDB RealmJS SDK](https://docs.mongodb.com/realm/sdk/react-native/) and React-Native and utilises many of Realm’s features. For example, the authentication process of registration, logging in, and logging out is handled using [Realm Email/Password authentication](https://docs.mongodb.com/realm/authentication/). Additionally, Realm enables a seamless data flow while updating device locations in groups, as demonstrated by the diagram below: 

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Find_Our_Devices_data_flow_updating_location_43a9d24b1f.png)

As a device moves, Realm writes the location to Atlas, provided the device has network connectivity. If the device doesn’t have network connectivity, Realm will sync the data into Atlas when the device is back online. Once the data is in Atlas, Realm will propagate the changes to the other users in the group. Upon receiving the new data, a change listener in the app is notified of this update in the device's location. As a result, the pin’s position on the map will update and users in the group can see the device’s new location.

Another feature of Realm used in this project is shared realms. In the Realm task tracker tutorial, available [here](https://docs.mongodb.com/realm/tutorial/), all users in a group have read/write permission to the group partition. The developers allowed this, as group members were trusted to change any data in the group’s shared resources. Indeed, this was encouraged, as it allowed team members to edit tasks created by other team members and mark them as completed. In this app, users couldn't have write permissions to the shared realm, as group members could modify other users' locations with write permission. The solution to this problem is shown in the diagram below. Group members only have read permissions for the shared realm, allowing them to read others' locations, but not edit them. You can learn more about Realm partitioning strategies [here](https://www.mongodb.com/developer/how-to/realm-partitioning-strategies/).

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Find_Our_Devices_comparison_of_permissions_for_shared_realms_072b1b6355.png)

<h2>Fixing a security vulnerability</h2>

Several difficult scenarios and edge cases came up during the development process. For example, in the initial version, users could write to the [*Group Membership*](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Demo_Video_2a492b355b.mov)(https://github.com/realm/FindOurDevices/blob/0b118053a3956d4415d40d9c059f6802960fc484/app/models/GroupMembership.js) class. The intention was that this permission would allow members to join new groups and write their new membership to Atlas from Realm. Unfortunately, this permission also created a security vulnerability, as the client could edit the *GroupMembership.groupId* value to anything they wanted. If they edited this value to another group’s ID value, this change would be synced to Atlas, as the user had write permission to this class. Malicious users could use this vulnerability to join a group without an invitation and snoop on the group members' locations.

Due to the serious ethical issues posed by this vulnerability, a fix needed to be found. Ultimately, the solution was to split the Device partition from the User partition and retract write permissions from the User class, as shown in the diagram below. Thanks to this amendment, users could no longer edit their *GroupMembership.groupId* value. As such, malicious actors could no longer join groups for which they had no invitation. Additionally, each device is now responsible for updating its location, as the Device partition is now separate from the User partition, with write permissions.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Find_Our_Devices_solving_privacy_issue_e339dae9c0.png)

<h2>Conclusion</h2>

In this blog post, we discussed a fascinating project built by two Realm interns this year. More specifically, we explored the functionality and use cases of the project, looked at how the project used MongoDB Realm, and examined a noteworthy security vulnerability that arose during development. 

If you want to learn more about the project or dive into the code, you can check out the backend repository [here](https://github.com/realm/FindOurDevices-backend) and the frontend repository [here](https://github.com/realm/FindOurDevices). You can also build the project yourself by following the instructions in the ReadMe files in the two repositories. Alternatively, if you'd like to learn more about MongoDB, you can visit our [community forums](https://www.mongodb.com/community/forums/), sign up for [MongoDB University](https://university.mongodb.com/), or sign up for the [MongoDB newsletter](https://www.mongodb.com/newsletter)!

Build an example mobile application using realm for iOS and Android

Find our Devices - A locator app built using Realm


## Introduction

In the [previous post in this series](https://www.mongodb.com/developer/how-to/realm-schema-migration), we saw how to migrate your Realm data when you upgraded your iOS app with a new schema. But, that only handled the data in your local, standalone Realm database. What if you're using [MongoDB Realm Sync](https://docs.mongodb.com/realm/sync/) to replicate your local Realm data with other instances of your mobile app and with MongoDB Atlas? That's what this article will focus on.

We'll start with the original [RChat app](https://www.mongodb.com/developer/how-to/building-a-mobile-chat-app-using-realm-new-way/). We'll then extend the iOS app and backend Realm schema to add a new feature that allows chat messages to be tagged as high priority. The next (and perhaps surprisingly more complicated from a Realm perspective) upgrade is to make the `author` attribute of the existing `ChatMessage` object non-optional.

You can find all of the code for this post in the RChat repo under these branches:

- [Starting point](https://github.com/realm/RChat)
- [Upgrade #1](https://github.com/realm/RChat/tree/new-schema)
- [Upgrade #2](https://github.com/realm/RChat/tree/v2-schema)

## Prerequisites

[Realm Cocoa 10.13.0](https://github.com/realm/realm-cocoa/releases) or later (for versions of the app that you're upgrading **to**)

## Catch-Up — The RChat App

RChat is a basic chat app:

- Users can register and log in using their email address and a password.
- Users can create chat rooms and include other users in those rooms.
- Users can post messages to a chat room (optionally including their location and photos).
- All members of a chatroom can see messages sent to the room by themselves or other users.

:youtube[Existing RChat iOS app functionality]{vid=BlV9El_MJqk}

## Upgrade #1: Add a High-Priority Flag to Chat Messages

The first update is to allow a user to tag a message as being high-priority as they post it to the chat room:

![Screenshot showing the option to click a thermometer button to tag the message as urgent](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Set_Priority_a2c8f60550.png)

That message is then highlighted with bold text and a "hot" icon in the list of chat messages:

![Screenshot showing that a high-priority message has bold text and a hot thermometer icon](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/View_Priority_1991c9d4bf.png)

### Updating the Backend Realm Schema

Adding a new field is an [additive change](https://docs.mongodb.com/realm/sync/synced-schema-overview/)—meaning that you don't need to restart sync (which would require every deployed instance of the RChat mobile app to recognize the change and start sync from scratch, potentially losing local changes).

We add the new `isHighPriority` bool to our Realm schema through the Realm UI:

![Screenshot from the RealmUI showing that the isHighPriority bool has been added to the schema](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Update_Schema_v1_b9ff24b45c.png)

We also make `isHighPriority` a required (non-optional field).

The resulting schema looks like this:

```js
{
   "bsonType": "object",
   "properties": {
     "_id": {
       "bsonType": "string"
     },
     "author": {
       "bsonType": "string"
     },
     "image": {
       "bsonType": "object",
       "properties": {
         "_id": {
           "bsonType": "string"
         },
         "date": {
           "bsonType": "date"
         },
         "picture": {
           "bsonType": "binData"
         },
         "thumbNail": {
           "bsonType": "binData"
         }
       },
       "required": [
         "_id",
         "date"
       ],
       "title": "Photo"
     },
     "isHighPriority": {
       "bsonType": "bool"
     },
     "location": {
       "bsonType": "array",
       "items": {
         "bsonType": "double"
       }
     },
     "partition": {
       "bsonType": "string"
     },
     "text": {
       "bsonType": "string"
     },
     "timestamp": {
       "bsonType": "date"
     }
   },
   "required": [
     "_id",
     "partition",
     "text",
     "timestamp",
     "isHighPriority"
   ],
   "title": "ChatMessage"
 }
```
Note that existing versions of our iOS RChat app can continue to work with our updated backend Realm app, even though their local `ChatMessage` Realm objects don't include the new field.

### Updating the iOS RChat App

While existing versions of the iOS RChat app can continue to work with the updated Realm backend app, they can't use the new `isHighPriority` field as it isn't part of the `ChatMessage` object.

To add the new feature, we need to update the mobile app after deploying the updated Realm backend application.

The first change is to add the `isHighPriority` field to the `ChatMessage` class:

```swift
class ChatMessage: Object, ObjectKeyIdentifiable {
   @Persisted(primaryKey: true) var _id = UUID().uuidString
   @Persisted var partition = "" // "conversation=<conversation-id>"
   @Persisted var author: String? // username
   @Persisted var text = ""
   @Persisted var image: Photo?
   @Persisted var location = List<Double>()
   @Persisted var timestamp = Date()
   @Persisted var isHighPriority = false
   ...
}
```

As seen in the [previous post in this series](https://www.mongodb.com/developer/how-to/realm-schema-migration), Realm can automatically update the local realm to include this new attribute and initialize it to `false`. Unlike with standalone realms, we **don't** need to signal to the Realm SDK that we've updated the schema by providing a schema version.

The new version of the app will happily exchange messages with instances of the original app on other devices (via our updated backend Realm app).

## Upgrade #2: Make `author` a Non-Optional Chat Message field

When the initial version of RChat was written, the `author` field of `ChatMessage` was declared as being optional. We've since realized that there are no scenarios where we wouldn't want the author included in a chat message. To make sure that no existing or future client apps neglect to include the author, we need to update our schema to make `author` a required field.

Unfortunately, changing a field from optional to required (or vice versa) is a [destructive change](https://docs.mongodb.com/realm/sync/synced-schema-overview/#destructive-changes), and so would break sync for any deployed instances of the RChat app.

Oops!

This means that there's extra work needed to make the upgrade seamless for the end users. We'll go through the process now.

### Updating the Backend Realm Schema

The change we need to make to the schema is destructive. This means that the new document schema is incompatible with the schema that's currently being used in our mobile app.

If RChat wasn't already deployed on the devices of hundreds of millions of users (we can dream!), then we could update the Realm schema for the `ChatMessage` collection and restart Realm Sync. During development, we can simply remove the original RChat mobile app and then install an updated version on our test devices.

To avoid that trauma for our end users, we leave the `ChatMessage` collection's schema as is and create a [partner collection](https://docs.mongodb.com/realm/sync/migrate-schema-partner-collection/#partner-collections). The partner collection (`ChatMessageV2`) will contain the same data as `ChatMessage`, except that its schema makes `author` a required field.

These are the steps we'll go through to create the partner collection:

- Define a Realm schema for the `ChatMessageV2` collection.
- Run an [aggregation](https://docs.mongodb.com/manual/aggregation/) to copy all of the documents from `ChatMessage` to `ChatMessageV2`. If `author` is missing from a `ChatMessage` document, then the aggregation will add it.
- Add a trigger to the `ChatMessage` collection to propagate any changes to `ChatMessageV2` (adding `author` if needed).
- Add a trigger to the `ChatMessageV2` collection to propagate any changes to `ChatMessage`.

#### Define the Schema for the Partner Collection

From the Realm UI, copy the schema from the `ChatMessage` collection. 

Click the button to create a new schema:

![Showing a plus button in the Realm UI to add a new collection](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/add_collection_c16ec9a063.png)

Set the database and collection name before clicking "Add Collection":

![Setting the database and collection names in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/config_collection_324bc0182e.png)

Paste in the schema copied from `ChatMessage`, add `author` to the `required` section, change the `title` to `ChatMessageV2`, and the click the "SAVE" button:

![Adding "author" to the required attribute list and naming the class ChatMessageV2 in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/define_schema_be6ae7c555.png)

This is the resulting schema:

```js
{
   "bsonType": "object",
   "properties": {
     "_id": {
       "bsonType": "string"
     },
     "author": {
       "bsonType": "string"
     },
     "image": {
       "bsonType": "object",
       "properties": {
         "_id": {
           "bsonType": "string"
         },
         "date": {
           "bsonType": "date"
         },
         "picture": {
           "bsonType": "binData"
         },
         "thumbNail": {
           "bsonType": "binData"
         }
       },
       "required": [
         "_id",
         "date"
       ],
       "title": "Photo"
     },
     "isHighPriority": {
       "bsonType": "bool"
     },
     "location": {
       "bsonType": "array",
       "items": {
         "bsonType": "double"
       }
     },
     "partition": {
       "bsonType": "string"
     },
     "text": {
       "bsonType": "string"
     },
     "timestamp": {
       "bsonType": "date"
     }
   },
   "required": [
     "_id",
     "partition",
     "text",
     "timestamp",
     "isHighPriority",
     "author"
   ],
   "title": "ChatMessageV2"
 }
```

#### Copy Existing Data to the Partner Collection

We're going to use an [aggregation pipeline](https://docs.mongodb.com/manual/aggregation/) to copy and transform the existing data from the original collection (`ChatMessage`) to the partner collection (`ChatMessageV2`).

You may want to pause sync just before you run the aggregation, and then unpause it after you enable the trigger on the `ChatMessage` collection in the next step:

![Pressing a button to pause Realm sync in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/pause_sync_707605a511.png)

The end users can continue to create new messages while sync is paused, but those messages won't be published to other users until sync is resumed. By pausing sync, you can ensure that all new messages will make it into the partner collection (and so be visible to users running the new version of the mobile app).

If pausing sync is too much of an inconvenience, then you could create a temporary trigger on the `ChatMessage` collection that will copy and transform document inserts to the `ChatMessageV2` collection (it's a subset of the `ChatMessageProp` trigger we'll define in the next section.).

From the Atlas UI, select "Collections" -> "ChatMessage", "New Pipeline From Text":

![Navigating through "Atlas/ChatMessage/Collections/New Pipeline from Text" in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/add_aggregation_2e84c4a8df.png)

Paste in this aggregation pipeline and click the "Create New" button:

```js
[
 {
   '$addFields': {
     'author': {
       '$convert': {
         'input': '$author',
         'to': 'string',
         'onError': 'unknown',
         'onNull': 'unknown'
       }
     }
   }
 },
 {
   '$merge': {
     into: "ChatMessageV2",
     on: "_id",
     whenMatched: "replace",
     whenNotMatched: "insert"
   }
 }
]
```

This aggregation will take each `ChatMessage` document, set `author` to "unknown" if it's not already set, and then add it to the `ChatMessageV2` collection.

Click "MERGE DOCUMENTS":

![Clicking the "Merge Documents" button in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/merge_documents_8b40ae6ce6.png)

`ChatMessageV2` now contains a (possibly transformed) copy of every document from `ChatMessage`. But, changes to one collection won't be propagated to the other. To address that, we add a database trigger to each collection…

#### Add Database Triggers

We need to create two [Realm Functions](https://docs.mongodb.com/realm/functions/)—one to copy/transfer documents to `ChatMessageV2`, and one to copy documents to `ChatMessage`.

From the "Functions" section of the Realm UI, click "Create New Function":

![Clicking the "Create New Function" button in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/new_function_3fd3b90a11.png)

Name the function `copyToChatMessageV2`. Set the authentication method to "System"—this will circumvent any access permissions on the `ChatMessageV2` collection. Ensure that the "Private" switch is turned on—that means that the function can be called from a trigger, but not directly from a frontend app. Click "Save":

![Set the name to "copyToChatMessageV2", authentication to "System" and "Private" to "On". Then click the "Save" button in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/configure_function_6acb29f42b.png)

Paste this code into the function editor and save:

```js
exports = function (changeEvent) {
   const db = context.services.get("mongodb-atlas").db("RChat");


   if (changeEvent.operationType === "delete") {
     return db.collection("ChatMessageV2").deleteOne({ _id: changeEvent.documentKey._id });
   }


   const author = changeEvent.fullDocument.author ? changeEvent.fullDocument.author : "Unknown";
   const pipeline = [
     { $match: { _id: changeEvent.documentKey._id } },
     {
       $addFields: {
         author: author,
       }
     },
     { $merge: "ChatMessageV2" }];


   return db.collection("ChatMessage").aggregate(pipeline);
};
```

This function will receive a `ChatMessage` document from our trigger. If the operation that triggered the function is a delete, then this function deletes the matching document from `ChatMessageV2`. Otherwise, the function either copies `author` from the incoming document or sets it to "Unknown" before writing the transformed document to `ChatMessageV2`. We could initialize `author` to any string, but I've used "Unknown" to tell the user that we don't know who the author was.

Create the `copyToChatMessage` function in the same way:

```js
exports = function (changeEvent) {
   const db = context.services.get("mongodb-atlas").db("RChat");


   if (changeEvent.operationType === "delete") {
     return db.collection("ChatMessage").deleteOne({ _id: changeEvent.documentKey._id })
   }
    const pipeline = [
     { $match: { _id: changeEvent.documentKey._id } },
     { $merge: "ChatMessage" }]
   return db.collection("ChatMessageV2").aggregate(pipeline);
};
```

The final change needed to the backend Realm application is to add database triggers that invoke these functions.

From the "Triggers" section of the Realm UI, click "Add a Trigger":

![Click the "Add a Trigger" button in the Realm UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/configure_trigger_558a629423.png)

Configure the `ChatMessageProp` trigger as shown:

![In the Realm UI, set "Trigger Type" to "Database". Set "Name" to "ChatMessageProp". Enabled = On. Event Ordering = on. Cluster Name = Cluster 0. Database name = RChat. Collection name = ChatMessage. Check all operation types. Full Document = on. Document Preimage = off. Event Type = Function. Function = copyToChatMessageV2](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/trigger_settings_1601e02011.png)

Repeat for `ChatMessageV2Change`:

![In the Realm UI, set "Trigger Type" to "Database". Set "Name" to "ChatMessageProp". Enabled = On. Event Ordering = on. Cluster Name = Cluster 0. Database name = RChat. Collection name = ChatMessage. Check all operation types. Full Document = off. Document Preimage = off. Event Type = Function. Function = copyToChatMessage](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/trigger2_settings_c55de55738.png)

If you paused sync in the previous section, then you can now unpause it.

### Updating the iOS RChat App

We want to ensure that users still running the old version of the app can continue to exchange messages with users running the latest version.

Existing versions of RChat will continue to work. They will create `ChatMessage` objects which will get synced to the `ChatMessage` Atlas collection. The database triggers will then copy/transform the document to the `ChatMessageV2` collection.

We now need to create a new version of the app that works with documents from the `ChatMessageV2` collection. We'll cover that in this section.

Recall that we set `title` to `ChatMessageV2` in the partner collection's schema. That means that to sync with that collection, we need to rename the `ChatMessage` class to `ChatMessageV2` in the iOS app. 

Changing the name of the class throughout the app is made trivial by Xcode.

Open `ChatMessage.swift` and right-click on the class name (`ChatMessage`), select "Refactor" and then "Rename…":

![In Xcode, select the "ChatMessage" class name, right-click and select "Refactor -> Rename..."](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/refactor1_4c2d938e3d.png)

Override the class name with `ChatMessageV2` and click "Rename":

![In Xcode, overwrite the class name with "ChatMessageV2" and then click the "Rename" button](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/refactor2_03837b2472.png)

The final step is to make the author field mandatory. Remove the ? from the author attribute to make it non-optional:

```swift
class ChatMessageV2: Object, ObjectKeyIdentifiable {
   @Persisted(primaryKey: true) var _id = UUID().uuidString
   @Persisted var partition = "" // "conversation=<conversation-id>"
   @Persisted var author: String
   ...
}
```

## Conclusion

Modifying a Realm schema is a little more complicated when you're using Realm Sync for a deployed app. You'll have end users who are using older versions of the schema, and those apps need to continue to work.

Fortunately, the most common schema changes (adding or removing fields) are additive. They simply require updates to the back end and iOS schema, together.

Things get a little trickier for destructive changes, such as changing the type or optionality of an existing field. For these cases, you need to create and maintain a partner collection to avoid loss of data or service for your users.

This article has stepped through how to handle both additive and destructive schema changes, allowing you to add new features or fix issues in your apps without impacting users running older versions of your app.

Remember, you can find all of the code for this post in the RChat repo under these branches:

- [Starting point](https://github.com/realm/RChat)
- [Upgrade #1](https://github.com/realm/RChat/tree/new-schema)
- [Upgrade #2](https://github.com/realm/RChat/tree/v2-schema)

If you're looking to upgrade the Realm schema for an iOS app that **isn't** using Realm Sync, then refer to the [previous post in this series](https://www.mongodb.com/developer/how-to/realm-schema-migration).

If you have any questions or comments on this post (or anything else Realm-related), then please raise them on our [community forum](https://www.mongodb.com/community/forums/c/realm-sdks/58). To keep up with the latest Realm news, follow [@realm](https://twitter.com/realm) on Twitter and join the [Realm global community](https://live.mongodb.com/realm-global-community/).


When you add features to your app, you may need to modify your Realm schema. Here, we step through how to migrate your synced schema and data.

Migrating Your iOS App's Synced Realm Schema in Production

Learn how to make your mobile app always-on, even when you can't connect to your API.

Build Offline-First Mobile Apps by Caching API Results in Realm

See how to use some of the most useful new iOS 15 SwiftUI features in your mobile apps

Most Useful iOS 15 SwiftUI Features

[Realm](https://realm.io/) is an open-source, easy-to-use local database that helps mobile developers to build better apps, faster. It offers a data synchronization service—MongoDB Realm Sync—that makes it simple to move data between the client and MongoDB Atlas on the back end. Using Realm can save you from writing thousands of lines of code, and offers an intuitive way to work with your data.

The Ionic team posted a fantastic article on how you can [use Ionic with Realm to build a React Web app](https://ionicframework.com/blog/ionic-react-and-realm/) quickly, taking advantage of Realm to easily persist your data in a MongoDB Atlas Database.

After [cloning the repo](https://github.com/mhartington/ionic-realm-demo) and running `ionic serve`, you'll have a really simple task management web application. You can register (using any user/password combination, Realm takes care of your onboarding needs). You can log in, have a look at your tasks, and add new tasks.

|   Login in the Web App      |   Browsing Tasks   | 
|--------------|-----------|
| ![Login window asking for user and password running in a browser. There’s a Login and Register button.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_login_web_44095db30a.png)|  ![Tasks already entered in the app, one for “Do the dishes”, another for “Finish post about Ionic / Realm” and last one “Install Ionic app running Realm in iOS”](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_tasks_web_98bd9784b2.png)      | 


Let’s build on what the Ionic team created for the web, and expand it by building a mobile app for iOS and Android using one of the best features Ionic has: the _“Write Once, Run Anywhere”_ approach to coding. I’ll start with an iOS app.


## Prerequisites

To follow along this post, you’ll need five things:

* A macOS-powered computer running Xcode (to develop for iOS). I’m using Xcode 13 Beta. You don’t have to risk your sanity.
* Ionic installed. You can follow the instructions [here](https://ionicframework.com/docs/intro/cli), but TL;DR it’s `npm install -g @ionic/cli`
* Clone the [repo with the Ionic React Web App](https://docs.mongodb.com/realm/tutorial/realm-app/) that we’ll turn into mobile.
* As we need an Atlas Database to store our data in the cloud, and a Realm app to make it easy to work with Atlas from mobile, set up a Free Forever MongoDB cluster and [create and import a Realm app schema](https://docs.mongodb.com/realm/tutorial/realm-app/) so everything is ready server-side.
* Once you have your Realm app created, copy the Realm app ID from the MongoDB admin interface for Realm, and paste it into `src/App.tsx`, in the line:

`export const APP_ID = '<Put your Realm App Id here>';`

Once your `APP_ID` is set, run:

```
$ npm run build
```


## The iOS app

To add iOS capabilities to our existing app, we need to open a terminal and run:

```bash
$ ionic cap add ios
``` 

This will create the iOS Xcode Project native developers know and love, with the code from our Ionic app. I ran into a problem doing that and it was that the version of Capacitor used in the repo was 3.1.2, but for iOS, I needed at least 3.2.0. So, I just changed `package.json` and ran `npm install` to update Capacitor.

`package.json` fragment:

```
...
"dependencies": {

    "@apollo/client": "^3.4.5",
    "@capacitor/android": "3.2.2",
    "@capacitor/app": "1.0.2",
    "@capacitor/core": "3.2.0",
    "@capacitor/haptics": "1.0.2",
    "@capacitor/ios": "3.2.2",
...
```

Now we have a new `ios` directory. If we enter that folder, we’ll see an `App` directory that has a CocoaPods-powered iOS app. To run this iOS app, we need to:



* Change to that directory with `cd ios`. You’ll find an `App` directory. `cd App`
* Install all CocoaPods with `pod repo update && pod install`, as usual in a native iOS project. This updates all libraries’ caches for CocoaPods and then installs the required libraries and dependencies in your project.
* Open the generated `App.xcworkspace` file with Xcode. From Terminal, you can just type `open App.xcworkspace`.
* Run the app from Xcode.

|   Login in the iOS App      |   Browsing Tasks   | 
|--------------|-----------|
|![Login screen in iOS asking for user and password running in a browser. There’s a Login and Register button.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_login_ios_21fa1f7446.png)|  ![Tasks already entered in the iOS app, one for “Do the dishes”, another for “Finish post about Ionic / Realm” and last one “Install Ionic app running Realm in iOS”](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_tasks_ios_04d29ff898.png)  |



That’s it. Apart from updating Capacitor, we only needed to run one command to get our Ionic web project running on iOS!


## The Android App

How hard can it be to build our Ionic app for Android now that we have done it for iOS? Well, it turns out to be super-simple. Just `cd` back to the root of the project and type in a terminal:

```
 ionic cap android
```

This will create the Android project. Once has finished, launch your app using:

```
ionic capacitor run android -l --host=10.0.1.81
```

In this case, `10.0.1.81` is my own IP address. As you can see, if you have more than one Emulator or even a plugged-in Android phone, you can select where you want to run the Ionic app.

![before running the Android App we can choose the Emulator where it will run.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_terminal_f3e08bace5.png)

Once running, you can register, log in, and add tasks in Android, just like you can do in the web and iOS apps.


|  Adding a task in Android      |   Browsing Tasks in Android   | 
|--------------|-----------|
|![Adding a new task screen from Android, with “New Task from Android” typed in.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_android_add_7040b32898.png)|![Tasks already entered in the Android app, one for “Do the dishes”, another for “Finish post about Ionic / Realm”, “Install Ionic app running Realm in iOS” and “New Task from Android”](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_android_tasks_7ee2c9c1bc.png)|

The best part is that thanks to the synchronization happening in the MongoDB Realm app, every time we add a new task locally, it gets uploaded to the cloud to a MongoDB Atlas database behind the scenes. And **all other apps accessing the same MongoDB Realm app can show that data**! 


![thanks to Ionic and Realm, Web, iOS and Android access the same data using the same code base.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_three_apps_1a7dbfbd05.png)


## Automatically refreshing tasks

[Realm SDKs](https://docs.mongodb.com/realm/sdk/) are well known for their syncing capabilities. You change something in the server, or in one app, and other users with access to the same data will see the changes almost immediately. You don’t have to worry about invalidating caches, writing complex networking/multithreading code that runs in the background, listening to silent push notifications, etc. MongoDB Realm takes care of all that for you.

But in this example, we access data using the [Apollo GraphQL Client](https://docs.mongodb.com/realm/web/graphql-apollo-react/) for React. Using this client, we can log into our Realm app and run GraphQL Queries—although as designed for the web, we don’t have access to the hard drive to store a .realm file. It’s just a simpler way to use the otherwise awesome [Apollo GraphQL Client](https://www.apollographql.com/docs/react/) with Realm, so we don’t have synchronization implemented. But luckily, Apollo GraphQL queries can automatically refresh themselves just passing a `pollInterval` argument. I told you it was awesome. You set the time interval in milliseconds to refresh the data.

So, in `useTasks.ts`, our function to get all tasks will look like this, auto-refreshing our data every half second.

```typescript
function useAllTasksInProject(project: any) {
 const { data, loading, error } = useQuery(
   gql`
     query GetAllTasksForProject($partition: String!) {
       tasks(query: { _partition: $partition }) {
         _id
         name
         status
       }
     }
   `,
   { variables: { partition: project.partition }, pollInterval: 500 }
 );
 if (error) {
   throw new Error(`Failed to fetch tasks: ${error.message}`);
 }

 // If the query has finished, return the tasks from the result data
 // Otherwise, return an empty list
 const tasks = data?.tasks ?? [];
 return { tasks, loading };
}
```

![Now we can sync our actions. Adding a task in the Android Emulator gets propagated to the iOS and Web versions](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_sync_add_task_cd8ec70ccc.gif)

## Pull to refresh

Adding automatic refresh is nice, but in mobile apps, we’re used to also refreshing lists of data just by pulling them. To get this, we’ll need to add the Ionic component `IonRefresher` to our Home component:

```html
<IonPage>
     <IonHeader>
       <IonToolbar>
         <IonTitle>Tasks</IonTitle>
         <IonButtons slot="end">
           <IonButton onClick={addNewTask}>
             <IonIcon slot="icon-only" icon={add}></IonIcon>
           </IonButton>
         </IonButtons>
       </IonToolbar>
     </IonHeader>
     <IonContent fullscreen>
       <IonRefresher slot="fixed" onIonRefresh={doRefresh}>
         <IonRefresherContent></IonRefresherContent>
       </IonRefresher>
       <IonHeader collapse="condense">
         <IonToolbar>
           <IonTitle size="large">Tasks</IonTitle>
         </IonToolbar>
       </IonHeader>
       <IonList>
         {loading ? <IonLoading isOpen={loading} /> : null}
         {tasks.map((task: any) => (
           <TaskItem key={parseInt(task._id)} {...task}></TaskItem>
         ))}
       </IonList>
     </IonContent>
   </IonPage>
```

As we can see, an `IonRefresher` component will add the pull-to-refresh functionality with an included loading indicator tailored for each platform.


```html
<IonRefresher slot="fixed" onIonRefresh={doRefresh}>
   <IonRefresherContent></IonRefresherContent>
</IonRefresher>
```

To refresh, we call `doRefresh` and there, we just reload the whole page.

```typescript
 const doRefresh = (event: CustomEvent<RefresherEventDetail>) => {
   window.location.reload(); // reload the whole page
   event.detail.complete();  // we signal the loading indicator to hide
 };
```


## Deleting tasks

Right now, we can swipe tasks from right to left to change the status of our tasks. But I wanted to also add a left to right swipe so we can delete tasks. We just need to add the swiping control to the already existing `IonItemSliding` control. In this case, we want a swipe from the _start_ of the control. This way, we avoid any ambiguities with right-to-left vs. left-to-right languages. When the user taps on the new “Delete” button (which will appear red as we’re using the _danger_ color), `deleteTaskSelected` is called.

```html
<IonItemSliding ref={slidingRef} className={'status-' + task.status}>
     <IonItem>
       <IonLabel>{task.name}</IonLabel>
     </IonItem>
     <IonItemOptions side="end">
       <IonItemOption onClick={toggleStatus}>Status</IonItemOption>
     </IonItemOptions>
     <IonItemOptions side="start">
       <IonItemOption onClick={deleteTaskSelected} color="danger">Delete</IonItemOption>
     </IonItemOptions>
   </IonItemSliding>
```

To delete the task, we use a GraphQL mutation defined in `useTaskMutations.ts`:

```typescript
const deleteTaskSelected = () => {
   slidingRef.current?.close();  // close sliding menu
   deleteTask(task);             // delete task
 };
```



![Deleting can be done with a Swipe. Here we show how it's been done in the Android Emulator and changes appear in the iOS Simulator and Web page](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/ionic_native_delete_184d02206d.gif)

## Recap

In this post, we’ve seen how easy it is to start with an Ionic React web application and, with only a few lines of code, turn it into a mobile app running on iOS and Android. Then, we easily added some functionality to the three apps at the same time. Ionic makes it super simple to run your Realm-powered apps everywhere!

You can check out the code from this post [in this branch](https://github.com/mongodb-developer/ionic-realm-demo/tree/observe-changes) of the [repo](https://github.com/mongodb-developer/ionic-realm-demo), just by typing:

```
$ git clone https://github.com/mongodb-developer/ionic-realm-demo
$ git checkout observe-changes
```

But this is not the only way to integrate Realm in your Ionic apps. Using Capacitor and our native SDKs, we’ll show you how to use Realm from Ionic in a future follow-up post. 




We can convert a existing Ionic React Web App that saves data in MongoDB Realm using Apollo GraphQL into an iOS and Android app using a couple commands, and the three apps will share the same MongoDB Realm backend. Also, we can easily add functionality to all three apps, just modifying one code base.


Let’s Give Your Realm-Powered Ionic Web App the Native Treatment on iOS and Android!

Eric Mossman

## Introduction

[Realm Swift v10.12.0](https://github.com/realm/realm-cocoa/releases) introduced the ability to filter change notifications for desired key paths. This level of granularity has been something we've had our eye on, so it’s really satisfying to release this kind of control and performance benefit. Here’s a quick rundown on what’s changed and why it matters.

## Notifications Before

By default, notifications return changes for all insertions, modifications, and deletions. Suppose that I have a schema that looks like the one below.

![Graph showing that all sub-components of the object are selected](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/keypath1_4619609829.png)

If I observe a `Results<Company>` object and the name of one of the companies in the results changes, the notification block would fire and my UI would update: 

```swift
let results = realm.objects(Company.self)
let notificationToken = results.observe() { changes in
    // update UI
}
```

That’s quite straightforward for non-collection properties. But what about other types, like lists?

Naturally, the block I passed into .`observe` will execute each time an `Order` is added or removed. But the block also executes each time a property on the `Order` list is edited. The same goes for _those_ properties’ collections too (and so on!). Even though I’m observing “just” a collection of `Company` objects, I’ll receive change notifications for properties on a half-dozen other collections.

This isn’t necessarily an issue for most cases. Small object graphs, or “siloed” objects, that don’t feature many relationships might not experience unneeded notifications at all. But for complex webs of objects, where several layers of children objects exist, an app developer may benefit from a **major performance enhancement and added control from KeyPath filtering**.

## KeyPath Filtering

Now `.observe` comes with an optional `keyPaths` parameter:

```swift
public func observe<T: RLMObjectBase>(keyPaths: [String]? = nil,
                                      on queue: DispatchQueue? = nil,
                                      _ block: @escaping (ObjectChange<T>) -> Void) -> NotificationToken
```

The `.observe `function will only notify on the field or fields specified in the `keyPaths` parameter. Other fields are ignored unless explicitly passed into the parameter.

This allows the app developer to tailor which relationship paths are observed. This reduces computing cost and grants finer control over when the notification fires.

Our modified code might look like this:

```swift
let results = realm.objects(Company.self)
let notificationToken = results.observe(keyPaths: ["orders.status"]) { changes in
	// update UI
}
```

`.observe `can alternatively take a `PartialKeyPath`:

```swift
let results = realm.objects(Company.self)
let notificationToken = results.observe(keyPaths: [\Company.orders.status]) { changes in
	// update UI
}
```

If we applied the above snippets to our previous example, we’d only receive notifications for this portion of the schema:

![Graph showing that just a single path through the Objects components is selected](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/keypath2_a799e8e8ca.png)

The notification process is no longer traversing an entire tree of relationships each time a modification is made. Within a complex tree of related objects, the change-notification checker will now traverse only the relevant paths. This saves huge amounts of work. 

In a large database, this can be a serious performance boost! The end-user can spend less time with a spinner and more time using your application.

## Conclusion

- `.observe` has a new optional `keyPaths` parameter. 
- The app developer has more granular control over when notifications are fired.
- This can greatly improve notification performance for large databases and complex object graphs.

Please provide feedback and ask any questions in the [Realm Community Forum](https://www.mongodb.com/community/forums/c/realm-sdks/58).


How to customize your notifications when your iOS app is observing Realm

Filter Realm Notifications in Your iOS App with KeyPaths

How to incorporate Realm into your iOS App. Building a chat app with SwiftUI and Realm-Cocoa – the new and easier way to work with Realm and SwiftUI

Building a Mobile Chat App Using Realm – The New and Easier Way

How to incorporate Realm into your iOS App. Building a chat app with SwiftUI and Realm-Cocoa

Building a Mobile Chat App Using Realm – Integrating Realm into Your App



<div class="introduction">

Porting an app that's using Core Data to Realm is very simple. If you
have an app that already uses Core Data, and have been considering the
move to Realm, this step-by-step guide is for you! The way that your
code interacts with Core Data and Realm is very different depending on
whether your app is based on SwiftUI or UIKit—this guide assumes SwiftUI
(a UIKit version will come soon.)

You're far from the first developer to port your app from Core Data to
Realm, and we've been told many times that it can be done in a matter of
hours. Both databases handle your data as objects, so migration is
usually very straightforward: Simply take your existing Core Data code
and refactor it to use the [Realm
SDK](https://docs.mongodb.com/realm/sdk/ios/).

After migrating, you should be thrilled with the ease of use, speed, and
stability that Realm can bring to your apps. Add in [MongoDB Realm
Sync](https://docs.mongodb.com/realm/sync/) and you can share the same
data between iOS, Android, desktop, and web apps.

>
>
>This article was updated in July 2021 to replace `objc` and `dynamic`
>with the `@Persisted` annotation that was introduced in Realm-Cocoa
>10.10.0.
>
>

<div class="prerequisites">

</div>

## Prerequisites

This guide assumes that your app is written in Swift and built on
SwiftUI rather than UIKit.

<div class="content">

</div>

## Steps to Migrate Your Code

### 1. Add the Realm Swift SDK to Your Project

To use Realm, you need to include [Realm's Swift SDK
(Realm-Cocoa)](https://docs.mongodb.com/realm/sdk/ios/) in your Xcode
project. The simplest method is to use the Swift Package Manager.

In Xcode, select "File/Swift Packages/Add Package Dependency...". The
package URL is <https://github.com/realm/realm-cocoa>:

<figure>
<img src="https://www.mongodb.com/developer/images/how-to/realm-core-data-migration/Realm-Cocoa-Package.png" class="align-center" />
</figure>

You can keep the default options and then select both the "Realm" and
"RealmSwift" packages.

### 2a. The Brutalist Approach—Remove the Core Data Framework

First things first. If your app is currently using Core Data, you'll
need to work out which parts of your codebase include Core Data code.
These will need to be refactored. Fortunately, there's a handy way to do
this. While you could manually perform searches on the codebase looking
for the relevant code, a much easier solution is to simply delete the
Core Data import statements at the top of your source files:

``` swift
import CoreData
```

Once this is done, every line of code implementing Core Data will throw
a compiler error, and then it's simply a matter of addressing each
compiler error, one at a time.

### 2b. The Incremental Approach—Leave the Core Data Framework Until Port Complete

Not everyone (including me) likes the idea of not being able to build a
project until every part of the port has been completed. If that's you,
I'd suggest this approach:

-   Leave the old code there for now.
-   Add a new model, adding `Realm` to the end of each class.
-   Work through your views to move them over to your new model.
-   Check and fix build breaks.
-   Remove the `Realm` from your model names using the Xcode refactoring
    feature.
-   Check and fix build breaks.
-   Find any files that still `import CoreData` and either remove that
    line or the entire file if it's now obsolete.
-   Check and fix build breaks.
-   Migrate existing user data from Core Data to Realm if needed.
-   Remove the original model code.

### 3. Remove Core Data Setup Code

In Core Data, changes to model objects are made against a managed object
context object. Managed object context objects are created against a
persistent store coordinator object, which themselves are created
against a managed object model object.

Suffice to say, before you can even begin to think about writing or
reading data with Core Data, you usually need to have code somewhere in
your app to set up these dependency objects and to expose Core Data's
functionality to your app's own logic. There will be a sizable chunk of
"setup" Core Data code lurking somewhere.

When you're switching to Realm, all of that code can go.

In Realm, all of the setting up is done on your behalf when you access a
Realm object for the first time, and while there are options to
configure it—such as where to place your Realm data file on disk—it's
all completely optional.

### 4. Migrate Your Model Files

Your Realm schema will be defined in code by defining your Realm Object
classes. There is no need for `.xcdatamodel` files when working with
Realm and so you can remove those Core Data files from your project.

In Core Data, the bread-and-butter class that causes subclassed model
objects to be persisted is `NSManagedObject`. The classes for these
kinds of objects are pretty much standard:

``` swift
import CoreData

@objc(ReminderList)
public class ReminderList: NSManagedObject {
   @NSManaged public var title: String
   @NSManaged public var reminders: Array<Reminder>
}

@objc(Reminder)
public class Reminder: NSManagedObject {
   @NSManaged var title: String
   @NSManaged var isCompleted: Bool
   @NSManaged var notes: String?
   @NSManaged var dueDate: Date?
   @NSManaged var priority: Int16
   @NSManaged var list: ReminderList
}
```

Converting these managed object subclasses to Realm is really simple:

``` swift
import RealmSwift

class ReminderList: Object, ObjectKeyIdentifiable {
   @Persisted var title: String
   @Persisted var reminders: List<Reminder>
}

class Reminder: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var title: String
   @Persisted var isCompleted: Bool
   @Persisted var notes: String?
   @Persisted var dueDate: Date?
   @Persisted var priority: Int16
}
```

Note that top-level objects inherit from `Object`, but objects that only
exist within higher-level objects inherit from `EmbeddedObject`.

### 5. Migrate Your Write Operations

Creating a new object in Core Data and then later modifying it is
relatively trivial, only taking a few lines of code.

Adding an object to Core Data must be done using a
`NSManagedObjectContext`. This context is available inside a SwiftUI
view through the environment:

``` swift
@Environment(\.managedObjectContext) var viewContext: NSManagedObjectContext
```

That context can then be used to save the object to Core Data:

``` swift
let reminder = Reminder(context: viewContext)
reminder.title = title
reminder.notes = notes
reminder.dueDate = date
reminder.priority = priority

do {
   try viewContext.save()
} catch {
   let nserror = error as NSError
   fatalError("Unresolved error \(nserror), \(nserror.userInfo)")
}
```

Realm requires that writes are made within a transaction, but the Realm
Swift SDK hides most of that complexity when you develop with SwiftUI.
The current Realm is made available through the SwiftUI environment and
the view can access objects in it using the `@ObserveredResults`
property wrapper:

``` swift
@ObservedResults(Reminder.self) var reminders
```

A new object can then be stored in the Realm:

``` swift
let reminder = Reminder()
reminder.title = title
reminder.notes = notes
reminder.dueDate = date
reminder.priority = priority
$reminders.append(reminder)
```

The Realm Swift SDK also hides the transactional complexity behind
making updates to objects already stored in Realm. The
`@ObservedRealmObject` property wrapper is used in the same way as
`@ObservedObject`—but for Realm managed objects:

``` swift
@ObservedRealmObject var reminder: Reminder
TextField("Notes", text: $reminder.notes)
```

To benefit from the transparent transaction functionality, make sure
that you use the `@ObservedRealmObject` property wrapper as you pass
Realm objects down the view hierarchy.

If you find that you need to directly update an attribute within a Realm
object within a view, then you can use this syntax to avoid having to
explicitly work with Realm transactions (where `reminder` is an
`@ObservedRealmObject`):

``` swift
$reminder.isCompleted.wrappedValue.toggle()
```

### 6. Migrate Your Queries

In its most basic implementation, Core Data uses the concept of fetch
requests in order to retrieve data from disk. A fetch can filter and
sort the objects:

``` swift
var reminders = FetchRequest(
   entity: Reminder.entity(),
   sortDescriptors: NSSortDescriptor(key: "title", ascending: true),
   predicate: NSPredicate(format: "%K == %@", "list.title", title)).wrappedValue
```

The equivalent code for such a query using Realm is very similar, but it
uses the `@ObservedResults` property wrapper rather than `FetchRequest`:

``` swift
@ObservedResults(
   Reminder.self,
   filter: NSPredicate(format: "%K == %@", "list.title", title),
   sortDescriptor: SortDescriptor(keyPath: "title", ascending: true)) var reminders
```

### 7. Migrate Your Users' Production Data

Once all of your code has been migrated to Realm, there's one more
outstanding issue: How do you migrate any production data that users may
already have on their devices out of Core Data and into Realm?

This can be a very complex issue. Depending on your app's functionality,
as well as your users' circumstances, how you go about handling this can
end up being very different each time.

We've seen two major approaches:

-   Once you've migrated your code to Realm, you can re-link the Core
    Data framework back into your app, use raw NSManagedObject objects
    to fetch your users' data from Core Data, and then manually pass it
    over to Realm. You can leave this migration code in your app
    permanently, or simply remove it after a sufficient period of time
    has passed.
-   If the user's data is replaceable—for example, if it is simply
    cached information that could be regenerated by other user data on
    disk—then it may be easier to simply blow all of the Core Data save
    files away, and start from scratch when the user next opens the app.
    This needs to be done with very careful consideration, or else it
    could end up being a bad user experience for a lot of people.

## SwiftUI Previews

As with Core Data, your SwiftUI previews can add some data to Realm so
that it's rendered in the preview. However, with Realm it's a lot easier
as you don't need to mess with contexts and view contexts:

``` swift
func bootstrapReminder() {
   do {
      let realm = try Realm()
      try realm.write {
         realm.deleteAll()
         let reminder = Reminder()
         reminder.title = "Do something"
         reminder.notes = "Anything will do"
         reminder.dueDate = Date()
         reminder.priority = 1
         realm.add(list)
      }
   } catch {
      print("Failed to bootstrap the default realm")
   }
}

struct ReminderListView_Previews: PreviewProvider {
   static var previews: some View {
      bootstrapReminder()
      return ReminderListView()
   }
}
```

## Syncing Realm Data

Now that your application data is stored in Realm, you have the option
to sync that data to other devices (including Android) using [MongoDB
Realm Sync](https://docs.mongodb.com/realm/sync/). That same data is
then stored in Atlas where it can be queried by web applications via
[GraphQL](https://docs.mongodb.com/realm/graphql/) or [Realm's web
SDK](https://docs.mongodb.com/realm/web/).

This enhanced functionality is beyond the scope of this guide, but you
can see how it can be added by reading the
[Building a Mobile Chat App Using Realm – Integrating Realm into Your App](/how-to/building-a-mobile-chat-app-using-realm) series.

</div>

<div class="summary">

## Conclusion

Thanks to their similarities in exposing data through model objects,
converting an app from using Core Data to Realm is very quick and
simple.

In this guide, we've focussed on the code that needs to be changed to
work with Realm, but you'll be pleasantly surprised at just how much
Core Data boilerplate code you're able to simply delete!

If you've been having trouble getting Core Data working in your app, or
you're looking for a way to sync data between platforms, we strongly
recommend giving Realm a try, to see if it works for you. And if it
does, please be sure to let us know!

If you've any questions or comments, then please let us know on our
[community
forum](https://developer.mongodb.com/community/forums/c/realm-sdks/58).

>
>
>If you have questions, please head to our [developer community
>website](https://community.mongodb.com/) where the MongoDB engineers and
>the MongoDB community will help you build your next big idea with
>MongoDB.
>
>

</div>


A guide to porting a SwiftUI iOS app from Core Data to MongoDB.

Migrating a SwiftUI iOS App from Core Data to Realm

Build your first iOS mobile app using Realm, SwiftUI, and Combine.

Build Your First iOS Mobile App Using Realm, SwiftUI, & Combine

Building a Mobile Chat App Using Realm – Data Architecture.

Building a Mobile Chat App Using Realm – Data Architecture

Apple published a great [tutorial](https://developer.apple.com/tutorials/app-dev-training) to teach developers how to create iOS apps using SwiftUI. I particularly like it because it doesn't make any assumptions about existing UIKit experience, making it ideal for developers new to iOS. That tutorial is built around an app named "Scrumdinger," which is designed to facilitate daily [scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) meetings.

Apple's Scrumdinger implementation saves the app data to a local file whenever the user minimizes the app, and loads it again when they open the app. It seemed an interesting exercise to modify Scrumdinger to use Realm rather than a flat file to persist the data. This article steps through what changes were required to rebase Scrumdinger onto Realm.

An immediate benefit of the move is that changes are now persisted immediately, so nothing is lost if the device or app crashes. It's beyond the scope of this article, but now that the app data is stored in Realm, it would be straightforward to add enhancements such as:

-   [Search](https://docs.mongodb.com/realm/sdk/ios/examples/filter-data/) meeting minutes for a string.
-   [Filter](https://docs.mongodb.com/realm/sdk/ios/examples/filter-data/) minutes by date or attendees.
-   [Sync data](https://docs.mongodb.com/realm/sync/) so that the same user can see all of their data on multiple iOS (and optionally, Android) devices.
-   Use [Realm Sync Partitions](https://docs.mongodb.com/realm/sync/partitioning/) to share scrum data between team members.
-   Sync the data to [MongoDB Atlas](https://docs.atlas.mongodb.com/) so that it can be accessed by web apps or through a [GraphQL API](https://docs.mongodb.com/realm/graphql/)

>
>
>This article was updated in July 2021 to replace `objc` and `dynamic` with the `@Persisted` annotation that was introduced in Realm-Cocoa 10.10.0.
>
>

## Prerequisites

-   Mac (sorry Windows and Linux users).
-   Xcode 12.4+.

I strongly recommend that you at least scan [Apple's tutorial](https://developer.apple.com/tutorials/app-dev-training). I don't explain any of the existing app structure or code in this article.

## Adding Realm to the Scrumdinger App

First of all, a couple of notes about the [GitHub repo for this project](https://github.com/realm/Scrumdinger):

-   The [main branch](https://github.com/realm/Scrumdinger) is the app as it appears in Apple's tutorial. This is the starting point for this article.
-   The [realm branch](https://github.com/realm/Scrumdinger/tree/realm) contains a modified version of the Scrumdinger app that persists the application data in Realm. This is the finishing point for this article.
-   You can view the [diff between the main and realm branches](https://github.com/realm/Scrumdinger/compare/realm) to see the changes needed to make the app run on Realm.

### Install and Run the Original Scrumdinger App

``` bash
git clone https://github.com/realm/Scrumdinger.git
cd Scrumdinger
open Scrumdinger.xcodeproj
```

From Xcode, select a simulator:

<figure align="center">
    <img
        style="border-radius: 10px; width: 80%"
        src="https://www.mongodb.com/developer/images/how-to/realm-scrumdinger/select-ios-simulator.png"
        alt="Select an iOS simulator in Xcode."
    />
    <figcaption style="color: rgb(184, 196, 194); font-size: 12px; line-height: 18px; margin-bottom: 30px">Select an iOS simulator in Xcode.</figcaption>
</figure>


Build and run the app with `⌘r`:

<figure align="center">
    <img
        style="border-radius: 10px; width: 40%"
        src="https://www.mongodb.com/developer/images/how-to/realm-scrumdinger/scrumdinger-screenshot.png"
        alt="Scrumdinger screen capture"
    />
    <figcaption style="color: rgb(184, 196, 194); font-size: 12px; line-height: 18px; margin-bottom: 30px">Scrumdinger screen capture</figcaption>
</figure>

Create a new daily scrum. Force close and restart the app with `⌘r`.  Note that your new scrum has been lost 😢. Don't worry, that's automatically fixed once we've migrated to Realm.

### Add the Realm SDK to the Project

To use Realm, we need to add the [Realm-Cocoa SDK](https://github.com/realm/realm-cocoa) to the Scrumdinger Xcode project using the Swift Package Manager. Select the "Scrumdinger" project and the "Swift Packages" tab, and then click the "+" button:

<figure align="center">
    <img
        style="border-radius: 10px"
        src="https://www.mongodb.com/developer/images/how-to/realm-scrumdinger/swift-package-manager.png"
        alt="Swift package manager configuration"
    />
</figure>

Paste in `https://github.com/realm/realm-cocoa` as the package repository URL:

<figure align="center">
    <img
        style="border-radius: 10px"
        src="https://www.mongodb.com/developer/images/how-to/realm-scrumdinger/realm-cocoa-package.png"
        alt="Choose package options for Realm-Cocoa"
    />
</figure>

Add the `RealmSwift` package to the `Scrumdinger` target:

<figure align="center">
    <img
        style="border-radius: 10px"
        src="https://www.mongodb.com/developer/images/how-to/realm-scrumdinger/scrumdinger-target.png"
        alt="Scrumdinger target configuration"
    />
</figure>

We can then start using the Realm SDK with `import RealmSwift`.

### Update Model Classes to be Realm Objects

To store an object in Realm, its class must inherit from Realm's `Object` class. If the class contains sub-classes, those classes must conform to Realm's `EmbeddedObject` protocol.

#### Color

As with the original app's flat file, Realm can't natively persist the SwiftUI `Color` class, and so colors need to be stored as components. To that end, we need a `Components` class. It conforms to `EmbeddedObject` so that it can be embedded in a higher-level Realm `Object` class.  Fields are flagged with the `@Persisted` annotation to indicate that they should be persisted in Realm:

``` swift
import RealmSwift

class Components: EmbeddedObject {
   @Persisted var red: Double = 0
   @Persisted var green: Double = 0
   @Persisted var blue: Double = 0
   @Persisted var alpha: Double = 0

   convenience init(red: Double, green: Double, blue: Double, alpha: Double) {
      self.init()
      self.red = red
      self.green = green
      self.blue = blue
      self.alpha = alpha
   }
}
```

#### DailyScrum

`DailyScrum` is converted from a `struct` to an `Object` `class` so that it can be persisted in Realm. By conforming to `ObjectKeyIdentifiable`, lists of `DailyScrum` objects can be used within SwiftUI `ForEach` views, with Realm managing the `id` identifier for each instance.

We use the Realm `List` class to store arrays.

``` swift
import RealmSwift

class DailyScrum: Object, ObjectKeyIdentifiable {
   @Persisted var title = ""
   @Persisted var attendeeList = RealmSwift.List<String>()
   @Persisted var lengthInMinutes = 0
   @Persisted var colorComponents: Components?
   @Persisted var historyList = RealmSwift.List<History>()

   var color: Color { Color(colorComponents ?? Components()) }
   var attendees: [String] { Array(attendeeList) }
   var history: [History] { Array(historyList) }

   convenience init(title: String, attendees: [String], lengthInMinutes: Int, color: Color, history: [History] = []) {
      self.init()
      self.title = title
      attendeeList.append(objectsIn: attendees)
      self.lengthInMinutes = lengthInMinutes
      self.colorComponents = color.components
      for entry in history {
            self.historyList.insert(entry, at: 0)
      }
   }
}

extension DailyScrum {
   struct Data {
      var title: String = ""
      var attendees: [String] = []
      var lengthInMinutes: Double = 5.0
      var color: Color = .random
   }

   var data: Data {
      return Data(title: title, attendees: attendees, lengthInMinutes: Double(lengthInMinutes), color: color)
   }

   func update(from data: Data) {
      title = data.title
      for attendee in data.attendees {
            if !attendees.contains(attendee) {
               self.attendeeList.append(attendee)
            }
      }
      lengthInMinutes = Int(data.lengthInMinutes)
      colorComponents = data.color.components
   }
}
```

#### History

The `History` struct is replaced with a Realm `Object` class:

``` swift
import RealmSwift

class History: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var date: Date?
   @Persisted var attendeeList = List<String>()
   @Persisted var lengthInMinutes: Int = 0
   @Persisted var transcript: String?
   var attendees: [String] { Array(attendeeList) }

   convenience init(date: Date = Date(), attendees: [String], lengthInMinutes: Int, transcript: String? = nil) {
      self.init()
      self.date = date
      attendeeList.append(objectsIn: attendees)
      self.lengthInMinutes = lengthInMinutes
      self.transcript = transcript
   }
}
```

#### ScrumData

The `ScrumData` `ObservableObject` class was used to manage the copying of scrum data between the in-memory copy and a local iOS file (including serialization and deserialization). This is now handled automatically by Realm, and so this class can be deleted.

Nothing feels better than deleting boiler-plate code!

### Top-Level SwiftUI App

Once the data is being stored in Realm, there's no need for lifecycle code to load data when the app starts or save it when it's minimized, and so `ScrumdingerApp` becomes a simple wrapper for the top-level view (`ScrumsView`):

``` swift
import SwiftUI

@main
struct ScrumdingerApp: App {
   var body: some Scene {
      WindowGroup {
            NavigationView {
               ScrumsView()
            }
      }
   }
}
```

### SwiftUI Views

#### ScrumsView

The move from a file to Realm simplifies the top-level view.

``` swift
import RealmSwift

struct ScrumsView: View {
   @ObservedResults(DailyScrum.self) var scrums
   @State private var isPresented = false
   @State private var newScrumData = DailyScrum.Data()
   @State private var currentScrum = DailyScrum()

   var body: some View {
      List {
            if let scrums = scrums {
               ForEach(scrums) { scrum in
                  NavigationLink(destination: DetailView(scrum: scrum)) {
                        CardView(scrum: scrum)
                  }
                  .listRowBackground(scrum.color)
               }
            }
      }
      .navigationTitle("Daily Scrums")
      .navigationBarItems(trailing: Button(action: {
            isPresented = true
      }) {
            Image(systemName: "plus")
      })
      .sheet(isPresented: $isPresented) {
            NavigationView {
               EditView(scrumData: $newScrumData)
                  .navigationBarItems(leading: Button("Dismiss") {
                        isPresented = false
                  }, trailing: Button("Add") {
                        let newScrum = DailyScrum(
                           title: newScrumData.title,
                           attendees: newScrumData.attendees,
                           lengthInMinutes: Int(newScrumData.lengthInMinutes),
                           color: newScrumData.color)
                        $scrums.append(newScrum)
                        isPresented = false
                  })
            }
      }
   }
}
```

The `DailyScrum` objects are automatically loaded from the default Realm using the `@ObservedResults` annotation.

New scrums can be added to Realm by appending them to the `scrums` result set with `$scrums.append(newScrum)`. Note that there's no need to open a Realm transaction explicitly. That's now handled under the covers by the Realm SDK.

### DetailView

The main change to `DetailView` is that any edits to a scrum are persisted immediately. At the time of writing ([Realm-Cocoa 10.7.2](https://github.com/realm/realm-cocoa/releases)), the view must open a transaction to store the change:

``` swift
do {
   try Realm().write() {
      guard let thawedScrum = scrum.thaw() else {
            print("Unable to thaw scrum")
            return
      }
      thawedScrum.update(from: data)
   }
} catch {
   print("Failed to save scrum: \(error.localizedDescription)")
}
```

### MeetingView

As with `DetailView`, `MeetingView` is enhanced so that meeting notes are added as soon as they've been created (rather than being stored in volatile RAM until the app is minimized):

``` swift
do {
   try Realm().write() {
      guard let thawedScrum = scrum.thaw() else {
            print("Unable to thaw scrum")
            return
      }
      thawedScrum.historyList.insert(newHistory, at: 0)
   }
} catch {
   print("Failed to add meeting to scrum: \(error.localizedDescription)")
}
```

### CardView (+ Other Views)

There are no changes needed to the view that's responsible for displaying a summary for a scrum. The changes we made to the `DailyScrum` model in order to store it in Realm don't impact how it's used within the app.

<figure align="center">
    <img
        style="border-radius: 10px; width: 50%"
        src="https://www.mongodb.com/developer/images/how-to/realm-scrumdinger/cardview.png"
        alt="Cardview"
    />
    <figcaption style="color: rgb(184, 196, 194); font-size: 12px; line-height: 18px; margin-bottom: 30px">Cardview</figcaption>
</figure>

Similarly, there are no significant changes needed to `EditView`, `HistoryView`, `MeetingTimerView`, `MeetingHeaderView`, or `MeetingFooterView`.

## Summary

I hope that this post has shown that moving an iOS app to Realm is a straightforward process. The Realm SDK abstracts away the complexity of serialization and persisting data to disk. This is especially true when developing with SwiftUI.

Now that Scrumdinger uses Realm, very little extra work is needed to add new features based on filtering, synchronizing, and sharing data. Let me know in the [community forum](https://developer.mongodb.com/community/forums/c/realm-sdks) if you try adding any of that functionality.

## Resources

-   [Apple's tutorial](https://developer.apple.com/tutorials/app-dev-training)
-   [Pre-Realm Scrumdinger code](https://github.com/realm/Scrumdinger)
-   [Realm Scrumdinger code](https://github.com/realm/Scrumdinger/tree/realm)
-   [Diff - all changes required to migrate Scrumdinger to Realm](https://github.com/realm/Scrumdinger/compare/realm)

>
>
>If you have questions, please head to our [developer community website](https://community.mongodb.com/) where the MongoDB engineers and the MongoDB community will help you build your next big idea with MongoDB.
>
>


Learn how to add Realm to an iOS/SwiftUI app to add persistence and flexibility. Uses Apple's Scrumdinger tutorial app as the starting point.

Adapting Apple's Scrumdinger SwiftUI Tutorial App to Use Realm

Thomas Goyne

After three years of work, we're proud to announce the public release of [Realm Cocoa 5.0](https://realm.io/docs/swift/latest/), with a ground-up rearchitecting of the core database.

In the time since we first released the Realm Mobile Database to the world in 2014, we've done our best to adapt to how people have wanted to use Realm and help our users build better apps, faster. Some of the difficulties developers ran into came down to some consequences of design decisions we made very early on, so in 2017 we began a project to rethink our core architecture. In the process, we came up with a new design that simplified our code base, improves performance, and lets us be more flexible around multi-threaded usage.

In case you missed a similar writeup for Realm Java with code examples you can [find it here](https://developer.mongodb.com/article/realm-database-and-frozen-objects#frozen-objects).

## Frozen Objects

One of the big new features this enables is Frozen Objects.

One of the core ideas of Realm is our concept of live, thread-confined objects that reduce the code mobile developers need to write. Objects are the data, so when the local database is updated for a particular thread, all objects are automatically updated too. This design ensures you have a consistent view of your data and makes it extremely easy to hook the local database up to the UI. But it came at a cost for developers using reactive frameworks.

Sometimes Live Objects don't work well with [Functional Reactive Programming (FRP)](https://en.wikipedia.org/wiki/Functional_reactive_programming) where you typically want a stream of immutable objects. This means that Realm objects have to be confined to a single thread. Frozen Objects solve both of these problems by letting you obtain an immutable snapshot of an object or collection which is fully thread-safe, *without* copying it out of the realm. This is especially important with Apple's release of [Combine](https://developer.apple.com/documentation/combine) and [SwiftUI](https://developer.apple.com/tutorials/swiftui/), which are built around many of the ideas of Reactive programming.

For example, suppose we have a nice simple list of Dogs in SwiftUI:

``` Swift
class Dog: Object, ObjectKeyIdentifable {
    @objc dynamic var name: String = ""
    @objc dynamic var age: Int = 0
}

struct DogList: View {
    @ObservedObject var dogs: RealmSwift.List<Dog>

    var body: some View {
        List {
            ForEach(dogs) { dog in
                Text(dog.name)
            }
        }
    }
}
```

If you've ever tried to use Realm with [SwiftUI](https://developer.apple.com/tutorials/swiftui/), you can probably see a problem here: SwiftUI holds onto references to the objects passed to `ForEach()`, and if you delete an object from the list of dogs it'll crash with an index out of range error. Solving this used to involve complicated workarounds, but with [Realm Cocoa 5.0](https://realm.io/docs/swift/latest/) is as simple as freezing the list passed to `ForEach()`:

``` swift
struct DogList: View {
    @ObservedObject var dogs: RealmSwift.List<Dog>

    var body: some View {
        List {
            ForEach(dogs.freeze()) { dog in
            Text(dog.name)
            }
        }
    }
}
```

Now let's suppose we want to make this a little more complicated, and group the dogs by their age. In addition, we want to do the grouping on a background thread to minimize the amount of work done on the main thread. Fortunately, [Realm Cocoa 5.0](https://realm.io/docs/swift/latest/) makes this easy:

``` swift
struct DogGroup {
    let label: String
    let dogs: [Dog]
}

final class DogSource: ObservableObject {
    @Published var groups: [DogGroup] = []

    private var cancellable: AnyCancellable?
    init() {
        cancellable = try! Realm().objects(Dog.self)
            .publisher
            .subscribe(on: DispatchQueue(label: "background queue"))
            .freeze()
            .map { dogs in
                Dictionary(grouping: dogs, by: { $0.age }).map { DogGroup(label: "\($0)", dogs: $1) }
            }
            .receive(on: DispatchQueue.main)
            .assertNoFailure()
            .assign(to: \.groups, on: self)
    }
    deinit {
        cancellable?.cancel()
    }
}

struct DogList: View {
    @EnvironmentObject var dogs: DogSource

    var body: some View {
        List {
            ForEach(dogs.groups, id: \.label) { group in
                Section(header: Text(group.label)) {
                    ForEach(group.dogs) { dog in
                        Text(dog.name)
                    }
                }
            }
        }
    }
}
```

Because frozen objects aren't thread-confined, we can subscribe to change notifications on a background thread, transform the data to a different form, and then pass it back to the main thread without any issues.

## Combine Support

You may also have noticed the `.publisher` in the code sample above. [Realm Cocoa 5.0](https://realm.io/docs/swift/latest/) comes with basic built-in support for using Realm objects and collections with [Combine](https://developer.apple.com/documentation/combine). Collections (List, Results, LinkingObjects, and AnyRealmCollection) come with a `.publisher` property which emits the collection each time it changes, along with a `.changesetPublisher` property that emits a `RealmCollectionChange<T>` each time the collection changes. For Realm objects, there are similar `publisher()` and `changesetPublisher()` free functions which produce the equivalent for objects.

For people who want to use live objects with [Combine](https://developer.apple.com/documentation/combine), we've added a `.threadSafeReference()` extension to `Publisher` which will let you safely use `receive(on:)` with thread-confined types. This lets you write things like the following code block to easily pass thread-confined objects or collections between threads.

``` swift
publisher(object)
  .subscribe(on: backgroundQueue)
  .map(myTransform)
  .threadSafeReference()
  .receive(on: .main)
  .sink {print("\($0)")}
```

## Queue-confined Realms

Another threading improvement coming in [Realm Cocoa 5.0](https://realm.io/docs/swift/latest/) is the ability to confine a realm to a serial dispatch queue rather than a thread. A common pattern in Swift is to use a dispatch queue as a lock which guards access to a variable. Historically, this has been difficult with Realm, where queues can run on any thread.

For example, suppose you're using URLSession and want to access a Realm each time you get a progress update. In previous versions of Realm you would have to open the realm each time the callback is invoked as it won't happen on the same thread each time. With [Realm Cocoa 5.0](https://realm.io/docs/swift/latest/) you can open a realm which is confined to that queue and can be reused:

``` swift
class ProgressTrackingDelegate: NSObject, URLSessionDownloadDelegate {
    public let queue = DispatchQueue(label: "background queue")
    private var realm: Realm!

    override init() {
        super.init()
        queue.sync { realm = try! Realm(queue: queue) }
    }

    public var operationQueue: OperationQueue {
        let operationQueue = OperationQueue()
        operationQueue.underlyingQueue = queue
        return operationQueue
    }

    func urlSession(_ session: URLSession,
                    downloadTask: URLSessionDownloadTask,
                    didWriteData bytesWritten: Int64,
                    totalBytesWritten: Int64,
                    totalBytesExpectedToWrite: Int64) {
        guard let url = downloadTask.originalRequest?.url?.absoluteString else { return }
        try! realm.write {
            let progress = realm.object(ofType: DownloadProgress.self, forPrimaryKey: url)
            if let progress = progress {
                progress.bytesWritten = totalBytesWritten
            } else {
                realm.create(DownloadProgress.self, value: [
                    "url": url,
                    "bytesWritten": bytesWritten
                ])
            }
        }
    }
}
let delegate = ProgressTrackingDelegate()
let session = URLSession(configuration: URLSessionConfiguration.default,
                         delegate: delegate,
                         delegateQueue: delegate.operationQueue)
```

You can also have notifications delivered to a dispatch queue rather than the current thread, including queues other than the active one. This is done by passing the queue to the observe function: `let token = object.observe(on: myQueue) { ... }`.

## Performance

With [Realm Cocoa 5.0](https://realm.io/docs/swift/latest/), we've greatly improved performance in a few important areas. Sorting Results is roughly twice as fast, and deleting objects from a Realm is as much as twenty times faster than in 4.x. Object insertions are 10-25% faster, with bigger gains being seen for types with primary keys.

Most other operations should be similar in speed to previous versions.

[Realm Cocoa 5.0](https://realm.io/docs/swift/latest/) should also typically produce smaller Realm files than previous versions. We've adjusted how we store large binary blobs so that they no longer result in files with a large amount of empty space, and we've reduced the size of the transaction log that's written to the file.

## Compatibility

[Realm Cocoa 5.0](https://realm.io/docs/swift/latest/) comes with a new version of the Realm file format. Any existing files that you open will be automatically upgraded to the new format, with the exception of read-only files (such as those bundled with your app). Those will need to be manually upgraded, which can be done by opening them in Realm Studio or recreating them through whatever means you originally created the file. The upgrade process is one-way, and realms cannot be converted back to the old file format.

Only minor API changes have been made, and we expect most applications which did not use any deprecated functions will compile and work with no changes. You may notice some changes to undocumented behavior, such as that deleting objects no longer changes the order of objects in an unsorted `Results`.

Pre-1.0 Realms containing `Date` or `Any` properties can no longer be opened.

Want to try it out for yourself? Check out our [working demo app using Frozen Objects, SwiftUI, and Combine](https://github.com/realm/realm-cocoa/tree/master/examples/ios/swift/ListSwiftUI).

-   Simply clone the realm-cocoa repo and open `RealmExamples.xworkspace` then select the `ListSwiftUI` app in Xcode and Build.

## Wrap Up

We're very excited to finally get these features out to you and to see what new things you'll be able to build with them. Stay tuned for more exciting new features to come; the investment in the Realm Database continues.

## Links

Want to learn more? [Review the documentation.](https://realm.io/docs).

Ready to get started? [Get Realm Core 6.0 and the SDKs](https://developer.mongodb.com/community/forums/t/realm-releases-core-6-and-multiple-sdk-updates/4276).

Want to ask a question? Head over to our [MongoDB Realm Developer Community Forums](https://developer.mongodb.com/community/forums/c/realm).

Public release of Realm Cocoa 5.0, with a ground-up rearchitecting of the core database

Realm Cocoa 5.0 - Multithreading Support with Integration for SwiftUI & Combine

How to use Realm Flexible Sync in your app. Worked example of an iOS chat app.

Using Realm Flexible Sync in Your App—an iOS Tutorial

The [Realm Mobile
Database](https://www.mongodb.com/realm/mobile/database) makes it much
faster to develop mobile applications. [MongoDB Realm
Studio](https://github.com/realm/realm-studio) is a desktop app that
lets you view, manipulate, and import data held within your mobile app's
Realm database.

This article steps through how to track down the locations of your iOS
Realm database files, open them in Realm Studio, view the data, and make
changes. If you're developing an Android app, then finding the Realm
database files will be a little different (we'll follow up with an
Android version later), but if you can figure out how to locate the
Realm file, then the instructions on using Realm Studio should work.

## Prerequisites

If you want to build and run the app for yourself, this is what you'll
need:

-   A Mac.
-   Xcode – any reasonably recent version will work.
-   Realm Studio 10.1.0+ – earlier versions had an issue when working
    with Realms using [MongoDB Realm
    Sync](https://www.mongodb.com/realm/mobile/sync).

I'll be using the data and schema from my existing
[RChat](https://github.com/ClusterDB/RChat) iOS app. You can use any
Realm-based app, but if you want to understand more about RChat, check
out [Building a Mobile Chat App Using Realm – Data Architecture](/how-to/realm-swiftui-ios-chat-app) and
[Building a Mobile Chat App Using Realm – Integrating Realm into Your App](/how-to/building-a-mobile-chat-app-using-realm).

## Walkthrough

This walkthrough shows you how to:

- [Install & Run MongoDB Realm Studio](#install---run-mongodb-realm-studio)
- [Track Down Realm Data Files – Xcode Simulator](#track-down-realm-data-files---xcode-simulator)
- [Track Down Realm Data Files – Real iOS Devices](#track-down-realm-data-files---real-ios-devices)
- [View Realm Data](#view-realm-data)
- [Add, Modify, and Delete Data](#add--modify--and-delete-data)

### Install & Run MongoDB Realm Studio

I'm using [Realm Studio
10.1.1](https://studio-releases.realm.io/v10.1.1) to create this
article. If you have 10.1.0 installed, then that should work too.

If you don't already have Realm Studio 10.1.0+ installed, then [download
it here](https://studio-releases.realm.io/) and install.

That's it.

But, when you open the app, you're greeted by this:

![Realm Studio Splash Screen](https://www.mongodb.com/developer/images/how-to/realm-studio/Realm-Studio-Splash-Screen.png)

There's a single button letting me "Open Realm file," and when I click
on it, I get a file explorer where I can browse my laptop's file system.

Where am I supposed to find my Realm file? I cover that in the next
section.

### Track Down Realm Data Files – Xcode Simulator

If you're running your app in one of Xcode's simulators, then the Realm
files are stored in your Mac's file system. They're typically somewhere
along the lines of
`~/Library/Developer/CoreSimulator/Devices/???????/data/Containers/Data/Application/???????/Documents/mongodb-realm/???????/????????/???????.realm`.

The scientific way to find the file's location is to add some extra code
to your app or to use a breakpoint.

While my app's in development, I'll normally print the location of a
Realm's file whenever I open it. Don't worry if you're not explicitly
opening your Realm(s) in your code (e.g., if you're using the default
realm) as I'll cover the file search approach soon. This is the code to
add to your app once you've opened your realm – `realm`:

``` swift
print("User Realm User file location: \(realm.configuration.fileURL!.path)")
```

If you don't want to edit the code, then an Xcode breakpoint delivers
the same result:

![XCode breakpoint to find realm file](https://www.mongodb.com/developer/images/how-to/realm-studio/xcode-breakpoint-to-find-realm-file.png)

Once you have the file location, open it in Realm Studio from the
terminal:

``` bash
open /Users/andrew.morgan/Library/Developer/CoreSimulator/Devices/E7526AFE-E886-490A-8085-349C8E8EDC5B/data/Containers/Data/Application/C3ADE2F2-ABF0-4BD0-9F47-F21894E850DB/Documents/mongodb-realm/rchat-saxgm/60099aefb33c57e9a9828d23/%22user%3D60099aefb33c57e9a9828d23%22.realm
```

Less scientific but simpler is to take advantage of the fact that the
data files will always be of type `realm` and located somewhere under
`~/Library/Developer/CoreSimulator/Devices`. Open Finder in that folder:
`open ~/Library/Developer/CoreSimulator/Devices` and then create a
"saved search" so that you can always find all of your realm files.
You'll most often be looking for the most recent one.

![Create saved search](https://www.mongodb.com/developer/images/how-to/realm-studio/Create-Saved-Search.gif)

The nice thing about this approach is that you only need to create the
search once. Then click on "Realms," find the file you need, and then
double-click it to open it in Realm Studio.

### Track Down Realm Data Files – Real iOS Devices

Unfortunately, you can't use Realm Studio to interact with live Realm
files on a real iOS device.

What we can do is download a copy of your app's Realm files from your
iOS device to your laptop. You need to connect your iOS device to your
Mac, agree to trust the computer, etc.

Once connected, you can use Xcode to download a copy of the "Container"
for your app. Open the Xcode device manager—"Window/Devices and
Simulators." Find your device and app, then download the container:

![Download iOS app container](https://www.mongodb.com/developer/images/how-to/realm-studio/Download-iOS-app-container.gif)

Note that you can only access the containers for apps that you've built
and installed through Xcode, not ones you've installed through the App
Store.

Right-click the downloaded file and "Show Package Contents." You'll find
your Realm files under
`AppData/Documents/mongodb-realm/<app-name>/?????`. Find the file for
the realm you're interested in and double-click it to open it in Realm
Studio.

### View Realm Data

After opening a Realm file, Realm Studio will show a window with all of
the top-level Realm Object classes in use by your app. In this example,
the realm I've opened only contains instances of the `Chatster` class.
There's a row for each `Chatster` Object that I'd created through the
app:

![Top level chatster view](https://www.mongodb.com/developer/images/how-to/realm-studio/top-level-chatster-view.png)

If there are a lot of objects, then you can filter them using a simple
[query
syntax](https://docs.mongodb.com/realm-legacy/docs/javascript/latest/api/tutorial-query-language.html):

![Janey search](https://www.mongodb.com/developer/images/how-to/realm-studio/Janey-search.png)

If the Realm Object class contains a `List` or an `EmbeddedObject`, then
they will show as blue links—in this example, `conversations` and
`userPreferences` are a list of `Conversation` objects and an embedded
`UserPreferences` object respectively:

![User object](https://www.mongodb.com/developer/images/how-to/realm-studio/user-object.png)

Clicking on one of the `UserPreferences` links brings up the contents of
the embedded object:

![User preferences object](https://www.mongodb.com/developer/images/how-to/realm-studio/user-preferences-object.png)

### Add, Modify, and Delete Data

The ability to view your Realm data is invaluable for understanding
what's going on inside your app.

Realm Studio takes it a step further by letting you add, modify, and
delete data. This ability helps to debug and test your app.

As a first example, I click on "Create ChatMessage" to add a new message
to a conversation:

![Create chat message button](https://www.mongodb.com/developer/images/how-to/realm-studio/create-chatmessage-button.png)

Fill out the form and click "Create" to add the new `ChatMessage`
object:

![Create new message](https://www.mongodb.com/developer/images/how-to/realm-studio/create-new-message.png)

We can then observe the effect of that change in our app:

![Add message](https://www.mongodb.com/developer/images/how-to/realm-studio/add-message.gif)

I could have tested that change using the app, but there are different
things that I can try using Realm Studio.

I haven't yet included the ability to delete or edit existing messages,
but I can now at least test that this view can cope when the data
changes:

![Modify chat objects](https://www.mongodb.com/developer/images/how-to/realm-studio/modify-chat-objects.gif)

## Summary

In this article, we've seen how to find and open your iOS Realm data
files in Realm Studio. We've viewed the data and then made changes and
observed the iOS app reacting to those changes.

Realm Studio has several other useful features that I haven't covered
here. As it's a GUI, it's fairly easy to figure out how to use them, and
the [docs](https://docs.realm.io/sync/realm-studio) are available if you
get stuck. These functions include:

-   Import data into Realm from a CSV file.
-   Export your Realm data as a JSON file.
-   Edit the schema.
-   Open the Realm file from an app and export the schema in a different
    language. We used this for the [WildAid O-FISH
    project](https://github.com/wildaid). I created the schema in the
    iOS app, and another developer exported a Kotlin version of the
    schema from Realm Studio to use in the Android app.

## References

-   [GitHub Repo for RChat App](https://github.com/ClusterDB/RChat).
-   Read [Building a Mobile Chat App Using Realm – Data Architecture](/how-to/realm-swiftui-ios-chat-app) to understand the data model and partitioning strategy behind the RChat app.
-   Read [Building a Mobile Chat App Using Realm – Integrating Realm into Your App](/how-to/building-a-mobile-chat-app-using-realm) to learn how to create the RChat app.
-   If you're building your first SwiftUI/Realm app, then check out [Build Your First iOS Mobile App Using Realm, SwiftUI, & Combine](/how-to/realm-swiftui-combine-first-app).
-   [GitHub Repo for Realm-Cocoa SDK](https://github.com/realm/realm-cocoa).
-   [Realm Cocoa SDK documentation](https://realm.io/docs/swift/latest/).
-   [MongoDB's Realm documentation](https://docs.mongodb.com/realm/).

>
>
>If you have questions, please head to our [developer community
>website](https://community.mongodb.com/) where the MongoDB engineers and
>the MongoDB community will help you build your next big idea with
>MongoDB.
>
>


Discover how to access and manipulate your iOS App's Realm data using the Realm Studio GUI.

Accessing Realm Data on iOS Using Realm Studio

## Introduction

I wanted to build an app that we could use at events to demonstrate [Realm Sync](https://www.mongodb.com/realm/mobile/sync). It needed to be fun to interact with, and so a multiplayer game made sense. Tic-tac-toe is too simple to get excited about. I'm not a game developer and so _Call Of Duty_ wasn't an option. Then I remembered Microsoft's [Minesweeper](https://en.wikipedia.org/wiki/Minesweeper). 

Minesweeper was a Windows fixture from 1990 until Windows 8 relegated it to the app store in 2012. It was a single-player game, but it struck me as something that could be a lot of fun to play with others. Some family beta-testing of my first version while waiting for a ferry proved that it did get people to interact with each other (even if most interactions involved shouting, "Which of you muppets clicked on that mine?!").

![Family sat around a table, all playing the Realm-Sweeper game on their iPhones](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/IMG_1301_81fa444116.jpeg)

You can download the back end and iOS apps from the [Realm-Sweeper repo](https://github.com/realm/Realm-Sweeper), and get it up and running in a few minutes if you want to play with it.

This article steps you through some of the key aspects of setting up the backend Realm app, as well as the iOS code. Hopefully, you'll see how simple it is and try building something for yourself. If anyone's looking for ideas, then [Sokoban](https://en.wikipedia.org/wiki/Sokoban) could be interesting.

## Prerequisites

- [Realm-Cocoa 10.20.1+](https://github.com/realm/realm-swift/releases/tag/v10.23.0)
- iOS 15+

## The Minesweeper game

The gameplay for Minesweeper is very simple.

You're presented with a grid of gray tiles. You tap on a tile to expose what's beneath. If you expose a mine, game over. If there isn't a mine, then you'll be rewarded with a hint as to how many mines are adjacent to that tile. If you deduce (or guess) that a tile is covering a mine, then you can plant a flag to record that.

You win the game when you correctly flag every mine and expose what's behind every non-mined tile.

### What Realm-Sweeper adds

Minesweeper wasn't designed for touchscreen devices; you had to use a physical mouse. Realm-Sweeper brings the game into the 21st century by adding touch controls. Tap a tile to reveal what's beneath; tap and hold to plant a flag.

Minesweeper was a single-player game. All people who sign into Realm-Sweeper with the same user ID get to collaborate on the same game in real time.

![Animation of two iPhones. As a user taps a tile on one device, the change appears almost instantly on the other](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_sweeper_24ef46cef1.gif)

You also get to configure the size of the grid and how many mines you'd like to hide.

## The data model

I decided to go for a simple data model that would put Realm sync to the test. 

Each game is a single document/object that contains meta data (score, number of rows/columns, etc.) together with the grid of tiles (the board):

![Data model for the Game Class](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/schema_f791f6acf6.png)

This means that even a modestly sized grid (20x20 tiles) results in a `Game` document/object with more than 2,000 attributes. 

Every time you tap on a tile, the `Game` object has to be synced with all other players. Those players are also tapping on tiles, and those changes have to be synced too. If you tap on a tile which isn't adjacent to any mines, then the app will recursively ripple through exposing similar, connected tiles. That's a lot of near-simultaneous changes being made to the same object from different devices—a great test of Realm's automatic conflict resolution!

## The backend Realm app

If you don't want to set this up yourself, simply follow the [instructions from the repo](https://github.com/realm/Realm-Sweeper/tree/main/Realm) to import the app.

If you opt to build the backend app yourself, there are only two things to configure once you create the empty Realm app:

1. [Enable email/password authentication](https://docs.mongodb.com/realm/authentication/email-password/#:~:text=Summary-,Overview,email%20addresses%20are%20case%2Dsensitive.). I kept it simple by opting to auto-confirm new users and sticking with the default password-reset function (which does nothing).
2. [Enable partitioned Realm sync](https://docs.mongodb.com/realm/sync/configure/enable-sync/). Set the partition key to `partition` and enable developer mode (so that the schema will be created automatically when the iOS app syncs for the first time).

The `partition` field will be set to the username—allowing anyone who connects as that user to sync all of their games.

You can also add sync rules to ensure that a user can only sync their own games (in case someone hacks the mobile app). I always prefer using Realm functions for permissions. You can add this for both the read and write rules:

```json
{
  "%%true": {
    "%function": {
      "arguments": [
        "%%partition"
      ],
      "name": "canAccessPartition"
    }
  }
}
```

The `canAccessPartition` function is:

```js
exports = function(partition) {
  const user = context.user.data.email;
  return partition === user;
};
```

## The iOS app

I'd suggest starting by downloading, configuring, and running the app—just follow the [instructions from the repo](https://github.com/realm/Realm-Sweeper/tree/main/iOS). That way, you can get a feel for how it works.

This isn't intended to be a full tutorial covering every line of code in the app. Instead, I'll point out some key components. 

As always with Realm and MongoDB, it all starts with the data…

### Model

There's a single top-level Realm Object—`Game`:

```swift
class Game: Object, ObjectKeyIdentifiable {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var numRows = 0
    @Persisted var numCols = 0
    @Persisted var score = 0
    @Persisted var startTime: Date? = Date()
    @Persisted var latestMoveTime: Date?
    @Persisted var secondsTakenToComplete: Int?
    @Persisted var board: Board?
    @Persisted var gameStatus = GameStatus.notStarted
    @Persisted var winningTimeInSeconds: Int?
    …
}
```

Most of the fields are pretty obvious.The most interesting is `board`, which contains the grid of tiles:

```swift
class Board: EmbeddedObject, ObjectKeyIdentifiable {
    @Persisted var rows = List<Row>()
    @Persisted var startingNumberOfMines = 0
    ... 
}
```

`row` is a list of `Cells`:

```swift
class Row: EmbeddedObject, ObjectKeyIdentifiable {
    @Persisted var cells = List<Cell>()
    ...
}

class Cell: EmbeddedObject, ObjectKeyIdentifiable {
    @Persisted var isMine = false
    @Persisted var numMineNeigbours = 0
    @Persisted var isExposed = false
    @Persisted var isFlagged = false
    @Persisted var hasExploded = false
    ...
}
```

The model is also where the ~~business~~ game logic is implemented. This means that the views can focus on the UI. For example, `Game` includes a computed variable to check whether the game has been solved:

```swift
var hasWon: Bool {
    guard let board = board else { return false }
    if board.remainingMines != 0 { return false }

    var result = true

    board.rows.forEach() { row in
        row.cells.forEach() { cell in
            if !cell.isExposed && !cell.isFlagged {
                result = false
                return
            }
        }
        if !result { return }
    }
    return result
}
```

### Views

As with any SwiftUI app, the UI is built up of a hierarchy of many views.

![Screen capture from Xcode showing the hierarchy of views making up the RealmSweeper UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/views_aaac46f078.png)

Here's a quick summary of the [views](https://github.com/realm/Realm-Sweeper/tree/main/iOS/RealmSweeper/Views) that make up Real-Sweeper:

**[`ContentView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/ContentView.swift)** is the top-level view. When the app first runs, it will show the `LoginView`. Once the user has logged in, it shows `GameListView` instead. It's here that we set the Realm Sync partition (to be the `username` of the user that's just logged in):

```swift
GameListView()
    .environment(\.realmConfiguration,
    realmApp.currentUser!.configuration(partitionValue: username))
```

`ContentView` also includes the `LogoutButton` view.

**[`LoginView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Users/LoginView.swift)** allows the user to provide a username and password:

![Screen capture of the login view. Fields to enter username and password. Checkbox to indicate that you're registering a new user. Button to login,](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Login_View_034d3f058f.png)

Those credentials are then used to register or log into the backend Realm app:

```swift
func userAction() {
    Task {
        do {
            if newUser {
                try await realmApp.emailPasswordAuth.registerUser(
                    email: email, password: password)
            }
            let _ = try await realmApp.login(
                    credentials: .emailPassword(email: email, password: password))
            username = email
        } catch {
            errorMessage = error.localizedDescription
        }
    }
}
```


[**`GameListView`**](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Game%20List/GameListView.swift) reads the list of this user's existing games.

```swift
@ObservedResults(Game.self, 
    sortDescriptor: SortDescriptor(keyPath: "startTime", ascending: false)) var games
```

It displays each of the games within a `GameSummaryView`. If you tap one of the games, then you jump to a `GameView` for that game:

```swift
NavigationLink(destination: GameView(game: game)) {
    GameSummaryView(game: game)
}
```

![GameListView, Screen capture of a list of games, together with buttons to logout, set settings, or create a new game](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Game_List_View_22711c2b4a.png)

Tap the settings button and you're sent to `SettingsView`.

Tap the "New Game" button and a new `Game` object is created and then stored in Realm by appending it to the `games` live query:

```swift
private func createGame() {
    numMines = min(numMines, numRows * numColumns)
    game = Game(rows: numRows, cols: numColumns, mines: numMines)
    if let game = game {
        $games.append(game)
    }
    startGame  = true
}
```

**[`SettingsView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/SettingsView.swift)** lets the user choose the number of tiles and mines to use:

![SettingsView. Steppers to set the number of rows, columns, and mines](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Settings_View_39aa24c7ce.png)

If the user uses multiple devices to play the game (e.g., an iPhone and an iPad), then they may want different-sized boards (taking advantage of the extra screen space on the iPad). Because of that, the view uses the device's `UserDefaults` to locally persist the settings rather than storing them in a synced realm:

```swift
@AppStorage("numRows") var numRows = 10
@AppStorage("numColumns") var numColumns = 10
@AppStorage("numMines") var numMines = 15
```

**[`GameSummaryView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Game%20List/GameSummaryView.swift)** displays a summary of one of the user's current or past games.

![GameSummaryView. Screen capture of view containing the start and completion times + emoji for the status of the game](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Game_Summary_View_e80a138236.png)

**[`GameView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Game/GameView.swift)** shows the latest stats for the current game at the top of the screen: 
 
![GameStatusView. Screen capture showing remaining mines, status of the game (smiling emoji) and elapsed time](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Game_Status_5ee8b8b6e0.png)

It uses the `LEDCounter` and `StatusButton` views for the summary.

Below the summary, it displays the `BoardView` for the game.

**[`LEDCounter`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Control%20Box/Counters/LEDCounter.swift)** displays the provided number as three digits using a retro LED font:

![CounterView – 3 red LED numbers](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Counter_View_d7b73c42ce.png)

**[`StatusButton`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Control%20Box/StatusButton.swift)** uses a `ZStack` to display the symbol for the game's status on top of a tile image:

![StatusButton. Smiling emoji in front of a gray tile](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Status_Button_8975894d39.png)

The view uses SwiftUI's [`GeometryReader`](https://www.hackingwithswift.com/quick-start/swiftui/how-to-provide-relative-sizes-using-geometryreader) function to discover how much space is available so that it can select an appropriate font size for the symbol:

```swift
GeometryReader { geo in
    Text(status)
        .font(.system(size: geo.size.height * 0.7))
}
```


**[`BoardView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Game/BoardView.swift)** displays the game's grid of tiles:

![BoardView. A grid of tiles. Some tiles have been removed, revealing colored numbers. One tile contains a red flag](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Board_View_703d6386db.png)

Each of the tiles is represented by a `CellView` view.

When a tile is tapped, this view exposes its contents:

```swift
.onTapGesture() {
    expose(row: row, col: col)
}
```

On a tap-and-hold, a flag is dropped:

```swift
.onLongPressGesture(minimumDuration: 0.1) {
    flag(row: row, col: col)
}
```

When my family tested the first version of the app, they were frustrated that they couldn't tell whether they'd held long enough for the flag to be dropped. This was an easy mistake to make as their finger was hiding the tile at the time—an example of where testing with a mouse and simulator wasn't a substitute for using real devices. It was especially frustrating as getting it wrong meant that you revealed a mine and immediately lost the game. Fortunately, this is easy to fix using iOS's haptic feedback:

```swift
func hapticFeedback(_ isSuccess: Bool) {
    let generator = UINotificationFeedbackGenerator()
    generator.notificationOccurred(isSuccess ? .success : .error)
}
```

You now feel a buzz when the flag has been dropped.

**[`CellView`](CellView)** displays an individual tile: 

![CellView. Tile containing a crossed out red flag](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Cell_View_6ee46c6103.png)

What's displayed depends on the contents of the `Cell` and the state of the game. It uses four further views to display different types of tile: `FlagView`, `MineCountView`, `MineView`, and `TileView`.

**[`FlagView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Tiles/FlagView.swift)**

![FlagView. 2 Tiles, both containing a flag, one shows the  flag crossed out](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Flag_View_fd57e245f3.png)

**[`MineCountView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Tiles/MineCountView.swift)**

![MineCountView, 6 gray tiles. One is empty the others containing numbers 1 through 5, each in a different color](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Mine_Count_View_e8392ff46d.png)

**[`MineView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Tiles/MineView.swift)**

![MineView. Two tiles containing mines, one with a gray background, one with a red background](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Mine_View_18eaaf517b.png)

**[`TileView`](https://github.com/realm/Realm-Sweeper/blob/main/iOS/RealmSweeper/Views/Tiles/TileView.swift)**

![TileView. A single gray tile](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Tile_View_1a01815c26.png)

## Conclusion

Realm-Sweeper gives a real feel for how quickly Realm is able to synchronize data over the internet.

I intentionally avoided optimizing how I updated the game data in Realm. When you see a single click exposing dozens of tiles, each cell change is an update to the `Game` object that needs to be synced.

![GIF showing changes in one game board appearing in near-realtime in the game board on a different device](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/sync_526ade2926.gif)

Note that both instances of the game are running in iPhone simulators on an overworked Macbook in England. The Realm backend app is running in the US—that's a 12,000 km/7,500 mile round trip for each sync.

I took this approach as I wanted to demonstrate the performance of Realm synchronization. If an app like this became super-popular with millions of users, then it would put a lot of extra strain on the backend Realm app.

An obvious optimization would be to condense all of the tile changes from a single tap into a single write to the Realm object. If you're interested in trying that out, just fork the [repo](https://github.com/realm/Realm-Sweeper) and make the changes. If you do implement the optimization, then please create a pull request. (I'd probably add it as an option within the settings so that the "slow" mode is still an option.)

Got questions? Ask them in our [Community forum](https://www.mongodb.com/community/forums/c/realm/realm-sync/111).

Using MongoDB Realm Sync to build an iOS multi-player version of the classic Windows game

Building a Collaborative iOS Minesweeper Game with Realm

Are you an experienced non-mobile developer interested in writing your first iOS app? Or maybe a mobile developer wondering how to enhance your app or simplify your code using Realm and SwiftUI?

I've written a number of [tutorials](https://www.mongodb.com/developer/author/andrew-morgan/) aimed at these cohorts, and I've published a video that attempts to cover everything in just 40 minutes.

I start with a brief tour of the anatomy of a mobile app—covering both the backend and frontend components.

The bulk of the tutorial is devoted to a hands-on demonstration of building a simple chat app. The app lets users open a chatroom of their choice. Once in a chat room, users can share messages with other members.

While the app is simple, it solves some complex distributed data issues, with real-time syncing of data between your backend database and your mobile apps. Realm is also available for other platforms, such as Android, so the same back end and data can be shared with all versions of your app.

:youtube[Video tutorial showing how to build your first mobile iOS/iPhone app using Realm and SwiftUI]{vid=lSp95xkvo1U}

You can find all of the code from the tutorial in the [repo](https://github.com/mongodb-developer/LiveTutorialChat).

If this tutorial whet your appetite and you'd like to see more (and maybe try it for yourself), then I'm running a more leisurely(?) two-hour workshop at MongoDB World 2022—[From 0 to Mobile Developer in 2 Hours with Realm and SwiftUI](https://app.swapcard.com/widget/event/mongodb-world-2022/planning/UGxhbm5pbmdfODYxNjk5), where I build an all-new app. There's still time to [register for MongoDB World 2002](https://www.mongodb.com/world-2022/tickets). **Use code AndrewMorgan25 for a 25% discount**.

Video showing how to build your first iOS app using SwiftUI and Realm

From Zero to Mobile Developer in 40 Minutes

Kaitlin Mahar

 I recently [revealed on Twitter](https://twitter.com/k__mahar/status/1494118397491269636) something that may have come as a surprise to many of my followers from the Swift/iOS community: I had never written an iOS app before! I've been writing Swift for a few years now but have focused entirely on [library development](https://www.youtube.com/watch?v=9-fdbG9jNt4) and [server-side Swift](https://www.swift.org/server/).

A highly compelling feature of Swift is that it allows you to write an iOS app and a corresponding backend – a complete, end-to-end application – all in the same language. This is similar to how using [Node.js](https://nodejs.org/en/) for a web app backend allows you to write Javascript everywhere.

To test this out and learn about iOS development, I decided to build a full-stack application entirely in Swift. I settled on a familiar CRUD app I've created a web version of before, an application that allows the user to manage a list of kittens and information about them.

I chose to build the app using the following components:
* A backend server, written using the popular Swift web framework [Vapor](https://vapor.codes/) and using the [MongoDB Swift driver](https://github.com/mongodb/mongo-swift-driver) via [MongoDBVapor](https://github.com/mongodb/mongodb-vapor) to store data in MongoDB
* An iOS application built with [SwiftUI](https://developer.apple.com/xcode/swiftui/) and using [SwiftBSON](https://github.com/mongodb/swift-bson) to support serializing/deserializing data to/from [extended JSON](https://docs.mongodb.com/manual/reference/mongodb-extended-json/), a version of JSON with MongoDB-specific extensions to simplify type preservation
* A [SwiftPM](https://www.swift.org/package-manager/) package containing the code I wanted to share between the two above components

I was able to combine all of this into a single code base with a folder structure as follows:
```
FullStackSwiftExample/
├── Models/
│   ├── Package.swift
│   └── Sources/
│       └── Models/
│           └── Models.swift
├── Backend/
│   ├── Package.swift
│   └── Sources/
│       ├── App/
│       │   ├── configure.swift
│       │   └── routes.swift
│       └── Run/
│           └── main.swift
└── iOSApp/
    └── Kittens/
        ├── KittensApp.swift
        ├── Utilities.swift
        ├── ViewModels/
        │   ├── AddKittenViewModel.swift
        │   ├── KittenListViewModel.swift
        │   └── ViewUpdateDeleteKittenViewModel.swift
        └── Views/
            ├── AddKitten.swift
            ├── KittenList.swift
            └── ViewUpdateDeleteKitten.swift
```

Overall, it was a great learning experience for me, and although the app is pretty basic, I'm proud of what I was able to put together! [Here](https://github.com/mongodb/mongo-swift-driver/tree/main/Examples/FullStackSwiftExample) is the finished application, instructions to run it, and documentation on each component.

In the rest of this post, I'll discuss some of my takeaways from this experience.

## 1. Sharing data model types made it straightforward to consistently represent my data throughout the stack.

As I mentioned above, I created a shared SwiftPM package for any code I wanted to use both in the frontend and backend of my application. In that package, I defined `Codable` types modeling the data in my application, for example:

```swift
/**
* Represents a kitten.
* This type conforms to `Codable` to allow us to serialize it to and deserialize it from extended JSON and BSON.
* This type conforms to `Identifiable` so that SwiftUI is able to uniquely identify instances of this type when they
* are used in the iOS interface.
*/
public struct Kitten: Identifiable, Codable {
   /// Unique identifier.
   public let id: BSONObjectID

   /// Name.
   public let name: String

   /// Fur color.
   public let color: String

   /// Favorite food.
   public let favoriteFood: CatFood

   /// Last updated time.
   public let lastUpdateTime: Date

   private enum CodingKeys: String, CodingKey {
       // We store the identifier under the name `id` on the struct to satisfy the requirements of the `Identifiable`
       // protocol, which this type conforms to in order to allow usage with certain SwiftUI features. However,
       // MongoDB uses the name `_id` for unique identifiers, so we need to use `_id` in the extended JSON
       // representation of this type.
       case id = "_id", name, color, favoriteFood, lastUpdateTime
   }
}
```

When you use separate code/programming languages to represent data on the frontend versus backend of an application, it's easy for implementations to get out of sync.  But in this application, since the same exact model type gets used for the frontend **and** backend representations of kittens, there can't be any inconsistency.

Since this type conforms to the `Codable` protocol, we also get a single, consistent definition for a kitten's representation in external data formats. The formats used in this application are:
* [Extended JSON](https://docs.mongodb.com/manual/reference/mongodb-extended-json/), which the frontend and backend use to communicate via HTTP, and
* [BSON](https://docs.mongodb.com/manual/reference/bson-types/), which the backend and MongoDB use to communicate

For a concrete example of using a model type throughout the stack, when a user adds a new kitten via the UI, the data flows through the application as follows:
1. The iOS app creates a new `Kitten` instance containing the user-provided data
1. The `Kitten` instance is serialized to extended JSON via `ExtendedJSONEncoder` and sent in a POST request to the backend
1. The Vapor backend deserializes a new instance of `Kitten` from the extended JSON data using `ExtendedJSONDecoder`
1. The `Kitten` is passed to the MongoDB driver method `MongoCollection<Kitten>.insertOne()`
1. The MongoDB driver uses its built-in `BSONEncoder` to serialize the `Kitten` to BSON and send it via the MongoDB [wire protocol](https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/) to the database

With all these transformations, it can be tricky to ensure that both the frontend and backend remain in sync in terms of how they model, serialize, and deserialize data.  Using Swift everywhere and sharing these `Codable` data types allowed me to avoid those problems altogether in this app.

## 2. Working in a single, familiar language made the development experience seamless.

Despite having never built an iOS app before, I found my existing Swift experience made it surprisingly easy to pick up on the concepts I needed to implement the iOS portion of my application. I suspect it's more common that someone would go in the opposite direction, but I think iOS experience would translate well to writing a Swift backend too!

I used several Swift language features such as [protocols](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html), [trailing closures](https://docs.swift.org/swift-book/LanguageGuide/Closures.html), and [computed properties](https://docs.swift.org/swift-book/LanguageGuide/Properties.html) in both the iOS and backend code. I was also able to take advantage of Swift's new built-in features for [concurrency](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html) throughout the stack. I used the `async` APIs on [`URLSession`](https://developer.apple.com/documentation/foundation/urlsession) to send HTTP requests from the frontend, and I used Vapor and the MongoDB driver's `async` APIs to handle requests on the backend.  It was much easier to use a consistent model and syntax for concurrent, asynchronous programming throughout the application than to try to keep straight in my head the concurrency models for two different languages at once.

In general, using the same language really made it feel like I was building a single application rather than two distinct ones, and greatly reduced the amount of context-switching I had to do as I alternated between work on the frontend and backend. 

## 3. SwiftUI and iOS development are really cool!

Many of my past experiences trying to cobble together a frontend for school or personal projects using HTML and Javascript were frustrating.  This time around, the combination of using my favorite programming language and an elegant, declarative framework made writing the frontend very enjoyable. More generally, it was great to finally learn a bit about iOS development and what most people writing Swift and that I know from the Swift community do!

---

In conclusion, my first foray into iOS development building this full-stack Swift app was a lot of fun and a great learning experience. It strongly demonstrated to me the benefits of using a single language to build an entire application, and using a language you're already familiar with as you venture into programming in a new domain.

I've included a list of references below, including a link to the example application. Please feel free to get in touch with any questions or suggestions regarding the application or the MongoDB libraries listed below – the best way to get in touch with me and my team is by filing a [GitHub issue](https://github.com/mongodb/mongo-swift-driver/issues/new/choose) or [Jira ticket](http://jira.mongodb.org/browse/SWIFT)!

## References
* [Example app source code](https://github.com/mongodb/mongo-swift-driver/tree/main/Examples/FullStackSwiftExample)
* [MongoDB Swift driver](https://github.com/mongodb/mongo-swift-driver) and [documentation](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/index.html)
* [MongoDBVapor](https://github.com/mongodb/mongodb-vapor) and [documentation](https://mongodb.github.io/mongodb-vapor/current/index.html)
* [SwiftBSON](https://github.com/mongodb/swift-bson) and [documentation](https://mongodb.github.io/swift-bson/docs/current/SwiftBSON/index.html)
* [Vapor](https://vapor.codes/)
* [SwiftUI](https://developer.apple.com/xcode/swiftui/)

Curious about mobile and server-side swift? Use this tutorial and example code!

Building a Full Stack application with Swift

Josman Pérez Expóstio

In a serverless application, one of the important features that we must implement for the success of our application is push notifications.

Realm allows us to have a complete push notification system directly in our [Services App](https://www.mongodb.com/atlas/app-services). To do this, we’ll make use of several components that we’ll explain here and develop in this tutorial. But first, let’s describe what our application does.

## Context

The application consists of a public list of books that are stored locally on the device thanks to [Atlas Device Sync](https://www.mongodb.com/atlas/app-services/device-sync), so we can add/delete or update the books directly in our Atlas collection and the changes will be reflected in our application.

We can also add as favorites any book from the list, although to do so, it’ll be necessary to register beforehand using an email and password. We will integrate email/password authentication in our application through the [Atlas App Services authentication providers](https://www.mongodb.com/docs/atlas/app-services/authentication/providers/).

The books, as they belong to a collection synchronized with Atlas Device Sync, will not only be stored persistently on our device but will also be synchronized with our user. This means that we can retrieve the list of favorites on any device where we register with our credentials. Changes made to our favorites using other devices are automatically synchronized.

![Example of the iOS app running on a device](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/books_28f8494f1d.gif)

### Firebase

The management of push notifications will be done through [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging). In this way, we benefit from a single service to send notifications to iOS, web, and Android.

The configuration is similar to the one we would follow for any other application. The difference is that we will install the [firebase-admin](https://www.npmjs.com/package/firebase-admin) SDK in our Atlas App Services application.

### Triggers

The logic of this application for sending push notifications will be done through triggers. To do this, we will define two use cases:

1. A book has been added or deleted: For this, we will make use of the [topics in Firebase](https://firebase.google.com/docs/cloud-messaging/ios/topic-messaging), so when a user registers to receive this type of notification, they will receive a message every time a book is added/deleted from the general list of books.
2. A book added to my favorites list has been modified: We will make use of the Firebase tokens for each device. We relate the token received to the user so that when a book is modified, only the user/s that have it in their favorites list will receive the notification.

### Functions

The Atlas Triggers will have a function linked that will apply the logic for sending push notifications to the end devices. We will make use of the Firebase Admin SDK that we will install in our App Services App as a [dependency](https://www.mongodb.com/docs/atlas/app-services/functions/dependencies/).

## Overall application logic

This application will show how we can integrate push notifications with an iOS application developed in Swift. We will discuss how we have created each part with code, diagrams, and example usage.

At the end of this tutorial, you’ll find a link to a Github repository where you’ll find both the code of the iOS application as well as the code of the App Services application.

![How to request a FCMToken](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/How_to_request_a_FCM_Token_01c90dfa97.png)

When we start the application for the first time, we log in using [anonymous authentication](https://www.mongodb.com/docs/atlas/app-services/authentication/anonymous/), since to view the list of books, it’s not necessary to register using email/password. However, an anonymous user will still be created and saved in a collection Users in Atlas.

When we first access our application and enable push notifications, in our code, we register with Firebase. This will generate a [registration token](https://firebase.google.com/docs/cloud-messaging/concept-options#credentials), also known as FCMToken, that we will use later to send custom push notifications.

```swift
Messaging.messaging().token { token, error in
   if let error = error {
       print("Error fetching FCM registration token: \(error)")
   } else if let token = token {
       print("FCM registration token: \(token)")
       // Save token in user collection
       user.functions.updateFCMUserToken([AnyBSON(token), AnyBSON("add")], self.onCustomDataUpdated(result:realmError:))
   }
}
```

Once we obtain the FCM token, we will [call a function](https://www.mongodb.com/docs/realm/sdk/swift/examples/call-a-function/) through the Realm SDK to save this token in the user document corresponding to the logged-in user. Within the document, we have defined a token field that will be composed of an array of FCM tokens.

To do this, we will make use of the Firebase SDK and the `Messaging` method, so that we are notified every time the token changes or a new token is generated. In our Swift code, we will use this function to insert a new FCToken for our user.

```swift
Messaging.messaging().token { token, error in
    if let error = error {
        print("Error fetching FCM registration token: \(error)")
    } else if let token = token {
        print("FCM registration token: \(token)")
        // Save token in user collection
        user.functions.updateFCMUserToken([AnyBSON(token), AnyBSON("add")], self.onCustomDataUpdated(result:realmError:))
    }
}
```

In our App Services app, we must implement the logic of the `updateFCMUserToken` function that will store the token in our user document.

#### Function code in Atlas

```javascript
exports = function(FCMToken, operation) {

  const db = context.services.get("mongodb-atlas").db("product");
  const userData = db.collection("customUserData");
  
  if (operation === "add") {
    console.log("add");
    userData.updateOne({"userId": context.user.id},
    { "$addToSet": {
      "FCMToken": FCMToken
    }  
    }).then((doc) => {
      return {success: `User token updated`};
    }).catch(err => {
      return {error: `User ${context.user.id} not found`};
    });
  } else if (operation === "remove") {
    console.log("remove"); 
  } 
};
```

We have decided to save an array of tokens to be able to send a notification to each device that the same user has used to access the application.

The following is an example of a User document in the collection:

```JSON
{
 "_id": {
   "$oid": "626c213ece7819d62ebbfb99"
 },
 "color": "#1AA7ECFF",
 "fullImage": false,
 "userId": "6268246e3e0b17265d085866",
 "bookNotification": true,
 "FCMToken": [
   "as3SiBN0kBol1ITGdBqGS:APA91bERtZt-O-jEg6jMMCjPCfYdo1wmP9RbeATAXIQKQ3rfOqj1HFmETvdqm2MJHOhx2ZXqGJydtMWjHkaAD20A8OtqYWU3oiSg17vX_gh-19b85lP9S8bvd2TRsV3DqHnJP8k-t2WV",
   "e_Os41X5ikUMk9Kdg3-GGc:APA91bFzFnmAgAhbtbqXOwD6NLnDzfyOzYbG2E-d6mYOQKZ8qVOCxd7cmYo8X3JAFTuXZ0QUXKJ1bzSzDo3E0D00z3B4WFKD7Yqq9YaGGzf_XSUcCexDTM46bm4Ave6SWzbh62L4pCbS"
 ]
}
```

## Send notification to a topic

Firebase allows us to subscribe to a topic so that we can send a notification to all devices that have ever subscribed to it without the need to send the notification to specific device tokens.

In our application, once we have registered using an email and password, we can subscribe to receive notifications every time a new book is added or deleted.

![Setting view in the iOS app](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Settings_1136d1eb16.png)

When we activate this option, what happens is that we use the Firebase SDK to register in the topic books.

```swift
static let booksTopic = "books"

@IBAction func setBookPushNotification(_ sender: Any) {
 if booksNotificationBtn.isOn {
     Messaging.messaging().subscribe(toTopic: SettingsViewController.booksTopic)
     print("Subscribed to \(SettingsViewController.booksTopic)")
 } else {
     Messaging.messaging().unsubscribe(fromTopic: SettingsViewController.booksTopic)
     print("Unsubscribed to \(SettingsViewController.booksTopic)")
 }
}
```

### How does it work?

The logic we follow will be as below:

![How push notifications to topic works](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Push_Notifications_diagram_Send_to_topic_b517db3b91.jpg)

In our Atlas App Services App, we will have a [database trigger](https://www.mongodb.com/docs/atlas/app-services/triggers/database-triggers/) that will monitor the Books collection for any new inserts or deletes.

Upon the occurrence of either of these two operations, the linked function shall be executed and send a push notification to the “books” topic.

To configure this trigger, we’ll make use of two very important options:

* **Full Document**: This will allow us to receive the document created or modified in our change event. 
* **Document Pre-Image**: For delete operations, we will receive the document that was modified or deleted before your change event.

With these options, we can determine which changes have occurred and send a message using the title of the book to inform about the change. 

The configuration of the trigger in the App Services UI will be as follows:

![Screenshot of the trigger configuration in the Atlas App Services UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Trigger_for_topic_push_notification_bcbc380591.jpg)

The function linked to the trigger will determine whether the operation occurred as an `insert` or `delete` and send the push notification to the topic **books** with the title information.

Function logic:

```javascript
 const admin = require('firebase-admin');
 admin.initializeApp({
   credential: admin.credential.cert({
     projectId: context.values.get('projectId'),
     clientEmail: context.values.get('clientEmail'),
     privateKey: context.values.get('fcm_private_key_value').replace(/\\n/g, '\n'),
   }),
 });
 const topic = 'books';
 const message = {topic};
 if (changeEvent.operationType === 'insert') {
   const name = changeEvent.fullDocument.volumeInfo.title;
   const image = changeEvent.fullDocument.volumeInfo.imageLinks.smallThumbnail;
   message.notification = {
     body: `${name} has been added to the list`,
     title: 'New book added'
   };
   if (image !== undefined) {
     message.apns = {
       payload: {
         aps: {
           'mutable-content': 1
         }
       },
       fcm_options: {
         image
       }
     };
   }
 } else if (changeEvent.operationType === 'delete') {
   console.log(JSON.stringify(changeEvent));
   const name = changeEvent.fullDocumentBeforeChange.volumeInfo.title;
   message.notification = {
     body: `${name} has been deleted from the list`,
     title: 'Book deleted'
   };
 }
 admin.messaging().send(message)
   .then((response) => {
     // Response is a message ID string.
     console.log('Successfully sent message:', response);
     return true;
   })
   .catch((error) => {
     console.log('Error sending message:', error);
     return false;
 });
```

When someone adds a new book, everyone who opted-in for push notifications will receive the following:

![Screenshot of a push notification on a device](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Example_of_push_to_topic_on_device_aa8f65fd48.png)

## Send notification to a specific device

To send a notification to a specific device, the logic will be somewhat different.

For this use case, every time a book is updated, we will search if it belongs to the favourites list of any user. For those users who have such a book, we will send a notification to all registered tokens.

This will ensure that only users who have added the updated book to their favorites will receive a notification alerting them that there has been a change.

### How does it work?

![Diagram of sending push notifications to a specific list of users](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Diagram_of_sending_push_notifications_to_a_specific_list_of_users_51080e63c4.jpg)

For this part, we will need a database trigger that will monitor for updates operations on the books collection.

The configuration of this trigger is much simpler, as we only need to monitor the `updates` that occur in the book collection. 

The configuration of the trigger in our UI will be as follows:

![Screenshot of the trigger configuration in the Atlas App Services UI](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Trigger_for_checking_updates_on_book_collection_dcb9e145d0.jpg)

When such an operation occurs, we’ll check if there is any user who has added that book to their favorites list. If there is, we will create a new document in the ***pushNotifications*** collection.

This auxiliary collection is used to optimize the sending of push notifications and handle exceptions. It will even allow us to set up a monitoring system as well as retries.

Every time we send a notification, we’ll insert a document with the following:

1. The changes that occurred in the original document.
2. The FCM tokens of the recipient devices.
3. The date when the notification was registered.
4. A processed property to know if the notification has been sent.

Here’s an example of a push notification document:

```JSON
{
 "_id": {
   "$oid": "62a0da5d860040b7938eab87"
 },
 "token": [
"e_OpA2X6ikUMk9Kdg3-GGc:APA91bFzFnmAgAhbtbqXOwD6NLnDzfyOzYbG2E-d6mYOQKZ8qVOCxd7cmYo8X3JAFTuXZ0QUXKJ1bzSzDo3E0D00z3B4WFKD7Yqq9YaGGzf_XSUcCexDTM46bm4Ave6SWzbh62L4pCbS",
   "fQvffGBN2kBol1ITGdBqGS:APA91bERtZt-O-jEg6jMMCjPCfYdo1wmP9RbeATAXIQKQ3rfOqj1HFmETvdqm2MJHOhx2ZXqGJydtMWjHkaAD20A8OtqYWU3oiSg17vX_gh-19b85lP9S8bvd2TRsV3DqHnJP8k-t2WV"
 ],
 "date": {
   "$date": {
     "$numberLong": "1654708829678"
   }
 },
 "processed": true,
 "changes": {
   "volumeInfo": {
     "title": "Pacific on Linguistics",
     "publishedDate": "1964",
     "industryIdentifiers": [
       {
         "type": "OTHER",
         "identifier": "UOM:39015069017963"
       }
     ],
     "readingModes": {
       "text": false,
       "image": false
     },
     "categories": [
       "Linguistics"
     ],
     "imageLinks": {
       "smallThumbnail": "http://books.google.com/books/content?id=aCVZAAAAMAAJ&printsec=frontcover&img=1&zoom=5&source=gbs_api",
       "thumbnail": "http://books.google.com/books/content?id=aCVZAAAAMAAJ&printsec=frontcover&img=1&zoom=1&source=gbs_api"
     },
     "language": "en"
   }
 }
}
```

To process the notifications, we’ll have a database trigger that will monitor the ***pushNotifications*** collection, and each new document will send a notification to the tokens of the client devices.

#### Function logic

```javascript
exports = async function(changeEvent) {

 const admin = require('firebase-admin');
 const db = context.services.get('mongodb-atlas').db('product');

 const id = changeEvent.documentKey._id;

 const bookCollection = db.collection('book');
 const pushNotification = db.collection('pushNotification');

 admin.initializeApp({
   credential: admin.credential.cert({
     projectId: context.values.get('projectId'),
     clientEmail: context.values.get('clientEmail'),
     privateKey: context.values.get('fcm_private_key_value').replace(/\\n/g, '\n'),
   }),
 });

 const registrationToken = changeEvent.fullDocument.token;
 console.log(JSON.stringify(registrationToken));
 const title = changeEvent.fullDocument.changes.volumeInfo.title;
 const image = changeEvent.fullDocument.changes.volumeInfo.imageLinks.smallThumbnail;

 const message = {
   notification:{
     body: 'One of your favorites changed',
     title: `${title} changed`
   },
   tokens: registrationToken
 };

 if (image !== undefined) {
   message.apns = {
     payload: {
       aps: {
         'mutable-content': 1
       }
     },
     fcm_options: {
      image
     }
   };
 }

 // Send a message to the device corresponding to the provided
 // registration token.
 admin.messaging().sendMulticast(message)
   .then((response) => {
     // Response is a message ID string.
     console.log('Successfully sent message:', response);
     pushNotification.updateOne({'_id': BSON.ObjectId(`${id}`)},{
       "$set" : {
         processed: true
       }
     });
   })
   .catch((error) => {
     console.log('Error sending message:', error);
 });
};
```

Example of a push notification to a user:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Screenshot_of_specific_push_notification_received_on_device_c650d5fae0.png)

## Repository

The complete code for both the App Services App as well as for the iOS application can be found in a [dedicated GitHub repository](https://github.com/josmanperez/BookRealmTutorial).

If you have found this tutorial useful, let me know so I can continue to add more information as well as step-by-step videos on how to do this.

And if you’re as excited about Atlas App Services as I am, create your [first free App](https://www.mongodb.com/atlas/app-services) today!

Use our Atlas App Services application to create a complete push notification system that fits our business logic.

iOS

Featured

Push Notifications Using Atlas App Services & iOS Realm SDK

Building a Full Stack application with Swift

Find our Devices - A locator app built using Realm

iOS Code Examples

Building a Full Stack application with Swift

Find our Devices - A locator app built using Realm

Building a Mobile Chat App Using Realm – The New and Easier Way

iOS Tutorials

Push Notifications Using Atlas App Services & iOS Realm SDK

Building a Collaborative iOS Minesweeper Game with Realm

Building a Mobile Chat App Using Realm – Integrating Realm into Your App

All iOS Content