Misfit Link SDK (iOS)

• Getting Started
  • Set Up a Misfit Link App
  • Configure Your Application’s PList File
  • Configure Linker Flags
  • Adding a Reference to the Sleep SDK
  • Enable Bluetooth LE Background Mode
• Setting Up the Application Delegate
• Enable the Flash Link Button
• Recieving Button Commands
• Recieving State Change Events
• Changing Button Command Mappings
  • Programmatically
  • UI Dialog
• Reference

Getting Started

Set Up a Misfit Link SDK App

1. go to the Misfit Developer Portal
2. if you do not have a developer account, create one
3. navigate to the “Building” section under “Misfit Link SDK Apps”
4. click “Register an App”

5. fill out the form
   

   Theme Color and Secondary Theme Color specify the gradient that will be shown in the Link App:

   

   In the commands section, you can create an action and link it to a button command:

   

   After filling out the form, click the “Register” button to register the app.

6. after registering, your app key and secret will be desplayed on the app settings page
   
7. add your Misfit email to the “Test Users” page
   
   IMPORTANT: While your app is in development, only emails added to this list will be able to test the application.
8. once your application is ready to release, press the “Submit” button and someone will review your application.
9. when your application has been approved, it will show in the “Approved” section under “Link SDK Apps”
10. your approved application will have a different app key and secret assigned to it. Make sure to update this in your app.

Configure Your Application’s PList File

Add the following to your application’s plist file:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string></string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>mfl-{appkey}</string>
    </array>
  </dict>
</array>

make sure to replace {appkey} with the app key that was assigned to you by Misfit.

When using iOS 9, the following should also be added to the plst file:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>misfitlink</string>
</array>

Configure Linker Flags

Finally, open your project properties and navigate to build settings -> linking and find the “other linker flags” section. Add “-ObjC” to both debug and release.

Adding a Reference to the Link SDK

1. In XCode, open up your project properties
2. Navigate to “Build Phases”
3. In the “Link Binaries With Libraries” section, add CoreBluetooth.framework and MisfitLinkSDK.framework

Enable Bluetooth LE Background Mode

1. In XCode, navigate to the “Capabilities” tab in your project properties
2. In the “Background Modes” secion, check the box next to “Uses Bluetooth LE accessories”

Setting Up the Application Delegate

First, import the SDK:

#import <MisfitLinkSDK/MisfitLinkSDK.h>

The following code should be added to your application delegate to handle redirection to your app after the authorization process:

- (void)applicationDidBecomeActive:(UIApplication *)application {
    [[MFLSession sharedInstance] handleDidBecomeActive];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation
{
    BOOL canHandle = NO;
    if ([[MFLSession sharedInstance] canHandleOpenUrl:url])
    {
        canHandle = [[MFLSession sharedInstance] handleOpenURL:url];
    }
    //other logic
    return canHandle;
}

Enable the Flash Link Button

The following code can be used to enable the Flash Link Button in your application using a standard UISwitch:

- (IBAction)onEnableSwitchChanged:(UISwitch *)sender
  [[MFLSession sharedInstance] enableWithAppId:@"yourAppId" appSecret:@"yourAppSecret"
  completion:^(NSDictionary * commandMappingDict,NSArray * supportedCommands, MFLError* error)
  {
      if (error)
      {
          //reset the status
          theSwitchControl.on = [MFLSession sharedInstance].enabled;
          //handle error.
          return;
      }
      //Button Command Settings for the user.
      if (commandMappingDict)
      {
        MFLCommand *command = [commandMappingDict objectForKey:@(MFLGestureTypeTriplePress)];
        NSLog(@"command desc:%@, name:%@", command.desc, command.name);
        //output: command desc:add to favorites, name:add_to_favorites, eventType: MFLGestureTypeTriplePress
      }
      for (MFLCommand * command in supportedCommands)
      {
           NSLog(@"supported command name:%@, desc: %@",command.name,command.desc);
      }
  }];
}

Recieving Button Commands

Setup a class in your project to receive events from the MFLGestureCommandDelegate. The example below uses a ViewController.

@interface MainViewController ()<MFLGestureCommandDelegate>
...
- (void)viewDidLoad {
    [MFLSession sharedInstance].gestureCommandDelegate = self;
}
...
- (void) performActionByCommand:(MFLCommand *)command
                         completion:(void (^)(MFLActionResultType result))completion{

    if ([command.name isEqualToString:@"play_pause_music"])
    {
        NSLog(@"Play/Pause Music!");
        //Your action here.
        if (your_action_failed)
        {
            //handle error.
            completion(MFLActionResultTypeFail);
            return;
        }
        completion(MFLActionResultTypeSuccess);
    }
    else if ([command.name isEqualToString:@"next_song"])
    {
        NSLog(@"Next Song!");
        //Your action here.
        if (your_action_failed)
        {
            //handle error.
            completion(MFLActionResultTypeFail);
            return;
        }

        completion(MFLActionResultTypeSuccess);
    }
    else if ([command.name isEqualToString:@"add_to_favorites"])
    {
        NSLog(@"Add the song to your favorites!");
        //Your action here.
        if (your_action_failed)
        {
            //handle error.
            completion(MFLActionResultTypeFail);
            return;
        }
        completion(MFLActionResultTypeSuccess);
    }
    else
    {
        completion(MFLActionResultTypeNotSet);
    }

}

Note: with each instance of

[command.name isEqualToString:@"command-name"]

command-name should be replaced with a command name that you specified when setting up your Misfit Link App

Recieving Device State Change Events

Setup a class in your project to receive events from the MFLStateTrackingDelegate.

MFLStateTrackingDelegate contains two functions:

- (void) onDeviceStateChangeWithState:(MFLDeviceState)state
                         serialNumber:(NSString *)serialNumber;

which can be used to receive events when the connected device becomes available or unavailable, and

- (void) onServiceStateChangeWithState:(MFLServiceState)state;

which can be used to receive events if your application is disconnected from the Misfit service (or reconnected).

The example below shows how these two delegates can be used in a ViewController:

@interface MainViewController ()<MFLStateTrackingDelegate>
...
- (void)viewDidLoad {
    [MFLSession sharedInstance].sessionStateDelegate = self;
}
...
- (void) onDeviceStateChangeWithState:(MFLDeviceState)state
                         serialNumber:(NSString *)serialNumber
{
  if (state == MFLDeviceStateUnavailable){
    //the device has become unavailable
  }else if (state == MFLDeviceStateAvailable){
    //the device has become available
  }
}

- (void) onServiceStateChangeWithState:(MFLServiceState)state
{
  if (state == MFLServiceStateDisabled){
    //the application has been disconnected from the Misfit service
  }else if (state == MFLServiceStateEnabled){
    //the application has been connected to the Misfit service
  }
}

Changing Button Command Mappings

The Link SDK provides two methods for changing your button command mappings:

Programmatically

[[MFLSession sharedInstance] updateCommandMappingByGestureType:(MFLGestureType)gestureType commandName:(NSString *)commandName
          completion:^(NSDictionary * commandMappingDict,NSArray * supportedCommands, MFLError* error)
{
    if (error)
    {
        //reset the status
        theSwitchControl.on = [MFLSession sharedInstance].enabled;
        //handle error.
        return;
    }
    //Button Command Settings for the user.
    if (commandMappingDict)
    {
      MFLCommand *command = [commandMappingDict objectForKey:@(MFLGestureTypeTriplePress)];
      NSLog(@"command desc:%@, name:%@", command.desc, command.name);
      //output: command desc:add to favorites , name:add_to_favorites
    }
    for (NSDictionary *command in supportedCommands)
    {
      NSLog(@"supported command name:%@, desc: %@",command[@"name"],command[@"desc"]);

    }
}];

UI Dialog

[[MFLSession sharedInstance] showGestureMappingSettingDialogWithNavigationController:(UINavigationController *)controller
          completion:^(NSDictionary * commandMappingDict,NSArray * supportedCommands, MFLError* error)
{
    if (error)
    {
        //reset the status
        theSwitchControl.on = [MFLSession sharedInstance].enabled;
        //handle error.
        return;
    }
    //Button Command Settings for the user.
    if (commandMappingDict)
    {
      MFLCommand *command = [commandMappingDict objectForKey:@(MFLGestureTypeTriplePress)];
      NSLog(@"command desc:%@, name:%@", command.desc, command.name);
      //output: command desc:add to favorites, name:add_to_favorites
    }
    for (NSDictionary *command in supportedCommands)
    {
      NSLog(@"supported command name:%@, desc: %@",command[@"name"],command[@"desc"]);

    }
}];

There are four different gesture types available:

typedef enum {
    MFLGestureTypeSinglePress,
    MFLGestureTypeDoublePress,
    MFLGestureTypeTriplePress,
    MFLGestureTypeLongPress,
} MFLGestureType;

Reference

@interface MFLSession : NSObject

+ (MFLSession *) sharedInstance;

@property (nonatomic, strong) id<MFLGestureCommandDelegate> gestureCommandDelegate;
@property (nonatomic, weak) id<MFLStateTrackingDelegate> sessionStateDelegate;

//is the Link SDK enabled?
@property (nonatomic, readonly) BOOL enabled;

//is the Link App installed?
- (BOOL) isMisfitLinkAppInstalled;

//enable the Link SDK button service
- (void) enableWithAppId:(NSString *) appId appSecret:(NSString *) appSecret completion:(MFLCompletion) completion;

//update the button command mapping programmatically
- (void) updateCommandMappingByGestureType:(MFLGestureType)gestureType command:(NSString *)commandName 
          completion:(MFLCompletion) completion;

//update the button command mapping by presenting the user with a dialog window
- (void)showGestureMappingSettingDialogWithNavigationController:(UINavigationController *)controller 
          completion:(MFLCompletion) completion;

- (MFLCommand *) getCommandByGestureType:(MFLGestureType)gestureType;

//disable the Link SDK
- (void) disable;

- (void) refreshStatus;

//used in the application delegate to handle redirection from the Link App
- (BOOL) handleOpenURL:(NSURL *) url;
- (BOOL) canHandleOpenUrl:(NSURL *) url;
- (void) handleDidBecomeActive;
@end