Configuring Mobile Analytics and Mobile Foundation Bluemix services

Note: Updated for changes after Mobile Analytics service went GA.

Note: Updated May 15, 2018 for changes to the IBM Cloud and Mobile Analytics service user interfaces.

Overview

When IBM Mobile Foundation 8.0 was released, it supported deployment as a service in IBM Cloud in addition to it’s traditional on-premises deployment model. The simplest way to provision an instance of Mobile Foundation by far is to use the new service that is available in the IBM Cloud catalog, which can be deployed to both IBM Cloud and IBM Cloud Private environments. This service provides all the capabilities that you need to build secure mobile apps using any technology you choose to run on all of the popular mobile operating systems.

However a new IBM Cloud service called Mobile Analytics was launched in April and has since been released for production use. Mobile Analytics provides organizations valuable insights beyond the the Analytics functionality packaged with Mobile Foundation. It provides a 360 degree view of mobile applications running on customer devices, including developer statistics and application analytics such as how many devices have connected, the distribution of operating systems used, crash reports, and much more. My personal favourite? Client side developer logs. This is how I get to know if the code is falling into catch blocks where “you should never be here!” messages tend to occur – especially when the application is running on a user’s phone! We know all too well the app performs at its best when running on the developers device! ;-)

Though the Mobile Analytics service is advertised (and documented) to be used only with its own client side SDKs, you can also connect it to a MobileFirst Server (either running on-premises or in the Cloud) so that analytics data collected by Mobile Foundation is pumped to this service! The Mobile Foundation SDK that you install as part of integrating an application with Mobile Foundation is enough to generate the analytics data - no additional SDK is required.

If you are familiar with the analytics features of Mobile Foundation, you will see the similiarities. Let’s see how you can configure a Mobile Foundation server to send analytics data to the IBM Cloud Mobile Analytics service.

Create an instance of the Mobile Analytics service

Login to your IBM Cloud account and click on Catalog in the upper right of the menu bar. Then in the left hand menu under Platform, click Mobile. In this section of the catalog you should see an entry for the “Mobile Analytics” service. Mobile Analytics Tile Click on it, then give it a name (if you wish). Select a pricing plan (the “Lite” version is free) and click the Create button to build your new instance. A Getting started page will then be displayed describing the steps required to use the service with the Mobile Analytics service’s SDK. We’ll skip that for now, since we are attaching this service to Mobile Foundation.

To continue configuring your service, first click Manage then CONFIGURE. Slide the Demo Mode button on the right to off. Disable Demo Mode Now we need to create secure credentails for your service. So in the left hand menu select Service Credentials, then press the New credential button. Create New Credentials On the resulting dialog just click the Add button to complete the process and you’ll be returned to the Service credentials page where a new line now exists in your Service credentials table. New Credentials

To display the credentials, click the View credentials down arrow. You’ll see some JSON text that contains your API Key and secret. Copy this text to a safe place because you will need this later.

{
  "apiKey": "your API key",
  "secret": "your super secret"
}

Create an instance of Mobile Foundation on IBM Cloud

If you don’t already have an on-premises installation of Mobile Foundation, you can create a free instance on IBM Cloud. To do so, go back to the catalog and in the “Mobile” section locate the “Mobile Foundation” service tile. Mobile Foundation Tile

As before, click on the tile, change the name if you wish, pick a plan (Developer is free), and click Create at the bottom of the page. Once the server has started the MobileFirst Operations Console is displayed. Mobile Foundation Console

The next step is to configure your Mobile Foundation instance. To do so, return to your dashboard by clicking the IBM Cloud graphic in the upper left of the screen. Then under Cloud Foundry Applications, locate the row containing your Mobile Foundation instance. It will have the string -Server appended to the name. This application is the runtime environment (Liberty server and Java BuildPack) that the Mobile Foundation Server requires to run. Therefore, it is here that you configure the Liberty server. Mobile Foundation Cloud Foundry App

Click the Mobile Foundation instance under Cloud Foundry Applications to display the Overview page, then click Runtime. On the Runtime page, select the Environment variables tab and scroll down to the User defined section at the bottom of the page. Here is where we set the variables that will tell Mobile Foundation to send analytics data to our Mobile Analytics service.

Change the following variable values:

  1. Change the value of BMS.ANALYTICS.APIKEY to be the apiKey parameter from the Mobile Analytics service credentials JSON text that you copied earlier.

  2. Change the value of MFP.ANALYTICS.URL to be https://mobile-analytics-dashboard.ng.bluemix.net/analytics-service/rest.

  3. Optionally change the value of MFP.ANALYTICS.CONSOLE.URL to be https://console.ng.bluemix.net/mobile/analytics/users?instanceId=<\your-instance-id-here> Be sure to replace the <\your-instance-id-here> with the instance ID of your Mobile Analytics service. To find the instance ID, open your Mobile Analytics Console, then look at the URL in your browser. The instance ID is the part of the URL between mobile-analytics-prod/ and the ?(https://console.ng.bluemix.net/services/mobile-analytics-prod/<your-instance-id>?<more stuff>) - This is needed only if you want a direct link from the Mobile Foundation Operations Console to the Mobile Analytics Console.

Configure an on-premises instance of the Mobile Foundation Server

If your Mobile Foundation instance is running on-premises, then you need to make similar changes to the JNDI properties in that environment. If your Mobile Foundation Server is running Liberty, then the JNDI properties need to be set in the server.xml file.

<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.console.url" value=" https://mobile.ng.bluemix.net/imfanalyticsdashboard?instanceId=your-instance-id-here"/>
<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.url" value="https://mobile-analytics-dashboard.ng.bluemix.net/analytics-service/rest"/>
<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/bms.analytics.apikey" value="your analytics api key"/>

If the server is running on WebSphere Application Server Network Deployment, then the JNDI properties need to be set in the Mobile Foundation Runtime web application. To set these open the WebSphere Application Server Network Deployment administration console. Then go to Applications → Application Types → WebSphere enterprise applications → MobileFirst Runtime → Environment entries for Web modules. Then set the following properties as follows:

mfp.analytics.console.url = https://mobile.ng.bluemix.net/imfanalyticsdashboard?instanceId=your-instance-id-here
mfp.analytics.url = https://mobile-analytics-dashboard.ng.bluemix.net/analytics-service/rest
bms.analytics.apikey = <your analytics api key>

Now restart your Mobile Foundation server and once it restarts, it should begin sending data to your Mobile Analytics service.

Deploy Mobile Foundation Server to IBM Cloud preconfigured to use the Mobile Analytics service using IBM provided scripts

Mobile Foundation, deployed using scripts, can also be connected to an Mobile Analytics service by adding the JNDI properties present in the mfpf-server-libertyapp/usr/config/mfpfproperties.xml.

Add the following JNDI properties in the above mentioned xml file:

<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.console.url" value=" https://mobile.ng.bluemix.net/imfanalyticsdashboard?instanceId=your-instance-id-here"/>
<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.url" value="https://mobile-analytics-dashboard.ng.bluemix.net/analytics-service/rest"/>
<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/bms.analytics.apikey" value="your analytics api key"/>

After adding the properties deploy the Mobile Foundation server using the scripts. In order to deploy the Mobile Foundation server follow the steps given here.

Gathering Analytics data

Once you start using applications connected to the Mobile Foundation server instance - the analytics data starts getting published to the Mobile Analytics service. If you want to see more in the analytics service - please leave a comment at the bottom of the analytics announcement article .

Troubleshooting

"CWPKI0022E: SSL HANDSHAKE FAILURE" displayed in server console or log files.

If your Mobile Foundation Server's keystore does not include the intermediate or root certificate for IBM Cloud, you may see the following error message in either the server's console or in the server's log files:

[ERROR ] CWPKI0022E: SSL HANDSHAKE FAILURE: A signer with SubjectDN CN=*.ng.bluemix.net, O=International Business Machines Corporation, L=Armonk, ST=New York, C=US was sent from the target host. The signer might need to be added to local trust store /Users/john_gerken/MobileFirst-8.0.0.0/mfp-server/usr/servers/mfp/resources/security/key.jks, located in SSL configuration alias defaultSSLConfig. The extended error message from the SSL handshake exception is: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

this indicates that the IBM Cloud root or intermediate certificate needs to be added to the [Mobile Foundation Server's keystore](https://mobilefirstplatform.ibmcloud.com/tutorials/en/foundation/8.0/authentication-and-security/configuring-the-mobilefirst-server-keystore/). To add the two certificates, do the following:

  1. Retrieve the intermediate and root certificates from IBM Cloud using the browser of your choice. Before proceeding you should have two files on your filesystem: DigiCertSHA2SecureServerCA.crt and DigiCertGlobalRootCA.crt.
  2. Locate your keystore. By default the keystore is named "key.jks" and can be found in your deployed server's "./mfp/resources/security" directory.
  3. Use the keytool (or similar utility) to add the intermediate and root certificate to your keystore. For example: keytool -importcert -alias <Certificate Name> -file <path to certificate file> -trustcacerts -storetype JKS -keystore <path to key.jks file> -storepass <key.jks password>
Last modified on May 18, 2018