iOS App SDK 16 Guide
Important:FileMaker, Inc. does not recommend or support using the App Store to distribute apps created with iOS App SDK. FileMaker, Inc. recommends using the Apple Developer Enterprise Program to distribute your iOS apps. You can also use the Volume Purchase Program (VPP) to distribute your iOS apps through the VPP store.
Introducing iOS App SDK
Overview
Use iOS App SDK to build a standalone iOS app from your FileMaker solution. After creating the app, use one of the supported deployment options to distribute it.
Here are some benefits of building iOS apps from your FileMaker solutions:
- You can deploy FileMaker solutions the same way you deploy other business apps for your organization.
- Users can access your FileMaker solutions the same way they access other iOS apps. They don't need to install FileMaker Go to use the solutions.
- You can choose the appearance of your solutions by customizing the app icon and launch image.
Note:iOS App SDK does not support authenticating user accounts via third-party OAuth identity providers.
Building an iOS app from your FileMaker solution
Before you begin
- Enroll in the Apple Developer Program.
- Make sure you are familiar with the workflow for developing and distributing iOS apps. See Xcode Help.
Step 1: Install Xcode and add your Apple ID account
- Download Xcode from the Mac App Store, and install it on your Mac.
- In the Xcode Accounts preferences, add the Apple ID that is associated with your Apple Developer Program.
Step 2: Download and open iOS App SDK
- Download iOSAppSDKPackage_<version number>.tbz, then move the file from the Downloads folder to a location of your choice.
- Double-click iOSAppSDKPackage_<version number>.tbz to unpack the file and create the iOSAppSDKPackage_<version number> folder.
Step 3: Use iOS App SDK to create a project directory
All resources for your app are stored in a project directory. Use iOS App SDK to create the project directory for your app.
- Open the Terminal app on your Mac.
- Use the
cd
command to change the directory to the location of the iOSAppSDKPackage_<version number> folder on your Mac. You created the folder in Step 2: Download and open iOS App SDK.Tip:Drag the folder to the Terminal window to enter the full path of the folder.
- Enter the following command at the Terminal prompt:
./makeprojdir <projectPath> <appName> <appBundleIdentifier>
- projectPath: The name and location of the project directory for your app. The project directory can be anywhere in your file system; it doesn't need to be in the iOS App SDK directory.
- appName: The name of your app. If the name contains spaces or special characters, enclose the name in quotation marks.
- appBundleIdentifier: The unique bundle identifier for your app. See Xcode Help.
The following example creates a new project directory called MyAppDir in the user's home directory for the “Hello World” app and the com.mycompany.helloworld bundle identifier:
./makeprojdir ~/MyAppDir “Hello World” com.mycompany.helloworld
Project directory contents
A project directory is created for your app in the location you specified. This directory includes:
- <appName> directory: The directory used for storing the files and resources for your app.
- <appName>.xcodeproj file: The Xcode project file for your app.
Do not modify the following:
- app.entitlements file: Specifies the entitlements for your app.
- iOSAppSDKResources directory: Contains the resources that iOS App SDK created for your app.
Step 4: Add your solution files to the Xcode project and modify configFile.txt
Note:Use the Show/Hide Menubar and Show/Hide Toolbars script steps in your FileMaker Pro solution to hide the FileMaker Go menu bar and toolbar. Otherwise, users will be able to access them from your iOS app.
- Open the Xcode project file for your app (<appName>.xcodeproj).
- In Xcode, click the disclosure triangle next to your project in the project navigator.
- Click the disclosure triangle next to the Custom Application Resources folder.
- Drag your solution files to the Solution Files folder, then remove the PlaceHolder.fmp12 file.
Note:This folder can contain multiple solution files. You specify which solution file to launch in configFile.txt.
- (optional) To include FileMaker plug-ins that are created for your iOS app, drag your plug-in files to the Plug-Ins folder.
Note:To create a plug-in, you need the FileMaker plug-in SDK available at www.filemaker.com. The plug-in extension must be .fmplugin.
- In the Custom Application Resources folder, click configFile.txt.
- Update the following information:
- launchSolution: Specify the solution file to open when your app is launched. The filename is case sensitive.
- (optional) helpURL: Specify the URL for your app's Help menu. If no URL is specified, the Help menu is removed from the app.
- Update the value for solutionCopyOption to specify when to copy the files in the Solution Files folder to the Documents directory on the iOS device. You can specify either the number or the string.
Warning:Set this option to 1 only for testing your app. Enabling this option causes all solution files to be replaced every time the app is launched.
- 1 (always): The solution files are copied every time the app is launched.
- 2 (once): The solution files are copied only the first time the app is launched.
- 3 (versionChange): The solution files are copied the first time the app is launched or whenever the app's version number changes. You specify the version number in Step 8: Specify the version and build number.
- 4 (buildVersionChange): The solution files are copied the first time the app is launched or whenever the app's build number changes. You specify the build number in Step 8: Specify the version and build number.
- (optional) If you used FileMaker Pro Advanced to encrypt your solution files, you can use the dbePassword option to specify the encryption passwords. The passwords will be embedded in the app, but they will be obfuscated to make it difficult to reconstruct them. For more information, see configFile.txt.
Step 5: Create images and add them to the Xcode project
Use the following guidelines for creating images for your app. For the latest information, see the Apple iOS Human Interface Guidelines.
App icons
Every app needs an app icon. Create different sizes of the app icon to make sure it displays correctly on all supported devices. Use the following sizes:
- For iPhone:
- 120 by 120 pixels for 2x
- 180 by 180 pixels for 3x
- For iPad:
- 76 by 76 pixels for 1x
- 152 by 152 pixels for 2x
- For iPad Pro: 83.5 by 83.5 pixels for 2x
- For the App Store: 1024 by 1024 pixels
The recommended file format for icons is PNG.
Launch image
A launch image is used as a splash screen that iOS displays when your app launches. The image appears instantly and is quickly replaced by the first screen of your app.
You can create images at 1x, 2x, or 3x resolution to provide the sharpest image for each device. In portrait orientation, the left and right edges may be cropped. In landscape orientation, top and bottom edges may be cropped. For best results in both orientations, use a square image.
Security shield image
If a FileMaker solution uses the fmreauthenticate extended privilege, a security shield covers the content of the screen after the solution moves to the background. You can create an image to be displayed near the top center of the security shield screen.
Design a security shield image that looks similar to the app icon. The height of the security shield image can't exceed 120 pixels. You can create the security images at 1x, 2x, or 3x resolution to provide the sharpest image for each device.
To add image resources to the Xcode project
- In Xcode, click the disclosure triangle next to your project in the project navigator.
- Click the disclosure triangle next to the Custom Application Resources folder, then click CustomAppMedia.xcassets.
- Click AppIcon, then:
- For iPhone App iOS 7-10 60pt, drag the 120-by-120 image to the 2x box, and drag the 180-by-180 image to the 3x box.
- For iPad App iOS 7-10 76pt, drag the 76-by-76 image to the 1x box, and drag the 152-by-152 image to the 2x box.
- For iPad Pro App iOS 9-10 83.5pt, drag the 83.5-by-83.5 image to the 2x box.
- Click LaunchImage to add your launch images and click ObscureIcon to add your security shield images. Drag your images to the targets for each image. If you do not provide all versions, delete the remaining placeholder files. iOS will automatically scale one of your existing images for the required resolutions.
Step 6: Update the information for accessing external media
Explain why your app needs to access an iOS device's camera, location, photo library, microphone, or the media library.
- In Xcode, click the disclosure triangle next to your project in the project navigator.
- Click the disclosure triangle next to the Custom Application Resources folder.
- Click Info.plist, then update the privacy description for external media.
Step 7: Enable Data Protection and iCloud capabilities
- In Xcode, select your project in the project navigator.
- Choose the target from the Project/Targets pop-up menu or in the Targets section of the project and targets sidebar.
- Click Capabilities at the top of the project editor.
- Enable Data Protection. The files associated with your app will be encrypted and inaccessible when the device is locked.
- Enable iCloud, then select iCloud Documents to allow transferring data to and from iCloud.
Step 8: Specify the version and build number
- In Xcode, select your project in the project navigator.
- Choose the target from the Project/Targets pop-up menu or in the Targets section of the project and targets sidebar.
- In the Identity section of the General pane, specify the version and build number for your app.
The format for the version string is
number.number.number
(for example, 1.0.1). The build number specifies which build you shipped for a specific app version. For more information, search for CFBundleShortVersionString and CFBundleVersion in the Xcode documentation.
Step 9: Specify a URL scheme for your app
To allow your app to respond to custom URLs, configure a custom URL scheme for your app.
Note:You cannot specify more than one URL scheme.
- In Xcode, select your project in the project navigator.
- Choose the target from the Project/Targets pop-up menu or in the Targets section of the project and targets sidebar.
- Click Info at the top of the project editor.
- Click URL Types, then click +.
- Specify information for the identifier, URL scheme, and role.
Step 10: Build and test your app
- In Xcode, select your project in the project navigator.
- Make sure your Mac is connected to your iOS device.
- In the workspace toolbar at the top of the window, click the name of your app, then choose the target device to use for building and running your app.
- Click the Run button in the toolbar to build and run your app.
- Run and test your app on all devices that you intend to support.
- Check the icons and images in different orientations.
- Verify that all expected solution files are present.
- Check the Help menu to make sure it opens the correct URL.
Considerations for launching your app
Considerations for launching your app
When you launch your app, the value of solutionCopyOption determines if the files for your app are copied to the Documents directory on the iOS device. See Step 4: Add your solution files to the Xcode project and modify configFile.txt.
When your app opens, the launch image is displayed immediately. After the first screen of your app replaces the launch image, the behavior is similar to FileMaker Go.
Note:To modify your FileMaker solution file, first delete the existing iOS app from your device, or set the solutionCopyOption configuration option to 1 (always). Make sure to change this option to a different setting before shipping your app.