Rebrand MicroStrategy Mobile for Android

You can rebrand the MicroStrategy Mobile application for Android by changing the name and icon, as well as the splash screen. The resulting mobile application then has your custom look and feel.

To create a rebranded application in Android Studio, perform the following steps.

Set up the environment to use the MicroStrategy Mobile project
Perform the desired rebranding actions
Build the project to confirm that the application compiles successfully
Add your Google Maps Android v2 API key to your application
Build the project again to confirm that the application compiles successfully

To deploy multiple mobile applications built using the MicroStrategy Mobile project, see Deploying Multiple MicroStrategy Mobile projects.

A detailed explanation of each of these steps is provided below.

Set up the environment to use the MicroStrategy Mobile project

Set up the environment so that you can use the MicroStrategy Mobile project as the base for your customizations.
Perform the desired rebranding actions

If the MicroStrategyMobile project is not open, open it in Android Studio, navigate toMicroStrategyMobile -> app -> src > main -> res, and do the following:
- Change the name of the application
  
  To customize the application name, you update an existing XML file (strings.xml).
  1. Navigate to the res -> values folder and open strings.xml.
  2. In strings.xml, update the current value of the app_name attribute with the name of your application.
```
<?xml version="1.0" encoding="utf-8"?>
 <resources>
    <string name="app_name">MSTRAndroidSample</string>
 </resources>
```
  3. Save strings.xml.
- Change the URL prefix for the application
  
  To give your application a custom scheme (URL prefix), update the manifest file and strings.xml.
  - To update the manifest file:
    1. Navigate to MicroStrategyMobile -> app -> src -> main to open AndroidManifest.xml.
    2. Change the code below, replacing DESIRED_SCHEME_NAME with your custom scheme.
      ... <activity android:launchMode="singleTask" android:name="com.microstrategy.android.webapp.MstrLoadConfigActivity" android:noHistory="true"> <intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:scheme="DESIRED_SCHEME_NAME"/> </intent-filter> <intent-filter> <action android:name="android.nfc.action.NDEF_DISCOVERED"/> <category android:name="android.intent.category.DEFAULT"/> <data android:pathPrefix="" android:scheme="DESIRED_SCHEME_NAME"/> </intent-filter> <intent-filter> <action android:name="android.nfc.action.TAG_DISCOVERED"/> </intent-filter> ...
    3. Save AndroidManifest.xml.
  - To update strings.xml:
    1. Open strings.xml under res -> values and add the code shown below, replacing DESIRED_SCHEME_NAME with your custom scheme.
      <string name="external_url_scheme">DESIRED_SCHEME_NAME</string>
    2. Save strings.xml.
  By default, the URL to open the application and run a document would be similar to the URL shown below:
```
mstr://?evt=2048001&documentID=41B1166B4C84A759CC2C19BB07C2EC00
```
  After you recompile your application, you can open the application using a URL with your custom scheme. For example, if your custom scheme was MyBigCompany, the URL to open the application and run a document would be similar to the URL shown below:
```
MyBigCompany://?evt=2048001&documentID=41B1166B4C84A759CC2C19BB07C2EC00
```
- Customize the icon for the application
  
  For 8.0+ devices, Google supports adaptive icons. When you customize the icon for Android 8.0 applications (API level 26+), you customize the adaptive icon. For Android applications with API level below 26, you customize the standard application icon.
  
  To customize the application icon, you replace an existing PNG file (mstr_icon.png or mstr_icon_foreground.png) and update an existing XML file (colors.xml).
  - Change the icon image for applications with API level below 26
    
    Inside res, there are drawable-* folders, where * represents different screen densities such as mdpi, hdpi, xhdpi, and xxhdpi. Each drawable-* folder contains a PNG file called mstr_icon.png that represents the standard icon for the application.
    
    The name of the icon image file, mstr_icon.png, cannot be changed.
    1. Create a new application icon and name it mstr_icon.png. Use Google's recommendations for the size of the icon.
    2. Overwrite the default mstr_icon.png in all the res->drawable-* folders with your new application icon (mstr_icon.png).
  - Change the adaptive icon image for applications with API level 26 or higher
    
    Inside res, there are drawable-* folders , where * represents different screen densities such as mdpi, hdpi, xhdpi, xxhdpi, and xxxhdpi. Each drawable-* folder contains a PNG file called mstr_icon_foreground.png that represents the adaptive the application.
    
    The name of the adaptive icon image file, mstr_icon_foreground.png, cannot be changed.
    1. Create a new application icon and name it mstr_icon_foreground.png. Use Google's recommendations for the size of the icon.
    2. Overwrite the default mstr_icon_foreground.png in all the res -> drawable-* folders with your new application icon (mstr_icon_foreground.png).
  - Change the adaptive icon color for applications with API level 26 or higher
    1. Navigate to res -> values and open colors.xml.
    2. In colors.xml, update the <color> node with the name attribute set to mstr_icon_bg. Replace the current color hex value with the hex value of the custom color you want to use for your application icon.
      <color name="mstr_icon_bg">#FFD9222D</color>
    3. Save colors.xml.
- Customize the notification icon for the application
  
  The notification icon is displayed each time the reconcile process occurs (that is, whenever subscriptions or live caches are being downloaded). The customization steps differ depending on the version of Android. To customize the notification icon for applications with API level below 21 (below Android 5.0), you add a new PNG file (called mstr_notification_icon.png. To customize the notification icon for applications with API level 21 or higher (Android 5.0+), you add a new transparent PNG file (called mstr_platform_notification.png and update an existing XML file (colors.xml).
  
  In Android 10 and below, modifying notification_tint_color changes both the notification app icon and app name color. In Android 10 and above, modifying notification_tint_color only changes the notification app icon.
  
  The background of the notification icon should always be transparent.
  - Change the notification icon image for applications with API level below 21 (below Android 5.0)
    
    Inside res, there are drawable-* folders , where * represents different screen densities such as mdpi, hdpi, xhdpi, and xxhdpi. You add a new PNG file called mstr_notification_icon.png to each drawable-* folder to specify the new custom notification icon for the application.
    1. Create a notification icon and name it mstr_notification_icon.png. Use Google's recommendations for the size of the icon.
    2. Copy mstr_notification_icon.png to all the res -> drawable-* folders.
  - Change the notification icon image for applications with API level 21 or higher
    
    Inside res, there are drawable-* folders , where * represents different screen densities such as mdpi, hdpi, xhdpi, and xxhdpi. You add a new PNG file called mstr_platform_notification.png to each drawable-* folder to specify the new custom notification icon for the application.
    1. Create a transparent notification icon and name it mstr_platform_notification.png. Use Google's recommendations for the size of the icon.
    2. Copy mstr_platform_notification.png to all the res -> drawable-* folders.
  - Change the notification icon color for applications with API level 21 or higher
    1. Navigate to res -> values and open colors.xml.
    2. In colors.xml, update the <color> node with the name attribute set to notification_tint_color. Replace the current color value with the hex value of the custom color you want to use for your custom notification icon.
      <color name="notification_tint_color">#FFD9232E</color>
    3. Save colors.xml.
- Customize the splash screen for the application
  
  There are two ways to customize the splash screen.
  - Replace the entire splash screen with a custom image
    
    When you use this method, you need to provide two splash screen images - one for portrait mode and one for landscape mode—and you must include the copyright and legal information on each custom image. You can also change the background color of the splash screen.
  - Replace the splash screen icon with a custom image and customize the text on the splash screen
    
    When you use this method, you customize the splash screen icon and the text, font size, and font color for the copyright and legal information. You can also change the background color of the splash screen.
  Replace the entire splash screen with a custom image
  
  To customize the splash screen for the application with this method, you need to provide two splash screen images - one for portrait mode and one for landscape mode - and create an XML layout file, called mstr_launch_screen.xml, for each orientation. If you also want to customize the background color for the splash screen, you modify the colors.xml file.
  
  You should include the copyright information on the splash screen image.
  - Customize the splash screen for portrait orientation
    1. Save the splash screen image for portrait mode under the res -> drawable* folders.
    2. Under res, navigate to layout-port and clear the content in mstr_launch_screen.xml.
    3. Copy the code below and paste it in mstr_launch_screen.xml. Replace the colored text in the code sample with the name of the .png file for your splash screen in portrait mode.
      <ImageView xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="match_parent" android:src="@drawable/image.png>" android:scaleType="fitXY" />
    4. Save mstr_launch_screen.xml.
  - Customize the splash screen for landscape orientation
    1. Save the splash screen image for landscape mode under the res -> drawable* folders.
    2. Under res, navigate to layout and clear the content in mstr_launch_screen.xml.
    3. Copy the code below and paste it in mstr_launch_screen.xml. Replace the colored text in the code sample with the name of the .png file for your splash screen in landscape mode.
      <ImageView xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="match_parent" android:layout_height="match_parent" android:src="@drawable/image.png>" android:scaleType="fitXY" />
    4. Save mstr_launch_screen.xml.
  - Change the background color for the splash screen
    1. Navigate to res -> values and open colors.xml.
    2. In colors.xml, update the <color> node with the name attribute set to splashscreen_background_color. Replace the current color hex value with the hex value of the color you want to use for the background of the splash screen.
      <color name="splashscreen_background_color">#D9232E</color>
    3. Save colors.xml.
  Replace the splash screen icon with a custom image and customize the text on the splash screen
  
  To customize the splash screen for the application with this method, you replace the icon on the splash screen and customize the text, font size, and font color for the copyright and legal information. The splash screen icon displays in the middle of the splash screen. You can also customize the background color for the splash screen.
  - Change the image for the splash screen icon
    
    Make sure that the mstr_launch_screen.xml files are not changed after you import the project for the first time.
    1. Save the image for the splash screen icon under the res -> drawable* folders.
    2. Rename all files to mstr_splash.png.
  - Change the copyright and legal information on the splash screen
  - Change the font color for the copyright and legal information on the splash screen
    1. Navigate to res -> values and open colors.xml.
    2. In colors.xml, update the <color> node with the name attribute set to splashscreen_text_color. Replace the current color hex value with the hex value of the color you want to use for the font color on the splash screen.
      <color name="splashscreen_text_color">#D9232E</color>
    3. Save colors.xml.
  - Change the font size for the copyright and legal information on the splash screen
    1. Navigate to res -> values.
    2. Open dimens.xml and update the following four font size variables:
      - splash_copy_right_legal_text_size_port
        This sets the text size for copyright and legal information in portrait mode.
      - splash_copy_right_legal_text_size_land
        This sets the text size for copyright and legal information in landscape mode.
    3. Set custom values for the four font size variables, as shown in the example code below.
      <resources> <dimen name="splash_copy_right_legal_text_size_port">8sp</dimen> <dimen name="splash_copy_right_legal_text_size_land">13sp</dimen> ... </resources>
    4. Save dimens.xml.
  - Change the background color for the splash screen
    1. Navigate to res -> values and open colors.xml.
    2. In colors.xml, update the <color> node with the name attribute set to splashscreen_background_color. Replace the current color hex value with the hex value of the color you want to use for the background of the splash screen.
      <color name="splashscreen_background_color">#D9232E</color>
    3. Save colors.xml.
- Customize the Action Bar for the application
  
  The Action Bar displays the name of the application and an icon.
  - Change the icon displayed on the Action Bar
    
    By default, the mstr_logo.png file inside the res/drawable-* folders provides the icon for the Action Bar. This is the same image used for the application icon. If you would like to have a different icon for the Action Bar, do the following:
    1. Create a new Action Bar icon and name it mstr_logo.png.
    2. Copy mstr_logo.png to all the res->drawable-* folders.
      
      The names of files in the drawable-* folders must contain only lowercase a-z, 0-9, or _.
  - Change the background color of the Action Bar
    
    If you want to change the background color of the Action Bar, do the following:
    1. Navigate to res -> values and open colors.xml.
    2. In colors.xml, update the <color> node with the name attribute set to actionbar_background_color. Replace the current color hex value with the hex value of the color you want to use for the background of the Action Bar.
      <?xml version="1.0" encoding="utf-8"?> <resources> <color name="actionbar_background_color">#1f1f1f</color> </resources>
    3. Save colors.xml.
  - Change the text color of the Action Bar
    
    If you want to change the text color of the Action Bar, do the following:
    1. Open colors.xml located under /MicroStrategyMobile/res/values.
    2. Add a new <color> node whose name attribute is set to "actionbar_text_color" and set the value of that node to the desired background color, as shown in bold in the code sample below:
      <?xml version="1.0" encoding="utf-8"?> <resources> <color name="actionbar_text_color">#e0e0e0</color> </resources>
    3. Save colors.xml.
- Customize URLs for the application
- Replace "MicroStrategy Mobile" with a custom string
  
  You can remove the default "MicroStrategy Mobile" string in error messages and subscription text, and replace it with your own custom string.
- Remove the confirmation dialog for reconfiguring your application
  
  When a user applies a configuration URL to a mobile device, the user must respond to the following dialog:
  
  “Are you sure you want to reconfigure your application to server ‘mobile server name’?”
  
  If you want to prevent this dialog from being displayed and have the reconfiguration happen without requiring a user response, do the following:
  1. Create bools.xml with the following code.
```
<?xml version="1.0" encoding="utf-8"?>                             
<resources>                                 
  <bool name="display_alert_when_applying_url">false</bool>                                
</resources>
```
  2. Save bools.xml under MicroStrategyMobile -> app -> src -> main -> res -> value.
- Use customized Badge login
  
  You can customize your app to use Badge to log in. You accomplish this by using the Badge SDK to log in to the MicroStrategy Mobile app. To use Badge to log in, you do the following:
  1. In the Badge SDK app, customize the app scheme (URL prefix).
  2. In the MicroStrategy Mobile app, you modify the usher_app_scheme attribute in the strings.xml file. Make sure the usher_app_scheme is consistent with the customized app scheme (URL prefix) of the Badge app.

Build the project to confirm that the application compiles and deploys successfully

Make sure that the MicroStrategyMobile project is selected in the Package Explorer.
1. Build the project by selecting Build Project from the Project menu.
2. From the Run menu, select Run As -> Android Application and select a target device. Confirm that the application compiles and deploys successfully.
Add your Google Maps Android v2 API key to your application

If you are developing an Android application that will use the Map widget, you must use a Google Maps Android v2 API Key. A single Maps API key is valid for all applications signed by the corresponding developer certificate. The Google Developers site provides instructions on how to get a Google API key.

Update the manifest file for your application so that it references your Google Maps Android v2 API Key:
1. Navigate to MicroStrategyMobile -> app -> src -> main to open AndroidManifest.xml.
2. Navigate to the <application> element.
  
  In the <meta-data> child element, replace the value of the android:value attribute with your API Key.
```
        <meta-data android:name="com.google.android.maps.v2.API_KEY" android:value="Enter your Google Maps API key here">
```
  Make sure to sign your application with the certificate to which the Maps API Key is registered.
Build the project again to confirm that the application compiles and deploys successfully
1. Build the project.
2. Run the compiled application on a device or simulator to confirm that the apk you built can run successfully.

To distribute mobile applications to your users, refer to the Distributing Android Applications topic.