Simperium iOS/macOS

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.


initWithModel:context:coordinator:

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 *)coordinator
Parameters

model — The Data Model used by your application.

context — The CoreData context associated to the main thread.

coordinator — The Persistent Store Coordinator to be used.

Discussion

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:

  • Set your NSManagedObjectContext's concurrencyType to NSMainQueueConcurrencyType
  • Do not set your NSManagedObjectContext's persistentStoreCoordinator. That will be done automatically for you.


authenticateWithAppID:APIKey:rootViewController: (iOS)

- (void)authenticateWithAppID:(NSString *)identifier
	               APIKey:(NSString *)key 
	   rootViewController:(UIViewController *)controller
Parameters

identifier — 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.

Discussion

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.


authenticateWithAppID:APIKey:window:

Same as the iOS method above, but accepts an NSWindow parameter for displaying an authentication dialog in OSX apps.


authenticateWithAppID:token:

Manually authenticates Simperium with the specified token.

- (void)authenticateWithAppID:(NSString *)identifier token:(NSString *)token
Parameters

identifier — 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.

Discussion

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

Save and sync all changed objects.

- (BOOL)save
Return Value

YES 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.

Discussion

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.


backgroundFetchWithCompletion: (iOS)

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)completion
Parameters

completion — A callback block that will provide the proper UIBackgroundFetchResult value.

Discussion

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);	
	}];
}

applicationShouldTerminate: (OSX)

Provides a mechanism to safely stop Simperium: internal queues will be emptied, and app termination will proceed safely.

- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
Parameters

sender — A reference to the current NSApplication instance..

Return Value

Will always return NSTerminateLater, and once the internal threads have been safely stopped, will proceed with App Termination.

Discussion

This method was designed to be used along with NSApplicationDelegate method 'applicationShouldTerminate':

- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender {
	return [simperium applicationShouldTerminate:sender];
}

Managing Objects via SPBucket

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.

objectForKey: (SPBucket)

Returns an object that has the specified Simperium key.

- (SPEntity *)objectForKey:(NSString *)key
Parameters

key — 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..

Return Value

An entity instance if the key is found, or nil otherwise.

Discussion

This is a convenience method if you want to get an entity instance that has a particular Simperium key.


allObjects (SPBucket)

Returns an array containing all instances of a particular entity.

- (NSArray *)allObjects
Parameters
Return Value

An array of entity instances from this bucket.

Discussion

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.


Other

setVerboseLoggingEnabled:

Toggle verbose logging for debugging purposes.

- (void)setVerboseLoggingEnabled:(BOOL)on
Parameters

on — Set to YES to enable verbose logging.


signOutAndRemoveLocalData:completion:

Signs out the current user and optionally clears all locally stored data.

- (void)signOutAndRemoveLocalData:(BOOL)remove completion:(SimperiumSignoutCompletion)completion
Parameters

remove — 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.

Discussion

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.


setAuthenticationOptional:

Allows the user to cancel the authentication workflow.

- (void)setAuthenticationOptional:(BOOL)optional
Parameters

optional — Set to YES if you need to be able to cancel the authentication dialog.

Discussion

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.


setNetworkEnabled:

Enables or disables the network.

- (void)setNetworkEnabled:(BOOL)enabled
Parameters

enabled — A Boolean value indicating whether the network should be enabled (YES) or not (NO).

Discussion

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.