Serving Data to the Apple Watch with IBM MobileFirst

This is the third entry in my series on powering Apple Watch apps using IBM MobileFirst.  In the first post I covered setting up the project, remote logging, and analytics. In the second post I covered bidirectional communication between the WatchKit extension and host app (not really MobileFirst, but still applicable).  In this post we’ll examine how to consume data from the MobileFirst Foundation Server inside of an Apple Watch app.

If you’re already familiar with consuming data using MobileFirst Adapters, then guess what… it is *exactly* the same as consuming an Adapter in a native iOS project. Since the logic for a WatchKit app is executed in the WatchKit extension, which is actually an executable that runs on the phone, there is no difference between between the two.

If you aren’t familiar with Adapters, they are server-side code that is used to transfer and retrieve information from back-end systems to client applications and cloud services.  You can write them in either Java or JavaScript, they can be consumed in any MobileFirst app, and they offer security, data transformation, and reporting metrics out of the box.

In the video below I walk through the process of recreating the Apple Watch Stocks app using data delivered from a MobileFirst Platform Foundation server instance. The data is simulated, so don’t use it for any investments. :)

The basic process was this: build out the Apple Watch apps user interface in Xcode/Interface Builder, build the adapters to expose the data, then start consuming the data within the WatchKit extension to deliver it to the watch app interface.

Full source code for this project is available at: https://github.com/triceam/MobileFirst-WatchKit/tree/master/Stocks

The User Interface

So, lets first look at the app interface.  I have two views that were built in Interface Builder.  One is a table that displays rows of data, one is a details screen which has lots of labels used to display data.

applewatch-ui

In the main interface I have a “loading…” label (that is hidden once the data is loaded) and a table that is used to display data.  For each row in the table there are 3 labels to display specific data fields. These were connected to IBOutlet references in the view controller class. All of these are straightforward WatchKit development practices.  Be sure to check out the WKInterfaceTable class reference for more detail on working with WatchKit tables.

Xcode-Interface Builder for Table View
Xcode-Interface Builder for Table View

For displaying the details screen, I also used very similar pattern.  I added labels for displaying data, and linked them to IBOutlet references in my view controller so I can change their values once the data is loaded.

Xcode-InterfaceBuilder Detail View
Xcode-InterfaceBuilder Detail View

Serving Data

Loading data into a WatchKit extension is identical to making a request to the MobileFirst server adapter from a native iOS app.  I did use my helper class so I can use code blocks instead of the delegate patter, but the implementation is exactly the same.

So, here’s how we can create an adapter using the MobileFirst Command Line Interface.  Use the “mfp add adapter” command and follow the prompts:

$ mfp add adapter
[?] What do you want to name your MobileFirst Adapter? StocksAdapter
[?] What type of adapter would you like?
 Cast Iron
 HTTP
 Java
 JMS
 SAP JCo
 SAP Netweaver Gateway
❯ SQL
 [?] Create procedures for offline JSONStore? No
 A new sql Adapter was added at /Users/andrewtrice/Documents/dev/MobileFirst-Stocks/server/MFStocks/adapters/StocksAdapter

Adapters can be used to easily connect back end systems to mobile clients.  You can quickly and easily expose data from a relational database, or even consume data from http endpoints and easily serialize it into a more compact mobile-friendly format.  You should definitely read more about MobileFirst adapters through the platform documentation for more detail.

What’s also great about the MobileFirst platform is that you get operational analytics for all adapters out of the box, with no additional configuration.  You can see the number of requests, data payload sizes, response times, devices/platforms used to consumes, and much more.  Plus, you can also remotely access client log messages from the mobile devices.  Take a look at the screenshots below for just a sample (these are from my dev instance on my laptop):

All of the data I am displaying is simulated.  I’m not actively pulling from a relational database or live service. However, you could use a very similar method to connect to a live data repository.

I exposed two pretty basic procedures on the MobileFirst server: getList – which returns a stripped down list of data, and getDetail – which returns complete data for a stock symbol:

function getList() {

  simulateData();

  var items = [];
  var trimmedProperties = ["symbol","price","change"];

  for (var i=0; i<data.length; i++) {
    var item = {};
    for (var j in trimmedProperties) {
      var prop = trimmedProperties[j];
      item[prop] = data[i][prop];
    }
    items.push(item);
  }

  return {
    "stocks":items
  };
}

function getDetail(symbol) {

  for (var i=0; i<data.length; i++) {
    if (data[i].symbol == symbol) {
      return data[i];
    }
  }
  return null;
}

Once these are deployed to the server using the CLI “mfp bd” command, you can invoke the adapter procedures from a client application, regardless of whether it is native iOS, native Android, or hybrid application.

Consuming the Data

OK, now we’re back to the native iOS project.  In either Objective-C or Swift you can invoke an adapter directly using the WLResourceRequest or invokeProcedure mechanisms.  In my sample I used a helper class to wrap invokeProcedure to support code blocks, so I can define the response/failure handlers directly inline in my code.  So, in my code, I invoke the adapters like so:

-(void) getList:(void (^)(NSArray*))callback{

  WLProcedureInvocationData *invocationData =
    [[WLProcedureInvocationData alloc]
      initWithAdapterName:@"StockAdapter"
          procedureName:@"getList"];

  [WLClientHelper invokeProcedure:invocationData successCallback:^(WLResponse *successResponse) {

    NSArray *responseData = [[successResponse responseJSON] objectForKey:@"stocks"];
    //do something with the response data

  } errorCallback:^(WLFailResponse *errorResponse) {

    //you should do better error handling than this
  }];
}

Once you have the data within the WatchKit extension, we can use it to update the user interface.

For the data table implementation, you simply need to set the number of rows, and then loop over the data to set values for each row based on the WKInterfaceTable specification.

[self.dataTable setNumberOfRows:[self.stocks count] withRowType:@"stockTableRow"];

for (NSInteger i = 0; i < self.dataTable.numberOfRows; i++) {

  StockTableRow* row = [self.dataTable rowControllerAtIndex:i];
  NSDictionary* item = [self.stocks objectAtIndex:i];

  [row.stockLabel setText:[item valueForKey:@"symbol"]];

  NSNumber *price = [item valueForKey:@"price"];
  NSNumber *change = [item valueForKey:@"change"];
  [row.priceLabel setText:[NSString stringWithFormat:@"%-.2f", [price floatValue]]];
  [row.changeLabel setText:[NSString stringWithFormat:@"%-.2f", [change floatValue]]];

  if ([change floatValue] > 0.0) {
    [row.changeLabel setTextColor: [UIColor greenColor]];
    [row.containerGroup setBackgroundColor:[UIColor colorWithRed:0 green:0.2 blue:0 alpha:1]];
  } else if ([change floatValue] < 0.0) {
    [row.changeLabel setTextColor: [UIColor redColor]];
    [row.containerGroup setBackgroundColor:[UIColor colorWithRed:0.2 green:0 blue:0 alpha:1]];
  }
  else {
    [row.changeLabel setTextColor: [UIColor whiteColor]];
    [row.containerGroup setBackgroundColor:[UIColor colorWithRed:0.15 green:0.15 blue:0.15 alpha:1]];
  }
}

For the detail screen we’re also doing things even more straightforward.  When the screen is initialized, we request detail data from the server.  Once we receive that data, we’re simply assigning label values based upon the data that was returned.

[self.nameLabel setText:[stockData objectForKey:@"name"]];

NSNumber *change = [stockData objectForKey:@"change"];
NSNumber *price = [stockData objectForKey:@"price"];
NSNumber *high = [stockData objectForKey:@"high"];
NSNumber *low = [stockData objectForKey:@"low"];
NSNumber *high52 = [stockData objectForKey:@"high52"];
NSNumber *low52 = [stockData objectForKey:@"low52"];
NSNumber *open = [stockData objectForKey:@"open"];
NSNumber *eps = [stockData objectForKey:@"eps"];

float percentChange = [change floatValue]/[price floatValue];

[self.priceLabel setText:[NSString stringWithFormat:@"%-.2f", [price floatValue]]];
[self.changeLabel setText:[NSString stringWithFormat:@"%.02f (%.02f%%)", [change floatValue], percentChange]];

if ([change floatValue] > 0.0) {
	[self.changeLabel setTextColor: [UIColor greenColor]];
} else if ([change floatValue] < 0.0) {
	[self.changeLabel setTextColor: [UIColor redColor]];
}
else {
	[self.changeLabel setTextColor: [UIColor whiteColor]];
}

//update change with percentage

[self.highLabel setText:[NSString stringWithFormat:@"%-.2f", [high floatValue]]];
[self.lowLabel setText:[NSString stringWithFormat:@"%-.2f", [low floatValue]]];
[self.high52Label setText:[NSString stringWithFormat:@"%-.2f", [high52 floatValue]]];
[self.low52Label setText:[NSString stringWithFormat:@"%-.2f", [low52 floatValue]]];

[self.openLabel setText:[NSString stringWithFormat:@"%-.2f", [open floatValue]]];
[self.epsLabel setText:[NSString stringWithFormat:@"%-.2f", [eps floatValue]]];
[self.volLabel setText:[stockData objectForKey:@"shares"]];

What next?

Ready to get started?  Just download the free MobileFirst Platform Server Developer Edition, and get started.

Complete source code for this project is available on my github account at: https://github.com/triceam/MobileFirst-WatchKit/tree/master/Stocks

Series on Apple WatchKit Apps powered by IBM MobileFirst:

 

Enjoy!

 

 

Using Code Blocks Instead of Delegates with IBM MobileFirst Platform in Native iOS Apps

We’ve been able to write native iOS apps leveraging the scaffolding and analytics of the IBM MobileFirst Platform Foundation Server for a while now. This was first introduced way back when MobileFirst still went by the Worklight name, serveral versions ago.

As I would write apps, one thing I really wanted was to use code blocks instead of having to implement delegate classes every time I need to call a procedure on the MobileFirst server.   In MobileFirst 7.0, the new WLResourceRequest API allows you to invoke requests using either the completionHandler (code block) or delegate implementations.

But… what if you’re still using an earlier version of the MobileFirst platform, or what if you still want to leverage your existing code that uses WLProcedureInvocationData parameters, but don’t want to have to create a new delegate for every request?  Well, look no further.  I put together a very simple utility class that helps with this task by allowing you to pass code blocks as parameters for the requests to the MobileFirst (or Worklight) server.

You can grab the Objective-C client-side utility class from https://github.com/triceam/MobileFirst-Helper

Right now it only contains two utlitiy methods, but I’ll update it if I i come up with anything else useful. 

The invokeProcedure method allows you to invoke a procedure and pass code blocks for success/error callbacks inline, without having to define delegates.

WLProcedureInvocationData *invocationData =
    [[WLProcedureInvocationData alloc]
        initWithAdapterName:@"StockAdapter"
              procedureName:@"getList"];

[WLClientHelper invokeProcedure:invocationData
  successCallback:^(WLResponse *successResponse) {

    //handle the response
  }
  errorCallback:^(WLFailResponse *errorResponse) {

    //handle the error response
}];

I normally prefer code blocks b/c they allow you to encapsulate functionality inside of a single class, instead of having logic spread between a controller and delegate class (and having to worry about communication between the two).

The other getLoggerForInstance utility function is just a shortcut to get an OClogger instance with the package string matching the class name of the instance passed, with just a single line of code:

OCLogger *logger = [WLClientHelper getLoggerForInstance:self];

Download the utility directly from https://github.com/triceam/MobileFirst-Helper

Enjoy!

Say What? Live video chat between iOS & WebRTC with Twilio & IBM Watson Cognitive Computing in Real Time

What I’m about to show you might seem like science fiction from the future, but I can assure you it is not. Actually, every piece of this is available for you to use as a service.  Today.

Yesterday Twilio, an IBM partner whose services are available via IBM Bluemix, announced several new SDKs, including live video chat as a service.  This makes live video very easy to integrate into your native mobile or web based applications, and gives you the power to do some very cool things. For example, what if you could add video chat capabilities between your mobile and web clients? Now, what if you could take things a step further, and add IBM Watson cognitive computing capabilities to add real-time transcription and analysis?

Check out this video from yesterday’s Twilio Signal conference keynote, where fellow IBM’ers Damion Heredia and Jeff Sloyer demonstrate exactly this scenario; the integration of the new Twilio video SDK between iOS native and WebRTC client with IBM Watson cognitive computing services providing realtime transcription and sentiment analysis.

If it doesn’t automatically jump to the IBM Bluemix Demo, skip ahead to 2 hours, 15 min, and 20 seconds.

Jeff and Damion did an awesome job showing of both the new video service and the power of IBM Watson. I can also say first-hand that the new Twilio video services are pretty easy to integrate into your own projects (I helped them integrate these services into the native iOS client (physician’s app) shown in the demo)!  You just pull in the SDK, add your app tokens, and instantiate a video chat.   Jeff is pulling the audio stream from the WebRTC client and pushing it up to Watson in real time for the transcription and sentiment analysis services.

Bidirectional Communication Between An Apple Watch Extension and the Host App

In this entry we’re going to focus on building Apple Watch apps that can communicate back and forth with the host application running on the iPhone.  This is extremely important since the Apple Watch provides a second screen/peripheral complimentary experience to the main app running on the iOS device – be it a remote control, or quick view/glance into whats happening within the bigger picture.

In my last post I showed how to setup remote logging and instrumentation/analytics in an Apple Watch app using IBM MobileFirst Platform Foundation server.   I used the methods described below for communicating between the WatchKit and host apps in the sample app from that previous post.

When we’re talking about bidirectional communication, we’re talking about sending data two ways:

  1. Sending data from the host app to the WatchKit app
  2. Sending data to the WatchKit app from the host app

At first thought, you might think “oh that’s easy, just use NSNotificationCenter to communicate between the separate classes of the application”, but things aren’t exactly that simple.

An Apple Watch app is really made of 3 parts: 1) the main iOS application binary, 2) the user interface on the Apple Watch, and 3) the WatchKit extension binary (on the iOS device).

Apple Watch App - Architectural Components
Apple Watch App – Architectural Components

Yep, you read that correctly, the WatchKit extension (which controls all of the logic inside the Apple Watch UI and resides on the iOS device) is a separate binary from the “main” iOS application binary.  These are separate processes, so objects in memory in the main app are not the same objects in memory in the extension, and as a result, these processes do not communicate directly. NSNotificationCenter isn’t going to work.

However there are definitely ways you can make this type of a scenario work.

First, WatchKit has methods to invoke actions on the host application from the WatchKit extension.  WatchKit’s openParentApplication or handleWatchKitExtensionRequest methods both provide the ability to invoke actions and pass data in the containing app, and provide a mechanism to invoke a “reply” code block back in the WatchKit extension after the code in the host application has been completed.

For example, in the WatchKit extension, this will invoke an action in the host application and handle the reply:

[WKInterfaceController openParentApplication:@{@"action":@"toggleStatus"} reply:^(NSDictionary *replyInfo, NSError *error) {
    [logger trace:@"toggleStatus reply"];
    [self updateUIFromHost:replyInfo];
}];

Inside the host application we have access to the userInfo NSDictionary that was passed, and we can respond to it accordingly. For example, in the code below I am setting a string value on the userInfo instance, and taking appropriate actions based upon the value of that string.

- (void)application:(UIApplication *)application
handleWatchKitExtensionRequest:(NSDictionary *)userInfo
  reply:(void (^)(NSDictionary *replyInfo))reply {

  //handle this as a background task
  __block UIBackgroundTaskIdentifier watchKitHandler;
  watchKitHandler = [[UIApplication sharedApplication] beginBackgroundTaskWithName:@"backgroundTask"
            expirationHandler:^{
              watchKitHandler = UIBackgroundTaskInvalid;
            }];

  NSString *action = (NSString*) [userInfo valueForKey:@"action"];
  [logger trace:@"incoming request from WatchKit: ", action];

  LocationManager * locationManager = [LocationManager sharedInstance];

  NSMutableDictionary *result = [[NSMutableDictionary alloc] init];

  if ([action isEqualToString:@"toggleStatus"]) {
    //toggle whether or not we're actually tracking the location
    [locationManager toggleTracking];
  } else if ([action isEqualToString:@"stopTracking"]) {
    [locationManager stopTracking];
  } else if ([action isEqualToString:@"currentStatus"]) {
    //do nothing for now
  }

  NSString *trackingString = [NSString stringWithFormat:@"%s", locationManager.trackingActive ? "true" : "false"];
  [result setValue:trackingString forKey:@"tracking"];
  reply(result);

  dispatch_after( dispatch_time( DISPATCH_TIME_NOW, (int64_t)NSEC_PER_SEC * 1 ), dispatch_get_global_queue( DISPATCH_QUEUE_PRIORITY_DEFAULT, 0 ), ^{
    [[UIApplication sharedApplication] endBackgroundTask:watchKitHandler];
  } );
}

This covers the “pull” scenario, and is great if you want to invoke actions within your host app from your WatchKit extension, and then handle the responses back in the WatchKit extension to update your Apple Watch UI accordingly.

What about the “push” scenario?  The previous scenario only covers requests that originate inside the WatchKit extension.  What happens if you have a process running inside of your host app, and have updates that you want to push to the WatchKit extension without an originating request?

There is no shared memory, and it is not a shared process, so neither NSNotificationCenter or direct method invocation will work. However, you *can* use Darwin notifications (which work across seprate processes by using CFNotificationCenter).  This enables near-realtime interactions across processes, and you can share data as attributes of a CFdictionary object based between processes. You can also share larger amounts of data using access groups, and notify the separate processes using the CFNotificationCenter implementation.

Note: CFNotificationCenter is C syntax, not Objective-C syntax.

First you’ll need to subscribe for the notifications in the WatchKitExtension. Pay attention to the static id instance “staticSelf”… you’ll need this later when invoking Objective-C methods from the C notification callback.

static id staticSelf;

- (void)awakeWithContext:(id)context {
  [super awakeWithContext:context];

  //add your initialization stuff here

  CFNotificationCenterAddObserver(CFNotificationCenterGetDarwinNotifyCenter(), (__bridge const void *)(self), didReceiveTrackingStatusNotificaiton, CFSTR("TrackingStatusUpdate"), NULL, CFNotificationSuspensionBehaviorDrop);

  staticSelf = self;
}

From within your host app you can invoke CFNotificationCenterPostNotification to invoke the Darwin Notification.

-(void) postTrackingStatusNotificationToWatchKit {

  NSString *trackingString = [NSString stringWithFormat:@"%s", self.trackingActive ? "true" : "false"];

  NSDictionary *payload = @{@"tracking":trackingString};
  CFDictionaryRef cfPayload = (__bridge CFDictionaryRef)payload;

  CFNotificationCenterPostNotification(CFNotificationCenterGetDarwinNotifyCenter(), CFSTR("TrackingStatusUpdate"), (__bridge const void *)(self), cfPayload, TRUE);
}

Then in the WatchKit extension, handle the notification, and update your WatchKit extension accordingly.

void didReceiveTrackingStatusNotificaiton() {
  [staticSelf respondToPostFromHostApp];
}

We’ve now covered scenarios where you you can request data or actions in the host application *from* the WatchKit extension, and also how you can push data from the host application to the WatchKit extension.

Now, what if there was a library that encapsulated some of this, and made it even easier for the developer?  When I wrote the app in my previous post, I used the methods described above. However, I recently stumbled across the open source MMWormhole, which wraps the Darwin Notifications method (above) for ease of use.  I’m pretty sure I’ll be using this in my next WatchKit app.

Helpful Links for inter-process communication between WatchKit and host apps:
Series on Apple WatchKit Apps powered by IBM MobileFirst:

 

Powering Apple Watch Apps with IBM MobileFirst – Part 1

This is the first entry in a multipart series on powering native iPhone and Apple Watch apps using the IBM MobileFirst Platform.  In this entry we will cover how to setup the MobileFirst Platform for use within Apple WatchKit apps and leverage the operational analytics and remote logging features.

So, let’s first take a look at the app we’re going to build in this video:

The app is a simple location tracker.  Think of something like a much simpler version of Run Keeper that will allow you to track your location path over a period of time, and show your location on a map.  We’re also building a WatchKit app that enables you to quickly start or stop tracking your location without ever having to pull your iPhone out of your pocket.  All of this powered by IBM MobileFirst.

WatchKit apps are essentially 3 parts:

  • The native iOS App on the phone
  • The watch app user interface
  • The WatchKit extension, which is a binary that runs *on the phone* but controls all of the logic for the watch interface

This means that when you run Apple Watch apps, they’re really no different than a native iOS app because all of the logic is executed on the Phone.

So… Setting up the MobileFirst Platform for WatchKit is really no different than setting it up for a native iOS app, with a few exceptions.

Full instructions how to setup MobileFirst Platform Foundation server with a native iOS app are available in the platform documentation.  Specifically, see the Configuring a Native iOS Application entry.

When you’re setting up your WatchKit app, you need to follow the exact same steps that you did for the native app target, just apply them to your WatchKit extension target.

First you need to add the required frameworks and dependencies (full list here, also be sure to include libWorklightStaticLibProjectNative.a that is inside the iOS API):

Add MobileFirst Frameworks and Dependencies
Add MobileFirst Frameworks and Dependencies

Next, add the “-ObjC” linker flag:

Add Linker Flag
Add Linker Flag

Then make sure that worklight.plist (which is inside of the MobileFirst API you generated from either the CLI or Eclipse Studio) so that it is included in both the native app and WatchKit extension.

Worklight.plist Target Membership
Worklight.plist Target Membership

 

This allows you to take advantage of MobileFirst APIs within your WatchKit extension, complete with operational analytics.  You cansave remote logs, you can access data adapters, and more. The server-side security mechanisms also work, so if you want to shut down your API for specific versions, you have that ability.

I mentioned earlier, it’s just like a native iOS app, but with a few exceptions.  The most important and notable exception is that the UI elements (modal dialogs, alerts, etc…) that you would normally see in the native phone interface do not appear in the WatchKit interface.  You don’t get errors – you just don’t see the notification.  So, you need to work around any scenarios that rely on this, and make sure you handle errors accordingly.

To invoke MobileFirst APIs, you call them as you wold normally in either Objective-C or Swift.  For example:

//InterfaceController for WatchKit app
- (void)awakeWithContext:(id)context {
  [super awakeWithContext:context];

  //setup MobileFirst remote logging
  logger = [OCLogger getInstanceWithPackage:@"WatchKit: InterfaceController"];
  [logger trace:@"InterfaceController awakeWithContext"];

  //connect to MobileFirst server
  [[WLClient sharedInstance] wlConnectWithDelegate: self];
}

Once your app is connected, you’ll be able to access the operational analytics, remote logs, push notification management, etc… from the MobileFirst Platform Foundation server.

For example, the operational analytics dashboard showing app activity:

MobileFirst Operation Analytics with the WatchKit App
MobileFirst Operation Analytics with the WatchKit App

… and the remote log search capability, including logs from the WatchKit extension:

MobileFirst Remote Logging with the WatchKit App
MobileFirst Remote Logging with the WatchKit App

That’s all that you need to get started!

Stay tuned!  Full source code will be released on my github account in a subsequent post. Also be sure to stay tuned for future entries that cover the MobileFirst platform with offline data, persisting data to the server, push notifications, geo notifications, bidirectional communication between the watch and host app, background processing, and more! I will update this post to links to each subsequent post as it is made available.

Wondering what IBM MobileFirst is?  It’s a platform that enables you to deliver and maintain mobile applications throughout their entire lifecycle.  This includes tools to easily manage data, offline storage, push notifications, user authentication, and more, plus you get operational analytics and remote logging to keep an eye on things once you’ve deployed it to the real world, and its available as either cloud or on-premise solutions.

Helpful Links for MobileFirst Platform

Helpful Links for WatchKit apps:

Also, did I mention, writing apps for the Apple Watch is *really* fun!

watchkit

Series on Apple WatchKit Apps powered by IBM MobileFirst: