Child pages
  • iPhone Building Guide
Skip to end of metadata
Go to start of metadata

Downloads

The RAMP iOS template project for Xcode can be downloaded here.

All iOS plugins, including the example plugin, are available here.

All the resources required to build an iOS plugin are provided as an Objective-C framework. The framework, rampvm.framework, is available here.

Introduction

A RAMP app can unfortunately not be deployed to iPhone or iPad device through the usual RAMP channels. This is because of restrictions imposed by Apple on its device, i.e.:

  • An app can only be installed on a device via the Apple App Store or Ad Hoc distribution that requires the device's ID.
  • The Apple Developer Program License Agreement does not allow an app to download code, i.e. a placeholder app cannot become your RAMP app at runtime.

The current path to submitting a RAMP app to the iPhone App Store is as follows:

  1. Create RAMP app as per normal.
  2. Download the iOS (iPhone and iPad's operating system) RAMP-app template project.
  3. Set a few properties in two configuration files.
  4. Run a script to build app.
  5. Distribute the built app via the App Store or Ad Hoc distribution.

This document guides you through the process.

Requirements

The RAMP app you created in Eclipse runs on a RAMP virtual machine. For this app to run on a specific device, it requires the RAMP virtual machine built for that device. This virtual machine is packaged with your app when it is downloaded from the RAMP deployment platform. Therefore, to build the iOS version of your RAMP app, you must package it with the iOS RAMP virtual machine.

Since the iOS RAMP virtual machine is written in native iOS code, i.e. in Objective-C using Xcode, the requirements to building the iOS RAMP app are similar to building a native iOS app. These requirements are:

Note

It is assumed that an active internet connection is present. It is required when downloading the latest version of your RAMP app during the build process.

There may be further requirements based on the type of iOS app the RAMP template project is configured to build. These requirements are listed below.

Requirements to deploy to iOS simulator

No further requirements.

Requirements to deploy to iOS device

  • Become a member of the iOS developer program. You can register here.
  • Prepare device running OS X for iOS development. This step requires the following digital assets:
    • Certificate signing request : Contains personal information that is submitted to the iOS Provisioning Portal to generate your development certificate.
    • Development certificate : Identifies an iOS application developer. Used to sign your application.
    • Provisioning profile : Associates one or more development certificates, devices, and an app ID (iOS application ID). To be able to install iOS applications signed with your development certificate on a device, you must install at least one provisioning profile on the device. This provisioning profile must identify you (through your development certificate) and your device (by listing its unique device identifier). If you’re part of an iOS developer team, other members of your team, with appropriately defined provisioning profiles, may run applications you build on their devices.
  • Provisioning the device for development. The steps to provisioning a new device for generic development:
    1. Open Xcode > Preferences > Accounts and click the plus icon to add an Apple ID associated with an Apple Developer Program
    2. In the dialog that appears, enter your iOS Developer Program credentials and click "Add"
    3. Connect your iOS device to your computer and navigate to Xcode > Window > Organizer > "Devices" Tab
    4. Find and select your iOS device in the devices
    5. Click the “Use for Development” or “Add to Member Center” button.
      If the device was previously used for development, the “Use for Development” button does not appear. If this happens, click “Add to Member Center” at the bottom of the window instead.

    6. In the team dialog that appears, select the checkbox next to your account name, and click Choose.
    7. If a Certificate Not Found dialog appears, click Request.

    If needed, Xcode creates a team provisioning profile for your app.
    Xcode manages a development profile for you called a team provisioning profile. Xcode automatically adds development certificates and devices to the team provisioning profile. Therefore, if you don’t have a development certificate, Xcode offers to request your development certificate for you. Xcode also registers the device you enable for development and adds it to the team provisioning profile. If you are an individual developer, wait while Xcode submits the certificate request. If you are a team member for a company, ask your team agent or admin to approve your development certificate and device.

A more in-depth guide is available here and here.

Requirements for Ad Hoc distribution

With Ad Hoc distribution you can share your application with up to 100 other iOS device users. Through email or by posting it to a website or server, users can download and install your app.

  • Become a member of the iOS developer program. You can register here.
  • Obtain the device IDs for all the supported devices.
  • Create a provisioning profile in the iOS Provisioning Portal with these characteristics:
    • Distribution method set to "Ad hoc".
    • Devices set to all the supported device IDs
  • Download the provisioning profile and install it in the Xcode Organizer.

A more in-depth guide is available here and here.

Requirements for App Store distribution

The App Store is accessible through Wi-Fi and cellular networks and makes it easy to reach millions of iOS customers.

  • Become a member of the iOS developer program. You can register here.
  • Create a provisioning profile in the iOS Provisioning Portal with Distribution method set to "App Store".
  • Download the provisioning profile and install it in the Xcode Organizer.

A more in-depth guide is available here and here.

Configure

The RAMP iOS template project for Xcode can be downloaded here. The template can be extracted to any location. To configure this template to your specific RAMP app and Apple developer profile, properties must be set in two configuration files: ramp_config.cfg and build_config.cfg.

Set ramp_config.cfg

Using Finder, navigate to the root directory of your RAMP iOS Project's folder and edit "ramp_config.cfg" in a text editor of your choice to reflect your app's RAMP-settings.

ramp_config.cfg
# Location where app's RAMP feature is hosted (feature server)
feature.host=s.ramp.virtualmobiletech.com/ramp/ramp/feature/ft

# Full name of the RAMP feature.
# Format is 'root'.(company ID).(application ID).'main'
config.feature.name=root.CompanyID.ApplicationID.main

# Set to 1 to load feature from file packaged with app (recommended). Requires "feature.persist=0".
feature.file=1

# Set to 0 to retrieve feature each time app starts. Requires "feature.file=0"
# Set to 1 to retrieve feature only the first time the app starts
feature.persist=0

# Set to 1 to be able to change the app's config.feature.name at runtime. Requires "feature.file=0" and "feature.persist=0"
feature.dev=0

# The n-th service server must be added as secure.host.(n-1)
# The location of the first service server
secure.host.0=s.ramp.virtualmobiletech.com/ramp

# list all the defined keys.
# Each key requires two entries:  'rsakey'.(key name).'mod'  and 'rsakey'.(key name).'version' 

# the feature-key's name is "testkey1"
rsakey.testkey1.mod=afefd5cc5322cf1f47181b7ecbe78fdaf7f7527e1411ab65afa61a555e55b3e7637bb94acb870bf13195210b7e307f53762fcb65d86f8e578d45c17e209549aad863ce358506e17e698b34a29880c631b4dee7765ca20ffa5d5ea3fc7fa56f235bee0b560a5923b3438cc0e4f33ba9c121592ff17d3fdbcdbebcb633a858942f
rsakey.testkey1.version=1

rsakey.keyexchange.mod=c6f3541a4f7c4db7b449db8042be4b2b5f653b0bc53dabd5b3e84b3063c02ef2ce314a52398ada8b0dabab2ce18cc55889359ecaa8d8e7be01c3ca51e327a789c4aeda73523c81bc4d1c73eebeffdff95b5ccbf208a235239dc64e46fc7be6c701c1380a2d17ae295c921c90408776c1e5eb763958893ff4b4252556e8594cad
rsakey.keyexchange.version=1

Most of the configuration file properties correspond to values you entered when creating a new application on the RAMP Deployment Platform. The Advanced Guide provides more information on the properties in this configuration file. Note the following:

  • The property feature.name contains your RAMP Deployment Platform's Company ID and your application's Application ID in the format 'root'.(company ID).(application ID).'main'.
  • The property feature.host refers to the app's feature server, and the key rsakey.testkey1.mod is its feature key.
  • The n-th defined service server must be added as a property named secure.host.(n-1). The property secure.host.0 refers to the first service server.
  • All user defined keys must be added to this file in the format rsakey.(key name).mod and must also include a version property defined in the format rsakey.(key name).version.

If you are building a basic app that uses the default RAMP settings, i.e.:

  • does not use a secure server
  • and does not access a custom feature server.
    Then the only property you have to set is feature.name.

It is possible to specify how the built iOS app retrieves its RAMP feature. The default, production-recommended setting is feature.file=1 and feature.persist=0. This specifies the app uses the feature that is packaged with it.

When testing an app in development, time is saved by setting properties feature.file=0 and feature.persist=0. A new feature is then retrieved from the feature server each time the app is started, and consequently an iOS app need not be rebuilt to test RAMP project changes.

A further testing timesaver is available when setting property feature.dev=1 when is set feature.file=0 and feature.persist=0. Now, when the app starts and the loading screen appears, tap the screen multiple times to reveal an alert that dynamically sets the property config.feature.name. A single iOS app can now test multiple RAMP projects. Note that specifying the RAMP feature by setting config.feature.name using feature.dev=1 is still limited to features hosted by the feature server specified in the property feature.host.

The alert provided by feature.dev

Set build_config.cfg

Using Finder, navigate to the root directory of your RAMP iOS Project's folder and edit "build_config.cfg" in a text editor of your choice to reflect your app's RAMP-settings.

build_config.cfg
# Name of the app package/file. Also known as CFBundleName.
PRODUCT_NAME="myapp"

# Name displayed for the app, e.g on a device, in iTunes, in the App Store. Also known as CFBundleDisplayName.
DISPLAY_NAME="My App"

# Version of the app. Also known as CFBundleVersion.
PRODUCT_VERSION=1.0

# Identity Name of the certificate used to sign app.
CODE_SIGN_IDENTITY='iPhone Developer: John Doe (JB9PA8YQ3Q)'

# Unique app identifier. Also known as the Bundle Identifier (CFBundleIdentifier). recommended practice example: "com.domainname.appname".
APP_ID_SUFFIX="com.mydomainname.myapp"

# iOS SDK version to compile against.
SDK_VERSION="6.1"

# Minimum iOS version to support.
MIN_VERSION="4.3"

# Targeted device family. Set to 1 to enable, 0 to disable.
TARGET_DEVICE_IPHONE_IPOD=1
TARGET_DEVICE_IPAD=1

# Provisioning Profile's file name. Only for Ad Hoc build.
PROVISIONING_PROFILE_FILE_NAME="01234567-89AB-CDEF-1011-121314151617.mobileprovision"

# Whether app splash images (Default.png and Default-Portrait~ipad.png) should be automatically generated from the loading screen images.
GENERATE_SPLASH_IMAGES=0

The property PRODUCT_NAME is the name of the app's package file and is sometimes referred to as CFBundleName in Apple literature. It is typically final part of the Bundle Identifier (CFBundleIdentifier) in the App ID. Note that this name does not have to be the same as the app's RAMP Application ID.

The property DISPLAY_NAME is what your built app will be called in the App Store, iTunes and on a device. It is sometimes referred to as CFBundleDisplayName in Apple literature.

The property PRODUCT_VERSION is the version of your app. It is sometimes referred to as CFBundleVersion in Apple literature.

The CODE_SIGN_IDENTITY property is the name of certificate used to sign the app. A development certificate's name is required for testing on an iPhone device and Ad Hoc distributing. For submitting to the App Store, the name of a distribution certificate is required. The value for this property can be found in application "Keychain Access" under Applications->Utilities on an OS X device. To locate the CODE_SIGN_IDENTITY in Keychain Access, navigate to the "My Certificates" category and the "login" keychain as shown in the provided image. Select the desired certificate then right-click an choose "Get info" to display a new info window. The CODE_SIGN_IDENTITY value is then the value of the "Common name" field in the new info window, note the marking in the provided image.

The APP_ID_SUFFIX property is the app's unique identifier, Also known as the Bundle Identifier or CFBundleIdentifier in Apple literature. Two apps with the same identifier cannot exist on the same device. The image below indicates where this property is defined in the Apple Member Center.

The SDK_VERSION property refers to the iOS SDK version the app will compile against. The RAMP iPhone project is typically designed to be compiled against the latest iOS version. It is required that the SDK version this property is set to be installed on the machine building the app. To view the list of iOS SDKs available on a machine, type the following in the command line:

 xcodebuild -showsdks 

The MIN_VERSION property specifies the minimum iOS version the app will support. Consequently, an app can be compiled against the latest SDK version but still support devices running an older iOS version. The SDK version of this property's value does not need to be installed on the machine building the app.

TARGET_DEVICE_IPHONE_IPOD and TARGET_DEVICE_IPAD refer to the device families your app will support. The app can support either iPhone and iPod Touch, or iPad, or both. Set the property to 1 to select it, or 0 to deselect it. At least one device family must be selected.

The property PROVISIONING_PROFILE_FILE_NAME is the file-name of the Provisioning Profile the app subscribes to. Setting this property is only required for the Ad Hoc build.

If the property GENERATE_SPLASH_IMAGES is set to 1, the app's launch images (or splash screens) for this app will be generated from the project's logo images. More info in section "Personalize app".

Build

The process that builds the iOS version of the RAMP app. The built iOS app is a universal iOS app, i.e. compatible with iPhone, iPad and iPod Touch devices if so configured in build_config.cfg.

The build process consists of:

  • Download latest version of RAMP app and include it in the project.
  • Compile project against desired iOS version.
  • Package compiled project in a file with a ".app" extension.
  • Sign app.

There are various build options, each with its own script:

  1. Build for simulator testing.
  2. Build for device testing.
  3. Build for Ad Hoc distribution.
  4. Build for App Store distribution.

Simulator testing

You can build your app to run on the iOS simulator that comes with Xcode. This is the fastest way to test your app and requires no signing keys, i.e. no valid value for the CODE_SIGN_IDENTITY property in build_config.cfg.

This build is performed with the script build_simulator.sh found in the root directory of your RAMP iOS Project's folder. The built app is then located in the "build/Release-iphonesimulator" path relative to the root of the project. Note that the script also installs your app in the simulator and launches the simulator during building. (If the built app is not visible in the simulator, close the simulator and restart it.)

Device Testing

This build is for testing your app on an actual iOS device. It requires the property CODE_SIGN_IDENTITY in build_config.cfg to be set to a valid development certificate.

Note

The app built with this build cannot be submitted to the App Store. There is a difference between a development certificate and a distribution certificate.

This build is launched with the build_device.sh script found in the root directory of your RAMP iOS Project's folder. The built app is then located in the "build/Release-iphoneos" path relative to the root of the project.

The built app can be installed on a iPhone or iPad device via Xcode. In Xcode on the top menu bar, select Window->Organizer. All iOS devices connected to the device running Xcode should show up in the Organizer window. Click on the device on which you wish to test your app. You will see the heading "Applications" and a list of all the apps installed on this device and a "+" and "-" button. Click on the "+" button and select your built app. The app is then installed on this device.

Ad Hoc Distribution

This build is for sharing your application with up to a 100 other iPad, iPhone, or iPod touch users. This app can be shared through email, or by posting it to a website or server.

Note

The app built with this build cannot be submitted to the App Store.

It is required that the build_config.cfg property PROVISIONING_PROFILE_FILE_NAME set to a Provisioning Profile's file-name and CODE_SIGN_IDENTITY is set to a valid development certificate. The name of the file associated with a Provisioning Profile can be found using Finder. Open a new Finder Window, toggle Finder's "Go to the folder" action (⌘⇧G) and go to "~/Library/MobileDevice/Provisioning Profiles". The process is displayed in the image below.

This build is launched with the build_adhoc.sh script found in the root directory of your RAMP iOS Project's folder. The built app then has the special ".ipa" extension and is located in the "build/Release-iphoneos" path relative to the root of the project.

The built app is installed via iTunes. Double-click on the app file to add it to iTunes. The app is then installed to a device like a normal iTunes app.

App Store Distribution

This final build is for the app you plan to submit to the App Store. In build_config.cfg it is required to have the property CODE_SIGN_IDENTITY set to the name of a distribution certificate.

Note

The app built with this build cannot be installed directly on an iOS device.

This build is launched with the build_appstore.sh script found in the root directory of your RAMP iOS Project's folder. The built app is then located in the "build/Release-iphoneos" path relative to the root of the project.

The app can now be compressed (right-click and selecting Compress) and uploaded with the Application Loader program that comes with the iOS SDK (typical location is "/Applications/Xcode.app/Contents/Applications/Application Loader.app").

Personalize app

It is possible to replace some images in the template project to personalize an app's representation on an iOS device. These changes should be made before the build script is launched.

The list of images that can be replaced:

Version <= 4.5.0

  • Icon.png, the icon representing the app on an iPhone. A 57x57 png image in the project's root folder.
  • Icon_ipad.png, the icon representing the app on an iPad. A 72x72 png image in the project's root folder.
  • ramp_logo.png, the logo displayed on the loading screen on an iPhone. A 349x200 png image located, relative to the project root, in folder frameworks/rampvm.framework/Versions/A/Resources/images.
  • ramp_logo_ipad.png, the logo displayed on the loading screen on an iPad. A 349x200 png image located, relative to the project root, in folder frameworks/rampvm.framework/Versions/A/Resources/images.
  • Default.png, the app's splash screen on a standard iPhone device. A 320×480 png image in the project's root folder. The GENERATE_SPLASH_IMAGES property in build_config.cfg must be set to "0" to change this image.
  • Default-568h@2x.png, the app's splash screen on an iPhone 5 device. A 640×1136 png image in the project's root folder. The GENERATE_SPLASH_IMAGES property in build_config.cfg must be set to "0" to change this image.
  • Default-Portrait.png, the app's splash screen on an iPad with portrait orientation. A 768x1004 png image in the project's root folder. The GENERATE_SPLASH_IMAGES property in build_config.cfg must be set to "0" to change this image.
  • Default-Landscape.png, the app's splash screen on an iPad with landscape orientation. A 1024×748 png image in the project's root folder. The GENERATE_SPLASH_IMAGES property in build_config.cfg must be set to "0" to change this image.
  • iTunesArtwork, the app's iTunes image if it is an Ad Hoc app. Only used by Ad Hoc apps. A 512x512 png image in the project's root folder. Note that the file has no extension.

Version >= 4.6.0

  • Icons located in folder vmt/Images.xcassets/AppIcon.appiconset/:
    • Icon-57.png, targets non-retina iOS < 7 iPhones. A 57x57 png image.
    • Icon-114.png, targets retina iOS < 7 iPhones. A 114x114 png image.
    • Icon-120.png, targets retina iOS >= 7 iPhones. A 120x120 png image.
    • Icon-72.png, targets non-retina iOS < 7 iPads. A 72x72 png image.
    • Icon-76.png, targets non-retina iOS >= 7 iPads. A 76x76 png image.
    • Icon-144.png, targets retina iOS < 7 iPads. A 144x144 png image.
    • Icon-152.png, targets retina iOS >= 7 iPads. A 152x152 png image.
  • ramp_logo.png, the logo displayed on the loading screen on an iPhone. A 349x200 png image located, relative to the project root, in folder frameworks/rampvm.framework/Versions/A/Resources/images.
  • ramp_logo_ipad.png, the logo displayed on the loading screen on an iPad. A 349x200 png image located, relative to the project root, in folder frameworks/rampvm.framework/Versions/A/Resources/images.
  • Launch images (app's splash screen) located in folder vmt/Images.xcassets/LaunchImage.launchimage/:
    • Default-568h@2x-1.png, targets 4 inch iOS < 7 iPhones. A 640×1136 png image.
    • Default-568h@2x.png, targets 4 inch iOS >= 7 iPhones. A 640×1136 png image.
    • Default-Landscape-full.png, targets non-retina iOS >= 7 iPads in landscape orientation. A 1024×768 png image.
    • Default-Landscape-full@x2.png, targets retina iOS >= 7 iPads in landscape orientation. A 2048×1536 png image.
    • Default-Landscape.png, targets non-retina iOS < 7 iPads in landscape orientation. A 11024×748 png image.
    • Default-Landscape@x2.png, targets retina iOS < 7 iPads in landscape orientation. A 2048×1496 png image.
    • Default-Portrait-full.png, targets non-retina iOS >= 7 iPads in landscape orientation. A 768×1024 png image.
    • Default-Portrait-full@x2.png, targets retina iOS >= 7 iPads in landscape orientation. A 1536×2048 png image.
    • Default-Portrait.png, targets non-retina iOS < 7 iPads in landscape orientation. A 768×1004 png image.
    • Default-Portrait@x2.png, targets retina iOS <7 iPads in landscape orientation. A 1536×2008 png image.
    • Default.png, targets non-retina iOS < 7 iPhones. A 320×480 png image.
    • Default@x2-1.png, targets retina iOS >= 7 iPhones. A 640×960 png image.
    • Default@x2.png, targets retina iOS < 7 iPhones. A 640×960 png image.
  • iTunesArtwork, the app's iTunes image if it is an Ad Hoc app. Only used by Ad Hoc apps. A 512x512 png image in the project's root folder. Note that the file has no extension.
  • No labels