Getting Started with IBM Bluemix Mobile Services (MBaaS)

I recently wrote an overview of IBM Bluemix’s Mobile Back-end as a Service offerings. I wanted to elaborate on the offerings, plus provide in-depth technical and implementation details, so I decided to produce this 5 part video series on Getting Started with IBM Bluemix Mobile Services.

This post specifically covers native iOS, though there are also Android and hybrid options available. This should have everything you need to get started. It covers all aspects from creating the app, to updating the back end, to leveraging Cloudant storage, push notifications, and monitoring & logging.

So, without further ado, let’s get started…

Part 1: Getting Started with Bluemix Mobile Services

In this first video I show how to create a new mobile app on Bluemix, connect to the cloud app instance, and implement remote logging from the client application. This process is covered in more detail in the Getting Started docs, but below are the basics from my experience.

You’ll first need to sign into your Bluemix account. If you don’t already have one, you can create a trial account for free. Once you’re signed in, you just need to create a new mobile app instance.

The process is very simple, and there is a “wizard” to guide you. The first thing that you need to do is create a new app by clicking the big “Create an App” button on your bluemix dashboard.

Create a new app from IBM Bluemix Dashboard

Next, select which kind of app you’re going to create. For MBaaS, you’ll want to select the “Mobile” option.

Next you’ll need to select your platform target. You can choose either “iOS, Android, Hybrid”, or the “iOS 8 beta” target. In this case I chose the iOS 8 beta, but the process is similar for both targets. Hybrid apps are built leveraging the Apache Cordova container.

Next, just specify an app name and click “Finish”.

Once your app is created, you will be presented with instructions how to connect the app in Xcode. I’ll get to that in a moment…

Now that your app has been created, you’ll be able to see it on your Bluemix dashboard. This app will consist of several components: a Node.js back-end instance, a Cloudant NoSQL database instance, an Advanced Mobile Access instance, and a Push instance. The Advanced Mobile Access component provides you with app analytics, user auth management, remote logging, and more. The Push component gives you the ability to manage and send push notifications (either manually, or with a rest-based API).

You app has been created – here are the components and the activity

Once your app has been created, you will need to setup the mobile app to connect to Bluemix to consume the services. Again, this is a very straightforward process.

The next step is to register your client application. Once your app is created, you will be presented with a screen to do this. If you don’t complete it right away, you can always come back later and register an application. You’ll need to specify the Bundle ID and version of your app, then you can setup any authentication (if you choose).

Register your app's bundle ID and version — Register your app’s bundle ID and version

Once your app has been registered, you need to configure Xcode. You’ll first need to create a new project in Xcode. There are two options for configuring your Xcode project: 1) automated installation using CocoaPods, or 2) manual installation. I used the CocoaPods installation simply because it is easier and manages dependencies for you.

If you aren’t familiar with CocoaPods, it is much like NPM… CocoaPods is a dependency manager for Cocoa projects. It helps you configure the Bluemix libraries and manages dependencies for you.

If you’ve got Xcode up and running, then close it and install CocoaPods, if you don’t already have it. Next open up a terminal/command prompt, go to the directory that contains your Xcode project and initialize CocoaPods using the “setup” command:

[shell]pod setup[/shell]

This will create a new file called “podfile”. Open this file in any text editor and paste the following (note: you can remove any lines that you don’t want to actually use):

[shell]source ‘https://github.com/CocoaPods/Specs.git’
# Copy the following list as is and
# remove the dependencies you do not need
pod ‘IMFCore’
pod ‘IMFGoogleAuthentication’
pod ‘IMFFacebookAuthentication’
pod ‘IMFURLProtocol’
pod ‘IMFPush’
pod ‘CloudantToolkit'[/shell]

Save the changes to the “podfile” file, and close the text editor. Then go back to your command promprt/terminal and run the installation process:

[shell]pod install[/shell]

Your project will be configured, and all dependencies will be downloaded automatically. Once this is complete, open up the newly created .xcworkspace file (Xcode Workspace).

You have to initialize the Bluemix inside of your application to connect to the cloud service to be able to take advantage of any Bluemix features (logging, data access, auth, etc…). The best place to put this is inside of your AppDelegate.m class application didFinishLaunchingWithOptions method because it is the first code that will be run within your application:

[js]- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.

// initialize SDK with IBM Bluemix application ID and route
IMFClient *imfClient = [IMFClient sharedInstance];
[imfClient
initializeWithBackendRoute:@"your route"
backendGUID:@"your guide"];

return YES;
}[/js]

One of the first features I wanted to take advantage of was remote collection of client-side logs. You can do this using the IMFLogger class, in much the same fashion as you do with OCLogger in MobileFirst Foundation server. Once great feature that requires almost no additional configuration is the captureUncaughtExceptions method, which automatically configures the Advanced Mobile Access component to collect information for all app crashes.

[js]// capture and record uncaught exceptions (crashes)
[IMFLogger captureUncaughtExceptions];

// change the verbosity filter to "debug and above"
[IMFLogger setLogLevel:IMFLogLevelDebug];

// create a logger instance
IMFLogger *logger = [IMFLogger loggerForName:@"AppDelegate"];

// log a message
[logger logDebugWithMessages:@"This is a log message from app launch."];

//send logged message to the server
[IMFLogger send];[/js]

Next, launch your app in the iOS simulator, or on a device, and you’ll see everything come together. Log into your Bluemix dashboard, and you’ll be able to monitor app analytics and remote logs.

Note: If you experience any issues connecting to the Bluemix mobile app from within the iOS simulator, just clear the iOS Simulator by going to the menu command “iOS Simulator -> Reset Content and Settings…”, and everything should connect properly the next time you launch the app.

Part 2: Configuring the Node.js Backend

In the next video, I demonstrate how to grab the code for the backend Node.js application, create a git repository on IBM JazzHub, then pull the code for local development.

There are two ways to push new backend Node.js code: 1) Using the Cloud Foundry command line API, or 2) by updating a git repository and leveraging automatic deployment from the git repo commits.

When the app is created, you’ll see an “add git” link under the app name. Using this link, you can create a git repository for the backend code.

Once your git repo has been created, you can check out the code using any Git client (I used the CLI). You’ll need to use the “npm install” command to pull down all the app dependencies. The biggest thing you need to know is that it uses express.js for the web application framework. You can make any changes that you want, and they will be automatically deployed to your Bluemix server instance upon commit. Yes, this workflow is also configurable b/c this process may not work for everyone.

One other thing that you will need to watch out for if you are doing local development: You will want to wrap the following code on line 6 in a try/catch block, otherwise you will hit errors in the local environment which will prevent your app from launching locally:

[js]try {
passport.use(new ImfBackendStrategy());
} catch ( e ) {
console.log(e);
}[/js]

Protected content behind the /protected url endpoint may not be accessible locally with this workaround, but you’ll be able to work on other pieces of your back end.

You can read more about the backend node instance for Bluemix mobile apps in the developer documentation.

Part 3: Consuming Data from Cloudant

Another part of Bluemix mobile applications is the Cloudant NoSQL database. The Cloudant NoSQL database is a powerful solution that gives you remote storage, querrying, and client-side data storage mechanisms with automatic online/offline synchronization, all with monitoring/analytics capabilities.

By default, objects within the Cloudant data store are treated as generic objects (over-simplification: think of it is an extremely powerful JSON store in the cloud). However you can also serialize your objects to strong data types within the client code configuration.

In your AppDelegate class application didFinishLaunchingWithOptions method, you’ll also want to initialize the IMFDataManager class, which is the class used for interacting with all Cloudant data operations.

[js]IMFDataManager *manager =
[IMFDataManager sharedInstance];[/js]

In my sample, I setup the database manually with open permissions, but you’ll probably want something more secure. Once your database is created, you can create indexes, search for data, create data, etc…

In the following code, I create a search index and query for data from the remote Cloudant database. You really only need to create the index if it doesn’t already exist. You can do this either through the mobile app code, or manually through the Cloudant database’s web interface. I did this inline in the following code, just for the sake of simplicity:

[js]//access the remote data store
[[IMFDataManager sharedInstance] remoteStore:@"insurancedb" completionHandler:^(CDTStore *store, NSError *error) {
// Remote store will be passed into the control handler if no errors occurred.

// create a search index
// this is an asynch operation
[store createIndexWithName:@"customerNameIndex" fields:@[@"customer"] completionHandler:^(NSError *error) {
// an error is set if index creation failed.

// Next, we search…
// Create a query with an NSPredicate
NSPredicate *queryPredicate = [NSPredicate predicateWithFormat: @"(customer > ”)"];
CDTCloudantQuery *query = [[CDTCloudantQuery alloc] initDataType:@"Claim" withPredicate:queryPredicate];

[store performQuery:query completionHandler:^(NSArray *results, NSError *error) {
// results is an array of CDTMutableDocumentRevision objects that are returned by the query

// convert to a NSArray of NSDictionary objects
// you could also serialize this to an array of strongly typed objects
NSMutableArray *array = [[NSMutableArray alloc] init];

for (CDTMutableDocumentRevision *revision in results) {
NSDictionary *body = [revision body];
[array addObject:body];
}

// do something with the data (this is specific to my app)
claimsData = array;

// reload my data table in the main thread
dispatch_async(dispatch_get_main_queue(), ^{
[self reloadData];
});

}];
}];
}];[/js]

Be sure to also read up on more of the Cloudant capabilities:

Part 4: Push Notifications

The IBM Bluemix mobile services app also contains a component for managing push notifications within your mobile applications. With this service, you can send push notifications to a specific device, a group of devices using tags, or all devices, and you can send push notifications either manually via the web interface, or as part of an automated workflow using the REST API.

You will first need to configure your app for push notifications. Apple systems using Apple’s Push Notification Service, and Android systems use Google Cloud Messaging. You must configure these hooks per the service providers.

For iOS apps, here are the basic steps for setting up the Push service. It also helps to be familiar with Local and Remote notifications in iOS.

In Xcode, open your AppDelegate class again. First you’ll need to register for remote notifications in application didFinishLaunchingWithOptions:

[js]//register for push notifications (iOS 8-specific)
[[UIApplication sharedApplication] registerUserNotificationSettings:
[UIUserNotificationSettings settingsForTypes:
(UIUserNotificationTypeSound |
UIUserNotificationTypeAlert |
UIUserNotificationTypeBadge)
categories:nil]];
[[UIApplication sharedApplication]
registerForRemoteNotifications];[/js]

Next, setup the didRegisterForRemoteNotificationsWithDeviceToken callback to register this device with the Bluemix Push service:

[js]-(void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{

// get Push instance
IMFPushClient* push = [IMFPushClient sharedInstance];

// set current working environment
push.environment = @"sandbox";

[push registerDeviceToken:deviceToken completionHandler:^(IMFResponse *response, NSError *error) {

IMFLogger *logger = [IMFLogger loggerForName:@"AppDelegate"];

if (error){
[logger logErrorWithMessages:@"error registering for push notifications: %@", error.description];
} else {
[logger logDebugWithMessages:@"registered for push notifications."];
}
}];
}[/js]

Next do something with the data whenever you receive a push notification inside of the didReceiveRemoteNotification method:

[js]-(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
//userInfo dictionary will contain data sent from server.

NSDictionary *notification = [[userInfo objectForKey:@"aps"] objectForKey:@"alert"];
NSString *body = [notification objectForKey:@"body"];

UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Notification Received"
message:body delegate:self cancelButtonTitle:@"OK"
otherButtonTitles:nil, nil];
[alert show];
}[/js]

Part 5: Monitoring and Logging

Did I mention that every action that you perform through Bluemix Mobile Services can be monitored? Analytics are available for the Advanced Mobile Access component, the Cloudant NoSQL data store, and the Push Notifications service. In addition, you also have remote collection of client logs and crash reports. This provides unparalleled insight into the health of your applications.

Need more info? You can find what you’re looking for here:

…. and of course, don’t forget the full 5-part video series available at https://www.youtube.com/playlist?list=PL0U4cUwfUs26kSKY0X-qdDNO5gKj6Lr6q

Ready to get started? Just head over to bluemix.net and create your first app!