iOS App SDK 15 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 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 your app.

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.

Building an iOS app from your FileMaker solution

Before you begin

Enroll in the Apple Developer Program. See https://developer.apple.com/programs.
Register the iOS devices that you will use for testing your app. Go to the Member Center in https://developer.apple.com.

Step 1: Download and install Xcode

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 iOS App SDK <version number>, 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: Create signing identities and certificates

In Xcode, use the Accounts preferences to create signing identities. Xcode automatically creates your development certificate for you. See the Apple App Distribution Guide.

Step 4: Create the App ID

To register your iOS apps with Apple, you need to create an App ID (a unique identifier) for each app.

Provide the App ID information in https://developer.apple.com.
Specify the name, description, and bundle identifier (ID) for your app.
In App Services, select iCloud to provision your app to use iCloud.
In App Services, select Data Protection, then select Complete Protection to provision your app to use data protection.

You enable iCloud and Data Protection services in Step 9: Enable Data Protection and iCloud capabilities. To learn more about registering App IDs, see the Apple App Distribution Guide.

Step 5: Download the provisioning profile

In Xcode, use the Accounts preferences to download the provisioning profile for your app.

Step 6: 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 <NewAppDir> <appName> <bundleIdentifier>
- NewAppDir: 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.
- bundleIdentifier: The bundle identifier you created in Step 4: Create the App ID.
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 7: Add your solution files to Xcode and modify configFile.txt

Note: Use the Show/Hide Menubar and Show/Hide Toolbars script steps in your 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.
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 10: 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 10: 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 8: 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-9 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-9 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 83.5pt, drag the 83.5-by-83.5 image to the 2x box.
Click LaunchImage, then drag your launch 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.
Click ObscureIcon, then drag your security shield 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 9: Enable Data Protection and iCloud capabilities

Make sure your app is provisioned to use Data Protection and iCloud services. See Step 4: Create the App ID.
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 10: 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 11: Specify a URL scheme for your app

To allow your app to respond to custom URLs, you need to 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 12: 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.

Launching your iOS app

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 7: Add your solution files to Xcode 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.

Acknowledgements

Advanced Software Engineering Limited (ChartDirector)

- This software is based in part on the work of the Independent JPEG Group

- This software is based in part of the work of the FreeType Team

Apache Software Foundation (Open SSL Toolkit)

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: “This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)” 4. The names "OpenSSL Toolkit” and “Open SSL Project” must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact openssl-core@openssl.org. 5. Products derived from this software may not be called "OpenSSL", nor may "OpenSSL" appear in their name, without prior written permission of the OpenSSL Project.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF, SUCH DAMAGE.

This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).

Carnegie Mellon University (CMU libsasl)

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name "Carnegie Mellon University" must not be used to endorse or promote products derived from this software without prior written permission. For permission or any other legal details, please contact

Office of Technology Transfer
Carnegie Mellon University
5000 Forbes Avenue
Pittsburgh, PA 15213-3890
(412) 268-4387, fax: (412) 268-7395
tech-transfer@andrew.cmu.edu

4. Redistributions of any form whatsoever must retain the following acknowledgment:

"This product includes software developed by Computing Services at Carnegie Mellon University (http://www.cmu.edu/computing/)."

CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT ABILITY AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Hoa, Dinh Viet (libEtPan!)

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

3. Neither the name of the libEtPan! project nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

JGuru.com (ANTLR)

Portions of this software are based in part on the work of JGuru.com and are in the public domain. For more info, see www.antlr.org.

Johnston, Jason (CSS3 PIE)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Payan, Arash (appirater)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Resig, John (jquery)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies of substantial portions of the Software.

Skipp, Alan (ASValueTrackingSlider)

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Starfield Technologies, Inc. / Go Daddy

All use of the SSL certificates are subject to the Starfield Technologies, Inc. SSL Certificate Service Relying Party Agreement. This agreement is available for download at:

https://certs.godaddy.com/repository/previous_versions/StarfieldRelyingPartyAgreement_V1.pdf

Stenberg, Daniel (libcurl)

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

Zbar (Jeff Brown)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

By using this software component, FileMaker is obligated to make Zbar available for download and to publicly state that it uses Zbar in its software. FileMaker’s website (www.filemaker.com) contains the download opportunity that fulfills this legal obligation.

Copyright statement

FileMaker, Inc.
5201 Patrick Henry Drive
Santa Clara, California 95054

FileMaker, FileMaker Go, and the file folder logo are trademarks of FileMaker, Inc. registered in the U.S. and other countries. FileMaker WebDirect is a trademark of FileMaker, Inc. All other trademarks are the property of their respective owners.

FileMaker documentation is copyrighted. You are not authorized to make additional copies or distribute this documentation without written permission from FileMaker. You may use this documentation solely with a valid licensed copy of FileMaker software.

All persons, companies, email addresses, and URLs listed in the examples are purely fictitious and any resemblance to existing persons, companies, email addresses, or URLs is purely coincidental. Credits are listed in the Acknowledgments documents provided with this software. Mention of third-party products and URLs is for informational purposes only and constitutes neither an endorsement nor a recommendation. FileMaker, Inc. assumes no responsibility with regard to the performance of these products.

For more information, visit our website at http://www.filemaker.com.

Edition: 03