MirrorSync with the iOS App SDK

This guide explains how to use the MirrorSyncLauncher file to deploy and sync your FileMaker solution as a standalone iOS app using the iOS App SDK.

What is the iOS App SDK?

The iOS App SDK is a free tool that FileMaker developers can use to bundle their FileMaker solutions into an iOS mobile app, which can be distributed via TestFlight, Mobile Device Management (MDM), or enterprise app distribution. This is powerful, because it allows the developer to redistribute new versions of their solution or app easily, rather than relying on users reading emails, downloading new databases, etc.

Developers can find the instructions for setting up and using the iOS App SDK here. When you reach “Step 9: Specify a URL scheme for your app,” we suggest setting it to ms, since our launcher file uses that as a default - but you can customize this if you'd like to use a different URL scheme.

Why use MirrorSync with the iOS App SDK?

Distributing your database through a mobile app has 2 big downsides:

1. When the database gets replaced, so does the data within it. The app can't tell whether the data within this file has been synced, duplicated, backed up, etc. The developer can configure when the files in the app will be replaced, but it still gives the developer very little control over what happens to the data in those databases.
2. Going through app store approval processes or MDM deployments can be slow or tedious. Sometimes you may discover a problem and need to immediately deploy a fix to your users, and it may not be possible to do that on a short timeline.

Our new launcher file solves this by acting as a bootstrapper. Instead of bundling your full solution in the app, you bundle the launcher. When the user first opens the app, the launcher contacts your MirrorSync server and downloads the actual solution files.

These files are stored in a persistent area of the app’s sandbox. Once downloaded, the launcher opens your actual solution. On future app launches, the launcher skips the download and just opens the solution directly.

After this is done, the developer has two tools to redistribute different portions of their app: using the iOS App SDK deployment configuration options will allow you to replace the built-in files in your app at appropriate times (including the 360Works launcher file), and the MirrorSync database replacement feature allows you to replace your solution files, the files that are downloaded by the 360Works launcher file.

This approach makes it easy to:

• Keep your app package small and lightweight.
• Preserve un-synced data across app updates.
• Push new solution files using MirrorSync’s database versioning feature.

Preparing and Using MirrorSyncLauncher for use with the iOS App SDK

The launcher file that we developed for use with the iOS App SDK is named MirrorSyncLauncher.fmp12, and developers can find it in the installation package that you get when initially downloading MirrorSync; you can download the most recent installation package here.

This file is intended to be customized as much as you like, but it will work with just two customizations:

1. Set a download URL. Steps and details:

• Retrieve a MirrorSync download URL from your config client.
• Open a new copy of MirrorSyncLauncher.fmp12. You'll see a home layout with an input field and a set of instructions for the developer; these will not be shown to the user.
• Paste the download URL into the input field in MirrorSyncLauncher.fmp12.
• Subsequently, any time the file is opened the MirrorSyncLauncher file will download and export the solution files that are associated with that download URL, assuming they're not already present in the Get(DocumentsPath) folder.
• If you need to get back into the file without triggering the script, hold down shift.

2. Set a custom URL scheme for your solution to use. Steps and details:

• If you've set your iOS App SDK project's URL scheme to "ms", no further customization is necessary.
• If you're using a different URL scheme:
  1. Open your MirrorSyncLauncher.fmp12 and open the "Startup" script. Customize the $$iosSdkUrlScheme variable on line 4 to your desired URL scheme.
  2. Open your hosted hub file, and open its MirrorSync 6 (<configurationName>) script. Line 126 of this script declares a variable named "$urlScheme" with the calculation If( Get( SystemPlatform ) ≠ 3 or Position ( Get( FileMakerPath ); "fmgo.app"; 1; 1 ); "fmp"; "ms" ) //Switch to custom protocol if using iOS App SDK
  3. Customize the "ms" in this calc to match your iOS App SDK URL scheme.

How can I open this file in the iOS App SDK environment?

In FileMaker Go, navigation between files doesn't necessarily need to be scripted, because FM Go provides a full file picker to allow the user to open the files in its directory. THe iOS App SDK doesn't expose that option. Because the iOS App SDK doesn't expose a typical FM Go GUI to open databases, the developer must also provide a way to access the database from within the app. There are two ways to do this:

• Modify the launchSolution parameter in your app's configFile to open the launcher immediately when the app is opened, like this: launchSolution = MirrorSyncLauncher.fmp12. This is what we had in mind when we designed MirrorSyncLauncher.
• If you'd rather use the launcher as a part of your app, but not as the default solution that gets opened first, you can use the Open File or Open URL script steps in scripted actions to open the MirrorSync file from the launch solution.

You can even bundle multiple MirrorSyncLaunchers (with different names) into the same app, all configured to download a different configuration's database, and all could be accessed from different buttons/scripts in a single wrapper file, which would probably be the launch solution.

If you're interested in this, but you're not sure where to start, 360Works offers custom FileMaker development; contact us at support@360works.com or 770-234-9293 to discuss how we can help build the solution you want to develop.

Can I use MirrorSyncLauncher without the iOS App SDK?

Yes! We've designed it to work in all environments, so developers can embed the MirrorSync download URL in it, email the user the launcher (it's small enough!), and use it on an iPad, a workstation, or wherever they'd like. We've found that the launcher is preferable over using a download URL by itself, because there are fewer steps from a user's perspective. In FM Go, the user only needs to click the database, click "Open in FileMaker Go", and MirrorSyncLauncher will take care of the rest.

For more information about MirrorSyncLauncher.fmp12, see this section of our documentation.

What can I customize in MirrorSyncLauncher.fmp12?

Anything. We intended this to be a developer tool, so feel free to read through its scripts, change its scripting/layouts, whatever you'd like.

Can I use this with a MirrorSync server that only supports HTTP connections?

Yes, you can, but it requires a small customization to your app’s property list file (Info.plist) in Xcode.

By default, iOS enforces secure (HTTPS) connections. To allow your app to connect to a MirrorSync server over insecure HTTP, you need to modify the NSAppTransportSecurity settings in your Info.plist.

Open your app’s Info.plist file and locate (or add) the NSAppTransportSecurity key. This key is a dictionary that lets you specify exceptions for particular domains. Inside it, add an NSExceptionDomains dictionary where each key is a domain name for which you want to allow exceptions.

For example, to allow HTTP connections to any .local domain and its subdomains, you would add the following:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>local</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

There are two keys within the domain:

• NSExceptionAllowsInsecureHTTPLoads enables HTTP (non-HTTPS) connections to the specified domain.
• NSIncludesSubdomains ensures the exception applies to all subdomains as well.

Replace "local" with your actual domain if it differs, such as myserver.example.com, or example.com if you want to allow connections to any example.com subdomain.