Subscribe

Share

Mobile

Analyzing What Matters

Use Oracle Mobile Cloud Service analytics with Oracle Mobile Application Framework.

By Chris Muir

July/August 2016

Analytics is a relatively new area of technology, and for many platforms, it is added as an afterthought. The relatively new world of mobile technology has grown up with analytics, however, so analytics is a key part of any successful mobile application development platform.

Oracle Mobile Cloud Service gives mobile developers as well as business users the ability to capture analytics about their mobile users and how they use their mobile apps. You can capture simple analytics such as where your users reside, what brand of mobile phone they’re using, and the date and time as well as more-sophisticated analytics that let you really get into the head of your mobile users, such as what app features they like most, what tasks they are starting, how far they have gotten, and what issues they are running into. And businesses can take this to the extreme and determine whether the app is meeting the needs of their customers and the goals of the business by gathering, for example, statistics on sales, the effect of mobile marketing campaigns, or something simple such as tasks completed.

Oracle Mobile Cloud Service provides mobile client SDKs enabling Android, iOS, Windows, and JavaScript developers to capture and log analytic events and data without using raw REST calls in their mobile code. Oracle Mobile Application Framework takes this capability one step further, by providing native support for raising analytic events to Oracle Mobile Cloud Service.

In this article, you will see how the combination of Oracle Mobile Cloud Service and Oracle Mobile Application Framework captures analytic events in a simple application. Recall that Oracle Mobile Cloud Service is client-agnostic and that mobile analytics can also be captured from other mobile platforms, including Android, iOS, Windows, JavaScript, and more.

Getting Ready

This article picks up where the previous Oracle Magazine article on Oracle Mobile Cloud Service (“Go Native with Apple iOS”) finished up. In addition to having a login on Oracle Mobile Cloud Service and the artifacts used in the previous article, you will need to install Oracle JDeveloper 12.2.1.0.0, along with the Oracle Mobile Application Framework 2.3.0.1+ extension, on your local Windows PC or Mac. The installation of Oracle JDeveloper and Oracle Mobile Application Framework is covered in the Oracle documentation in detail. Running the app you will build by taking the steps in this article on a Mac in the iOS Simulator or on the Android Emulator on a Mac or Windows PC is also documented and is a prerequisite for this article.
o46mcs-f1

Figure 1: Oracle Mobile Cloud Service analytics dashboard

Finally, download this simple Oracle Mobile Application Framework application, which will form the basis of this article, enabling you to focus on the analytics features rather than creating an Oracle Mobile Application Framework application shell.

Configuring Oracle Mobile Cloud Service for Analytics

If you’ve been following this Oracle Mobile Cloud Service article series in Oracle Magazine, you have already created the Oracle Mobile Cloud Service artifacts required for analytics: a mobile back end OraMagTestBackend and a mobile user account joedoe. The following steps summarize how to re-create the required artifacts and describe how to create a client registration (which was not covered in previous articles):

  1. Log in to Oracle Mobile Cloud Service.
  2. In the top left of the page, click the hamburger icon (the one with three horizontal stripes) followed by Applications -> User Management.
  3. From the middle menu, select Users.
  4. Click New User.
  5. In the Create User dialog box, enter
    Username: joedoe
    Email: <<an email address you own>>
    First Name: Joe
    Last Name: Doe
  6. Click Create.
  7. You’ll be sent a verification email to the email address you specified and instructed to change the new mobile user joedoe’s password. Follow the instructions in the email to complete this step.
  8. From the left menu under Applications, select Mobile Backends.
  9. Click New Mobile Backend.
  10. In the New Mobile Backend dialog box, enter OraMagTestBackend for Name.
  11. Click Create.
  12. This should place you on the Settings page of the mobile back end. Copy the Base URL and Mobile Backend ID values into your favorite text editor; you will use these in your Oracle Mobile Application Framework app.
  13. From the middle left menu, select Clients, and then click the Register Clients button.
  14. For demo purposes, rather than creating several client registrations, one each for the various mobile platforms Oracle Mobile Application Framework supports, you’ll create one generic web client that covers them all. In the Register Mobile Application dialog box, select or enter
    Platform: Web
    Application Name: analytics
    Application Id: analytics
  15. Select Register.
  16. On the resulting screen, copy the Application Key value to your favorite text editor. Ensure that you’ve copied this value and the values in step 12 accurately, with no extra or missing spaces or characters.
Exploring and Configuring the Oracle Mobile Application Framework App

With the Oracle Mobile Application Framework application downloaded and unzipped on your local machine, follow these steps to configure the app in Oracle JDeveloper:

  1. Click File -> Open.
  2. In the Open dialog box, locate the directory where you unzipped the downloaded Oracle Mobile Application Framework application, select the Analytics.jws file, and select Open.
  3. In the Application Navigator’s Application Resources panel, double-click the connections.xml file to open it. There are three things you must change in this file and replace with settings you recorded in your text editor from the mobile back end earlier. Find and replace the following, and then click Save: • CHANGE-BASE-URL: Replace this value with the mobile back-end base URL, including the port number in the form http://myserver:myport. There are three instances of this in the connections.xml file. • CHANGE-MBE-ID: Replace this value with the mobile back-end ID. There is only one instance of this to replace. • CHANGE-APP-KEY: Replace this value with the client registration app key. There is only one instance of this to replace.
  4. On the Application Resources panel, expand the Descriptors and ADF META-INF nodes and double-click the maf-application.xml file to open it. Select the Security tab. Note that the one Oracle Mobile Application Framework feature for this application is secured against the custom McsLoginConn. This setting will ensure that the application asks you to enter a username and password for authentication when you run it.
  5. In the maf-application.xml file, note Policy in the Web Service Security Policies section. Double-click the pencil icon and, in the resulting dialog box, click OK. (This step forces Oracle Mobile Application Framework to update the security policy settings based on what you configured in step 19.) Click Save All.
  6. Within the ViewController project in the Application Navigator, locate the events.amx page and double-click it to open it. Note that the AMX page is very simple; it contains one button to invoke a bean method via the expression language (EL) expression #{myBean.doAction}.
  7. Right-click the doAction text within the EL expression, and select Go To Declaration. This will open the MyBean.java file, where you can see the doAction method, ready to raise analytics events.
  8. With the events.amx page and MyBean.java file open in separate tabs within Oracle JDeveloper, expand Application Resources-> Descriptors-> META-INF within the Application Navigator and double-click the logging.properties file to open it.
Enabling Analytics

The logging.properties file includes the options for configuring analytics to work with Oracle Mobile Cloud Service:

# Configure the analytics logger
oracle.maf.api.analytics.level=ALL
oracle.maf.api.analytics.handlers=
  oracle.maf.api.analytics.LoggerAnalyticsHandler,   
  oracle.maf.api.analytics.McsAnalyticsHandler
oracle.maf.api.analytics.custom.level=INFO
oracle.maf.api.analytics.LoggerAnalyticsHandler.level=INFO
# Configure MCSHandler
oracle.maf.api.analytics.McsAnalyticsHandler.level=INFO
oracle.maf.api.analytics.McsAnalyticsHandler.connectionId=McsConn
oracle.maf.api.analytics.McsAnalyticsHandler.batchSize=1
oracle.maf.api.analytics.McsAnalyticsHandler.offlineWrite=true
oracle.maf.api.analytics.McsAnalyticsHandler.recordUsername=false
oracle.maf.api.analytics.McsAnalyticsHandler.contextProviderClassName=
  oracle.maf.api.analytics.McsContextProvider

The logging.properties file options demonstrate several analytics capabilities.

The oracle.maf.api.analytics.handlers option reveals two handler classes: LoggerAnalyticsHandler and McsAnalyticsHandler. The logger handler takes care of the logs written by your Oracle Mobile Application Framework application. The MCS analytics handler provides the analytics capabilities. The oracle.maf.api.McsAnalyticsHandler options include the following:

  • level enables you to filter which analytics are sent to Oracle Mobile Cloud Service by their level, with values such as INFO, WARNING, and SEVERE.
  • connection must refer to a named URL connection in your Oracle Mobile Application Framework connections.xml file that maps to the Oracle Mobile Cloud Service server. This is what you set in the connections.xml file when you changed the value of CHANGE-BASE-URL to the value you copied from the mobile back end.
  • batchSize controls how many analytics events are queued before they are sent in one batch call to Oracle Mobile Cloud Service, with 1 being the minimum and 65 the maximum value. Increasing or decreasing this number changes the “chattiness” of your application to Oracle Mobile Cloud Service, with trade-offs of performance versus the timeliness of the analytics data sent to Oracle Mobile Cloud Service. For the purposes of this article, the value is set to 1, so it’s easier to see the analytics flushed to Oracle Mobile Cloud Service during testing.
  • offlineWrite—when set to true—enables the analytics events to be queued while the device is offline, a very common and needed mobile use case that is built into Oracle Mobile Application Framework. Oracle Mobile Application Framework can queue as many as 250 events.
  • recordUsername gives you the ability and choice to capture the mobile username in any analytics events.
Raising Custom Analytics Events and Properties

To capture explicit analytics data about your application, Oracle Mobile Application Framework provides a programming API for raising custom events and properties that can be posted to Oracle Mobile Cloud Service. Let’s include the code for raising a custom event:

  1. Within Oracle JDeveloper, open the MyBean.java file.
  2. In the file header, add the following imports:
    import java.util.logging.Level;
    import oracle.adfmf.json.JSONObject;
    import oracle.maf.api.analytics.AnalyticsUtilities;
  3. Locate the doAction method, and replace it with the following code:
    public void doAction(ActionEvent actionEvent) {
      try {
      JSONObject payload = new JSONObject();
      payload.put("CUSTOM_PROPERTY", "5");
      payload.put("ANOTHER_CUSTOM_PROPERTY", "FISH");
      AnalyticsUtilities.fireEvent(Level.INFO, 
      AnalyticsUtilities.CATEGORY_CUSTOM, "CUSTOM_EVENT", payload);
        } catch (Exception e) {
            // handle error
        }
    }

The AnalyticsUtilities.fireEvent function enables you to raise various custom events. In this example, you are raising an event named CUSTOM_EVENT and providing additional properties to post along with the event via a JSON object.
o46mcs-f2
 

Figure 2: Oracle Mobile Cloud Service Events analytics report

Let’s explore how custom events are surfaced in Oracle Mobile Cloud Service reports.

  1. Run your Oracle Mobile Application Framework application and, once it is running, log in, using joedoe and the password you previously set.
  2. On the events.amx page, click the button on the page to fire the doAction method to log the analytics event you coded.
  3. Return to Oracle Mobile Cloud Service and, from the left menu (under the Analytics option), select the Events page.
  4. On the Events page, note the Select an event list box. Open the list box, and select the CUSTOM_EVENT event.
  5. A graph presents details of when the event was captured and how many times. To the right of the Select an event list box, you will see the Select a group by property list box. Select this, and note the different properties Oracle Mobile Application Framework and Oracle Mobile Cloud Service have captured about the mobile user. This includes implicit analytics data captured by Oracle Mobile Application Framework. Select Operating System, and you should now see in the graph the operating system—Android or iOS, for example—from which you were running the app.
  6. From the Select a group by property list, select ANOTHER_CUSTOM_PROPERTY which you added earlier, and note how it is reflected in the analytics graph.
Going Offline

As you discovered in the logging.properties file, the Oracle Mobile Application Framework analytics feature has the ability to allow analytics data to be captured while the application is offline and flush that to Oracle Mobile Cloud Service when the application returns online. Let’s take a look at that capability:

  1. In the Oracle Mobile Cloud Service Events report, select the 1H (one-hour) option from the range of time filters, refresh the report by clicking the Reload Data button, and note the number of analytics events you raised and the last time they were raised, before you take the app offline. This will provide a baseline.
  2. For Android Emulator users only, in the Android Emulator, open Settings, select the More option under the Wireless & Networks group, and enable Airplane mode.
  3. For iOS Simulator users only, the iOS Simulator provides no way to go offline for testing purposes. Rather, you need to disconnect your Mac from the internet by disabling your Ethernet and Wi-Fi network on your Mac.
  4. Wait a couple of minutes, so the analytics data you are about to raise doesn’t get logged in at the same time as the previous data.
  5. Return to the application in the Android Emulator or the iOS Simulator, and click the Raise Event button a few times to raise analytics events, remembering how many times you did so and when.
  6. Return the app and device online. For Android Emulator users only, disable Airplane mode.
  7. For iOS Simulator users only, re-enable your Ethernet or Wi-Fi on your Mac.
  8. Again, wait a couple of minutes so the analytics data you are about to raise doesn’t get logged in at the same time as the previous data.
  9. Return to the mobile application, and click the Raise Event button a few times, remembering how many times you did it and when.
  10. Finally, return to Oracle Mobile Cloud Service and the Events report, click the Reload Data button, and observe all the analytics data captured. It includes analytics captured when the app was online and offline.

This demonstrates the capabilities of the Oracle Mobile Application Framework analytics features to record analytics even when the mobile app is offline, saving the analytics data for when the app returns online. Going offline is a very common occurrence in the mobile world, and with Oracle Mobile Application Framework’s analytics implementation, you’re not losing valuable analytics data.

Conclusion

In combination, Oracle Mobile Cloud Service’s analytic reporting and Oracle Mobile Application Framework’s native support for raising analytics events give you the ability to gain insight into your day-to-day users and their activities, so you can find out if your mobile application is effective, whether your mobile users are online or offline. With the analytics data—rather than guesses—in hand, you can make informed decisions that will have an impact on your users, app, and business moving forward, based on real empirical evidence.

Next Steps

TRY Oracle Mobile Cloud Service.

READ more about Oracle Mobile Cloud Service.

WATCH Oracle Mobile Cloud Service YouTube training.

JOIN the Oracle Mobile Platform Google+ community.

DOWNLOAD the starter application for this article.

 

Photography by Raw Pixel, Unsplash