Login
The Wasabi Sync system is broken up into several different components. There's the admin interface, a Mac framework, a static library for iOS, and an optional web service REST API.
The first step in using Wasabi Sync in your app is to add your app to the admin interface. If you click here the admin interface will open in a new window so you can keep reading this documentation and follow along.
To add an app to the admin interface, you'll need just two bits of information: The application name, and an application identifier. The application name can be anything you want. The application identifier, however, will be used to uniquely identify your app and must not conflict with any other applications. We suggest using reverse dns notation for the identifier. An example would be something like: com.yourcompany.yourappname. Later, when you do data migrations with your app, you may even want to include a version number in your app identifier so that your data doesn't cross versions.
Once you have these two items, simply log into the admin interface, and click the "Create Application" button. Enter the name and identifier, and then your app will be ready to go.
You'll need an API key for when you add the SDK to your application, so once you've added your application, click the "Add" button under the API keys panel. It will prompt you for a name for your key. API keys can be deleted at any time, allowing you to disable access to your data for a given application. This is useful in cases when you may give other developers the ability to write to your data store on the Wasabi Sync servers. If you need to later disallow their access, you can simply delete their key. For average use, however, you'll only need one API key, so you can name it whatever you want. You'll want to copy and paste it into your code when you're adding the SDK.
The admin interface has lots of other capabilities, including the ability to browse your customer data, export your customer list, and view the total number of transactions, users, and data objects in the system.
Download the SDK. The SDK comes in two forms, a framework for Mac OS, and a static library for iOS. Although it's in two different forms, the steps to use the SDK in Xcode are basically identical for each.
If you're using the iOS library, drag and drop the libWasabiSynciOS folder into your project. When prompted, choose to copy the files into your project if needed. Once the files are in your project, drill down into the libWasabiSynciOS folder and find the two .a files.
Wasabi Sync currently relies on TouchJSON for JSON serialization. Although it's recommended that you use our bundled version of TouchJSON, this might cause an issue for you if you already have TouchJSON in your app. If so, use the -noTouchJSON version of the .a files. Once you've decided which version of the library you want to use, just delete the other one altogether.
Next, you need to add the -all_load flag to your Other Linker Flags setting in your Xcode project. You can do this by clicking the blue icon in your project, and then choosing "Build Settings".
Finally, Wasabi Sync also requires libz. To add libz go to the "Build Phases" tab in your project settings, find "Link Binary With Libraries" and click the "+" button there. Then choose libz.dylib and hit "OK".
Add the framework or library to your project by visiting your project settings, and then clicking on the "Build Phases" tab. Find the "Link Binary With Libraries" section, and click the "+" button. Click "Add Other" on the browse window showing the system libraries, and then find the framework or static library for Wasabi Sync. Once this is done, you'll need to add a few small changes to your application to tell start the sync system and to tell Wasabi Sync what objects are "Syncable."
Wasabi Sync uses a custom protocol to determine which objects to sync. This protocol is the WHISyncableObject protocol. Wasabi Sync will only sync Core Data objects which implement this protocol.
The WHISyncableObject protocol specifies one required method, guid. This method is up to you to implement on your Core Data objects. You must implement it to return a globally unique identifier for your object. This identifier will identify your object in the Wasabi Sync system.
We find the best way to handle this is to add an attribute to your managed object called "guid" and have your model class create a value for this attribute and set it in your managed object model class -awakeFromInsert method. An example implementation of this, would be something like:
-(NSString *)generateGuid
{
CFUUIDRef uuid = CFUUIDCreate(kCFAllocatorDefault);
NSString* str = (__bridge_transfer NSString *)CFUUIDCreateString(kCFAllocatorDefault, uuid);
CFRelease(uuid);
return str;
}
-(void)awakeFromInsert
{
[super awakeFromInsert];
[self setGuid:[self generateGuid]];
}
There are other methods on the WHISyncableObject protocol which you can use to customize the behavior of Wasabi Sync. See the WHISyncableObject protocol documentation for details.
The WHISyncController class is the main entry point for starting and interfacing with the Wasabi Sync subsystem. Currently this is a singleton, but you should not rely on this behavior as this is likely to change in future releases.
To begin synchronizing data, You should first initialize the system by using the +globalInstanceWithServerURL:contextCreator: class method. This should be done early in your application launch cycle. You should also set the appId and apiKey. These values correspond to the application identifier and API key you set up earlier.
Finally, you should log in using the -loginWithEmailAddress:password:callback: method. The sync engine can be started without logging in, but no data will actually flow to the server until you log in.
For the purposes of testing, you can log in using your own Wasabi Sync developer account username and password. A typical initialization would look something like the following:
WHISyncController *sync = [WHISyncController globalInstanceWithServerURL:@"http://www.wasabisync.com/"
contextCreator:^NSManagedObjectContext *
{
return {... code to create new NSManagedObjectContexts for your app ...} ;
}];
[sync setAppId:@"com.yourcompany.yourapp"];
[sync setApiKey:@"yourkey"];
// load old saved transactions...
[sync load];
// start syncing!
[sync start];
// typically you will have asked the user for their email address and password as part of
// an account setup screen in your app. Here, for the purposes of example, you can just
// use your own email address and password as you used when you set up your developer account.
[sync loginWithEmailAddress:@"you@somewhere.com" password:@"yourpassword" callback:nil];
The call to -load loads the synchronization state, if any, that was previously saved. This allows any transactions which are currently in progress to be saved to disk so that they can be continued later. There is a corresponding -save method which you can put in your application shutdown sequence to save the synchronization state.
The purpose of the context creator block is to give the synchronization system a mechanism for creating new NSManagedObjectContexts as needed. The synchronization system uses background threads in some operations. In these cases, it needs to be able to create new contexts that can be used with these threads. Therefore, it is very important that the context returned from this block is not your main thread context. It is generally preferred that the code used here returns a new context whenever this block is executed.
Eventually, you will need to add an interface in your app to create an account and/or login to an existing account. When you do this, you'll want to use the login and logout methods on the WHISyncController to log in. You should store the user's email address and password using the keychain API to insure it is secure. Never store the user's password in the clear.
Once you've done this, your data should start syncing with the server, and you should be able to browse it there.
Wasabi Sync also fires notifications when it starts and finishes a synchronization cycle. You can watch for the STARTED_SYNC and ENDED_SYNC notifications. See the WHISyncController documentation for more information.
When data is synchronized with the server, your app will send your changes up, and then download any modifications that the server has. These modifications are saved to your persistent store in the background using a background thread. This can have some impact on how you architect your app.
To update your UI with the latest changes, you will want to listen for the NSManagedObjectContextDidSave notification, and use it to refresh any data that you may be displaying at the time of the update.
It should be noted, and this is very important: Updates from the server occur in a background thread, so your handler for the NSManagedObjectContextDidSave notification MUST be threadsafe and you may NOT access the managed objects in the notification directly in alternate threads.
In particular, all UI updates should occur in your application's main thread, so if you're updating your UI, you should note the change, but then dispatch the actual updates to the main thread using something like:
[[NSOperationQueue mainQueue] addOperationWithBlock:^{ ... your UI updating code goes here ... }];
The Wasabi Sync server has a REST API that allows you to access your customer's data using your own backend systems. To find out how, see the REST API Documentation
Email us at: support@wasabisync.com