mrfufufu / icecream Goto Github PK

IceCream helps you sync Realm Database with CloudKit.

"It works like magic!"

• Realm Database

  • Off-line First
  • Thread Safety
  • Reactive Programming
  • Optimized for mobile apps
  • Easy when migrating

• Apple CloudKit

  • Automatical Authentication
  • Silent Push
  • Free with limits(Private database consumes your user's iCloud quota)

• Delta update

• Reachability(Support Long-lived Operation)

• Powerful Error Handling

• Sync Automatically

• Manually Synchronization is also supported

• User Account Status Check

• Complete Documentation

1. Be sure to have enrolled in Apple Developer Program

2. Turn on your iCloud in Capabilities and choose CloudKit

3. Turn on Background Modes and check Background fetch and Remote notification

1. Prepare your Realm Object(e.g. Dog)

class Dog: Object {
    @objc dynamic var id = NSUUID().uuidString
    @objc dynamic var name = ""
    @objc dynamic var age = 0
    @objc dynamic var isDeleted = false

    override class func primaryKey() -> String? {
        return "id"
    }
}

2. Do stuffs like that

extension Dog: CKRecordConvertible {
    // Yep, leave it blank!    
}

extension Dog: CKRecordRecoverable {
    typealias O = Dog
}

Is that easy? Protocol Extensions do this trick.

3. Start the Engine!

var syncEngine: SyncEngine<Dog>?
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    ...
    syncEngine = SyncEngine<Dog>()
    application.registerForRemoteNotifications()
    ...
}

That's all you need to do! Everytime you write to Realm, the SyncEngine will get notified and handle sync stuffs!

For more details, clone the project to see the source code.

Yep, we highly recommend you use Soft Deletions. That's why we add a isDeleted property to CKRecordConvertible protocol.

When you want to delete a object, you just need to set its isDeleted property to true. And the rest of things are already taken care of.

You also don't need to worry about the clean-up things. It has also been considered.

Example project is provided to see the detailed usage.

• iOS 10.0+
• Swift 4
• Realm Swift ~> 3.0

It's true that debugging CloudKit is hard and tedious. But I have some tips for you guys when facing puzzles.

• You should know how Realm and CloudKit works.
• Using GUI tools, like Realm Browser and CloudKit Dashboard.
• When you are lost and don't remember where you are, I suggest starting all over again. In CloudKit Dashboard, "Reset..." button is provided. You can also clear local database by re-install apps.
• Keep calm and carry on!

Warning: If you're going to launch your app onto App Store, don't forget to deploy your environment settings to production. You can do it easily in the CloudKit Dashboard. Write & Read permissions are also need to be considered.

How to debug CloudKit in production mode? See this post.

To run the example project, clone the repo, and run pod install from the Example directory first.

IceCream is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'IceCream', '~> 1.1.0'

These are the to-do list in IceCream project. You can join us to become a contributor.

• CKReference & Realm's LinkingObjects
• CloudKit Shared Database
• Other platforms supported, like macOS, tvOS and watchOS
• Multiple objects supported

See the CONTRIBUTING file for contributing guidelines.

My app Sprint(A lightweight task management app) is using IceCream. You can download it and try it on your muiltiple devices to see this magic.

If your app has adopted IceCream, feel free to raise a PR to add to this page.

• Synchronizing data with CloudKit(Recommended)
• CloudKit Best Practices
• Mastering Realm Notifications

By now, IceCream is mainly maintained by myself. I'd be appreciated if you could be a backer to support the maintenance of IceCream. Thank you to all our backers! Become a backer

Support this project by becoming a sponsor. Your logo will show up here with a link to your designated website. Become a sponsor

IceCream is available under the MIT license. See the LICENSE file for more info.