Cordova Plugin for IBM Bluemix Mobile Services Core SDK
npm install bms-core
$ cordova create {appName}
$ cd {appName}
`
2. Edit the config.xml file and set the desired application name in the element instead of a default HelloCordova.
3. Continue editing config.xml
##### iOS
For iOS, update the element with a deployment target declaration as shown in the following code snippet.
`XML
`
##### Android
For Android, update the element with a minimum and target SDK versions as shown in the following code snippet.
`XML
`
Note:
* The minSdkVersion should be above 15.
* The targetSdkVersion should always reflect the latest Android SDK available from Google supported by Cordova. Currently,
Cordova supports up to Android 24.
$3
Run the following commands for the platforms that you want to add to your Cordova application:
`Bash
cordova platform add ios
cordova platform add android@5.2.2
`
$3
Run the following command from your Cordova application's root directory to add the bms-core plugin:
`Bash
cordova plugin add bms-core
`
You can check if the plugin installed successfully by running the following command, which lists your installed Cordova plugins:
`Bash
cordova plugin list
`
$3
#### 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:
`Bash
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”.
`
3. Verify that your Cordova application was correctly linked with the iOS Bluemix Core SDK that is bundled with the Plugin.
* If you get a prompt asking whether you want to convert Swift code to the latest version, click Cancel.
1. Click your project name in the project directory and go to Build Phases > Link Library with Libraries.
2. Verify that the Pods_{YOUR_PROJECT_MODULE_NAME}.framework is present in the linked libraries list.
* Note: If you get the message that your application requires Use Legacy Swift Language Version, set the flag to NO.
1. Go to Build Settings > Use Legacy Swift Language.
2. You may need to do this with other Pod dependencies such as BMSAnalytics and BMSAnalyticsAPI.
#### Configuring Your Android Environment
1. Build your Android project by running the following command:
`Bash
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.
Using the Cordova Plugin
$3
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.
* Initialize the BMSClient by copying and pasting the following code snippet into your main JavaScript file. If your app is in a different region, the following constants are available: BMSClient.REGION_US_SOUTH, BMSClient.REGION_UK,BMSClient.REGION_GERMANY, BMSClient.REGION_SYDNEY, BMSClient.REGION_US_EAST and BMSClient.REGION_TOKYO.
`JavaScript
BMSClient.initialize(BMSClient.REGION_US_SOUTH);
`
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.
`JavaScript
onDeviceReady: function() {
BMSClient.initialize(BMSClient.REGION_US_SOUTH);
},
`
Examples
$3
#### 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:
`JavaScript
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"
`
`JavaScript
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.
`JavaScript
var request = new BMSRequest("http://your_app.mybluemix.net/protected", BMSRequest.GET, 20000);
`
#### Setting headers for your request
`JavaScript
var headers = {
header1: "val1",
header2: "val2"
};
request.setHeaders(headers);
`
#### Setting your BMSRequest's query parameters
`JavaScript
var queryParams = {
param1: "val1",
param2: "val2"
};
request.setQueryParameters(queryParams);
`
The query parameters are parameters that are added to the request URL.
#### Sending the request
`JavaScript
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:
`JavaScript
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
`
$3
`JavaScript
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();
`
$3
`JavaScript
//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.
Change log
##### 2.5.0
Removed BMSSecurity (mobileaccess)
##### 2.3.7
* Fixed bug with DeviceEvents in iOS
* See Issue 29
##### 2.3.6
* Update README to state only Cordova 6 and Android 24 support
##### 2.3.5
* Update code snippet to show setting userIdentity
##### 2.3.4
* Updated Cocoapods requirment and fixed examples in README
##### 2.3.3
* Fixed logLevelDictionary EXEC_BAD_ACCESS error
##### 2.3.2
* Added DeviceEvent.NETWORK as an available event for BMSAnalytics
##### 2.2.2
* Use to grab the latest pod dependency from version [2.0,3.0)
##### 2.2.1
* Use to grab the latest pod dependency
##### 2.2.0
* Update BMSAnalytics pod dependency to 2.1.1
* Update BMSSecurity pod dependency to 2.0.2
##### 2.1.0
* Added setUserIdentity method to BMSAnalytics
##### 2.0.0
* Changed JS API signatures
* BMSClient.initialize(backendRoute, backendGuid) --> BMSClient.initialize(region)
* MFPRequest --> BMSClient
* MFPLogger --> BMSLogger
* getInstance --> getLogger
* getCapture --> isStoringLogs
* setCapture --> storeLogs
* getMaxStoreSize --> getMaxLogStoreSize
* setMaxStoreSize --> setMaxLogStoreSize
* getLevel --> getLogLevel
* setLevel --> setLogLevel
* MFPAuthorizationManager --> BMSAuthorizationManager
* MFPAnalytics --> BMSAnalytics
* Added isSDKDebugLoggingEnabled to BMSLogger/MFPLogger
* Added BMSAnalytics.NONE, BMSAnalytics.ALL, and BMSAnalytics.LIFECYCLE to BMSLogger/MFPLogger
* Added BMSAnalytics.initialize to BMSLogger/MFPLogger
* Removed initialize from BMSAuthorization/MFPAuthorizationManager, use native implementation
* Removed the use of using a copy of Bridging-Header.h, so that developers will no longer need to do this manually
* Added a new initializer for BMSClient that does not require the app route and app guid: BMSClient.initialize(BMSClient.REGION_US_SOUTH);
* Removed filters and capture methods for BMSLogger, use BMSLogger.getLogLevel or BMSLogger.setLogLevel
* Added initMCAAuthorizationManagerManager` to handle initialize MCA in iOS native