Home

Awesome

Cordova Plugin for IBM Bluemix Mobile Services Core SDK

Build Status

npm package

Table of Contents

<a name="before_you_begin"></a>

Before you begin

Make sure you install the following tools and libraries.

To create a Cordova application, use the Cordova Plugin for the IBM Bluemix Mobile Services Core SDK:

  1. Create a Cordova application
  2. Add Cordova platforms
  3. Add Cordova plugin
  4. Configure your platform

<a name="init_sdk"></a>

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. Edit the config.xml file and set the desired application name in the <name> element instead of a default HelloCordova.

  3. Continue editing config.xml

iOS

For iOS, update the <platform name="ios"> element with a deployment target declaration as shown in the following code snippet.

	<platform name="ios">
		<preference name="deployment-target" value="8.0" />
		<!-- add deployment target declaration -->
	</platform>
Android

For Android, update the <platform name="android"> element with a minimum and target SDK versions as shown in the following code snippet.

	<platform name="android">
		<preference name="android-minSdkVersion" value="15" />
		<preference name="android-targetSdkVersion" value="23" />
		<!-- add minimum and target Android API level declaration -->
	</platform>

Note:

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@5.2.2

3. Adding Cordova plugin

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

cordova plugin add 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 Xcode 7 or above.

  1. Run cordova prepare ios to prepare the Cordova application with the necessary CocoaPod dependencies.

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

    cordova build ios

Note: You may receive the following error when running cordova build ios. This issue is due to a bug in a dependency plugin which is being tracked in Issue 12. You can still run the iOS project in XCode through a simulator or device.

xcodebuild: error: Unable to find a destination matching the provided destination specifier:
		{ platform:iOS Simulator }

	Missing required device specifier option.
	The device type “iOS Simulator” requires that either “name” or “id” be specified.
	Please supply either “name” or “id”.
  1. Verify that your Cordova application was correctly linked with the iOS Bluemix Core SDK that is bundled with the Plugin.

Configuring Your Android Environment

  1. 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.

<a name="using_cordova"></a>

Using the Cordova Plugin

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.

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

onDeviceReady: function() {
    BMSClient.initialize(BMSClient.REGION_US_SOUTH);
},

<a name="examples"></a>

Examples

Using BMSClient

Initializing BMSClient

The following JavaScript code is your entry point to the Bluemix Mobile services. Call this method before making any request. You must pass in the region for your application. The following constants are provided:

 REGION_US_SOUTH // ".ng.bluemix.net";
 REGION_UK //".eu-gb.bluemix.net";
 REGION_SYDNEY // ".au-syd.bluemix.net";
 REGION_GERMANY // ".eu-de.bluemix.net"
 REGION_US_EAST // ".us-east.bluemix.net"

BMSClient.initialize(BMSClient.REGION_US_SOUTH);

Creating a request

After you initialize the client, you can create a new BMSRequest instance by specifiying a URL endpoint, request method, and an optional timeout value in milliseconds.

var request = new BMSRequest("http://your_app.mybluemix.net/protected", BMSRequest.GET, 20000);

Setting headers for your request

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

Setting your BMSRequest's 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.responseText);
		console.log("status :: " + successResponse.status);
		console.log("headers :: " + successResponse.headers);
	}, 
	function (failureResponse){
		console.log("text :: " + failureResponse.responseText);
		console.log("errorCode:: " + failureResponse.errorCode);
		console.log("errorDescription :: " + failureResponse.errorDescription);
	}
);

The successResponse and failureResponse 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  =>  Integer 
response.errorDescription  =>  Undefined or String

Using BMSLogger

var myPackageLogger = BMSLogger.getLogger("myPackage");


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

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


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

Using BMSAnalytics


//Initialize BMSClient
BMSClient.initialize(BMClient.REGION_US_SOUTH);

//Initialize BMSAnalytics
BMSAnalytics.initialize(appName, apiKey, hasUserContext, [BMSAnalytics.ALL]

// Enable analytics logging
BMSAnalytics.enable();

// If hasUserContext is set to true set "userIdentity"
BMSAnalytcs.setUserIdentity("user1");

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

// Invoke feedback mode on any application event such as buttons, menu actions or gestures on calling the method
BMSAnalytics.triggerFeedbackMode();

Note: In iOS, BMSAnalytics.ALL and BMSAnalytics.NONE is not supported natively and will be treated as BMAnaltyics.LIFECYCLE.

Note: For more information about Mobile Analytics, see the documentation.

<a name="change_log"></a>

Change log

2.5.0

Removed BMSSecurity (mobileaccess)

2.3.7
2.3.6
2.3.5
2.3.4
2.3.3
2.3.2
2.2.2
2.2.1
2.2.0
2.1.0
2.0.0
1.0.0

<a name="copyrights"></a>

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.