Overview

To begin making the SDK your own, you can change the app’s default name and icons, including the app icon. You can also change any images and add some fonts, which you’ll reference later in your theme file.

Display Name

To change the app’s display name, open institutions/mxmobile/config/overrides.yaml and edit app_name.

Logo

To change the logo that appears throughout your app, place your new mxmobile_logo_white.png images in the SD and HD folders in institutions/mxmobile/assets/mxmobile.

For more info, see the instructions for changing an image.

Icons

All default icons are located in the client/default/assets/icons folder. You can override as many default icons as you like. All overridable icons are Scalable Vector Graphic (SVG) files.

To override one or more icons:

  1. Correctly format your SVG file. See SVG Examples for examples of correctly and incorrectly formatted SVG files.
    1.1 Group graphical elements in a group tag (<g>...</g>).
    1.2 Set the default stroke and fill color to white (<g fill='#FFFFFF' stroke='#FFFFFF'>).
    1.3 Set the default width and height to 16.
    1.4 Set the viewBox attribute to “0 0 16 16” (<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' width='16' height='16'>).
  2. Add your correctly formatted SVG file into the institutions/mxmobile/assets/mxmobile/icons folder with the same file name as the SVG file you want to replace from the client/default/assets/icons folder.
  3. Run ./verify to validate your custom SVG files. We support a subset of the Scalable Vector Graphics’ standard. This command can emit the following warnings:
    • class attributes are not supported! Use 'style' attribute to inline CSS declarations.
    • 'mask' elements are not supported!
    • 'opacity' attributes and declarations are not supported! Use '[fill|stroke|stop]-opacity' instead.

SVG Examples

The following examples show a correctly formatted SVG, an incorrectly formatted SVG, and example output from ./verify for the incorrectly formatted SVG.

Correctly Formatted SVG

1
2
3
4
5
6
7

<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' width='16' height='16'>
  <g fill='#FFFFFF' stroke='#FFFFFF'>
    <path d='M 1 1 L 15 15' fill='none' stroke-linecap='round' stroke-linejoin='round' stroke-width="2"/>
    <path d='M 1 15 L 15 1' fill='none' stroke-linecap='round' stroke-linejoin='round' stroke-width="2"/>
    <circle cx='8' cy='8' r='4' data-cap='butt' data-stroke='none' stroke='none'/>
  </g>
</svg>

Incorrectly Formatted SVG

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' width='16' height='16'>
  <title>
    gifts donations
  </title>
  <mask id="myMask" />
  <g fill='#FFFFFF' stroke='#FFFFFF'>
    <path d='M2.5 2.5a1.922 1.922 0 0 1 1.833-2C7.045.5 8 4.5 8 4.5H4.333a1.921 1.921 0 0 1-1.833-2z' fill='none' stroke-linecap='round' stroke-linejoin='round' data-color='color-2'/>
    <path d='M13.5 2.5a1.922 1.922 0 0 0-1.833-2C8.955.5 8 4.5 8 4.5h3.667a1.921 1.921 0 0 0 1.833-2z' fill='none' stroke-linecap='round' stroke-linejoin='round' data-color='color-2'/>
    <path fill='none' stroke-linecap='round' stroke-linejoin='round' data-color='color-2' d='M6.5 15.5v-6'/>
    <path fill='none' stroke-linecap='round' stroke-linejoin='round' data-color='color-2' d='M9.5 15.5v-6' class="blue-fill"/>
    <path fill='none' opacity="0.4" stroke='#FFFFFF' stroke-linecap='round' stroke-linejoin='round' d='M13.5 9.5v6h-11v-6'/>
    <path fill='#FF0000' stroke='#FFFFFF' stroke-linecap='round' stroke-linejoin='round' d='M.5 4.5h15v3H.5z'/>
  </g>
</svg>

./verify Linter Warning Messages

1
2
3
4
5
6
7
8
9
10
11
12

$ ./verify
...
class attributes are not supported! Use 'style' attribute to inline CSS declarations.
<path fill="none" stroke-linecap="round" stroke-linejoin="round" data-color="color-2" d="M9.5 15.5v-6" class="blue-fill">
                                                                                                       ^

'mask' elements are not supported!
<mask id="myMask">
 ^

'opacity' attributes and declarations are not supported! Use '[fill|stroke|stop]-opacity' instead.
<path fill="none" opacity="0.4" stroke="#FFFFFF" stroke-linecap="round" stroke-linejoin="round" d="M13.5 9.5v6h-11v-6">

Change Icon Background

To help make the icons within some components appear more prominent, you can customize the icon style definition — and each icon style definition’s properties — for the following components in your theme file.

Component Location in Theme File Icons
Dashboard Card Buttons Search for “card_button_styles” then change the icon_type in the DASHBOARD section. Changing the icon_type in the DASHBOARD section changes the icons in the Transfers, Deposits, and Payments cards that appear in a single row on the Dashboard view.
Dashboard Portrait Header Component Search for “portrait_dashboard_header_styles” then change the icon_type in the PORTRAIT_DASHBOARD_HEADER section. Changing the icon_type in this section changes the burger menu icon on the dashboard view. This will only change the burger menu icon in this location. For example, if you change this component’s icon_type, then select an account in-app, the burger menu icon that appears on that view won’t be affected, as that icon is only affected by changing the Navigation Bar Component’s icon_type.
Modal Header Search for “modal_header_styles” then change the close_icon_style in the MODAL_HEADER section. Changing the close_icon_style will change the close icon that appears on many modals, such as the Forgot Password modal or Account Name modal.
Navigation Bar Search for “navigation_bar_styles” then change the icon_type. Changing the icon_type in this section changes the back arrow icon, add icon, kabob icon, and burger menu icon (not including the burger menu icon on the dashboard view) that can appear at the top of a view navigated to from the dashboard or sidebar menu. These icons are also present in some links on the login view, such as Locations and Help & Legal.

To modify an icon background style:

  1. Open your theme file (default is institutions/mxmobile/config/themes/theme_light.json) and search for a style definition section, as seen in the previous table, for the component containing the icons you want to customize.
  2. Set icon_type (or the close_icon_style and action_icon_style, if customizing the Modal Header component) to one of the following predefined icon style definitions:
    • CIRCLE_FILL
    • CIRCLE_OUTLINE
    • CIRCLE_OUTLINE_HIGHLIGHT
    • SMALL_CARD_BUTTON_ICON
    • LARGE_CARD_BUTTON_ICON
    • BOTTOM_SHEET_CLOSE_ICON
    • BOTTOM_SHEET_ACTION_ICON
    • BOTTOM_SHEET_ICON_HIGHLIGHT
    • SMALL_CIRCLE_FILL
  3. For the icon style definition you set the icon_type to, customize the icon style definition’s properties. See Icon Style Definition Properties for more information.

Icon Style Definition Properties

Each icon style definition contains the following properties.

Property Type Description
background_color Color (for example, SUCCESS_300) Color used for circular filled or stroked icon backing when component is in a neutral state.
background_opacity Byte (0-255) Opacity of the background stroke or fill.
background_selected_color Color (for example, SUCCESS_300) Color used for circular filled or stroked icon backing when component is in a selected state.
circle_diameter Number Diameter (in design points) of circular icon backing.
has_border Boolean If true, the circular icon backing is a circle with a 2 design-point width stroke. When false, the circle is filled.
icon_color Color (for example, PRIMARY_300) Color used for the icon when the component is in a neutral state.
icon_selected_color Color (for example, PRIMARY_300) Color used for the icon when the component is in a selected state.
icon_size_type Named icon size type (for example, JUMBO) Icon size. One of DEFAULT, JUMBO, LARGE, MEDIUM, MEDIUM_LARGE, SMALL, or SMALL_MEDIUM.
lightest_background_opacity Byte (0-255) Not used, but reserved for future use.
show_gradient Boolean Not used, but reserved for future use.

Fixed Icons

The following locations have an icon_type that is fixed; you can’t change the icon style definition they reference:

  • Move Money List Row uses SMALL_CIRCLE_FILL
  • Transaction Detail Header uses CIRCLE_OUTLINE
  • Notifications icon uses CIRCLE_FILL
  • Start back button uses CIRCLE_FILL
  • Dashboard View back button uses CIRCLE_FILL
  • Transaction Filter view uses BOTTOM_SHEET_CLOSE_ICON

Change the App Icon

Changing the app icon has a different process than changing in-app icons.

Your app icon should be a 1024x1024px .png.

To change your app icon:

  1. Edit institutions/mxmobile/config/overrides.yaml and change icon_url to either the:
    • Path to a local file (/Users/<you>/images/new_icon.png).
    • URL of a file hosted by MX (contact MX to have your new icon uploaded).
  2. Run ./generate

Fonts

You can use any TrueType font. To change a font, you must first add it, then reference it in the font definitions section of your theme file.

For more info on the theme file, refer to the theme section.

Once you have a .ttf file you’d like to add:

  1. Use a program like FontForge or FontBook to verify that the “Fontname” (FontForge) or “PostScript name” (FontBook) is the same as the file name (without the .ttf extension).
  2. Use a program like FontForge and ensure that the font has a glyph for U+25CF (the password masking character).
  3. Copy your .ttf file to institutions/mxmobile/assets.

After you’ve added and verified your .ttf file:

  1. Edit institutions/mxmobile/config/themes/theme_light.json, and change any font definitions you want to the new .ttf filename.
  2. Run ./generate.

If building for iOS, you may want to follow some additional steps to minimize problems:

  1. In the Xcode project navigator, add the font to the assets group.
  2. Edit proj.apple/Info.plist and add the font file name to the UIAppFonts array.

Images

Every image has an SD and HD variant. SD images are typically the same image as the HD image, but reduced to half the respective HD image’s size.

On almost all modern devices with a high pixel density display, the HD variant of an image will be used.

All default HD and SD images are in the client folder:

  • HD - client/mxmobile/assets/mxmobile/hd/images.
  • SD - client/mxmobile/assets/mxmobile/sd/images.

However, to override an image you must place your new image (which has the same name as the one you want to replace in the client folder) in the institutions folder:

  • HD - institutions/mxmobile/assets/mxmobile/hd/images.
  • SD - institutions/mxmobile/assets/mxmobile/sd/images.

For more info about which images you can change in some commonly used features and views, refer to the images sections throughout the features and views reference.