Mapbook iOS

This repo is home to the mobile mapbook app, an example application using the ArcGIS Runtime SDK for iOS. Replace the paper maps you use for field work with offline maps.

• Features
• Best Practices
• Detailed Documentation
• Get Started
  • Fork the repo
  • Clone the repo
    • Command line Git
  • Configuring a Remote for a Fork
  • Configure the app
    • 1. Register an Application
    • 2. Configuring the project
    • 3. License the app (Optional)
• Learn More
• Requirements
• Contributing
• MDTOC
• Licensing

Features

• Mobile map packages
• Feature layers
• Identify
• Table of Contents
• Show a legend
• Use a map view callout
• Geocode addresses
• Suggestion search
• Bookmarks
• Sign in to your portal

Best Practices

The project also demonstrates some patterns for building real-world apps around the ArcGIS Runtime SDK.

• Defining a modular, decoupled UI that operates alongside a map view
• Asynchronous service and UI coding patterns
• Internal application communication patterns
• FileManager used with ArcGIS

Detailed Documentation

Read the docs for a detailed explanation of the application, including its architecture and how it leverages the ArcGIS platform, as well as how you can begin using the app right away.

Get Started

Make sure you've installed Xcode and the ArcGIS Runtime SDK for iOS and that they meet these requirements.

Fork the repo

Fork the Mapbook App repo.

Clone the repo

Once you have forked the repo, you can make a clone.

Make sure to use the "recursive" option to ensure you get the ArcGIS Runtime Toolkit submodule

git clone --recursive [URL to forked Git repo]

If you've already cloned the repo without the submodule, you can load the submodule using

git submodule update --init

Command line Git

1. Clone the Mapbook App
2. cd into the mapbook-ios folder
3. Make your changes and create a pull request

Configuring a Remote for a Fork

If you make changes in the fork and would like to sync those changes with the upstream repository, you must first configure the remote. This will be required when you have created local branches and would like to make a pull request to your upstream branch.

1. In the Terminal (for Mac users) or command prompt (fow Windows and Linus users) type git remote -v to list the current configured remote repo for your fork.
2. git remote add upstream https://github.com/Esri/mapbook-ios.git to specify new remote upstream repository that will be synced with the fork. You can type git remote -v to verify the new upstream.

If there are changes made in the original repository, you can sync the fork to keep it updated with upstream repository.

1. In the terminal, change the current working directory to your local project
2. Type git fetch upstream to fetch the commits from the upstream repository
3. git checkout master to checkout your fork's local master branch.
4. git merge upstream/master to sync your local master branch with upstream/master. Note: Your local changes will be retained and your fork's master branch will be in sync with the upstream repository.

Configure the app

Before running the app, it must be configured with application credentials. Follow the steps below to obtain application credentials used for browsing and downloading Portal content.

1. Register an ArcGIS Portal Application.
2. Configure the Mapbook App project to reference that application.
3. License the app to remove the Developer Mode watermark.

1. Register an Application

For OAuth configuration, create a new Application in your ArcGIS Portal to obtain a Client ID and configure a Redirect URL. The Client ID configures the ArcGIS Runtime to show your users, during the log in process, that the application was built by you and can be trusted. The Redirect URL configures the OAuth process to then return to your app once authentication is complete.

1. Log in to https://developers.arcgis.com with either your ArcGIS Organizational Account or an ArcGIS Developer Account.
2. Visit your dashboard and create a new application.
3. In the Authentication tab, note the Client ID
4. In the Authentication tab add a redirect URI to the Current Redirect URIs section. By default the Xcode project is configured to authentication callbacks using:

   mapbook://auth

2. Configuring the project

Configure Redirect URL

1. Open the project in Xcode and browse to the mapbook-iOS target's Info panel and expand the AGSConfiguration dictionary (see steps 1-4 in the screenshot below).

2. Set the AppURLScheme value to match the Redirect URL scheme configured in "Register an Application" above. The scheme is the app name that comes before :// in the redirect URI.

   mapbook://auth

3. Expand the URL Types section and modify the existing entry.

   • The Identifier doesn't matter, but should be unique.

     ex: com.esri.mapbook

   • The URL Scheme should match the Redirect URL scheme configured in "Register an Application" above. The scheme is the app name that comes before :// in the redirect URI.

     mapbook://auth

   

Configure Client ID

1. In the Navigator pane under the project, find the file named AppSettings.swift.
2. Within AppSettings.swift set the value of the static variable clientID to the application's Client ID noted in the step 'Register an Application'.

3. License the app (Optional)

This step is optional during development, but required for deployment.

1. Access your dashboard and get your Runtime Lite license key.
2. Open the project in Xcode and navigate to AppSettings.swift, the same file used to configure your applications client id.
3. Set the value of the static variable licenseKey to the value from step 1.

Learn More

Learn more about the App Architecture and usage here.

Requirements

• Xcode 12 and Swift 5
• ArcGIS Runtime SDK for iOS, version 100.10.
• ArcGIS Runtime Toolkit for iOS, version 100.10.
• Device or Simulator running iOS 13.0 or later.

Note: Starting from the 100.8 release, the ArcGIS Runtime SDK for iOS uses Apple's Metal framework to display maps and scenes. However, Xcode does not support Metal based rendering in any version of iOS simulator on macOS Mojave. If you are developing map or scene based apps in these environments, you will need test and debug them on a physical device instead of the simulator.

Note: The 100.10 release of the ArcGIS Runtime SDK for iOS replaces the installed "fat framework" ArcGIS.framework with a new binary framework ArcGIS.xcframework. It also changes the location of the installed framework file and removes the need for the strip-frameworks.sh Build Phase. These changes have been incorporated in the latest release of Mapbook iOS.

Contributing

Anyone and everyone is welcome to contribute. We do accept pull requests.

1. Get involved
2. Report issues
3. Contribute code
4. Improve documentation

MDTOC

Generation of this and other documents' table of contents in this repository was performed using the MDTOC package for Atom.

Licensing

Copyright 2017 Esri

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.

A copy of the license is available in the repository's LICENSE file.

For information about licensing your deployed app, see License your app.