esri/maps-app-android

Your organisations mapping app built with the runtime SDK for android

Maps App Android

This repo provides an example app for Android devices called Maps App that can be used as a starter for your organization's mapping app built with ArcGIS Runtime SDK for Android. You can use the Maps App as is, or extend it using the ArcGIS Runtime SDK for Android.

Visit Esri's open source apps site to read more about this app and how the Runtime features are implemented.

• Features
• Detailed Documentation
• Development Instructions
  • Fork the repo
  • Clone the repo
    • Command line Git
  • Configuring a Remote for a Fork
• Requirements
• Resources
• Issues
• Contributing
• MDTOC
• Licensing

---

Features

• Dynamically switch basemaps
• Place search
• Routing
• Geocode addresses
• Reverse geocode
• Sign into an ArcGIS account

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.

Development Instructions

This Maps App repo is an Android Studio Project and App Module that can be directly cloned and imported into Android Studio. In addition, you'll need to follow the steps below to obtain your client id and redirect uri. Both are required for leveraging all the features of the app.

• Log in to ArcGIS for Developers and register your app.

• Once you've registered your version of the maps-app, grab a copy of the client id from the registration and set the client id in the applications app_settings.xml file.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- TODO: add your OAuth Client ID here-->
    <string name="client_id">YOUR_CLIENT_ID</string>
    <!-- This redirect URI is the default value for https://www.arcgis.com -->
    <string name="redirect_uri">my-ags-app://auth</string>
    <!-- The following values are used in the Robotium tests only -->
    <string name="username">YOUR_PORTAL_USERNAME</string>
    <string name="password">YOUR_PORTAL_PASSWORD</string>
    <string name="testPartialName">vo</string>
</resources>

• As part of the registration process, add a redirect uri for your app. Navigate to the Redirect URIs section at the bottom of the registration page and set the redirect uri to my-ags-app://auth. This redirect uri is the default redirect for https://www.arcgis.com.

• Note that the scheme for the DefaultOAuthIntentReceiver in the Android Manifest file is derived from the redirect uri.

        <activity
            android:name="com.esri.arcgisruntime.security.DefaultOAuthIntentReceiver"
            android:label="OAuthIntentReceiver"
            android:launchMode="singleTask">
            <intent-filter>
                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>

                <data android:scheme="my-ags-app"/>
            </intent-filter>
        </activity>

Fork the repo

Fork the Maps App Android repo

Clone the repo

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

Command line Git

1. Clone the Maps App repo
2. cd into the maps-app-android 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 (for Windows and Linux users) type git remote -v to list the current configured remote repo for your fork.
2. git remote add upstream https://github.com/Esri/maps-app-android.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.

Requirements

• Android Studio

Resources

• ArcGIS Runtime SDK for Android Developers Site
• ArcGIS Mobile Blog
• ArcGIS Developer Blog
• Google+
• twitter@ArcGISRuntime
• twitter@esri

Issues

Find a bug or want to request a new feature enhancement? Let us know by submitting an issue.

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

Generating table of contents for documents in this repository was performed using the MDTOC package for Atom.

Licensing

Copyright 2016 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.txt file.

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

[](Esri Tags: ArcGIS Android Mobile) [](Esri Language: Java)​

maps-app-android's Issues

Need to refactor getLastNonConfigurationInstance() to use Fragment API

App crashes on getLastConfigurationInstance() method when attempting to retrieve the non-configured instance. Need to refactor to use Fragment API setRetainINstance(boolean) instead.

Need a way to clear a search result

Results from place search or reverse geocoding cannot be removed from layer w/o using the result in a route.

The Options > About button doesn't display anything

It looks like the layout for the "About" view hasn't been built out yet.

Android 4.3, Nexus 4

Need a start graphic location for routing

When app uses My Location the GPS symbol represents the start location of a route. If the user changes the start location the app does not create a start Graphic to represent the starting point of the route.

Redesign Basemaps View

Redesign the basemap view as a dialog similar to Google Maps app and ArcGIS Collector app.

Refactor ProgressDialog

Simplify ProgressDialog pattern and implement backing out of the dialog cleanly.

Go to a versions/milestone methodology?

@doneill would you consider moving to a versioning and milestones approach? Some of the recent updates are fairly large. Having release milestones would also help developers in planning ahead as to when certain aspects of functionality are being considered for integration. Example: https://github.com/Esri/esri-leaflet/blob/master/CHANGELOG.md

Implement turn by turn routing

Routing is currently implemented and default to users location as start point and display the route. Need to implement turn by turn routing.

Refactor place search to use android search toolbar

Android helps implement a user interface with either a search dialog that appears at the top of the activity window or a search widget that can be inserted in a layout. Both deliver the user's search query to a specific activity in the application.

Features available for the search dialog and widget include:

• Voice search
• Search suggestions based on recent queries
• Search suggestions that match actual results in our app data.

Offline Base Map and Layers

Can you use an offline basemap and also show offline layers on the basemap?

Single tap on features doesn't work

Implement directions segment view

The directions fragment needs to support tapping direction and zooming into the segment of the route on the map.

Remove static modifier to MapView

Potential for memory leaks since MapView extends ViewGroup and the potential Context not being released.

Remove Recreation Feature Layer and popup support

App should be more generic when first opened. Adding this layer shows custom content/data/service that would not be expected in a Mapping app.

Implement simplification api

Look at simplification api to see where the pattern can be used.

Add measure tool

Implement distance/area measure tool based on placing points on a map. GeometrySample SDK sample has an implementation to look at.

Application stops responding when the search button in action bar is tapped

Tapping the search button in the ActionBar causes the app to crash with the following fatal exception logged:

FATAL EXCEPTION: main
    Process: com.esri.android.mapsapp, PID: 7283
    java.lang.IllegalStateException: Could not find a method onSearchButtonClicked(View) in the activity class android.view.ContextThemeWrapper for onClick handler on view class android.widget.ImageButton with id 'searchButton'

Steps to reproduce:

1. Tap the Search button in the ActionBar to initiate the Search Contextual Action Bar.
2. Tap the Search button next to the Search Text.

LocationService doesn't terminate on minimize

The LocationService stays on even when the application is minimized causing a hidden battery drain.

I suggest the following:

• Assign LocationService to a global variable
• Stop the LocationService in onPause() and onStop()
• Include mMapView.pause() in onPause().
• Include mMapView.unpause() in onResume().
• Re-evaluate if the GPS needs to be on all the time. Maybe the use cases only call for a snapshot approach? That way once a minimum level of accuracy is reached you can kill off the GPS.
• In onResume() add some logic that detects if the map is loaded and then kicks off LocationService. I did something heavier duty in my delayedStartLocationProvider() in my android-gps-test-tool repo at line 997: https://github.com/Esri/android-gps-test-tool/blob/master/src/com/agup/gps/controllers/GPSTesterActivityController.java.

Remove sign in from action bar

Hello, I am new to android developpement and I was asked to develop an android application using the ESRI android SDK. I based my application on your model, and I was able to remove the "measure tool". I want now to remove "Sign in" from the action bar but I couldnt. I would like some help please on the lines or the files that I should remove or add to make this happen?

Update measure tool

Update the measure tool to show units in a callout and not the action bar.

Override the keyboard Done/Finished button

When app in place search mode the Done/Finish button on keyboard closes the keyboard requiring a user to tap the search icon to initiate the search. A better UX would be to override the Done/Finished button to initiate the search immediately w/o the secondary requirement to tap the search button.

Choosing a new basemap recenters app on Esri Redlands campus

Nexus 4 Android 4.3

Assumption: when choosing a new basemap it should honor the previous basemaps extent.

Problem: When app is first installed, choosing certain new basemaps results in the map being recentered on Esri Redlands.

Workflow:

• Install application fresh (no cached data) -- Or, once application is installed emulate a newly installed app by using these steps: Apps > Maps App > Force stop > Clear data > restart app)
• Open app.
• Allow app to automatically center based on GPS location
• Select base map picker
• Choose a base map: Streets, National, Oceans, Terrain with labels, Topographic, Imagery with Labels, Imagery
• New basemap displays and it is centered on Redlands, CA.

Note 1: the following basemaps seem to work correctly "most of the time" in this workflow: Light Grey Canvas, Streets, OpenStreetMap. I saw some intermittently incorrect behavior when switching to Light Grey Canvas.

Note 2: Terrain with Labels also seemed to work correctly intermittently. However, It's safe to say that it works "incorrectly" the majority of the time.

Note 3: I didn't see any obvious errors in logcat.

Implement location suggestions in Search Bar

Introduced at v10.2.4, Geocoding suggestions provide character-by-character auto-completion for facilitating interactive search experiences. A LocatorSuggestionResult can be Locator.find() method to receive more detailed information about geocoding suggestions.

Refactor to ArcGIS Android 10.2.2 SDK

Once ArcGIS Android 10.2.2 is release we will need to update to use the new libraries and programming patterns.

Mesurement Tool

Is There a measurement tool ?

Action bar messed up after Search>Directions>BACK

I find the action bar gets messed up when I select the Search tool, then select the Directions tool (when Search still selected), then press BACK. I'm using a phone.

Retain Reverse Geocoding functionality when changing basemaps

After changing the basemap the reverse geocoding long press feature is disabled.

Current tested implementation does not work:
BasemapsAdapter.java line 174

updateMapView.setOnLongPressListener(new OnLongPressListener() {

    @Override
    public void onLongPress(float x, float y) {
        Point mapPoint = updateMapView.toMapPoint(x, y);
        new ReverseGeocoding(MapsApp.this, updateMapView).execute(mapPoint);

    }
});

Refactor to optimize fragment patterns

Refactor Reverse Geocoding results to callout

Reverse Geocoding should show results in a Callout instead of a TextSymbol. The showCallout method has been implemented for place search results and can be implemented for reverse geocoding results.

Need a way to clear a route

Once a route has been added to the map there is no way to remove the route without performing another task.

Move ActionBar features to drawer

Move the following ActionBar items to the drawer

• Measure Tool
• Basemap Selection

Create a Legend Tool

Dev summit 2014 attendees who were exposed to the measure tool requested a Legend tool. We have an issue in the android tookit API to design a spec around creating tools.

Update Default Basemaps

Default Basemaps are limited to 4. We need to include more popular basemaps and remove some existing basemaps.

• Topographic - Default
• Streets
• Light Gray
• National Geographic
• Ocean
• Imagery

Implement clearing of routing results

Need a way for a user to clear a route result and the resulting graphics on the map.

GPS keeps running when you quit the app

Refactor opening basemap to TOPO

Currently the Streets basemaps opens on start of the app. We need to change this to the Topo basemap on start of the app.

Refactor Toggle GPS on/off to My Location

Redesign the toggle gps button to behave as a See your location on the map feature.

Implement 2 ways you can see where you are on the map using the location button:

• Center the map at your location
  When you are exploring a map, searched for a place or moved the map away from your location, tapping the location button zooms to your current location and center zoom in level.
• Use the map from your perspective
  When you are at your current location and center zoom level, tapping the location button puts you in compass mode whereby the map moves as you do. This mode orients the map in the direction you are facing.

We need to add support for rotating the map to support the compass mode feature. Rotating a map should be supported in both ways described above. The difference will be that in center the map mode the user can rotate the map, in map from your perspective mode the device can rotate the map.

Refactor MyLocation as floating overlay button

With the removal of the ActionBar per #67 we need to move the MyLocation button from the ActionBar as a floating overlay button in the bottom right hand corner.

Create a scale bar tool

Scale bar tool was requested by dev summit 2014 session attendees who were exposed to the measure tool.

Add example of extending the measure tool

The measure tool can be extended to use a custom set of units and change the symbols used to draw the lines and polygons. We need to add an example of extending the measure tool in this way.

Add ArcGIS Online access

Allow users to leverage their ArcGIS Online subscription to access custom basemaps and webmaps.

Import into Eclipse

I am having trouble importing into eclipse. Can you please provide directions to properly import into eclipse?

Map's My Location is Redlands

When the map opens it does not open to the GPS location but instead to Redlands, CA. Furthermore, when you leave My Location as the routing start point it uses Redlands, CA instead of the GPS location.

Need to support API 15 and above

We have some users who are requesting support for API 15 and above.

NullPointerException when trying to enter a search string

I got this crash when trying to enter a search string. I think I ended up doing a search without having entered any text. Unable to reproduce it now.

12-03 11:33:09.894: W/TextView(21533): TextView does not support text selection. Action mode cancelled.
12-03 11:33:10.084: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 41 mFalseSizeCnt:0
12-03 11:33:11.586: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 9 mFalseSizeCnt:0
12-03 11:33:12.417: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 9 mFalseSizeCnt:0
12-03 11:33:15.970: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 6 mFalseSizeCnt:0
12-03 11:33:16.951: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 7 mFalseSizeCnt:0
12-03 11:33:18.092: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 8 mFalseSizeCnt:0
12-03 11:33:22.987: D/AbsListView(21533): unregisterIRListener() is called
12-03 11:33:23.027: D/AbsListView(21533): unregisterIRListener() is called
12-03 11:33:25.860: D/AbsListView(21533): onDetachedFromWindow
12-03 11:33:25.880: W/InputEventReceiver(21533): Attempted to finish an input event but the input event receiver has already been disposed.
12-03 11:33:25.880: E/ViewRootImpl(21533): sendUserActionEvent() mView == null
12-03 11:33:27.732: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 12 mFalseSizeCnt:0
12-03 11:33:28.632: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 8 mFalseSizeCnt:0
12-03 11:33:29.363: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 7 mFalseSizeCnt:0
12-03 11:33:29.704: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 8 mFalseSizeCnt:0
12-03 11:33:30.334: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 11 mFalseSizeCnt:0
12-03 11:33:30.785: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 8 mFalseSizeCnt:0
12-03 11:33:31.265: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 9 mFalseSizeCnt:0
12-03 11:33:31.635: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 8 mFalseSizeCnt:0
12-03 11:33:31.886: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 9 mFalseSizeCnt:0
12-03 11:33:32.096: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 7 mFalseSizeCnt:0
12-03 11:33:32.286: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 13 mFalseSizeCnt:0
12-03 11:33:32.917: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 12 mFalseSizeCnt:0
12-03 11:33:34.678: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 7 mFalseSizeCnt:0
12-03 11:33:39.423: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 8 mFalseSizeCnt:0
12-03 11:33:40.324: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 7 mFalseSizeCnt:0
12-03 11:33:40.884: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 10 mFalseSizeCnt:0
12-03 11:33:44.558: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 10 mFalseSizeCnt:0
12-03 11:33:46.180: D/GestureDetector(21533): [Surface Touch Event] mSweepDown False, mLRSDCnt : -1 mTouchCnt : 9 mFalseSizeCnt:0
12-03 11:33:46.190: D/AndroidRuntime(21533): Shutting down VM
12-03 11:33:46.190: W/dalvikvm(21533): threadid=1: thread exiting with uncaught exception (group=0x4130bac8)
12-03 11:33:46.200: E/AndroidRuntime(21533): FATAL EXCEPTION: main
12-03 11:33:46.200: E/AndroidRuntime(21533): java.lang.IllegalStateException: Could not execute method of the activity
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.view.View$1.onClick(View.java:3748)
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.view.View.performClick(View.java:4367)
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.view.View$PerformClick.run(View.java:17984)
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.os.Handler.handleCallback(Handler.java:725)
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.os.Handler.dispatchMessage(Handler.java:92)
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.os.Looper.loop(Looper.java:137)
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.app.ActivityThread.main(ActivityThread.java:5306)
12-03 11:33:46.200: E/AndroidRuntime(21533): at java.lang.reflect.Method.invokeNative(Native Method)
12-03 11:33:46.200: E/AndroidRuntime(21533): at java.lang.reflect.Method.invoke(Method.java:511)
12-03 11:33:46.200: E/AndroidRuntime(21533): at com.android.internal.os.ZygoteInit$MethodAndArgsCaller.run(ZygoteInit.java:1102)
12-03 11:33:46.200: E/AndroidRuntime(21533): at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:869)
12-03 11:33:46.200: E/AndroidRuntime(21533): at dalvik.system.NativeStart.main(Native Method)
12-03 11:33:46.200: E/AndroidRuntime(21533): Caused by: java.lang.reflect.InvocationTargetException
12-03 11:33:46.200: E/AndroidRuntime(21533): at java.lang.reflect.Method.invokeNative(Native Method)
12-03 11:33:46.200: E/AndroidRuntime(21533): at java.lang.reflect.Method.invoke(Method.java:511)
12-03 11:33:46.200: E/AndroidRuntime(21533): at android.view.View$1.onClick(View.java:3743)
12-03 11:33:46.200: E/AndroidRuntime(21533): ... 11 more
12-03 11:33:46.200: E/AndroidRuntime(21533): Caused by: java.lang.NullPointerException
12-03 11:33:46.200: E/AndroidRuntime(21533): at com.esri.android.rt.map.MapsApp.locate(MapsApp.java:348)
12-03 11:33:46.200: E/AndroidRuntime(21533): ... 14 more

Offline Address Search

Would it be possible to do an offline address search?

Make Map available offline

Provide feature and workflow for viewing maps when offline.

Feature

• Taking basemap offline
• Set a reasonable extent such that the user does not have to select Tile Levels as all levels below extent should be taken by default.

Workflow
User initiated

• Add a icon and text in the drawer
• The app will use the existing extent as candidate for offline.

Auto

• App automatically caches areas where the user has been. There will be a defined limit on space and saved to app data space. These tiles will be private to the app and should be placed in the directory returned by Context.getExternalFilesDir then the system will take care of deleting if the app is uninstalled. With Android 4.4 we can use getExternalCacheDir().

Implement reverse geocoding

Implement clearing of Place Search Results

Need to add a way to clear results from the place search on the map. The place search action bar could add a tool to delete the result.

Routing Dialog Fragment needs to explicity state Start and End

The screenshot below shows icon representing start and end point. On the far right there is an icon to tap to switch between start and stop points, which we should consider as well.

Here is our current implementation: