Customizing Your iOS Application (Magic xpa 3.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.

You can change the following images in the Source folder with your own images:

• Device icons – The iPad* and iPhone* images.

• iTunes and App Store icons – The iTuneArtwork* images. Note that the file should not have an extension.

• Startup screen logo – The Default* images.

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.