Fulfilling app store guidelines by prepackaging user interface files
To make the mobile app fulfill app store guidelines that required apps to initialize without downloading any resources from external servers. prepackage user interface files when you build a mobile app that is based on Pega Mobile Client™ and eliminate the need to connect to Pega Platform™ immediately after installation.
When you build a mobile app that is based on Pega Mobile Client, Pega Platform bundles executable files and other resources to create an .ipa or .apk application package, depending on the target platform. By default, the application package does not contain any user interface files. Therefore, when the application starts on the device for the first time, it must connect to the server and download the user interface files and other required resources.
By packaging user interface files when you build a mobile app on the Mobile channel page, you can achieve the following results:
- Make the mobile app initialize faster.
- Display a login page that allows users to access the mobile app without downloading any data from the server.
- Display a notification to users in case of a data connection problem.
To package the user interface files, you can create your own single HTML file that includes all the required logic and resources, and upload the file to Pega Platform in the same way that you upload custom branding assets or custom modules. Alternatively, you can download an existing login page for your application and modify the files, for example, to make the login page connect to authentication services of your choice.
Use case
The uPlusTelco company wants to publish an updated version of their mobile app to an app store that lists mobile apps. The app store guidelines have changed and mobile apps are now required to initialize without downloading any resources from external servers. uPlusTelco must modify their mobile app to fulfill this requirement.
To package custom user interface files in a mobile app, complete the following tasks:
- Preparing the file structure
- Creating the user interface file
- Modifying the custom.properties file
- Uploading the package file
Prerequisites
- Ensure that you have an existing mobile app that is based on Pega Mobile Client. For more information, see Configuring a mobile app.
- Ensure that you are experienced in creating HTML pages.
- Read Preparing custom branding assets and Contents of the branding assets package.
- Download the branding assets template that corresponds to your version of Pega Mobile Client. For more information, see Branding assets templates for various Pega Mobile Client and Pega Infinity Mobile Client versions.
- Download the custom properties template. For more information, see Adjusting the Pega Mobile Client behavior with custom parameters.
- Download the assets.zip file that contains a sample login page. The sample login page is compatible with Pega Platform 8.2.
Take the following statements into consideration:
- When you modify the .zip file that you use to upload your custom branding assets or custom modules, do not alter the existing files.
- To reuse an existing login page that uses AJAX requests, you must modify the logic, because AJAX requests are not supported by a mobile app.
Preparing the file structure
Before you can package the user interface file, prepare a file structure that will later be populated with user interface files.
- Extract the .zip file that you use to upload custom branding resources or custom modules for your mobile app:
- If you already have the .zip file, extract the files to a local folder on your computer.
- If you have not uploaded branding assets or custom modules before, use the branding assets template that corresponds to your version of Pega Mobile Client, and extract the files to a local folder on your computer.
- In the root directory of the file that you extracted, create an empty customBootstrap directory.
Creating the user interface file
After you prepare the file structure, use the editor of your choice to create a single HTML file that includes all the logic and resources required to, for example, display a login page or notification in case of a data connection problem.
- Prepare the single HTML file, with all resources included:
- If you want to create your own user interface file, create the HTML file that, for example, displays a notification and handles redirection to a login page after connectivity is restored.
- If you want to reuse the existing login page for your Pega Platform application, download the page with the download tool of your choice, for example:
wget -m -p -E -k -K -np -U "Mozilla/5.0 (Linux; Android 8.0.0; SM-G935F Build/R16NW; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/68.0.3440.91 Mobile Safari/537.36 AmpWebControl/7.41.1.4" https://<application_server>/prweb/LoginPage
- Ensure that the HTML file is displayed correctly in a browser, when it is loaded from the local file:
- Make relative all links to external resources such as JS, image, CSS and woff files.
- Remove the manifest attribute from the HTML file.
- Ensure that the logic in the HTML file does not use AJAX requests.
- Paste the single HTML file page into the customBootstrap directory.
Modifying the custom.properties file
After you create the user interface file, modify the custom.properties file by setting a parameter that indicates where to find resources that are used, for example, to initialize when no data connection is available.
- Prepare the custom.properties file:
- If you have used the custom.properties file before, to override certain Pega Mobile Client settings, paste this file into the root directory that you created in the "Prepare the file structure" section.
- Otherwise, paste the downloaded custom.properties file template into the root directory that you created in the "Prepare the file structure" section.
- Uncomment the
container.applicationURL
property and set its value toprepackaged://bootstrap/
followed by the name of the user interface file that you prepared in the "Create the user interface file" section, for example:prepackaged://bootstrap/LoginPage.html
- Save the custom.properties file.
Uploading the package file
When you have prepared the file structure, created the user interface file, and modified the custom.properties file as necessary, create a package file and upload it to Pega Platform. This way you can, for example, display a login page or notification in case of a data connection problem.
- Compress the folder that you created in the "Prepare the file structure" section to create a .zip file with the user interface file, the custom.properties file, and any branding assets that you need.
- In Dev Studio, click the name of your application, and then click .
- Access the mobile channel page by doing one of the following actions:
- Open an existing mobile channel:
- In the Current channel interfaces section, click a tile that represents your mobile channel.
- Click Modify Build.
- Create a new mobile channel:
- In the Create new channel interface section, click Mobile.
- In the Mobile app type area, select Pega Mobile Client to build a mobile app.
- Open an existing mobile channel:
- On the Layout tab, in the App branding section, click .
- Click .
- Browse and select the .zip file from your directory.
- Click .
Next steps
Build your mobile app and publish it in the app store of your choice. For more information, see Building mobile apps and Best practices for publishing mobile apps in app stores.