ibm-bms-core v1.0.1

Cordova Plugin for IBM Bluemix Mobile Services Core SDK

Contents

• Installation Configuring iOS Configuring Android
• API Reference BMSClient BMSRequest BMSLogger BMSAnalytics MCAAuthorizationManager AuthenticationListener * AuthenticationContext
• Examples Using BMSClient Using BMSRequest Using BMSLogger Using BMSAnalytics * Custom Authentication

Before you begin

Make sure you install the following tools and libraries.

• You should already have Node.js/NPM installed. If you don't, you can download and install Node from https://nodejs.org/en/download/.

• The Cordova CLI tool is required to use this plugin. You can find instructions to install Cordova and set up your Cordova app at https://cordova.apache.org/#getstarted.

• Carthage is required to install the necessary frameworks for iOS. You can learn more about Carthage at https://github.com/Carthage/Carthage

Install Carthage using Homebrew:

brew install carthage

Installing the Cordova Plugin for Bluemix Mobile Services Core SDK

1. Creating a Cordova application

1. Run the following commands to create a new Cordova application. Alternatively you can use an existing application as well.

$ cordova create {appName}
$ cd {appName}

2. Adding Cordova platforms

Run the following commands for the platforms that you want to add to your Cordova application:

cordova platform add ios

cordova platform add android

3. Adding Cordova plugin

Run the following command from your Cordova application's root directory to add the ibm-mfp-core plugin:

cordova plugin add ibm-bms-core

You can check if the plugin installed successfully by running the following command, which lists your installed Cordova plugins:

cordova plugin list

4. Configuring your platform

Configuring Your iOS Environment

Note: Before you begin, make sure that you are using the latest version of Xcode.

1. Open your [your-app-name].xcodeproj file in the [your-app-name]/platforms/ios directory with Xcode

   If confronted with an alert asking to “Convert to Latest Swift Syntax”, click Cancel.

2. On your application targets’ "General" settings tab, in the "Linked Frameworks and Libraries" section, drag and drop each of the following frameworks from the platforms/ios/Carthage/Build/iOS folder on disk:

   • BMSCore.framework
   • BMSAnalytics.framework
   • BMSAnalyticsAPI.framework
   • BMSSecurity.framework
   • RNCryptor.framework

3. Click on your application target click the “Build Phases” settings tab

4. Click the top left “+” icon and choose “New Run Script Phase”

5. Create a Run Script in which you specify your shell (/bin/sh) and add the following to the script area below the shell:

   • /usr/local/bin/carthage copy-frameworks

6. Add the paths to the frameworks under “Input Files”:

   • $(SRCROOT)/Carthage/Build/iOS/BMSCore.framework
   • $(SRCROOT)/Carthage/Build/iOS/BMSAnalytics.framework
   • $(SRCROOT)/Carthage/Build/iOS/BMSAnalyticsAPI.framework
   • $(SRCROOT)/Carthage/Build/iOS/BMSSecurity.framework
   • $(SRCROOT)/Carthage/Build/iOS/RNCryptor.framework

7. Build and run your application with Xcode or by running the following command:

cordova build ios

Configuring Your Android Environment

Build your Android project by running the following command:

cordova build android

Important: Before opening your project in Android Studio, you must first build your Cordova application through the Cordova commmand-line interface (CLI). Otherwise, you will encounter build errors.

API Reference

BMSClient

The BMSClient class is a singleton that serves as an entry point to Bluemix client-server communication.

The following constants are available:

BMSRequest

The BMSRequest class is used to build and send HTTP network requests.

BMSLogger

The BMSLogger class is a singleton that provides a wrapper to the native platform Logger.

The following log level constants are available:

The following methods are available for an instance of BMSLogger:

BMSAnalytics

The BMSAnalytics class is a singleton that serves as an entry point to Bluemix client-server communication.

The following DeviceEvent constants are available:

MCAAuthorizationManager

The MCAAuthorizationManager class is used for obtaining authorization tokens from Mobile Client Access service and providing user, device and application identities.

AuthenticationListener interface

Mobile Client Access Client SDK provides an Authentication Listener interface to implement custom authentication flows. A developer implementing Authentication Listener is expected to add the three below methods that will be called in different phases of an authentication process.

AuthenticationContext

authenticationContext is supplied as an argument to the onAuthenticationChallengeReceived method of a custom Authentication Listener. It is developer's responsibility to collect credentials and use authenticationContext methods to either return credentials to Mobile Client Access Client SDK or report a failure. Use one of the below methods.

Examples

Using BMSClient

The BMSClient class allows you to initialize the SDK. By initializing the SDK, you can connect to the server app that you created in the Bluemix dashboard. Initializing the BMSClient instance is required before sending requests.

Initializing BMSClient

Initialize the BMSClient by copying and pasting the following code snippet into your main JavaScript file.

BMSClient.initialize("http://example.mybluemix.net", "appGUID", BMSClient.REGION_US_SOUTH);

Note: If you have created a Cordova app using the cordova CLI, for example, using the cordova create app-name command with the Cordova command-line, put this Javascript code in the index.js file, within the onDeviceReady function to initialize the BMS client.

onDeviceReady: function() {
    BMSClient.initialize("http://example.mybluemix.net", "appGUID", BMSClient.REGION_US_SOUTH);
}

Get functions

BMSClient.getDefaultRequestTimeout(function(timeout) {
	console.log(timeout);
});

Using BMSRequest

Creating a request

After initializing the BMSClient you may create a new BMSRequest instance by specifiying a URL endpoint, request method, and an optional timeout value in milliseconds.

// Specific URL
var request = new BMSRequest("http://example.mybluemix.net", BMSRequest.GET, 200);

// Relative endpoint
var request = new BMSRequest("myapp/API/action", BMSRequest.POST, 200);

Setting the headers

var headers = {
    header1: "val1",
    header2: "val2"
};
request.setHeaders(headers);

Setting the query parameters

var queryParams = {
    param1: "val1",
    param2: "val2"
};
request.setQueryParameters(queryParams);

The query parameters are parameters that are added to the request URL.

Sending the request

request.send("some body",
    function(successResponse){
        console.log("text :: " + successResponse.text);
        console.log("status :: " + successResponse.status);
        console.log("headers :: " + successResponse.headers);
    }, 
    function (failureResponse){
        console.log("text :: " + failureResponse.text);
        console.log("errorCode:: " + failureResponse.errorCode);
        console.log("errorDescription :: " + failureResponse.errorDescription);
    }
);

The response parameters are JSON objects that will be passed to your callbacks with the following fields:

response.status  =>  Integer
response.responseText  =>  Undefined or String
response.headers  =>  JSON object with key:value pairs of headers
response.errorCode  =>  Undefined or Integer 
response.errorDescription  =>  Undefined or String

Using BMSLogger

Below are some examples of how to use the BMSLogger class.

var myLogger = BMSLogger.getLogger("myLogger");

// Enable native SDK debug logging
BMSLogger.setSDKDebugLogging(true);

// Globally set the logging level
BMSLogger.setLogLevelFilter(BMSLogger.WARN);

// Get the maximum file size for log storage
BMSLogger.getMaxLogStoreSize(function(size) {
	console.log(size);
});

// Log a message at FATAL level
myLogger.fatal("Fatal level message");

// Send the logs to the server
BMSLogger.send();

// Send the logs with a callback
BMSLogger.send(function(message) {
	console.log(message);
})

Using BMSAnalytics

Below are some examples of how to use the BMSAnalytics class.

// Initialize analytics logging
BMSAnalytics.initialize("appName", "appGUID", [DeviceEvents.LIFECYCLE]);

// Enable analytics logging
BMSAnalytcs.enable();

// Set user identity
BMSAnalytics.setUserIdentity("myIdentity");

// Log analytics data
var eventMetadata = {
	data1: "val1",
	data2: "val2"
}
BMSAnalytics.log(eventMetadata);

// Send the analytics log to the server 
BMSAnalytics.send();

Custom Authentication

var customAuthenticationListener = {
    onAuthenticationChallengeReceived: function(authenticationContext, challenge) {
        console.log("onAuthenticationChallengeReceived :: ", challenge);

        // In this sample the Authentication Listener immediatelly returns a hardcoded
        // set of credentials. In a real life scenario this is where developer would
        // show a login screen, collect credentials and invoke 
        // authenticationContext.submitAuthenticationChallengeAnswer()

        var challengeResponse = {
            username: "john.lennon",
            password: "12345"
        }

        authenticationContext.submitAuthenticationChallengeAnswer(challengeResponse);

        // In case there was a failure collecting credentials you need to report
        // it back to the authenticationContext. Otherwise Mobile Client 
        // Access Client SDK will remain in a waiting-for-credentials state forever
    },

    onAuthenticationSuccess: function(info){
        console.log("onAuthenticationSuccess :: ", info);
    },

    onAuthenticationFailure: function(info){
        console.log("onAuthenticationFailure :: ", info);
    }
};

// Once you create a custom Authentication Listener you need to register it 
// with BMSClient before you can start using it. 
// Use realmName you've specified when configuring custom authentication
// in Mobile Client Access Dashboard

BMSClient.registerAuthenticationListener(realmName, customAuthenticationListener);

Release Notes

Copyrights

Copyright 2016 IBM Corp.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.