iOS App SDK 19 Guide

Note: This guide uses iOS to mean both iOS and iPadOS unless otherwise stated.

Use iOS App SDK to build a standalone iOS app from your FileMaker® custom app. 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 custom apps:

• You can deploy FileMaker custom apps the same way you deploy other business apps for your organization.
• Users can access your FileMaker custom apps the same way they access other iOS apps. They don't need to install Claris™ FileMaker Go® to use the custom apps.
• You can choose the appearance of your custom apps by customizing the app icon and launch image.

Note:iOS App SDK supports authenticating user accounts via Claris ID and third-party OAuth identity providers.

1. Enroll in the Apple Developer Program.
2. Make sure you are familiar with the workflow for developing and distributing iOS apps. See Xcode Help.

1. Download Xcode from the Mac App Store, and install it on your Mac.
2. In the Xcode Accounts preferences, add the Apple ID that is associated with your Apple Developer Program.

1. Download iOSAppSDKPackage_<version number>.zip, then move the file from the Downloads folder to a location of your choice.
2. Double-click iOSAppSDKPackage_<version number>.zip to unpack the file and create the iOSAppSDKPackage_<version number> folder.

All resources for your app are stored in a project directory. Use iOS App SDK to create the project directory for your app.

1. Open the Terminal app on your Mac.

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

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

Note:Use the Show/Hide Menubar and Show/Hide Toolbars script steps in your Claris FileMaker Pro™ custom app to hide the FileMaker Go menu bar and toolbar. Otherwise, users will be able to access them from your iOS app.

1. Open the Xcode project file for your app (<appName>.xcodeproj).
2. In Xcode, click the disclosure triangle next to your project in the project navigator.
3. Click the disclosure triangle next to the Custom Application Resources folder.

4. Drag your custom app files to the Solution Files folder, then remove the PlaceHolder.fmp12 file.

   Note:This folder can contain multiple custom app files. You specify which custom app file to launch in configFile.txt.

5. (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 our website. The plug-in extension must be .fmplugin.

1. In the Xcode Custom Application Resources folder, click configFile.txt.

2. Update the following information:

   • launchSolution: Specify the custom app 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.
3. 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 custom app files to be replaced every time the app is launched.

   • 1 (always): The custom app files are copied every time the app is launched.
   • 2 (once): The custom app files are copied only the first time the app is launched.
   • 3 (versionChange): The custom app 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 9: Specify the version and build number.
   • 4 (buildVersionChange): The custom app 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 9: Specify the version and build number.
4. (optional) If you used FileMaker Pro to encrypt your custom app files, use the dbePassword option to specify the encryption passwords. The passwords will be embedded in the app, but obfuscated to make reconstructing them difficult.

5. (optional) To add your own app delegate, add the Swift or Objective-C file that includes the app delegate to your project in Xcode. Then use the applicationDelegateClass option in configFile.txt to specify the name of the class that defines your app delegate. When the app launches, an instance of the class is created to receive the UIApplicationDelegate messages. You need to implement only the UIApplicationDelegate messages that you want your app delegate to receive. For a list of UIApplicationDelegate methods, see the Apple UIKit documentation.

   To find out when your app returned to the foreground and finished reauthentication and reconnecting to remote files, use the following app delegate method:

   - (void)completedReturnToForegroundActive

   Example

   In the following example, a FileMaker script called MyScript is invoked if the device orientation changes.

   #import <UIKit/UIKit.h>
#import "FMX_Exports.h"
@interface MyDelegate : NSObject
@end
@implementation MyDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
NSLog(@"MyDelegate: %s", __func__);
return YES;
}
- (void)completedReturnToForegroundActive
{
NSLog(@"MyDelegate: %s", __func__);
}
- (void)application:(UIApplication *)application didChangeStatusBarOrientation: (UIInterfaceOrientation)oldStatusBarOrientation
{
NSLog(@"MyDelegate: %s Calling FMX_Queue_Script", __func__);
NSDictionary<NSString *, NSString *> *variables = @
{
@"$a": @"Value of $a",
@"$z": @"Value of $z"
};
if (FMX_Queue_Script(@"MyFile", @"MyScript", kFMXT_Pause, @"A script param", variables))
{
NSLog(@"MyDelegate: FMX_Queue_Script Succeeded");
}
else
{
NSLog(@"MyDelegate: FMX_Queue_Script Failed");
}
}
@end

Use the following guidelines for creating images for your app. For the latest information, see the Apple iOS Human Interface Guidelines.

App icons

Create different sizes of the app icon for each app to make sure it displays correctly on all supported devices. You need to provide only the icons that your app uses.

The recommended file format for icons is PNG.

Launch image

When your app launches, a launch image is displayed immediately. It is then 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. If you don't want the image to be cropped, use a square image.

Security shield image

If a FileMaker custom app uses the fmreauthenticate extended privilege, a security shield covers the content of the screen after the custom app 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.

Add image resources to the Xcode project

1. In Xcode, click the disclosure triangle next to your project in the project navigator.
2. Click the disclosure triangle next to the Custom Application Resources folder, then click CustomAppMedia.xcassets.
3. Click AppIcon, then drag each image to its target box.
4. Click LaunchImage to add your launch images, and click ObscureIcon to add your security shield images. Drag each image to its target. 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.

Explain why your app needs to access an iOS device's camera, location, photo library, microphone, or the media library.

1. In Xcode, click the disclosure triangle next to your project in the project navigator.
2. Click the disclosure triangle next to the Custom Application Resources folder.
3. Click Info.plist, then update the privacy description for external media.

1. In Xcode, select your project in the project navigator.
2. Choose the target from the Project/Targets pop-up menu or in the Targets section of the project and targets sidebar.
3. Click Capabilities at the top of the project editor.
4. Enable iCloud, then select iCloud Documents to allow transferring data to and from iCloud.

1. In Xcode, select your project in the project navigator.
2. Choose the target from the Project/Targets pop-up menu or in the Targets section of the project and targets sidebar.

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

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.

1. In Xcode, select your project in the project navigator.
2. Choose the target from the Project/Targets pop-up menu or in the Targets section of the project and targets sidebar.
3. Click Info at the top of the project editor.
4. Click URL Types, then click +.
5. Specify information for the identifier, URL scheme, and role.

1. In Xcode, select your project in the project navigator.
2. Make sure your Mac is connected to your iOS device.
3. 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.
4. Click the Run button in the toolbar to build and run your app.

5. 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 custom app files are present.
   • Check the Help menu to make sure it opens the correct URL.

To invoke a FileMaker script directly from your Objective-C or Swift code, use the FMX_Queue_Script function.

Format

FMX_Queue_Script(NSString *fileName, NSString *scriptName, FMX_ScriptControl control, NSString *scriptParameter, NSDictionary *variables)

Parameters

fileName - the name of the file that includes the script. The file must be open.

scriptName - the name of the script to run.

control - the action to take if an existing script is running: kFMXT_Halt, kFMXT_Exit, kFMXT_Resume, kFMXT_Pause.

scriptParameter - the parameter to pass to the script. This parameter may be nil.

variables - An NSDictionary that contains key-value pairs that are all NSStrings. Local variables will be created using the keys as the names of the variables and the values as the values of the variables. This parameter may be nil.

Return value

The return value is true if the script is queued, or false if the script can't be queued.

Notes

• The FMX_Exports.h header file declares the FMX_Queue_Script function.
• The user's account must have the FMURLScript extended privilege enabled.
• If multiple scripts are queued, the scripts run in the order they were queued.

Example

In the following example, the AddEntry script is invoked from the MyScripts file. The myParameter variable points to an NSString, and myVariablesDict is an NSDictorary of variables.

FMX_Queue_Script(@"MyScripts", @"AddEntry", kFMXT_Pause, myParameter, myVariablesDict)

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 5: 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 custom app 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.