Integrate app customization

The Mobile Authenticator Studio app can be customized to meet your needs and enrich the user experience. You can customize a number of graphical items, the app name, and in-app text. For the implementation of the app customization, please contact OneSpan.

• The customizable graphical elements are:

  • App icon

    For details, see Customization of the app icon.

  • Splash screen

    The splash screen is briefly displayed at app start.

    The splash screen implemented in Mobile Authenticator Studio consists of two elements:

    • A static app icon in an SVG format. If not provided, the launcher icon will be used by default.

      For details about a customized splash screen icon and specifications, see Customization of the splash screen icon.

    • A window background

      The window background color is a HEX value representing a plain color. Define this value in the customization file and provide it to OneSpan. It must be a single opaque color.

      Customization key: splashScreen

    For more information about best practices regarding splash screens on Android, refer to the Android developer documentation on splash screens.

  • Primary color / app theme

    This is a single color used on various graphical elements throughout the Mobile Authenticator Studio app. To customize the primary app color / app theme, provide the required color in HEX color code to OneSpan.

• The customizable text includes:

  • App name

    The app name is a text that is displayed on the device dashboard below the app icon and as subtitle on the device's Home screen. The recommended length is a maximum of 12 characters. If longer, the name can be truncated.

  • Localized in-app text

    For details, see Customization of the in-app text.

Customization of the app icon

You can customize the Mobile Authenticator Studio app's launcher icon as well as the splash screen icon.

Customization of launcher icons

iOS

To customize the app / launcher icon on iOS, provide a PNG file in square mode, 1024x1024 px, to OneSpan. For more information about app icons on iOS, refer to the iOS developer documentation.

Android

Android supports two types of icons: legacy PNG and adaptive SVG icons.

An adaptive icon consists of two layers, foreground and background, each defined in a separate SVG file. This type of icon can display a variety of shapes across different device models. While adaptive icons are the new standard on Android 8.0 and later, a PNG icon is still needed to support versions prior to Android 8.0. For more information about Android adaptive icons, refer to the Android developer documentation on adaptive icons.

A legacy PNG icon does not have a foreground, and background resources can have any shape. Any PNG files you provide must be the maximum resolution possible. However, we do not recommend this and advise using SVG files.

Legacy PNG icons are required for all versions prior to Android 8.

For the customization of the Mobile Authenticator Studio launcher icon, the legacy PNG icon must always be provided. If no adaptive SVG icons are provided, the legacy PNG icons will be used instead for all Android versions. If adaptive SVG icons are provided, those icons will be used by default, where the system version allows it, and the legacy PNG icon will be used as fallback for versions prior to Android 8.0 which do not support the adaptive format.

Special considerations for adaptive SVG icons

• The foreground and background layers are stacked on top of each other. The foreground layer might include transparency, and the background one must be fully opaque.

• Usually a logo is placed in the foreground layer but this is not a requirement. Placing elements in different layers gives an opportunity to create some advanced visual effects.

• Use clean edges. The layers should not have masks or background shadows around the outline.

• The generated launcher icon can be of a poor quality (scale up or down depending on the device resolution, which can lead to a blurry icon). The background of the icon will be white.

Customization examples

On devices running Android 8.0 and later, a launcher icon will be created from the ic_launcher_background.svg and ic_launcher_foreground.svg files, on devices running Android 7.1 and lower, ic_launcher.png will be used as a launcher icon.

1. Customization using adaptive SVG icons

   "assets": {
      "android": {
         "launcherIcon": "android/icons/ic_launcher.png",
         "launcherAdaptiveIconBackground": "android/icons/ic_launcher_background.svg",
         "launcherAdaptiveIconForeground": "android/icons/ic_launcher_foreground.svg",
      }
   }

2. Customization using legacy PNG icons

   "assets": {
      "android": {
         "launcherIcon": "android/icons/ic_launcher.png",
      }
   }

Customization of the splash screen icon

The implementation and customization of a splash screen icon is optional but recommended.

iOS

On iOS, the splash screen must be an svg file. For more information about app icons on iOS, refer to the iOS developer documentation.

Android

On Android, if you do not provide an svg file for the splash screen, the launcher icon you specified will automatically be used to also render the splash screen. This may have different visual effects depending on what was used for the launcher icon:

• If an adaptive SVG icon is used, the splash screen will be displayed correctly.

• If a legacy PNG icon is provided, the splash screen might appear slightly blurred, depending on the quality of the PNG used.

Specifications:

• Customization key: splashScreen

• Dimensions: 288x288 dp. The icon must fit within a circle 192 dp in diameter. Everything outside the circle will become invisible (masked).

Animations are not supported in Mobile Authenticator Studio..

For more information, refer to the Android developer documentation on splash screens.

Customization examples

1. Using a dedicated splash screen SVG file

   "assets": {
      "splashScreenBackgroundColor": "#FFFFFF",
      "android": {
         "splashScreen": "android/icons/ic_splash_logo.svg",
      }
   }

2. Using a launcher icon as a splash screen. If the splashScreen key is not specified, the app will automatically use the provided launcher icon (SVG or PNG) to render the splash screen.

   1. Adaptive icons (SVG) are provided: the splash screen will display the icon which was created from ic_launcher_foreground.svg layer.

      "assets": {
         "splashScreenBackgroundColor": "#FFFFFF",
         "android": {
            "launcherAdaptiveIconBackground": "android/icons/ic_launcher_background.svg",
            "launcherAdaptiveIconForeground": "android/icons/ic_launcher_foreground.svg",
         }
      }

   2. Standard app icon (PNG) is provided: the splash screen will display the PNG launcher icon (can be blurry).

      "assets": {
         "splashScreenBackgroundColor": "#FFFFFF",
         "android": {
            (...)
         }
      }

Customization of the in-app text

The Mobile Authenticator Studio app offers the in-app text strings in different languages. By default, the following five languages are available:

• English (mandatory, cannot be removed)

• German

• Italian

• French

• Spanish

You can add languages and/or remove any of the default languages except English as well as customize the default text strings.

The default text strings are for the most parts identical for iOS and Android, except for the permissions as these are platform-specific.

Customization CSV file

For the language and text customizations, OneSpan provides a CSV file where you make the changes as required. Once you return the updated CSV file to OneSpan, your customizations will be implemented in the app.

To modify the CSV file and save it correctly, we recommend one of the following editors as these work correctly and keep the encodings:

• Windows: Modern CSV

• MAC: Table Tool

• Web: Edit CSV

The following points must be taken into account when you update the CSV file:

• The supported languages are deduced from the columns of the CSV file where each column corresponds to a language defined by its language/country code. The language/country codes must follow the ISO 3166 standard. For a list of codes, refer to ISO 3166 Country Codes.

  You can reuse the codes you are using in Mobile Authenticator Studio 4.x.

• As English is mandatory, it must be the first column. English will always be used as default language for missing values in any language or for unsupported languages.

• If the value for a certain key is empty, the value for English is used.

• If an entire key (i.e., a row) is missing, the default English value is used for this missing key.

• The length of the new text should be approximately the same as that of the original text to avoid breaking the Mobile Authenticator Studio user interface.

• The CSV must use commas "," as separator.

Example scenarios

No CSV file provided

If you do not provide a CSV file, Mobile Authenticator Studio is available in English, French, German, Italian and Spanish with the default values translated by OneSpan.

CSV file provided with all keys defined

You provide the updated CSV file:

• With three columns, "en", "fr, "pt"

• All keys are defined inside the file.

Mobile Authenticator Studio is available in English, French, and Portuguese. All values are used from your file.

CSV file provided, only certain keys are defined

You provide a CSV file with two columns: "en", "ar" but only four keys (i.e., four rows) are defined inside.

Mobile Authenticator Studio displays the four values in Arabic and English as per the definition in the file. All other strings are the English default values as defined by OneSpan.