Integrating MobileFirst Foundation 8.0 in Ionic v3 based apps
Vittal R Pai June 28, 2018
MobileFirst_Foundation iOS Android Cordova IonicIonic SDK is a framework built on AngularJS and Apache Cordova that helps you rapidly build hybrid mobile apps using web technologies such as HTML, CSS, and Javascript.
This post will walk you through how to create, build, and deploy Ionic version 3.x application implemented with MobileFirst Foundation and run it on mobile & browser platforms.
Install MobileFirst Components and SDKs
Ensure that you have NodeJS and npm downloaded and installed.
MobileFirst CLI
Install the MobileFirst CLI by running the following command:
npm install -g mfpdev-cli
Ionic SDK
Install latest Ionic 3 and Cordova version by running following command:
npm install -g cordova ionic
MobileFirst 8.0 Server
Ensure that you have installed and started MobileFirst 8.0 server locally. More details on how to run MFP Server locally is here.
Create a New Ionic Project
Create a new Ionic 3 project with a blank template by entering the command below.
ionic start MFPUserLogin blank
navigate to application folder and add the platform by running following command.
cd MFPUserLogin
ionic cordova platform add ios
Note : You can add Android, iOS, Windows and browser platforms.
Add the MobileFirst Cordova SDK
The MobileFirst Cordova SDK is provided as a Cordova plugin and can be installed by running:
ionic cordova plugin add cordova-plugin-mfp
You can confirm the installed plugins by entering ionic plugin list
.
Register App on MobileFirst Server
Register the application which you have created with MobileFirst 8.0 Server by running following command.
mfpdev app register
Note: Ensure you have your MobileFirst Server running.
Open your MobileFirst console and confirm that your app has been registered.
Implement the MobileFirst Adapter
MobileFirst adapters provide a way to retrieve and manage data for your mobile client app on the server side.
Here I’m using the ResourceAdapter to call a resource API and UserLogin for security in this example.
Download both the adapters and build it by running the following command
mfpdev adapter build
and deploy them to your MobileFirst server.
mfpdev adapter deploy
Security
The URL that gets the balance in the ResourceAdapter is protected by a OAuth Scope named accessRestricted.
@OAuthSecurity(scope="accessRestricted")
In the Security tab of your registered app in the MobileFirst Operations Console’s dashboard, select the New button under the Scope-Elements Mapping section.
Enter accessRestricted in the scope element and select UserLogin in the Custom Security Checks section.
The steps above needs to be followed for all the platforms, which you have added in the application.
Call your resource adapter
Create a new typescript file with a name custom.typing.d.ts inside src
folder and add the following code.
/// <reference path="../plugins/cordova-plugin-mfp/typings/worklight.d.ts" />
Add logic to do resource request call to the resource adapter endpoint in the typescript file of the page which is located at src/pages/home/home.ts
. The file contents look as below.
import { Component } from '@angular/core';
import { NavController } from 'ionic-angular';
@Component({
selector: 'page-home',
templateUrl: 'home.html'
})
export class HomePage {
balance: string;
constructor(public navCtrl: NavController) {
console.log('--> HomePage constructor')
}
getBalance() {
var resourceRequest = new WLResourceRequest("/adapters/ResourceAdapter/balance",WLResourceRequest.GET);
resourceRequest.send().then((response) => {
console.log('--> getBalance(): Success ', response);
this.balance = response.responseText;
},
function(error){
console.log('--> getBalance(): ERROR ', error.responseText);
console.log(error);
});
}
}
Update the view
Add the following code in your home.html in the <ion-content padding>
elements:
<p><button ion-button icon-left outline (click)="getBalance()">
<ion-icon name="ios-cloud-upload-outline">
</ion-icon>Get Balance</button>
</p>
<p>Your Balance : <font color="red"><pre> {{ balance }}</pre></font></p>
- The click action calls the
getBalance
function. - To display the value of a variable in your view, you surround it with double curly brackets:
<pre> {{ balance }}</pre>
Add the UserLogin Challenge Handler
When we start the app, we want to go ahead and register the challengeHandler for the UserLogin securityCheck. We will make these changes in the app.component.ts file which is located in the path src/app/app.component.ts
.
import { Component, Renderer, ViewChild } from '@angular/core';
import { Platform, App, AlertController } from 'ionic-angular';
import { StatusBar } from '@ionic-native/status-bar';
import { SplashScreen } from '@ionic-native/splash-screen';
import { HomePage } from '../pages/home/home';
@Component({
templateUrl: 'app.html'
})
export class MyApp {
rootPage:any = HomePage;
private UserLoginChallengeHandler: any
constructor(platform: Platform, statusBar: StatusBar, splashScreen: SplashScreen, renderer: Renderer, public appCtrl: App, public alertCtrl: AlertController) {
platform.ready().then(() => {
// Okay, so the platform is ready and our plugins are available.
// Here you can do any higher level native things you might need.
statusBar.styleDefault();
splashScreen.hide();
});
// register mfp init function after plugin loaded
renderer.listenGlobal('document', 'mfpjsloaded', () => {
console.log('--> MobileFirst API plugin init complete');
this.MFPInitComplete();
});
}
// MFP Init complete function
MFPInitComplete() {
console.log('--> MFPInitComplete function called');
this.registerChallengeHandler(); // register a ChallengeHandler callback for UserLogin security check
}
registerChallengeHandler() {
this.UserLoginChallengeHandler = WL.Client.createSecurityCheckChallengeHandler("UserLogin");
this.UserLoginChallengeHandler.handleChallenge = ((challenge: any) => {
console.log('--> UserLoginChallengeHandler.handleChallenge called');
this.displayLoginChallenge(challenge);
});
}
displayLoginChallenge(response) {
if (response.errorMsg) {
var msg = response.errorMsg + ' <br> Remaining attempts: ' + response.remainingAttempts;
console.log('--> displayLoginChallenge ERROR: ' + msg);
}
let prompt = this.alertCtrl.create({
title: 'MFP Login Gateway',
message: msg,
inputs: [
{
name: 'username',
placeholder: 'username'
},
{
name: 'password',
placeholder: 'password',
type: 'password'
},
],
buttons: [
{
text: 'Login',
handler: data => {
console.log('UserLoginChallengeHandler', data.username);
this.UserLoginChallengeHandler.submitChallengeAnswer(data);
}
}
]
});
prompt.present();
}
}
If you are using the browser platform, add the following code inside <head>
tag of the index.html file which is located in the path src/index.html
.
<script>
var wlInitOptions = {
// Options to initialize with the WL.Client object.
// For initialization options please refer to IBM MobileFirst Platform Foundation Knowledge Center.
mfpContextRoot : '/mfp', // "mfp" is the default context root in the MobileFirst Development server
applicationId : 'com.mfp.userlogin' // Replace with your own app id/package name.
};
</script>
where mfpContextRoot
is the runtime name of MobileFirst Platform and applicationId
is the application ID for browser platform.
Test the Application
Run the app in the mobile or browser by running following commands as applicable to the platform used.
iOS
ionic cordova prepare
ionic cordova run ios
Android
ionic cordova prepare
ionic cordova run android
Windows
ionic cordova prepare
ionic cordova run windows
Browser
ionic cordova prepare
ionic cordova run browser
Note : Launch the application on browser which runs on the port 9081 as it runs with proxy which redirects MobileFirst Platform (MFP) requests to MFP Server. In this sample, the URL looks like
http://localhost:9081/MFPUserLogin/
Click the Get Balance to view the balance amount.
This calls the ResourceAdapter and you will need to enter your authorization. After your username and password is validated, your balance is shown in the app.
This tutorial has demonstrated the security capability of MobileFirst in an Ionic 3.x application.
Source code of the application is available in Github.
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.