1. Installing and Configuring Oracle Application Performance Monitoring
  2. Install and Configure APM on Mobile Clients

12 Install and Configure APM on Mobile Clients

Topics:

iOS: Requirements and Installation Instructions

You can deploy Application Performance Monitoring on a mobile device running on iOS.

Download the APM iOS Mobile Agent, configure and include it in your iOS Mobile App and repackage the iOS Mobile App. Any iOS device running that application will now send APM metrics to Oracle Management Cloud, where you will be able to analyze them from the APM UI on the Oracle Management Cloud.
Prerequisites:

  • XCode version 8.1 and above

  • iOS – v 9 and above

Provision APM Mobile Agent on an iOS device:

  1. Generate a Registration Key, if you do not have one already. See Manage Registration Keys in Installing and Managing Oracle Management Cloud Agents.

    For Linux, the key is ${REG_KEY} , and for Windows, %REG_KEY%.

  2. Register your Mobile Client App and obtain a Mobile Client App Id:

    1. In the left pane of the Oracle Management Cloud home page, select Administration.

    2. Click APM Admin menu and select Mobile Client Registrations.

    3. Register iOS mobile client on Application Performance Monitoring:

      1. Click Register Mobile Client.

      2. Provide the registration details — name of the application, mobile client platform (iOS), and the registration key. You can reuse the registration key generated in the Agent Download page.

        Note:

        The name of the mobile application you provide here must be the same as your target iOS mobile app.

      3. Click Register.

      This generates the Mobile Client App ID for the application, and this ID will be used in a later step. Copy and save this ${MOBILE_CLIENT_APP_ID}.

    4. Click OK.

  3. Download the APM Mobile iOS Agent Installer. See Downloading the APM Agent Software. Ensure that the downloaded installer ZIP file is accessible from a Linux or Darwin (MacOS) shell window, or a Windows cmd window.

  4. Extract the ZIP to a local work directory like /scratch/work. 

    $ unzip <apm ios installer>.zip -d /scratch/work
    Verify that the extracted content contains the following:

    • agent_software_build.xml

    • ApmAgent-<version>.zip

    • ProvisionApmiOSAgent.sh

    • AgentConfig.info

    • certificates/

    • certificates/emaas.cer

    • hybrid/

  5. Run ProvisionApmiOSAgent.sh to extract ApmAgent-<ver>.zip and to configure the ApmMobileAgent.properties file: 

    $ sh ./ProvisionApmiOSAgent.sh -a ${MOBILE_CLIENT_APP_ID}

  6. Verify that the following new files get created in the directory where you ran the above step:

    • APMMobileAgent.framework

    • APMMobileAgent.framework/APMMobileAgent

    • APMMobileAgent.framework/APMMobileAgent.bundle

    • APMMobileAgent.framework/Headers

    • APMMobileAgent.framework//APMMobileAgent.bundle/AgentStartup.properties

    • hybrid/apmeum.js
    • hybrid/apmeumConfig.js
    • hybrid/apmeumBridge.js

  7. Verify that the file ApmMobileAgent.properties is configured with the correct OMC details.

Configure APM with your Mobile Application:

These steps are documented for Xcode version 9.0. From your Xcode IDE, include the APM iOS Mobile Agent into your mobile application so that Application Performance Monitoring starts when the application starts:

  1. Add APMMobileAgent.framework and APMMobileAgent.bundle into your project (one at a time):

    1. Open the Finder window, and locate the APMMobileAgent.framework or the APMMobileAgent.bundle directory.

    2. Drag and drop the APMMobileAgent.framework or the APMMobileAgent.bundledirectory from the Finder window into your Xcode Application Project, Framework folder.

    3. In the Choose options for adding these files: window,

      1. Select the Copy items if needed checkbox.

      2. From the Add to targets list, select the target iOS application.

      3. Select Finish.

  2. Verify the APM Mobile Agent libraries to your project.

    1. Click the Build Phases menu.

    2. Expand the Link Binary with Libraries section.

    3. Verify that the APMMobileAgent.framework folder is in the Link Binary With Libraries table.

  3. Add libsqlite3.0.tbd to your project.

    1. In the Link Binary With Libraries section, below the table of libraries, click + icon.

    2. Select the application’s Xcode project.

    3. In the Choose frameworks and libraries to add: window, search for libsqlite3.0.tbd.
    4. Select libsqlite3.0.tbd and click Add.
  4. Modify your code to initialize APMMobileAgent.framework and start the APM iOS Mobile Agent:

    1. Open AppDelegate.m

    2. Import APMMobileAgent to the header of AppDelegate.m file:
      #import<APMMobileAgent/OMCAPMMobileAgent.h>

    3. Find the method (BOOL)application: (UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOption{}.

    4. Add this line to method to start APM iOS Mobile Agent:
      - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ 
    // Start the APM iOS Mobile Agent
    
        .
        .
        .

     [OMCAPMMobileAgent initializeSDK];
 }
    Example:
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{ 
    // Start the APM iOS Mobile Agent
     [OMCAPMMobileAgent initializeSDK];
}
  5. If you are running a hybrid mobile application:
      • Copy the files apmeum.js, apmeumBridge.js and apmeumConfig.js from hybrid directory into the app's src js directory.
      • The properties in the file apmeumConfig.js are set automatically after running the provisioning script. Verify to see if the properties are set correctly.
      • From the app's src folder, edit the index.html file, and add these below lines within the body tag.
        <script type="text/javascript" src="js/apmeumConfig.js"></script>
<script type="text/javascript" src="js/apmeumBridge.js"></script>
<script async type="text/javascript" src="js/apmeum.js"></script>
      • In the same index.html file, modify the Content-Security-Policy for default-src, and include omcapmjs: as below:
        <meta http-equiv="Content-Security-Policy"content="default-src omcapmjs:
      • Repeat these steps for all the HTML pages in the app.
  6. Rebuild your mobile application in Xcode to include APM iOS Mobile Agent.

Android: Requirements and Installation Instructions

You can deploy Application Performance Monitoring on a mobile device running on Android.

Prerequisites:

  • Android Studio version 3.0.1 and above

  • Android SDK API version 21 (Lollipop) and above.

  • Ensure that the ANDROID_HOME environment variable is set and it contains the path to Android SDK. Verify that the Android SDK contains the following sub folders such as platforms, platform-tools, and build-tools. Set the ANDROID_HOME property on My Computer as well as in the Android Studio Settings.

    Example: ANDROID_HOME - C:\Android\sdk

  • Create staticlibs directory in the app's root folder (app/staticlibs). Ensure that the app's root folder contains both the libs and staticlibs folders.

  • If you have enabled Proguard in the Android app, then set the Proguard rules as follows:

    -keepattributes EnclosingMethod 
-keepattributes InnerClasses         
-dontwarn InnerClasses         
-dontwarn com.oracle.diagnostics.instrumentor.**         
-keep class com.oracle.emaas.agent.android.instrumentation.** { *; }         
-keep class com.oracle.diagnostics.instrumentor.** { *; }
To provision APM Mobile Agent on an Android device:
  1. Generate a Registration Key, if you do not have one already. See Manage Registration Keys in Installing and Managing Oracle Management Cloud Agents.
  2. Register your Mobile Client App and obtain a Mobile Client Id:
    1. In the left pane of the Oracle Management Cloud home page, select Administration.
    2. Click APM Admin menu and select Mobile Client Registrations.
    3. Register Android mobile client on Application Performance Monitoring:

      1. Click Register Mobile Client.

      2. Provide the registration details — name of the application, mobile client platform (Android), and the registration key.

        Note that the name of the mobile client you provide here must be the same as your target Android mobile client. You can find the app name in your Android application in the AndroidManifest.xml file, within the <application> tag, android:label.

      3. Click Register.

        This generates the Mobile Client App ID for the application, and this ID will be used in a later step. Copy and save this ${MOBILE_CLIENT_APP_ID}.

      4. Click OK.

  3. Download the APM Mobile Android Agent Installer. See Downloading the APM Agent Software.
  4. Extract the ZIP to a local work directory like /scratch/work.
    $ unzip <apm android installer>.zip -d /scratch/work
  5. Navigate to the extracted staging directory and verify that it has these contents:
    ApmAgent-<version>.zip       
ProvisionApmAndroidAgent.sh  
ProvisionApmAndroidAgent.cmd  
agent_software_build.xml  
AgentConfig.info        
certificates/
certificates/emaas.cer 
hybrid/apmeum.js
  6. Run ProvisionApmAndroidAgent.sh to extract ApmAgent-<ver>.zip and to configure the ApmMobileAgent.properties file:
    $ sh ./ProvisionApmAndroidAgent.sh -a ${MOBILE_CLIENT_APP_ID}
  7. Verify that the following new files get created in the directory where you ran the above step:

    • apmandroidagentruntime.jar

    • apmdxagent.jar

    • ApmMobileAgent.properties

    • hybrid/apmeumConfig.js
  8. Verify that the file ApmMobileAgent.properties is configured with the correct OMC details.
Configure your mobile client with APM agent:

These Steps are documented for Android Studio 3.0.1.

  1. Update the compile and runtime jar files (jar files extracted from the APM Agent Installer zip file).

    1. Copy apmandroidagentruntime.jar to app/libs.

    2. Copy apmdxagent.jar to a location and update the path in the build.gradle file.

      Example:
      dependencies {
	classpath files('<path to apmdxagent.jar>/apmdxagent.jar')
}
apply plugin: 'com.oracle.agentplugin'
      Note: It is recommended that you add the apply plugin tag at the end of the build.gradle file.

  2. Repeat the above step in all the build.gradle in the app's library.

  3. Copy ApmMobileAgent.properties file into the app's assets folder (app/src/main/assets).

  4. Create Application class extending android.app.Application if it does not exist and override onTrimMemory(). Define application class name in the application tag of the manifest file: 

    package org.oracle.emaas.app123;
import android.app.Application;
public class app123Application extends Application {
     @Override
     public void onTrimMemory(int level) {
     } 
}

  5. Edit the app's AndroidManifest.xml and do the following:

    1. Set the following permissions :

      <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    2. Add the following in the application tag:
      <receiver android:name="com.oracle.emaas.agent.android.runtime.receiver.APMReceiver"/>
<service android:name="com.oracle.emaas.agent.android.runtime.service.APMService"/>
  6. If you are running a hybrid mobile application:
      • Copy the files apmeum.js and apmeumConfig.js from hybrid directory into the app's src js directory.
      • The properties in the file apmeumConfig.js are set automatically after running the provisioning script. Verify to see if the properties are set correctly.
      • From the app's src folder, edit the index.html file, and add these below lines within the body tag.
        <script type="text/javascript" src="js/apmeumConfig.js"></script>
<script async type="text/javascript" src="js/apmeum.js"></script>
      • Repeat these steps for all the HTML pages in the app.
  7. If using Webviews, then set the Webview client and override the following methods:
    onPageStarted(WebView view, String url, Bitmap favicon)
onPageFinished(WebView view, String url)
onReceivedError(WebView view, int errorCode, String description, String failingUrl)
Troubleshooting:

  1. Include the following in the app's build.gradle file to bypass errors that may be caused by APM Agent. 

    android{            
		lintOptions {
                   abortOnError false
            }
         }