Prepare a build

Prev Next

To successfully build your app in OneSpan Mobile Authenticator Studio Portal, you must prepare a number of customization assets for upload in the portal. The list of required assets depends on the extent to which you want to customize the app. The following is an overview of these assets, for more detailed information see Integrate app customization.

The maximum size per file is 5 MB. The total size of all uploaded files is limited to 50 MB.

Customization file

Based on the customization schema definitions and your integration type of Mobile Authenticator Studio, you customize your Mobile Authenticator Studio app. By defining the parameters in the customization file you control the look and behavior of the app, including e.g. the app name, static vector, supported languages, primary app color, font color of the in-app texts etc.

As a customization file contain potentially sensitive information, the portal’s build management service encrypts each file with its own data key upon upload.

The encryption keys are only used during the build process and never leave our back end.

The Mobile Authenticator Studio Portal generally only uses the relevant information in the file for the operating system that has been selected for the build, and discards the rest. For more information about the schema definitions and examples, see JSON customization schemas.

Required file format: JSON

Create and use a single customization for all builds and operating systems. Only a small number of properties are platform-specific, and these can be applied as needed through the portal. Maintaining a single customization file reduces the risk of errors and significantly lowers maintenance effort, especially since updating to a new version of Mobile Authenticator Studio may require changes.

Translation file: in-app texts

This is an optional feature. To display customized and/or localized in-app text strings and labels, upload a single translation file containing your text strings- The portal verifies which languages you included in the file and ignores text strings in any of the other languages.

By default, the text strings are in English. This is mandatory—you cannot replace the English texts with another language.

Required file format: CSV

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

For more information, see also Customization of the in-app text.

End user license agreement and offline help

Displaying an end user license agreement (EULA) and offline help are optional features. To use either or both, prepare one file per language with the texts you wish to use for each feature. By default, the following languages can be selected:

  • English (mandatory)

  • French

  • German

  • Italian

  • Spanish

Required file format: HTML

For more information, see also Display end user license agreement and offline help.

Icons and splash screen

You can customize the launcher and notification icons of the Mobile Authenticator Studio app. The launcher icon is displayed on the device's dashboard, and the notification icon is displayed for any incoming notification. For Android devices, Mobile Authenticator Studio supports both regular and adaptive icons. With the integration of Android adaptive icons, the icons used in Mobile Authenticator Studio are compatible with different Android devices.

The splash screen is briefly displayed at app start. You can customize the window background color and the icon of the splash screen.

For information about required file formats and other details, see Icon customization.

Assets download

The Mobile Authenticator Studio Portal also offers you the option to download the asset files you have uploaded for creating a build.

The files are downloaded as zip archives. If the build name is a valid filename the archive is named: <build name>-assets.zip. Otherwise, the portal uses the build ID as the archive name. The asset files within the archive retain their original name where possible. However, invalid or reserved characters such as the backward slash (\) are removed from the filenames.

Contents of the asset archive

If you download the asset files, the zip archive will contain the following:

  • customization_file.json

    The build’s customization file in readable form, where the system-generated technical entries have been removed.

  • <asset type>/<file>

    An uploaded asset that does not depend on a language, e.g. an icon. The portal creates one folder per asset type.

  • <asset type>/<language>/<file>

    An uploaded asset that exists once per language, in a dedicated folder for that language.

  • info.yaml

    A summary of the download, meant to be shared with OneSpan support. This file lists the tenant, build data (ID, name, creation date, status), the date of the download, and every file with its type, language, path in the archive, and whether it was included. It also states whether the download is complete or incomplete.The info file does not contain any personal data and does not contain information about who requested the download.

    This file must not be manually edited!

The archive is always downloaded, even if a file cannot be read. In that case, the unreadable file is left out, info.yaml marks it as not included, and the download is marked incomplete.

Expired builds cannot be downloaded.

Filename cleaning

Files keep the name they had when they were uploaded, but will be cleaned so that the zip can be safely extracted on Windows, macOS, and Linux. The following rules are applied in this order:

  1. Only the file name is kept.

    Any folder part is dropped, so C:\Users\me\logo.png and ../../logo.png both become logo.png.

  2. Invisible characters are removed.

    This includes control characters and characters that can hide the real name of a file.

  3. Characters Windows does not accept are replaced by _.

    These are < > : " | ? *.

  4. A leading ._ is removed.

    macOS treats such files as hidden metadata.

  5. Trailing dots and spaces are removed.

    Windows drops them silently.

  6. Names longer than 255 bytes are shortened.

    The extension (for example .png) is kept.

  7. Unusable names are replaced by a default name.

    This applies to an empty name, . or .., and to names Windows reserves CON, PRN, AUX, NUL, COM1 to COM9, LPT1 to LPT9, with or without an extension). The default is the standard name of that type of file, and customization_file.json for the customization file.

The language folder name is also cleaned: every character other than a letter, a digit, - or _ becomes _.

For very old builds, a generic filename may be used, if the original filename is not or no longer known.

Examples

Original name

Name in the archive

C:\Users\me\logo.png

logo.png

icon:v2?.png

icon_v2_.png

._logo.png

logo.png

logo.png.

logo.png

CON.png

the default name