Customizing Your iOS Application (Magic xpa 4.x)

To see a video demonstration about customizing your iOS application, click here.

To compile the code you need to install Xcode as defined in the iOS simulator section and a valid provision profile signed with the app identifier (AppID).

This should be done in the Apple developer portal as explained at How Do I Create a Provisioning File to Sign My iOS App?

This concept paper covers ‘in-house’ packages (enterprise). ‘App store’ distribution is not covered in this concept paper.

There are three ways that you can customize your iOS application:

1. Automatically, using Magic xpa’s Rich Client Deployment Builder.

2. Manually, by changing a settings file as described below.

3. Manually, by changing the values using Xcode as explained at How Do I Manually Change the iOS Project to Compile It Using Xcode?

Manual customization of the iOS app

The source code for the iOS application is located at: %EngineDir%\RIAModules\iOS\Source.

You can change the characteristics of the application in the settings.properties file as follows:

• bundle.display.name – The application title as visible to the user.

• build – An integer value that represents the version of the application code, relative to other versions.

• version – A string value that represents the release version of the application code, as it should be shown to users.

• bundle.identifier – The identifier of the project. The identifier must be unique across all packages installed on the iOS system.

Note: When creating a provisioning file, the application identifier in the provisioning needs to be the same as the value entered here.

• target.name – The application title as visible in the AppStore.

• developer.account.name – The name of the developer account in Apple (as shown in the Certificates screen in the Apple portal) prefixed by iPhone Distribution: or iPhone Developer: according to the provisioning type.
  
  For example, if the name of the certificate at the iOS provisioning portal is Magic Software Enterprises Ltd., then for the development certificate, the developer name is iPhone Developer: Magic Software Enterprises Ltd. and for the distribution certificate, the developer name is iPhone Distribution: Magic Software Enterprises Ltd..

• provisioning.profile.filename – This is the file that you download from the Apple developer portal after creating the provision. For example: Magic_distribution.mobileprovision.

Note: The file format of all iOS files should be compatible with iOS. This means that if you generate an iOS file yourself, the end of line character should be only a line feed ('0A') and not carriage return and line feed ('0D 0A') as in Windows.

Providing Launch images and App Icons

In order to comply with the standards enforced by Apple, Magic xpa provides an asset catalog under the source\Media.xcassets folder.

This folder contains two folders:

1. AppIcon - It is used to customize the App Icons.

2. LaunchImage - It is used to customize the Launch Images.

These images and icons are the default images and icons provided by Magic xpa, and are referred to by the contents.json file in the same folder.

To customize an image from any of these two folders, there are two options:

• You can replace the existing image with a custom image of the same dimensions. In this case, the image name will remain same as the previous one.

• If you want your image to have a custom name then you need to replace the existing file with custom name. In addition, you need to update the corresponding Json entry with the same custom name.

You can select the following image sizes for iPhone and iPad devices:

Device	Portrait Display	Landscape Display
iPhone X iOS 11+	1125 x 2436px	2436 x 1125px
iPad iOS 7-9 1x: 2x:	768 x 1024px 1536 x 2048px	1024 x 768px 2048 x 1536px
iPhone iOS 8, 9 Retina HD 5.5: Retina HD 4.7:	1242 x 2208px 750 x 1334px	2208 x 1242px Not Required
iPad Without Status Bar iOS 5, 6 1x: 2x:	768 x 1004px 1536 x 2008px	1024 x 748px 2048 x 1496px
iPhone 7-9 2x: Retina 4:	640 x 960px 640 x 1136px	Not Required Not Required
iPhone 5, 6 1x: 2x: Retina 4:	320 x 480px 640 x 960px 640 x 1136px	1024 x 768px 2048 x 1536px Not Required
iPad iOS 5, 6 1x: 2x:	768 x 1024px 1536 x 2048px	Not Required Not Required

Since version: 3.3a

You can also change the following file:

• Execution properties – Open the execution.properties file located in the MagicApp folder and change the execution values.

o You need to define either the execution properties’ values or a URL referring to a file containing them as defined above.

o Leaving the URL property empty means that a dialog box will be opened and the end user will need to write the URL.

This is useful when having a generic application where different customers can log in to different servers.

After specifying the URL in the dialog box, you can change the URL value in the iOS device’s built-in Settings screen.

Note that if you compile the client using Xcode and not by running the build.sh command, then in order to see the application in the Settings screen, you need to do the following from Xcode:

o From the File menu, select Add Files to “MagicApp”. In the opened dialog box, select the Settings.Bundle folder and click Add.

Resources, such as images, can be packaged as part of the IPA. Refer to: Packaging Resource Files.

After making your changes, you need to compile the application and sign it.

The compilation and signing of the iOS project is done using a shell script file named build.sh located in the build folder. Once you generate your application, you will find this folder in the following path: [Magic xpa installation]\PublishedApplications\[Magic xpa program name]\iOS.

1. Copy the build folder to your Mac.

2. Open the terminal shell on your Mac and navigate to the source folder.

3. Execute the script by running: sh build.sh

The result file (an ipa file) will be created in the output folder to your Mac.

Note: If while running the build you get the following error message: “Code Sign error: Provisioning profile 'XXX' specifies the Application Identifier 'YYY' which doesn't match the current setting 'ZZZ'”, then your Xcode might be defined with a different developer name. To change it, open the project in Xcode and in the Code Signing section under the project properties, change the developer to the one defined in the settings.properties file.