Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Building a mobile app locally

Updated on September 6, 2019

After you build a Pega Platform™ application, you can generate it as a mobile app for Android or iOS devices. To adhere to potential security or testing requirements in your company, you can build a Pega Mobile Client™ app locally without uploading any sensitive files to the server.


To build a mobile app for your Pega Platform application, make sure that you complete the following tasks first:

  • Get the distribution package for either Android or iOS from your Pegasystems Global Customer Support representative.
  • Download and install Apache Ant 1.9.6 or later, a tool for automating software build processes.
  • Download and configure the following items:
    For Android
    • Android SDK Tools 25.2.3 or later
    • Android SDK Build Tools 24.0.1
    • Android SDK Platform for API level 25
    • Android SDK extras: Google Repository (rev. 40 or later)
    • Java Runtime Environment (JRE) 8 x64
    • A code-signing key
      For more information, see Sign Your App on the Android Studio website.
    • Android Support Repository (rev. 40 or later)
    For iOS
    • Mac OS X 10.11.5 or later (the latest update is recommended)
    • Ruby 2.0.0 or later (included with OS X)
    • Bundler gem 1.13.6 or later
      You must install the bundler package manually, for example, by calling sudo gem install bundler in a terminal window.
    • Xcode 8.1.
    • Java Runtime Environment (JRE) 8 x64
    • A mobile provision profile prepared for the app
      For more information, see Creating Development Provisioning Profiles on the Apple Developer Portal.
    • A valid development and distribution certificate
      For more information, see the Certificate, Key, and Trust Services Programmer's Guide on the Apple Developer Portal.

Creating a file

Before you build a mobile app, create a file to hold all the configuration files, certificates, and assets that are needed to build your mobile app locally.

  1. Download the file that contains the Pega default branding resources such as, for example, the app icon or a splash logo. To do so, go to the Branding assets templates for various Pega Mobile Client versions article and choose the latest simplified branding template.
  2. Use Windows Explorer, Mac Finder, or a similar tool to create an empty file in a directory of your choice.
  3. Copy the android, common_assets, and ios folders from the file to the root directory of the file.
  4. To customize the look of your mobile app, replace the contents of the android, common_assets, and ios folders with your branding assets.
  5. In the root directory of the file, create a text file and populate it with a map of parameters and their values, according to your needs. For a complete list of available parameters, see the Setting Pega Mobile Client parameters section of the Adjusting the Pega Mobile Client behavior with custom parameters article.

Building a mobile app

Do the following steps to build the mobile app, which you can then install and debug on a device or emulator.

  1. Extract the contents of the distribution package (Android or iOS) into an empty directory of your choice.
  2. Place the file that you created in the previous section in the root directory of the distribution package.
  3. Do one of the following actions:
    • If you are building an app for the Android platform, paste an Android certificate file (android-certificate.p12) for signing APK applications in the root directory of the distribution package.
    • If you are building an app for the iOS platform:
      1. Paste an Apple certificate file (ios-certificate.p12) in the root directory of the distribution package,
      2. Paste a mobile provisioning profile file (named default.mobileprovision) for signing iOS applications in the resources directory of the distribution package.
  4. Run the tool that builds the mobile app by entering the following command from the distribution package's root directory:
    ant pega
  5. Navigate to the out/ directory to confirm that the output APK or IPA files have been created.
  6. To view the status of the build, review the exit_status.json file for the status of the build:
  • A successful build has a status similar to the following example:
  • An unsuccessful build has a status similar to the following example:
    {"exitCode":3000,"messageArguments":[],"warnings":[],"reason":"Customization zip is empty or not provided"}
    For a list of error codes, see Error codes for locally built mobile apps.

Related articles

Generating iOS provisioning files on a Windows computerUploading branding assets


Pega Platform 7.1.1 - 7.4 Mobile Communications and Media Consumer Services Financial Services Government Healthcare and Life Sciences Insurance Healthcare and Life Sciences Manufacturing Consumer Services Consumer Services

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us