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
-
Multiple object models support
-
Large Data Syncing
-
Manually Synchronization is also supported
-
Many-to-one relationship support
-
Available on every Apple platform(iOS/macOS/tvOS/watchOS)
-
Support Realm Lists of Natural Types
-
Complete Documentation
- Be sure to have enrolled in Apple Developer Program
- Turn on your iCloud in Capabilities and choose
CloudKit
- Turn on Background Modes and check
Background fetch
andRemote notification
- Prepare your Realm Objects (e.g. Dog, Cat...):
class Dog: Object {
@objc dynamic var id = NSUUID().uuidString
@objc dynamic var name = ""
@objc dynamic var age = 0
@objc dynamic var isDeleted = false
static let AVATAR_KEY = "avatar"
@objc dynamic var avatar: CreamAsset?
@objc dynamic var owner: Person? // to-one relationships must be optional
override class func primaryKey() -> String? {
return "id"
}
}
- Do stuff like this:
extension Dog: CKRecordConvertible {
// Yep, leave it blank!
}
extension Dog: CKRecordRecoverable {
// Leave it blank, too.
}
Is that easy? Protocol Extensions do this trick.
- Start the Engine!
var syncEngine: SyncEngine?
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
...
syncEngine = SyncEngine(objects: [
SyncObject<Person>(),
SyncObject<Dog>(),
SyncObject<Cat>()
])
application.registerForRemoteNotifications()
...
}
- Listen for remote notifications
The sample code in AppDelegate will be a good reference.
That's all you need to do! Every time you write to Realm, the SyncEngine will get notified and handle sync stuff!
For more details, clone the project to see the source code.
Yep, we highly recommend you use Soft Deletions. That's why we add an isDeleted
property to CKRecordConvertible
protocol.
When you want to delete an object, you just need to set its isDeleted
property to true and the rest of the things are already taken care of.
You also don't need to worry about cleaning-up things. It has also been considered.
Luckily, we have a perfect solution for syncing asset.
Absolutely, you could also store your image or kind of resource stuff as Data
type and everything works fine. But Realm has a 16MB limit of data property. And CloudKit encourages us to use CKAsset
in places where the data you want to assign to a field is more than a few kilobytes in size.
So taking the consideration of the above two, we recommend you to use CreamAsset
property to hold data. CreamAsset
will store local data on the file system and just save file paths in the Realm, all automatically. And we'll wrap things up to upload to CloudKit as CKAsset
.
An example project is provided to see the detailed usage.
Thanks to the CKReference in the CloudKit, IceCream has supported many-to-one relationship nicely. As the Dog
example shows, a dog may have an owner. And we'll wrap the owner up as CKReference and push them to the CloudKit.
Inversely, the Person
object has a dogs
property which is the type of LinkingObjects
. So we've successfully supported to-many relationship with a nice workaround. All make sense.
- iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+
- Swift 4.2 (For Swift 4.0, lock IceCream to 1.6.0 version)
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.
- By default, IceCream only prints some logs to your console in DEBUG mode. However, you could turn it off by adding
IceCream.shared.enableLogging = false
if it bothers you. - 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.
Using Carthage or CocoaPods.
Carthage is a decentralized dependency manager for Cocoa applications.
To integrate IceCream into your Xcode project using Carthage, specify it in your Cartfile
:
github "caiyue1993/IceCream"
Then, run the following command to build the frameworks:
carthage update
Normally, you'll get IceCream, Realm and RealmSwift frameworks. You need to set up your Xcode project manually to add these 3 frameworks.
On your application targets’ General settings tab, in the Linked Frameworks and Libraries section, drag and drop each framework to use from the Carthage/Build
folder on disk.
On your application targets’ Build Phases settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script with the following content:
/usr/local/bin/carthage copy-frameworks
and add the paths to the frameworks you want to use under “Input Files”(taking iOS platform for example):
$(SRCROOT)/Carthage/Build/iOS/IceCream.framework
$(SRCROOT)/Carthage/Build/iOS/Realm.framework
$(SRCROOT)/Carthage/Build/iOS/RealmSwift.framework
For more information about how to use Carthage, please see its project page.
IceCream is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'IceCream'
If you want to build IceCream as a static framework, CocoaPods 1.4.0+ is required.
This is the to-do list for the IceCream project. You can join us to become a contributor.
- CloudKit Shared Database
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 multiple devices to see this magic.
![](https://github.com/caiyue1993/Tiptoes/raw/master/images/appstore.png?raw=true)
- 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
This project exists thanks to all the people who contribute. Contribute.
Now IceCream has been adopted by hundreds of developers and successfully used in their apps. We're greatly humbled by your enthusiam around the projects, and want to continue to move this project forward. Your financial support will encourge me to spend more time and provide better services.
Any amount you can donate today to help us reach our goal would be greatly appreciated.
IceCream is available under the MIT license. See the LICENSE file for more info.