{"id":24665626,"url":"https://github.com/ditto-examples/guides-mongodb-connector","last_synced_at":"2025-03-21T10:43:44.414Z","repository":{"id":273630191,"uuid":"920357828","full_name":"ditto-examples/guides-mongodb-connector","owner":"ditto-examples","description":"Sample apps for the Ditto MongoDb Connector that uses the MongoDb Atlas \"Sample Guides\" dataset.","archived":false,"fork":false,"pushed_at":"2025-02-06T16:03:13.000Z","size":702,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-06T17:23:02.636Z","etag":null,"topics":["android","ditto","flutter","jetpack-compose","swift","swiftui"],"latest_commit_sha":null,"homepage":"https://docs.ditto.live/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ditto-examples.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-22T02:21:38.000Z","updated_at":"2025-01-30T19:10:10.000Z","dependencies_parsed_at":"2025-01-22T03:23:23.037Z","dependency_job_id":"15c01032-4901-4c5f-abe3-26994eef07a2","html_url":"https://github.com/ditto-examples/guides-mongodb-connector","commit_stats":null,"previous_names":["ditto-examples/guides-mongodb-connector"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ditto-examples%2Fguides-mongodb-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ditto-examples%2Fguides-mongodb-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ditto-examples%2Fguides-mongodb-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ditto-examples%2Fguides-mongodb-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ditto-examples","download_url":"https://codeload.github.com/ditto-examples/guides-mongodb-connector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244781733,"owners_count":20509656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","ditto","flutter","jetpack-compose","swift","swiftui"],"created_at":"2025-01-26T07:12:57.232Z","updated_at":"2025-03-21T10:43:44.408Z","avatar_url":"https://github.com/ditto-examples.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ditto - Sample MongoDB Connector `Solar System Guides` App\n\nThis is a sample application that demonstrates how to use the MongoDB Connector for Ditto with the **`guides`** sample data that comes with MongoDb Atlas. \n\n# Prerequisites\n\n## MongoDb Atlas \n\n- Basic understanding of MongoDB Atlas\n- Active MongoDB Atlas account with cluster pre-configured \n- [MongoDB Shell Installed](https://www.mongodb.com/docs/mongodb-shell/)\n\n## SwiftUI \n\n- Basic understanding of Swift and SwiftUI for SwiftUI app\n- Xcode 16 or higher\n\n## Android with Jetpack Compose\n- Basic understanding of Kotlin and Jetpack Compose for Android app\n- Android Studio \"Koala\" 2024.1.1 or higher\n\n# Setup in MongoDB Atlas\n\n## Setup Atlas User from within MongoDB Atlas\n\nFor this setup, we will need to create two different users.  One for setting up the Cluster and one for the Ditto MongoDB Connector.\n\n### Create a User for managing the Cluster\n\nOpen MongoDb Atlas and make sure you are on the Cluster Overview page.\n\n1. Click on the Database Access link under the Security section from the navigation menu on the left.\n2. Under the Database Users tab, click on the `+ ADD NEW DATABASE USER` button.\n3. Make sure Authentication Method is set to `Password`. \n4. Under the first field, add in the username for the user.  In the examples we will use the username `atlasAdmin`.\n5. Under the Password Authentication set a password for the user. \n6. Under Database User Privileges, click the `Add Built In Role` button and select the `Atlas admin` role.\n7. Click the `Add User` button.\n\n### Create a User for the Ditto MongoDB Connector\n\nMore information about why this user is needed can be found in the [Ditto documentation](https://docs.ditto.live/cloud/mongodb-connector#create-a-mongodb-database-user).\n\n1. Under the `Database Users` tab, click on the `+ ADD NEW DATABASE USER` button.\n2. Make sure Authentication Method is set to `Password`. \n3. Under the first field, add in the username for the user.  In the examples we will use the username `connector`.\n4. Under the Password Authentication set a password for the user. \n5. Under `Database User Privileges`, click the `Add Built In Role` button and select the `Read and write to any database` role.\n6. Click the `Add User` button.\n\n## Setup Atlas Networking from within MongoDB Atlas\n\nFor this setup, we will need to add the IP Addresses for Ditto Big Peer to the list of allowed IP Addresses to communicate with the MongoDB Atlas cluster.  More information can be found in the [Ditto documentation](https://docs.ditto.live/cloud/mongodb-connector#add-ditto-ips-to-mongodb-allowlist).\n\n### Add the IP Addresses for Ditto Big Peer to the list of allowed IP Addresses\n\nOpen MongoDb Atlas and make sure you are on the `Cluster Overview` page.\n\n1. Click on the `Network Access` link under the `Security` section from the navigation menu on the left.  It should open to the `IP Access List` page.\n2. Click on the `+ ADD IP ADDRESS` button.\n3. From the Add IP Access List Entry window:\n  - Add the following IP to the Access List Entry, enter:  **52.15.232.117/32**\n  - For Comments add, enter:  **Ditto-52.15.232.117** \n4. Click the `Confirm` button.\n\nRepeat this process for these IP Addresses:\n  - **3.130.255.9/32**\n  - **3.147.233.88/32**\n\n## Load the Sample Data\n\nThis sample application uses the [sample_guides](https://www.mongodb.com/docs/atlas/sample-data/sample-guides/) database from the MongoDB Atlas cluster and the planets collection.  Use the [MongoDB Atlas documentation](https://www.mongodb.com/docs/guides/atlas/sample-data/) to load the sample_guides data into your cluster before moving forward.  More information on the sample_guides data can be found [here](https://www.mongodb.com/docs/atlas/sample-data/#std-label-load-sample-data).\n\nThis dataset was chosen for its small size, which eliminates the need to load large amounts of data into MongoDB Atlas and the Ditto Portal. This makes it an efficient way to test the Ditto MongoDB Connector.\n\n## Setup Collection Settings with the MongoDB Shell\n\nDitto requires the planets collection to have change stream pre and post images enabled.  The following commands update the collection in order to enable [Change Stream Pre and Post Images](https://docs.ditto.live/cloud/mongodb-connector#create-mongodb-collections).  \n\n### Getting the MongoDb Connection String\n\nFrom Atlas, click on the Clusters link under the Database section from the menu on the left.  Next, click on the Connect button under your cluster listing.\n\nFrom the Connect window, select `Shell` from the list.  This should give you the connection string for your cluster.\n\n### Running the Commands in the MongoDB Shell\n\nWith the MongoDB Shell installed, run the following commands, replacing the srv:// with the proper connection string for your cluster and `atlasAdmin` with the username you created with admin rights to the cluster:\n\n```sh\nmongosh \"mongodb+srv://freecluster.abcd1.mongodb.net/sample_guides\" \n--apiVersion 1 --username atlasAdmin \n```\n\nOnce connected, run the following command to enable change stream pre and post images:\n\n```sh\nuse sample_guides \ndb.runCommand({ \n    collMod: \"planets\", \n    changeStreamPreAndPostImages: { enabled: true } \n})\n```\n\nKeep the MongoDB shell open as we will need it in future steps.\n\n# Setup the Ditto MongoDB Connector\n\nCurrently, the Ditto MongoDB Connector will only work with documents that have been updated since the connector was created.  This means the workflow needs to be:\n\n1. Create the Ditto MongoDB Connector in the Ditto Portal \n2. Use MongoDb Shell to update the planets collection with the `planetId`  and soft delete field `isArchived`\n3. Validate in the Ditto Portal that the documents have been synced into Ditto with the `planetId` field\n\n\n## Setup the Ditto MongoDB Connector in the Ditto Portal\n\nThe [Ditto documentation](https://docs.ditto.live/cloud/mongodb-connector#configuring-the-connector) has information about how to setup the Ditto MongoDB Connector in the Ditto Portal. \n\nThe Step-By-Step Guide can be found [here](https://docs.ditto.live/cloud/mongodb-connector#step-by-step-guide)\n\n## Updating the Planet with `planetId` and `isArchived` field\n\nGo back to the MongoDb Shell.  Run the following command to add a unique planetId field to all documents in the planets collection and setting the soft delete field `isArchived` to false.  This should update all the documents in the collection, which should trigger the Ditto MongoDB Connector to sync the documents to Ditto:\n\n```sh\ndb.planets.updateMany(\n    { planetId: { $exists: false } },\n    [\n        { \n            $set: { \n                planetId: { $toString: \"$_id\" },\n                isArchived: false \n            }\n        }\n    ]\n)\n```\n\nThis command will:\n1. Find all documents that don't have a planetId field\n2. Use the document's existing `_id` field (which is already a unique ObjectId)\n3. Convert the ObjectId to a string\n4. Add it as the planetId field\n5. Add a `isArchived` field and set it to true for [soft delete](https://docs.ditto.live/crud/delete#Zb1T7) purposes with subscription \n\n\nYou can verify the update by running:\n```sh\ndb.planets.findOne()  \n```\nIt should show a document with a planetId field, for example:\n\n```json\n{\n  \"_id\": \"621ff30d2a3e781873fcb65d\",\n  \"_mdb\": {\n    \"_id\": \"621ff30d2a3e781873fcb65d\",\n    \"ct\": [\n      1737496378,\n      185\n    ],\n    \"tm\": {\n      \"_id\": 7\n    }\n  },\n  \"hasRings\": true,\n  \"isArchived\": false,\n  \"mainAtmosphere\": [\n    \"H2\",\n    \"He\",\n    \"CH4\"\n  ],\n  \"name\": \"Uranus\",\n  \"orderFromSun\": 7,\n  \"planetId\": \"621ff30d2a3e781873fcb65d\",\n  \"surfaceTemperatureC\": {\n    \"max\": null,\n    \"mean\": -197.2,\n    \"min\": null\n  }\n}\n```\n\n## Validate the documents have been updated with the planetId field\n\nTo validate that the documents are syncing in Ditto.\n\n- Log into the [Ditto Portal](https://portal.ditto.live/).  \n- Select your app.\n- Click on the `Collections` tab\n  - You should see the planets collection with the count of documents that were synced from MongoDb Atlas.  The count should be 8 documents.  \n  - Click the `View` link for the planets collection to see the documents in the DQL Editor.\n\n\n# Setup the SwiftUI App\n\n## Setup the DittoConfig.plist file\n\nUpdate the `dittoConfig.plist` file with the proper values for `appId` and `authToken`.  You can find these values in the Ditto Portal `Connect` tab listed as the App ID and Online Playground Authentication Token.\n\nThe endpointUrl in the config file is currently used to connect to the preview environment of Big Peer that is used for the Ditto MongoDB Connector.\n\n## Run the SwiftUI App\n\nOpen the `Guides.xcodeproj` file in XCode that can be found in the Run the SwiftUI folder. \n\n# Setup the Android Jetpack Compose App\n\n## Application Permissions for Ditto\n\nThe Ditto Android SDK requires specific system permissions to enable its core functionality, including peer-to-peer synchronization and network operations. These permissions are configured through:\n\n1. Declaration in the `AndroidManifest.xml`\n2. Runtime permission handling in `MainActivity.kt`\n\nThis sample application demonstrates the recommended permission implementation. However, developers should consult the [official Ditto documentation](https://docs.ditto.live/sdk/latest/install-guides/kotlin#declaring-permissions-in-the-android-manifest) for comprehensive guidance on permission requirements and best practices when integrating the SDK into their applications.\n\nRequired permissions include:\n- Bluetooth permissions for peer-to-peer sync\n- Location permissions for BLE scanning\n- Network and WiFi permissions for cloud synchronization\n\nFor a complete list of permissions and implementation details, please refer to the documentation.\n\n## Setup the dittoConfig.xml file\n\nUpdate the `dittoConfig.xml` file found in the Android/app/src/main/res/values/ folder with the proper values for `appId` and `authToken`.  You can find these values in the Ditto Portal `Connect` tab listed as the App ID and Online Playground Authentication Token.\n\nThe `endpointUrl` in the config file is currently used to connect to the preview environment of Big Peer that is used for the Ditto MongoDB Connector.\n\n## Run the Android Jetpack Compose App\n\nOpen the `Android` folder in Android Studio.  \n\n\u003e [!NOTE] \n\u003e Make sure you open this folder specifically, otherwise Android Studio will not open the application properly because it will be missing the gradle files it needs to properly restore packages.     \n\n# Known Limitations\n\nAn updated list of known limitations with the Ditto MongoDB Connector can be found [here](https://docs.ditto.live/cloud/mongodb-connector#current-limitations).\n\n# YouTube Video\nA YouTube video that walks you through the setup can be found [here](https://www.youtube.com/watch?v=BtssEpG4m38).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fditto-examples%2Fguides-mongodb-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fditto-examples%2Fguides-mongodb-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fditto-examples%2Fguides-mongodb-connector/lists"}