Version 2021

Rebrand Library Mobile for Android

You can rebrand the MicroStrategy Library Mobile application for Android by changing the name and icon, customizing the splash screen, and making a number of other customizations. The resulting mobile application then has your custom look and feel.

In order to create a rebranded application in Android Studio, perform the following steps.

  1. Set up the environment to use the MicroStrategy Library Mobile sample Android project

  2. Perform the desired rebranding actions

  3. Build the project to confirm that the application compiles successfully  

  4. Add your Google Maps Android v2 API key to your application  

  5. Build the project again to confirm that the application compiles successfully

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

  1. Set up the environment to use the MicroStrategy Library Mobile project

    Set up the environment so that you can use the MicroStrategy Library Mobile project as the base for your customizations.  

  2. Perform the desired rebranding actions

    If the MicroStrategyLibraryMobile project is not open, open it in Android Studio, navigate to MicroStrategyLibraryMobile > app > src > main > res,  and do the following:

    • Change the name of the application

      To give your application a custom name, update the value of the app_name attribute in strings.xml.

      1. Navigate to the res >values folder and open strings.xml with a text editor.

      2. In strings.xml, update the value of the app_name attribute with the name of your application.

        <?xml version="1.0" encoding="utf-8" standalone="no"?
           <resources>
              <string name="app_name">your custom application name</string>
           </resources>
        
      3. Save strings.xml.  

    • 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 need to customize the adaptive icon. For Android applications with API level below 26, you only need to customize the standard application icon.

      • Change the icon image for applications with API level below 26

        The drawable-* folders (where * represents different screen densities such as mdpi, hdpi, and so on) inside res contain a PNG file called dossier_icon.png that represents the adaptive icon of the application

        The name of the icon image file, dossier_icon.png, cannot be changed.  

        1. Create a new application icon and name it dossier_icon.png. Use Google's recommendations for the size of the icon.

        2. Overwrite the default dossier_icon.png in all the res > drawable-* folders with your new application icon (dossier_icon.png).

          The names of files in the drawable-* folders must contain only lowercase a-z, 0-9, or _.

      • Change the adaptive icon image for applications with API level 26 or higher

        The drawable-* folders (where * represents different screen densities such as mdpi, hdpi, and so on) inside res contain a PNG file called dossier_icon_foreground.png that represents the adaptive icon of the application.

        The name of the adaptive icon image file, dossier_icon_foreground.png, cannot be changed.  

        1. Create a new application icon and name it dossier_icon_foreground.png. Use Google's recommendations for the size of the icon.  
        2. Overwrite the default dossier_icon_foreground.png in all the res > drawable-* folders with your new application icon (dossier_icon_foreground.png).

          The names of files in the drawable-* folders must contain only lowercase a-z, 0-9, or _.

      • Change the adaptive icon color for applications with API level 26 or higher

        1. Navigate to res > values.
        2. If one does not already exist, create a file called colors.xml under values. In a text editor, add a <color> node with the name attribute set to dossier_icon_bg, like the one shown below. You specify the color variable by providing the hex value of the color you want to use. For example, in the code shown below, you set the background color to pale gray (#CCC5CC):

          <color name="dossier_icon_bg">#CCC5CC</color>

        3. Save colors.xml.
    • Customize the notification icon for the application

      • Change the notification icon image for the application

        The drawable-*folders (for different screen densities) inside res contain a PNG file called library_notification.png. The notification icon is displayed each time the reconcile process occurs (that is, whenever subscriptions or live caches are being downloaded).

        1. Create a notification icon and name it library_notification.png. Use Google's recommendations for the size of the icon.  
        2. Copy library_notification.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 notification icon color for the application

        1. Navigate to res > values.
        2. If one does not already exist, create a file called colors.xml under values. In a text editor, add a <color> node with the name attribute set to dossier_notification_tint_color, like the one shown below. You specify the color variable by providing the hex value of the color you want to use. For example, in the code shown below, you set the background color to pale gray (#CCC5CC):

          <color name="dossier_notification_tint_color">#CCC5CC</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

      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 dossier_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.

      If the MicroStrategyLibraryMobile project is not open, open it in Android Studio. Navigate to MicroStrategyLibraryMobile > app > src > main > res.

      You should include the version number and 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 dossier_launch_screen.xml.
        3. Copy the code below and paste it in dossier_launch_screen.xml. Replace the bold text in the code sample with the name of your splash screen .PNG file for portrait mode.

          <?xml version="1.0" encoding="utf-8"?> 
          <ImageView xmlns:android="http://schemas.android.com/apk/res/android"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:src="@drawable/your splash screen image for portrait mode>"
            android:scaleType="fitXY" />
        4. Save dossier_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 dossier_launch_screen.xml.
        3. Copy the code below and paste it in dossier_launch_screen.xml. Replace the bold text in the code sample with the name of your splash screen .PNG file for landscape mode.

          <?xml version="1.0" encoding="utf-8"?> 
          <ImageView xmlns:android="http://schemas.android.com/apk/res/android"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:src="@drawable/<your splash screen image for landscape mode>"
            android:scaleType="fitXY" />
          
        4. Save dossier_launch_screen.xml.

      • Change the background color for the splash screen

        1. Navigate to res > values.
        2. If one does not already exist, create a file called colors.xml under values. In a text editor, add a <color> node like the one shown below. You specify the color variable by providing the hex value of the color you want to use. For example, in the code shown below, you set the background color to dark orange/red (#D9232E):

          <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.

      If the MicroStrategyLibraryMobile project is not open, open it in Android Studio. Navigate to MicroStrategyLibraryMobile > app > src > main > res.

      • Change the image for the splash screen icon

        Make sure that the dossier_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. Under res, navigate to layout and create a file called dossier_splash_screen.xml.
        3. Copy the code below and paste it in dossier_splash_screen.xml. Replace the bold text in the code sample with the name of your splash screen icon .PNG file.

          <?xml version="1.0" encoding="utf-8"?> 
          <ImageView xmlns:android="http://schemas.android.com/apk/res/android"
            android:id="@+id/mstr_splashscreen"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:src="@drawable/your splash screen image for portrait mode>" />
        4. Save dossier_launch_screen.xml.

      • Change the copyright and legal information on the splash screen

        1. Create a locale-specific values-* folder under res or use one that you have already created. For example, for US English, create or use a folder called values-en-rUS. This folder is a sibling of the values folder inside res. ClosedClick here to see a list of all locale-specific values-* folders that you can create or use.  

          • values-da-rDK

          • values-de

          • values-en

          • values-en-rGB

          • values-en-rUS

          • values-es

          • values-fr

          • values-it

          • values-ja

          • values-ko

          • values-nl

          • values-pl

          • values-pt

          • values-ru

          • values-sv

          • values-zh-rCN

          • values-zh-rTW

        2. Add a strings.xml file to the desired values-* folder or use one that you have already created.
        3. Add the two attributes—SPLASH_COPYRIGHT and SPLASH_LEGAL—to the strings.xml file and set their values to the strings that represent the copyright and legal information you want to use for the application.

          <?xml version="1.0" encoding="utf-8" standalone="no"?> 
          <resources> 
              <string name="SPLASH_COPYRIGHT">custom copyright string</string>
              <string name="SPLASH_LEGAL">custom legal info string</string>
              ... 
          </resources>
        4. Save strings.xml.  

      • Change the font color for the copyright and legal information on the splash screen

        1. Navigate to res > values.
        2. If one does not already exist, create a file called colors.xml under values. In a text editor, add a <color> node like the one shown below. You specify the value for the splashscreen_text_color variable by providing the hex value of the color you want to use. For example, in the code shown below, you set the text color to dark orange/red (#D9232E):

          <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 two font size variables, as shown in the example code below.

          <?xml version="1.0" encoding="utf-8" standalone="no"?> 
          <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.
        2. If one does not already exist, create a file called colors.xml under values. In a text editor, add a <color> node like the one shown below. You specify the value for the splashscreen_background_color variable by providing the hex value of the color you want to use. For example, in the code shown below, you set the background color to dark orange/red (#D9232E):

          <color name="splashscreen_background_color">#D9232E</color>
        3. Save colors.xml.
    • Change the logo used on the login page for the application

      If the MicroStrategyLibraryMobile project is not open, open it in Android Studio. Navigate to MicroStrategyLibraryMobile > app > src > main > res.

      You can customize the login page logo for the application using either an image or a new icon font for the logo. To do this, navigate to layout under res and create a file called dossier_login_icon.xml. Do one of the following:

      Use a custom image

      1. Copy the code below to dossier_login_icon.xml and save the file:

        <?xml version="1.0" encoding="utf-8"?> 
        <ImageView amlns:android="http:/schemas.android.com/apk/res/android"
          android:id="@+id/dossier_login_icon" 
          android:layout_width="wrap_content" 
          android:layout_height="wrap_content" 
          android:src="@drawable/login_logo" />
      2. Rename the image you want to use as login_logo.png and copy it to all the res > drawable-* folders.

        The names of files in the drawable-* folders must contain only lowercase a-z, 0-9, or _.

      Using a new icon font for the logo

      1. Create an icon font file and put it under MicroStrategyLibraryMobile > app > src > main > assets.
      2. Copy the code below to dossier_login_icon.xml:

        <?xml version="1.0" encoding="utf-8"?> 
        <com.microstrategy.android.dossier.ui.view.IconFontTextView
          xmlns:app="http://schemas.android.com/apk/res-auto"
          xmlns:android="http://schemas.android.com/apk/res/android"
          android:id="@+id/dossier_login_icon"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:text="@string/dossier_icon_text"
          android:textSize="65sp"
          android:textColor="@color/white"
          app:typefaceFile="YOUR_ICONFONT_FILE_NAME"
        />
        
      3. Make the following changes to dossier_login_icon.xml:
        • Replace the value of Android:text (@string/dossier_icon_text) with the Hex code of the logo icon string.
        • Replace the value of Android:textSize (65sp) with the text size you want to use.
        • Replace the value of Android:textColor (@color/white) with the text color you want to use.
        • Replace the value of app:typefaceFile (YOUR_ICONFONT_FILE_NAME) with the icon font file name.
      4. Save dossier_login_icon.xml.

    • Change the link for Help and Support for the application

      If the MicroStrategyLibraryMobile project is not open, open it in Android Studio. Navigate to MicroStrategyLibraryMobile > app > src > main > res.

      To customize the Help and Support page for the application, update the value of the dossier_help_url attribute in the locale-specific version of strings.xml.

      1. Under res, create locale-specific values-* folders for each language whose Help and SUpport page you want to customize, or use folders that you have already created. For example, for US English, create or use a folder called values-en-rUS. This folder is a sibling of the values folder inside res. ClosedClick here to see a list of all locale-specific values-* folders that you can create or use.  

        • values-da-rDK

        • values-de

        • values-en

        • values-en-rGB

        • values-en-rUS

        • values-es

        • values-fr

        • values-it

        • values-ja

        • values-ko

        • values-nl

        • values-pl

        • values-pt

        • values-ru

        • values-sv

        • values-zh-rCN

        • values-zh-rTW

      2. Inside each locale-specific values-* folder, create a strings.xml file.
      3. Add a dossier_help_url attribute to each strings.xml file and set its value to the string that represents the path to the Legal page you want to use for the application. For example, you might set the value to "http://Help.myCompany.com" for US English.

        <resources> 
            <string name="dossier_help_url">custom Help URL</string>
            ... 
        </resources> 
      4. Save each strings.xml file.  

    • Change the link for the Legal page for the application

      If the MicroStrategyLibraryMobile project is not open, open it in Android Studio. Navigate to MicroStrategyLibraryMobile > app > src > main > res.

      To customize the Legal page for the application, update the value of the dossier_legal_url attribute in the locale-specific version of strings.xml.

      1. Under res, create locale-specific values-* folders for each language whose Legal page you want to customize, or use folders that you have already created. For example, for US English, create or use a folder called values-en-rUS. This folder is a sibling of the values folder inside res. ClosedClick here to see a list of all locale-specific values-* folders that you can create or use.  

        • values-da-rDK

        • values-de

        • values-en

        • values-en-rGB

        • values-en-rUS

        • values-es

        • values-fr

        • values-it

        • values-ja

        • values-ko

        • values-nl

        • values-pl

        • values-pt

        • values-ru

        • values-sv

        • values-zh-rCN

        • values-zh-rTW

      2. Inside each locale-specific values-* folder, create a strings.xml file.
      3. Add a dossier_legal_url attribute to each strings.xml file and set its value to the string that represents the path to the Legal page you want to use for the application. For example, you might set the value to "http://LegalInfo.myCompany.com" for US English.

        <resources> 
            <string name="dossier_legal_url">custom Legal page</string>
            ... 
        </resources> 
        
      4. Save each strings.xml file.  

    • Change the error message title

      To change the error message title, update the value of the ERROR_DIALOG_TITLE attribute in strings.xml.

      1. Navigate to the res > values folder and open strings.xml with a text editor.

      2. In strings.xml, update the value of the ERROR_DIALOG_TITLE attribute with the error dialog title you want to use.

        <?xml version="1.0" encoding="utf-8" standalone="no"?
           <resources>
              <string name="ERROR_DIALOG_TITLE">your custom error dialog title name</string>
           </resources>
        
      3. Save strings.xml.  

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

    Make sure that the MicroStrategyLibraryMobile 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.
  2. 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 MicroStrategyLibraryMobile > 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, as shown in bold below.

              <meta-data android:name="com.google.android.maps.v2.API_KEY" android:value=insert your Google Maps API key here> 

      Make sure to sign your application with the certificate to which the Maps API Key is registered.

  3. 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.