Adding the MobileFirst SDK to web applications

Add the MobileFirst web SDK to an existing or new web application to add IBM MobileFirst™ Foundation capabilities to the application.

Before you begin

Get a copy of the MobileFirst web SDK, and save the ibm-mfp-web-sdk SDK directory, or the containing npm_modules directory (if you downloaded the SDK from npm), to the root directory of your web application. For information about acquiring a copy of the web SDK, see Acquiring the MobileFirst web SDK.

About this task

To use the APIs that are exported by the MobileFirst JavaScript web-SDK modules, you must first load the appropriate modules into your web application:

ibmmfpf.js - the core web-SDK module, which exports the JavaScript client-side API. You must load this module to develop a MobileFirst web application. This module enables you, for example, to add MobileFirst security capabilities to your application.
ibmmfpfanalytics.js (provided in the lib/analytics directory) - the web-analytics module, which exports the MobileFirst JavaScript web analytics client-side API. Use this module to add IBM MobileFirst Analytics capabilities to your web application. For information about MobileFirst Analytics, see Analytics and Logger.

Note: ibmmfpfanalytics.js depends on ibmmfpf.js, and must be loaded first (when used).

The MobileFirst web SDK supports the common standards for loading JavaScript modules:

In the Asynchronous Module Definition (AMD) standard, JavaScript modules are loaded asynchronously from JavaScript code. You use a module loader, such as RequireJS, to define your asynchronous modules and their dependencies. Then, you load the modules from the locations within your JavaScript code where the modules are needed, without affecting the global namespace. This method is especially suited for browser environments, and is commonly used in development of client web applications.
The sample MobileFirst starter web application (MFPStarterWeb), and the web-application samples that are available from the Developer Center, demonstrate how to use RequireJS to load the modules of the MobileFirst web SDK asynchronously. For more information about the starter sample and how to obtain a copy of the sample, see Getting started with a sample MobileFirst application.
In the CommonJs Modules standard, JavaScript modules are loaded synchronously by importing the module into the global namespace. In web applications that use this standard, you import the modules from the <head> element of your main HTML file. This method is more suited for server environments, and is commonly used in development of Node.js servers.

Use one of the following alternative procedures, which correspond to the described load methods, to load the web-SDK modules:

Asynchronous loading with RequiredJS
Synchronous loading with HTML import

Note: The examples in the procedure assume that your SDK directory is found in the root of your application directory. If you select to store it in a different location, adjust the script paths in the examples. For example, if you downloaded the SDK with npm and saved the node_modules directory that contains the SDK directory in the root directory of your application, add node_modules/ before each SDK module name.

Procedure

Asynchronous loading with RequiredJS
1. Get the RequireJS JavaScript module loader. For detailed instructions, see the RequireJS documentation.
  Note: The code examples in the following steps assume that require.js and your application's main HTML and JavaScript files are all stored in the application's root directory, which is used as the RequireJs baseUrl. You can select to save the scripts in different locations, and adjust the examples. For more information, see the RequireJS documentation.
2. Load RequireJS by adding a <script> tag in the <head> tag of the application's main HTML file (typically index.html). Set the <script> tag's type attribute to text/javascript; set the src attribute to require.js; and set the data-main attribute to the path to your application's main JavaScript file (without the .js file extension) to instruct RequireJs to load the specified script after require.js loads. For more information, including alternative methods for adding require.js, see the RequireJS documentation. The following example is for an application with an index.js JavaScript file that is stored in the application's root directory together with the reuiqre.js script:
```
<html>
    <head>
        <script type="text/javascript" src="require.js" data-main="index"></script>
    </head>
</html>
```
3. Use the methods of the require object that is created by RequireJS to load your application scripts from your application's JavaScript code.
  There are different ways for loading your scripts with RequireJS. This step demonstrates how to use the require.config method to configure module IDs for the SDK JavaScript modules; and then use the RequireJS require function to load the module scripts by using the configured IDs instead of specifying the script paths. For more information and for alternative methods, see the RequireJS documentation.
  1. In your application's main JavaScript file (for example, index.js), use the config method of the require object that is created by RequireJs to configure the SDK modules to load. The configuration specifies the paths to the script modules, and assigns each module an ID that is later used to load its script. The following example assigns the module ID ibmmfpf to the ibmmfpf.js module, and the module ID ibmmfpfanalytics to the ibmmfpfanalytics.js module.
```
require.config({
    'paths': {
        'ibmmfpfanalytics': 'ibm-mfp-web-sdk/lib/analytics/ibmmfpfanalytics',
        'ibmmfpf': 'ibm-mfp-web-sdk/ibmmfpf'
}
});
```
    Note:
    - If you select to use ibmmfpfanalytics.js, you must add it before ibmmfpf.js in the configuration paths.
    - The names of the configured script modules are specified without the .js extension.
  2. Use the RequireJS require function to load the SDK modules that you configured, from within your applications JavaScript code. The modules are loaded asynchronously into the local namespace when they are needed. The following example uses the ibmmfpf and ibmmfpfanalytics module IDs that you configured in the previous step to load the ibmmfpf.js and ibmmfpfanalytics.js SDK modules:
```
require(['ibmmfpfanalytics','ibmmfpf'], function(wlanalytics, WL)
```
    Note: If you select to use ibmmfpfanalytics.js, you must load it before ibmmfpf.js.
Synchronous loading with HTML import Load (import) the required modules from the <head> tag of the application's main HTML file (typically, index.html) by adding a <script> tag for each module. Set the script element's type attribute to text/javascript, and set its src attribute to the name of the target module. The following example loads both the core and analytics modules of the web SDK:
```
<html>
    <head>
        ...
        <script src="ibm-mfp-web-sdk/lib/analytics/ibmmfpfanalytics.js"></script>
        <script src="ibm-mfp-web-sdk/ibmmfpf.js"></script>
    </head>
</html>
```
Note: If you select to use ibmmfpfanalytics.js, you must load it before ibmmfpf.js.

What to do next

Use the initialization method of the core web API to initialize the SDK, and then develop your application by using the web SDK APIs. For more information, see Initializing the MobileFirst SDK.