Customizing Your iOS Application (Magic xpa 2.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 concept paper covers ‘in-house’ packages (enterprise). ‘App store’ distribution is not covered in this concept paper.

You can customize the application automatically using Magic xpa’s Rich Client Deployment Builder or you can do it manually as described below. After the customization, you will need to compile the application and sign it as described below. Since version: 2.3

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.

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

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

Follow these steps to compile and sign your custom application:

1. Apple Developer program / certificates and provisioning profiles

• You need a valid ‘iOS Developer Enterprise Program’ account or you need to join an existing account as a team member. Additional details can be found at: https://developer.apple.com/support/ios/enterprise.html.

• A Standard developer account can be used as well, but an application signed using a developer account can only be distributed using the Apple store or ad-hoc.

• After registering, you need to create a certificate for your account and download it to your Mac. Additional details can be found at: https://developer.apple.com/ios/manage/certificates/team/howto.action.

• Once you have a certificate, you need to create an “in-house” provision for the app. You can create unlimited provisions linked to your account. Additional details can be found at: https://developer.apple.com/ios/manage/provisioningprofiles/howto.action.

2. Create a signed IPA file.

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.

• Copy the build folder to your Mac.

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

• 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.