esri / mapbook-ios Goto Github PK

Offline Mapbook app built with ArcGIS Runtime iOS SDK and Swift.

License: Apache License 2.0

Swift 100.00%

ios swift arcgis runtime offline map mapbook open-source-app

mapbook-ios's Introduction

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

Clone the Mapbook App
cd into the mapbook-ios folder
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.

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

In the terminal, change the current working directory to your local project
Type git fetch upstream to fetch the commits from the upstream repository
git checkout master to checkout your fork's local master branch.
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.

Register an ArcGIS Portal Application.
Configure the Mapbook App project to reference that application.
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.

Log in to https://developers.arcgis.com with either your ArcGIS Organizational Account or an ArcGIS Developer Account.
Visit your dashboard and create a new application.
In the Authentication tab, note the Client ID
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

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

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

In the Navigator pane under the project, find the file named AppSettings.swift.
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.

Access your dashboard and get your Runtime Lite license key.
Open the project in Xcode and navigate to AppSettings.swift, the same file used to configure your applications client id.
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.

Get involved
Report issues
Contribute code
Improve documentation

MDTOC

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

Licensing

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.

mapbook-ios's People

Contributors

Stargazers

Watchers

Forkers

cologispro obolorhuu sirbuks hng003 rcplay uponex ngeib chandradee23 kurtispoettcker isabella232

mapbook-ios's Issues

Handle authentication

Login
Credential storage

Map rotation and orientation enforcement from bookmarks

Since the app supports map rotation, should zooming/panning to a bookmark reset the orientation?

Bug: Side loaded package showed up in Portal mode

Update README to reflect the new home for 'Client ID' & 'License Key'

The location of placeholder strings for Client ID and License Key have been move from the plist an into the AppConfiguration as static variables.

Portal info is not cleared on uninstall

When app is uninstalled and reinstalled, the portal info is retained and logging in automatically without challenging for credentials

Offline mode username display

If the app is offline in Portal mode, tapping on the User button shows the words "username" and "fullname" in the popup. This should probably not show anything, if showing the actual user is not possible.

TOC content is reversed

Per the review meeting today, the TOC content should show the point layers at the top and the basemap at the bottom.

Logging in to organization with valid credentials throws error

Attempting to log into the runtime.maps.arcgis.com organization with username "mwilburn_runtime" and a valid password throws the error The username you entered is not a member of this organization.

From the app:

Logging on to the org:

Create mobile map package detail screen

Mobile map package meta-data
List mobile maps in package
Check for updates

Portal mode - after downloading an mmpk, the My Maps screen doesn't show it

Also, no pull to refresh is available. I'm just seeing the message to "tap the plus button to download..."

Mobile map package provisioning

Download mmpk from portal
Check for updates

Enhancements:

Side load mmpk

Selecting suggestion doesn't dismiss keyboard

When searching, after selecting a suggestion, both the keyboard and the search panel remain open. They should both be dismissed.

Document for the app

Switching to Portal mode while offline

If I try to switch to Portal mode while device is offline, the following happens:

I'm asked to confirm I want to switch
I get the message to hit the + to download maps
Once I hit the + I get the popup to specify the URL
When I hit continue, nothing happens. No error, no crash, nothing

What I think should happen:

When I try to switch to Portal mode while offline, I should get a message letting me know that I need to be online in order to use Portal mode.

@zinfin @mikewilburn thoughts?

Autosuggest results limit

See screenshot please https://github.com/ArcGIS/mapbook-ios/raw/master/docs/images/suggestion.png

Are you limiting the autosuggest results to 5? The tableview looks weird with just the 5 results. I would recommend either trimming the tableview or increasing the autosuggest results limit so the tableview is filled

Signing into another org shows the same mmpks like arcgis.com

Signing into another org shows the same mmpks like arcgis.com. Shouldn't signing into an org only display the mmpks belonging to that org? So, runtime.maps.arcgis.com should only show the runtime mmpks? @zinfin @mikewilburn thoughts?

Updating mobile map packages from Portal isn't very user friendly

When performing Pull to Refresh, give a more obvious indication to the user which map packages have updates available. Perhaps a small Update available label underneath the grayed out Refresh button

Use doesn't get logged out when switching portals

This should follow the same behavior as when user is switching from Device mode to Portal mode. The downloaded maps should be deleted and the logged in user should be logged out.

Update app for iOS 13

Migrate app to Swift 5

https://swift.org/migration-guide-swift5/

Upgrade app to Runtime 100.2

@esreli Here's your reminder issue for upgrading the mapbook-ios to 100.2

HTML tags are displayed in Description labels

HTML is not parsed properly and the tags are displayed in the description labels.

When there is only one map in the package, the HTML tags are displayed in the offline maps list.
When a package has multiple maps, then the the description is the tableView is rendered fine but the description of the individual maps has the tags.

Change repo topics

To be consistent with other Esri repo topics categorization, please remove topics ios-swift and ios-app, add topics native-development, ios, and swift

Search view controller

Provide suggestions for input
Geocode based on selected suggestion
Show results on map view

Update for SDK v 100.3

Handle expiration of mobile map packages

100.5 Runtime added ability to handle expiration of mobile map packages -

Time-based expiration of mobile map packages and mobile scene packages is now supported in ArcGIS Runtime. An author can choose either a hard expiration where the package is not usable after the expiry date, or a soft expiration where a warning message my be displayed to the user but the package is still usable after the expiry date. Packages with such expiration constraints can be created using an upcoming version of ArcGIS Pro.

See https://developers.arcgis.com/ios/latest/api-reference/interface_a_g_s_mobile_map_package.html#a39fca5954cf2d4176c82322ff51726d9

Hide update UI in Device mode

Migrate app to Swift 5.1

Download spinner doesn't go away unless table is refreshed

When the download is finished, the spinner doesn't go away unless the tableView is scrolled to refresh.

Update the default portal url string to omit the 'www'

Logging into the generic https://www.arcgis.com portal works just fine.
However, modifying the string to be that of a specific portal, say https://www.runtime.maps.arcgis.com, will throw an error:

An SSL error has occurred and a secure connection to the server cannot be made.

This is because the 'www' ought to be omitted in this case --> https://runtime.maps.arcgis.com should be used instead.
To encourage this, and to prevent users from running into this error, I suggest we remove the www from the default string altogether.

Add map view controller

Capabilities:

Identify

Hitting Search in the Portal Items filter screen does not dismiss keyboard

Write documentation

Spin up a wiki that documents the application from a developer pattern and data perspective that can eventually be duplicated to the developers.arcgis.com/example-apps/mapbook-ios site.

Background download

MMPKs should be downloading in the background. As a best practice, the user should not be tied to the app as the data is being downloaded, especially since some of the MMPKs are quite large and will take a while to download.

Build for 100.4.0

Size is missing for offline maps

For downloaded maps, size attribute is not displayed. Size needs to be displayed in two locations

In the tableView in the list of maps
In the view that displays the details of the map

Remove ATS allows arbitrary loads.

ArcGIS Online has updated it's owning system URL. https://www.arcgis.com/sharing/rest/info?f=pjson

This change should be reflected in

XCode
~~README~~

Add Layer name to the Identify Popup

For consistency purposes with the other apps and for clarity, the identify popup should show the name of the layer the feature belongs to. See below screenshots from the Android and WPF apps:

https://developers.arcgis.com/example-apps/mapbook-android/img/callout.png
https://developers.arcgis.com/example-apps/mapbook-wpf/img/identify.png

Popup doesn't resize

The popup window should resize based on content. If the identified feature only has 2 attributes, most of the popup box is blank

Rotating device causes popup to no longer point at the identified feature

When identifying, the tip of the popup points to the identified feature. However, if the device is rotated, the popup moves and the tip no longer points to the identified feature

Option to cancel a map download

At present, when a map download is initiated by accident, there is no option to cancel the download unless the user logs off and delete all local data. A button can be added to cancel the ongoing download.

Add legend

Capabilities:

List operational layers
Change visibility of each layer
Legend for each layer

Update code base to Swift 4

Referencing the swift migration guide.

Migrate to Swift 4.2 and build for XCode 10

Search button doesn't trigger search

When searching for a feature, tapping the Search button doesn't trigger a search. Only tapping on one of the suggestions actually triggers the search. It should do both, in case user's locator doesn't support autosuggest

Bookmarks list view controller

List bookmarks stored in the map
Set bookmark's viewpoint on the map view

App crashes when switching to Portal mode

When I switch to Portal mode, on the "Specify the URL..." popup, when I hit Continue, the app crashes. Below is the error from XCode. The url is the default one: https://www.arcgis.com

2017-08-25 09:33:00.714 mapbook-iOS[564:138335] <CATransformLayer: 0x1464dff0> - changing property contentsGravity in transform-only layer, will have no effect
2017-08-25 09:33:12.249 mapbook-iOS[564:138335] *** Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: 'The specified URL has an unsupported scheme. Only HTTP and HTTPS URLs are supported'
*** First throw call stack:
(0x2383791b 0x22fd2e17 0x23837861 0x2e63386f 0x37363f 0x372c91 0x444093 0x12538b7f 0x12538b6b 0x1253d655 0x237f9b6d 0x237f8067 0x23747229 0x23747015 0x24d37ac9 0x27e1b189 0xee960 0x233ef873)
libc++abi.dylib: terminating with uncaught exception of type NSException```

Test app compiled with U6

Switching to Portal from Device warns user of deleting maps

When switching to Portal from Device mode, I get a message alerting me that all packages I have on the device will be deleted. When I go back to Device from Portal, the packages are still there. Sooo, should they be deleted? Or should the warning not show? It's very confusing. @zinfin @mikewilburn please chime in

Error on loading map packages

Sometimes while opening downloaded maps, following error is displayed. This error is totally random and when opened again the same package opens as expected.