This is the official reference for the Simperium iOS/OSX framework. It's intended for developers who have already familiarized themselves with how Simperium works.
Additional methods and properties can be found in Simperium.h and SPBucket.h.
This is the designed initializer. After calling this method, your CoreData stack will be fully wired and ready for usage.
- (id)initWithModel:(NSManagedObjectModel *)model
context:(NSManagedObjectContext *)context
coordinator:(NSPersistentStoreCoordinator *)coordinatormodel — The Data Model used by your application.
context — The CoreData context associated to the main thread.
coordinator — The Persistent Store Coordinator to be used.
You’re responsible for creating/managing your own Core Data stack and providing it here. This is fairly easy. You can copy and paste code from the samples, or create a new Xcode project that includes Core Data and you'll be provided with boilerplate code.
Simperium Framework will move any disk operation to a background Grand Central Dispatch queue, so your UI remains smooth. As a requirement, you will need to:
- (void)authenticateWithAppID:(NSString *)identifier
APIKey:(NSString *)key
rootViewController:(UIViewController *)controlleridentifier — An application name that is set when you create your app at simperium.com.
key — The access token that is configured inside your app management panel at simperium.com.
controller — The controller that Simperium will use when it needs to display an authentication dialog.
Simperium will display a bundled Authentication User Interface when needed, using the ViewController provided here as a parent. You can fully customize the authentication UI by simply subclassing SPAuthenticationViewController, and mapping the authenticationViewControllerClass property to your own AuthViewController class.
Same as the iOS method above, but accepts an NSWindow parameter for displaying an authentication dialog in OSX apps.
Manually authenticates Simperium with the specified token.
- (void)authenticateWithAppID:(NSString *)identifier token:(NSString *)tokenidentifier — An application name that is set when you create your app at simperium.com.
token — The authentication token that should be used to initialize Simperium Sync.
Although Simperium already ships with Authentication UI mechanisms, there might be some scenarios in which you wish to perform manual authentication.
This method allows you to manually authenticate a Simperium instance with an authToken, and initiate Sync'ing. Such token can be either generated manually in your App's Dashboard, or obtained through our backend API, and consumed by your cocoa app.
Save and sync all changed objects.
- (BOOL)saveYES if the context was saved successfully, NO otherwise (critical error). It’s possible that YES will be returned even though a sync does not occur, for example due to a network error. Simperium handles all network errors automatically (including changes that are saved while offline), so no action is required as long as YES is returned.
This is a convenience method. You can also save your NSManagedObjectContext instance directly if you prefer. Simperium is able to detect and manage all online and offline changes.
Apple iOS 7 (and higher) implements a mechanism that helps your app to stay always in sync: when enabled, the OS itself will wake up your app periodically, and grant a finite amount of time to perform any operations required.
We've designed Simperium's performFetchWithCompletionHandler helper method to smoothly integrate with UIApplicationDelegate's API. When called, it will retrieve any new changes available, and hit the completion handler when ready.
- (void)backgroundFetchWithCompletion:(SimperiumBackgroundFetchCompletion)completioncompletion — A callback block that will provide the proper UIBackgroundFetchResult value.
Please, refer to Apple's documentation regarding how to enable Background Fetch in your app.
- (void)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[simperium backgroundFetchWithCompletion:^(UIBackgroundFetchResult result) {
completionHandler(result);
}];
}Provides a mechanism to safely stop Simperium: internal queues will be emptied, and app termination will proceed safely.
- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sendersender — A reference to the current NSApplication instance..
Will always return NSTerminateLater, and once the internal threads have been safely stopped, will proceed with App Termination.
This method was designed to be used along with NSApplicationDelegate method 'applicationShouldTerminate':
- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender {
return [simperium applicationShouldTerminate:sender];
}You can call bucketNamed: on your Simperium instance to get access to individual buckets. A bucket maps to each entity type in your Core Data model. The bucket instance gives you lower level access to your objects if you need it. The SPBucketDelegate protocol allows you to receive fine grained notifications as data in a bucket changes.
Returns an object that has the specified Simperium key.
- (SPEntity *)objectForKey:(NSString *)keykey — An identifier that is unique across any given entity class. These keys are used to globally identify a particular instance. They’re usually automatically created when you call insertNewObjectForEntityForName: but you can also specify your own by setting the simperiumKey property on your object after creating it..
An entity instance if the key is found, or nil otherwise.
This is a convenience method if you want to get an entity instance that has a particular Simperium key.
Returns an array containing all instances of a particular entity.
- (NSArray *)allObjectsAn array of entity instances from this bucket.
This is a convenience method for getting an array of all entity instances. It’s useful if you need to perform some kind of processing, for example a manual sort.
Toggle verbose logging for debugging purposes.
- (void)setVerboseLoggingEnabled:(BOOL)onon — Set to YES to enable verbose logging.
Signs out the current user and optionally clears all locally stored data.
- (void)signOutAndRemoveLocalData:(BOOL)remove completion:(SimperiumSignoutCompletion)completionremove — Set to YES to remove all local data for the signed in user.
completion — The callback to be executed as soon as signOut is completed.
Usually you should clear local data, which can be restored in the future when that users signs in again and the data is pulled from the network.
Due to the multi-threaded nature of Simperium, the signout mechanism is an asynchronous operation. If needed, you may provide a callback to be executed when signout is complete.
Allows the user to cancel the authentication workflow.
- (void)setAuthenticationOptional:(BOOL)optionaloptional — Set to YES if you need to be able to cancel the authentication dialog.
By setting this flag to true, your users will be able to dismiss the authentication interface. This is useful in scenarios in which Sync is an optional functionality.
Enables or disables the network.
- (void)setNetworkEnabled:(BOOL)enabledenabled — A Boolean value indicating whether the network should be enabled (YES) or not (NO).
If you need to support enabling or disabling network transmissions (for example, if you provide this option to your users), you can call setNetworkEnabled: at any time. Simperium will gracefully cancel all current requests and pick up where it left off next time the network is enabled.
The network is enabled by default.