Navigation

ToDo (iOS App)

This tutorial demonstrates how to use MongoDB Stitch to integrate Atlas, Mobile, and Sync into an iOS mobile app.

This tutorial walks through creating a Stitch application that backs a pre-created ToDo iOS application. The ToDo application maintains a list of todo items for each user. After logging in anonymously, users can add todo items to their list, re-arrange items in their list, and check off items as they complete them. The app stores all todo items on the device in a local MongoDB Mobile database and syncs the documents to a remote Atlas cluster whenever it has internet access.

The ToDo app uses the items collection in the todo database, and stores each todo item as a single document. A todo document has the following format:

{
   _id : ObjectId("5be2118cc6eda6d1671ddee3"),
   owner_id : ObjectId("5be1158f4ffdc28344840ae4"),
   text : "Put your right foot in.",
   checked : true,
   __stitch_sync_version : {
      spv : 1,
      id : "c73dd901-bba3-44ab-bf49-9b8abc99c7d1",
      v : 3
   }
}

Prerequisites

For this app, you need the following:

  • A MongoDB Atlas cluster using MongoDB version 3.6+. This tutorial uses an Atlas Free Tier cluster.
  • MacOS 10.13 (High Sierra) or later.
  • Xcode 10.0+ and Swift 4.2+.

Procedure

A. Create a Stitch App

Estimated Time to Complete: ~8 minutes

1

Log into Atlas.

To use MongoDB Stitch, you must be logged into MongoDB Atlas. If you do not have an Atlas account, follow the instructions in the Atlas documentation to create an account.

2

Create an Atlas cluster.

If you do not already have an Atlas cluster for use with MongoDB Stitch, create a cluster.

Atlas provides a Free Tier M0 replica set as well as paid M10+ clusters. Free Tier deployments have restrictions as compared to paid M10+ deployments but will work for the purposes of this tutorial. For complete documentation on these restrictions, see Atlas M0 (Free Tier), M2, and M5 Limitations.

3

Add a MongoDB Stitch application.

  1. In Atlas, click Stitch Apps in the left-hand navigation.
  2. Click the Create New Application button.
  3. Under Application Name, enter a name for your application. The name can only contain ASCII letters, numbers, underscores, and hyphens.
  4. Under Link To Cluster, select the MongoDB Atlas cluster that you’d like to use for your application.
  5. Click Create.

After you click Create, a new Stitch application will be created for you. The application will include a MongoDB service named mongodb-atlas that is linked to your cluster. This process may take several minutes.

Once your application has been created, you will be automatically redirected to the Stitch application console.

B. Define Stitch Rules

Estimated Time to Complete: ~10 minutes

Stitch rules specify the read and write access for the fields in your collections. This tutorial uses 3 collections, each of which you will create a rule for.

1

Configure MongoDB.

Create a namespace for the todo.items collection:

  1. Click on Rules under Atlas Clusters in the left navigation pane.

  2. Click the + Add Collection button.

  3. In the Add New Collection dialog, provide the following values:

    Property Value
    Database Name todo
    Collection Name items
    Select a Template Users can only read and write their own data
    Field Name For User ID owner_id

    Stitch creates a new rule (a combination of a role and permissions) based on the template. This rule allows an authenticated user to only read and write their own documents and to insert new documents.

  4. Click Add Collection.

MongoDB Authorization

MongoDB Stitch rules do not override the read and write access (i.e. authorization) that may have been set up separately in MongoDB. That is, MongoDB Stitch rules determine whether the fields are readable or writable; not whether the client has authorization to read or write to a particular database or collection.

Similarly, MongoDB Stitch validation rules do not override document validation rules set up separately in MongoDB.

2

Review Rules for Documents in todo.items.

To view the rule associated with the template, expand todo, and then click on items. Click on the edit button ( pencil icon ) to open the role editor.

By default, the collection has the following Apply When rule:

{
  "owner_id": "%%user.id"
}

With this rule, read and write operations can access all fields in a document if the document contains an owner_id field whose value equals the user ID (%%user.id) of the client issuing the read. If the owner_id field in the document does not equal the client user id, the document is not readable.

For more information on MongoDB rules, see the rules section of the MongoDB service overview.

3

Add a Filter for todo.items.

Filters improve performance by filtering the results returned from a MongoDB call. To add a filter, click on the Filters tab.

To create a query filter, click the Filters tab, and then click the + New Filter button. Click the filter 1 header to expand it, and then provide the following values:

Field Value
Apply When { "%%true": true }
Query Filter { "owner_id": "%%user.id" }

This filter indicates that when %%true equals true (i.e. always), return only the documents where the owner_id field matches the %%user.id.

Click the Save button to save your changes.

Note

Adding this filter is optional, because it duplicates the logic in the rules that were added with the template we chose. However, in a large-scale application, this filter improves performance significantly.

For more information on MongoDB rules, see the query filters section of the MongoDB service overview.

4

Create a rule for todo.lists.

  1. In the Add New Collection dialog, provide the following values. Note that the field name for the user ID is different from the todo.items collection:

    Property Value
    Database Name todo
    Collection Name lists
    Select a Template Users can only read and write their own data
    Field Name For User ID _id
  2. Click Add Collection.

5

Create a rule for todo.index_swaps.

  1. In the Add New Collection dialog, provide the following values. Note that, other than the collection name, the values are the same as you provided for todo.lists:

    Property Value
    Database Name todo
    Collection Name index_swaps
    Select a Template Users can only read and write their own data
    Field Name For User ID _id
  2. Click Add Collection.

When you are finished, your Rules pane should look similar to this:

../../_images/todo-rules.png

C. Enable Anonymous Auth

Estimated Time to Complete: 1 minute

To use Anonymous Authentication in the application:

1

Go to Authentication page.

Select Users from the left-side navigation.

2

Enable anonymous authentication.

  1. For Allow users to log in anonymously, click the Edit button.
  2. Switch the toggle to enabled, and then save your changes.

D. Download the Application Source Code

Estimated Time to Complete: ~2 minutes

1

Download the code.

Clone the Stitch github example repository, or download the zip file for the repo and unzip it.

The source code for the ToDo iOS application can be found in todo/ios directory.

2

Install the pods.

This project uses CocoaPods to manage dependencies, which means you need to install the pods before building the project. To do so, follow these steps:

  1. In a terminal window, navigate to the todo/ios directory.
  2. Run pod install to install the project dependencies.

Update your Pod repo

If you experience problems installing pods or building the app, you may need to update your pod repo by running pod repo update, and then running pod update.

3

Open the project.

Open the workspace file ToDoSync.xcworkspace:

open ToDoSync.xcworkspace

E. Configure and Run the Application

1

Open the project in Xcode.

  1. Navigate to the downloaded example directory and navigate to the /todo/ios directory.
  2. Open the workspace file ToDoSync.xcworkspace.
2

Update Xcode project with your MongoDB Stitch App ID.

  1. Open the TodoSync/AppDelegate.swift file.

  2. On the following line of code, repalce the <APP_ID> with your Stitch app id, and then save the file.

    let stitch = try! Stitch.initializeAppClient(withClientAppID: "<APP_ID>")
    

    Note

    In the MongoDB Stitch console, you can find your App ID at the top of the left side navigation, below the app name.

3

Run the todo app.

From the top menu bar, go to Product and select Clean. You can now run the app.