NimbusBase iOS Tutorial

Project Setup

Prerequisites

  • iOS 6.0 or later

Configuration

    If you are using Cocoapods, just add pod 'NimbusBase' to your "Podfile". If not, please follow this paragraph to setup your project.

  1. Add files

    Download NimbusBase iOS SDK, and uncompress it. Copy the "NimbusBase" folder into your project (select "Create groups for any added folders" if needed). The folder consists of a static library, Objective-C header files, and a resource bundle named "NimbusBaseResources.bundle". The static library is a universal binary for use on iOS device and simulator architectures (armv7/7s and i386).

  2. Link to libraries

    Check your target's "Link Binary With Libraries" build phase. Make sure your app is being linked to all of the following libraries:

    • CoreData.framework
    • libNimbusBase.a
    • MobileCoreServices.framework
    • QuartzCore.framework
    • Security.framework
    • SystemConfiguration.framework
  3. Copy resources

    Make sure "NimbusBaseResources.bundle" is included in your target's "Copy Bundle Resources" build phase. Copy Bundle Resources

  4. Add linker flags

    Update your target's (or project's) build settings to include the following "Other Linker Flags:"

    • -ObjC
    • -all_load
    Other Linker Flags

  5. Register "URL Types" (Optional)

    If you want to use Dropbox or Box, you need to register "URL Types" in your target's "Info". URL Types

  6. Header search path

    Make sure "the_path_to_NimbusBase" is included in "Library Search Paths" of your target's "Build Settings". Library Search Paths

  7. Import headers

    Include the following line to make NimbusBase available to your code:

    #import "NimbusBase.h"
  8. Open URL in app delegate

    Add the following code to your application delegate in order to complete the authentication flow:

    - (BOOL)application:(UIApplication *)application
                openURL:(NSURL *)url
      sourceApplication:(NSString *)sourceApplication
             annotation:(id)annotation{
    
        return [<Your_singleton_of_NMBase> application:application
                                                     openURL:url
                                           sourceApplication:sourceApplication
                                                  annotation:annotation];
    
    }
    			            

Usage

Config

All the magic of NimbusBase begins with NMBase. You should init it with a config dictionary and keep it as a singleton:

NMBase *base = [[NMBase alloc] initWithPSCoordinator:nil configs:<Your_config_dictionary>];
			    

Note: If you don't want to use sync function of NimbusBase, you can pass nil as first parameter. For more about 'sync', see NimbusBase iOS Sync Tutorial.

NimbusBase uses an instance of NSDictionary to config. The key and legal values are defined as follows:

KeyLegal valuesDescription
NCfgK_Servers<NSArray>Set of servers' information will be setup.
NCfgK_AppName<NSString>Name of your app, will be used to name the app folder on cloud.
NCfgK_CloudNCfgV_GDrive | NCfgV_Dropbox | NCfgV_BoxCloud provider type.
NCfgK_AppID<NSString>ID of your app, can be retrieved from app console of the cloud provider.
NCfgK_AppSecret<NSString>Secret of your app, can be retrieved from app console of the cloud provider.
NCfgK_AuthScopeNCfgV_Root | NCfgV_AppDataIndicate whether you want to access all data on the cloud or just the data it creates.

Note: In current version, only one server of each cloud provider can be configured in the dictionary.

A demo of config dictionary:

+ (NSDictionary *)configs{
    return @{
             NCfgK_Servers: @[
                     @{
                         NCfgK_AppName: kAppName,
                         NCfgK_Cloud: NCfgV_GDrive,
                         NCfgK_AppID: @"your_app_id_from_google_drive",
                         NCfgK_AppSecret: @"your_app_secret_from_google_drive",
                         },
                     @{
                         NCfgK_AppName: kAppName,
                         NCfgK_Cloud: NCfgV_Dropbox,
                         NCfgK_AppID: @"your_app_id_from_dropbox",
                         NCfgK_AppSecret: @"your_app_secret_dropbox",
                         },
                     @{
                         NCfgK_AppName: kAppName,
                         NCfgK_Cloud: NCfgV_Box,
                         NCfgK_AppID: @"your_app_id_from_box",
                         NCfgK_AppSecret: @"your_app_secret_from_box",
                         },
                     ]
             };
}
			    

If you want to use Google Drive, don't forget to turn on "Drive API" and "Drive SDK" on following page: Turn On And create a credential. Then you can get your "App ID (Client ID)" and "App secret (Client secret)". GDrive App ID

For Dropbox, you can get "App ID (App key)" and "App secret" on this page: Dropbox App ID

For Box, you can get "App ID (client_id)" and "App secret (client_secret)" on this page: Box App ID

To get information about the 3 cloud providers NimbusBase supports, please visit:

Auth

+ (void)server:(NMBServer *)server authWithViewController:(UIViewController *)viewController{
    [server authorizeWithController:viewController];
}
			    

After call method above, viewController will present a model view controller to let user enter user name and password.

If user succeeds to auth, NimbusBase will keep the access token in keychain and authorize automatically without presenting model view controller until the access token expires.

The auth state can be retrieved via the variable server.authState. It's an enum type defined as follows:

typedef NS_ENUM(NSUInteger, NMBAuthState) {
    /** In the progress of signing in. */
    NMBAuthStateSignIn,
    /** Succeed to sign in. */
    NMBAuthStateIn,
    /** In the progress of signing out. */
    NMBAuthStateSignOut,
    /** Already sign out. */
    NMBAuthStateOut,
};
			    

CRUD (Create, Retrieve, Update, Delete)

After signing in, NimbusBase needs to do some initialization work on the cloud. If it is done, the variable server.isInitialized will change from NO to YES. And only from that point your app is able to CRUD files on the cloud.

The class NMBServer has 4 methods responsible for CRUD operations:

- (NMBPromise *)createFileWithForm:(NMBFileForm *)form inParent:(NMBFile *)parent;
- (NMBPromise *)retrieveFile:(NMBFile *)file;
- (NMBPromise *)updateFile:(NMBFile *)file withForm:(NMBFileForm *)form;
- (NMBPromise *)deleteFile:(NMBFile *)file;
			    

NMBFile represents a file on the cloud, which you should never instantiate one by yourself, as they are always returned by an instance of NMBServer. NimbusBase regards folder as file too. The difference is in the callback of retrieving a file, you get an instance of NSData as response, but in the callback of retrieving folder you get an instance of NSArray, which contains its children.

NMBFileForm is responsible for collecting information of a file when you want to create or update it.

NMBPromise manages network operations. You can set success/fail callbacks on it, get its progress and more. After you get an instance of NMBPromise, don't forget to call method go on it, or nothing will happen.

Here’s a demo about how to create a new folder in the root folder:

+ (void)createFolderNamed:(NSString *)name inRootOfServer:(NMBServer *)server{

    NMBFileForm *form = [NMBFileForm folderWithName:name];
    NMBFile *root = server.root;

    NMBPromise *promise = [server createFileWithForm:form inParent:root];
    [[promise success:^(NMBPromise *promise, NMBFile *file) {

        NSLog(@"I created a folder named %@ in root folder", file.name);

    }] fail:^(NMBPromise *promise, NSError *error) {

        NMBFileForm *form = promise[NKeyPrmsForm];
        NSLog(@"Oops! An error occurred when creating folder named %@.", form.name);
        NSLog(@"Reason:%@", error.localizedFailureReason);

    }];

    [server firePromise:promise];
}
			    

Demo Project

Branch List

A todo list app powered by NimbusBase, which was promoted by Apple as "Best New Apps". Check it out on this page or iTunes.

Photo Space

To see an example of what other things NimbusBase can manage, please download our demo app on iTunes.

Open source demo

For more specific instructions, please visit our open source demo project on Github.