make onboarding with offline maps easier for new users of c:geo

[moving-bits]

One of the steepest hurdles for new users of c:geo is installing an offline map, IMHO. Thus probably most new users (except technically very savant) stick to Google maps and miss one of the greatest features of c:geo - offline caching.

There have been proposals for downloading maps in the past (eg #6072, #7529), but they are very sophisticated approaches which try to automate everything and cover a wide range of use cases. Sadly, they are also a bit more heavy to implement, not only on our side but on providers' side as well, and nobody has done it yet.

I propose a more basic approach with the focus on simplifying onboarding for new users of c:geo:

• Skip themeing, only support downloading map files for this onboarding feature. Therefore use a map source which does not need a separate theme file. (This would be the hs-esslingen mirror of download.mapsforge.org)
• Direct the user to the relevant directory, let them download the map file using the browser, and make c:geo integrate the downloaded file...
• ... which would include copying the file to c:geo map directory, set the map provider and current map file accordingly.

Implementation wise there are three areas of work:

• Offer a link to the map download site
• Recognize downloaded map files and move them to c:geo maps dir (current map dir, if already set, or new default one)
• Set map handler and current map file accordingly

I've started working on it. Current state is:

a) Initiate download via Settings => Map => Download basic offline maps:

b) Info screen:

c) Detecting that a map already exists under the same file name:

d) cancellable progress dialog during transfer:

e) confirmation dialog after successful installation:
(recognition of file name depends on Android version and map source; may be a more generic name like "5.map" or "msf:27.map")

Alternatively you can tap on a map file stored locally. This would enter the process shown above at step c).

This is work in progress. May be ready featurewise, but needs more testing with other file types (locally and online) as well as under more Android versions.

[jakedot]

this is a very good idea. Can we also implement this over at whereyougo? I think it needs a new map first, but then...

thanks for your work so far!

[moving-bits]

Can we also implement this over at whereyougo?

We could, but to my current understanding that would lead to the same side effects for WherYouGo as described in #7663 for c:geo, meaning then WhereYouGo would be offered as possible target for every application/octet-stream MIMEType files as well.

A possible solution could be WhereYouGo querying c:geo for the map path and saving that as their map path as well (haven't tried yet).

[jakedot]

in whereyougo#39, I tried around with the opening of .gwc files. I came to a similar conclusion as you in #7663 - your approach with filtering after the fact might be the only possible way to do it. The problem is that for content: URIs, which are the norm now, the file extension check isn't possible.

[bekuno]

At first we need at WhereYouGo support for OSM > v3

[jakedot]

The problem is that for content: URIs, which are the norm now, the file extension check isn't possible.

Well, not quite - more that we can't be sure to get a .gwc extension in the content: URL. For example Whatsapp downloads used to have .enc, regardless of the original extension (I think they applied this for all application/octet-stream content or similar)

@bekuno thought so

[moving-bits]

Current implementation in c:geo (reused and extended in #8180) works by reading the first lines of the opened file, identifying zip / gpx / ggc (and upcoming: map) files and routing the call accordingly. Might be extended later to recognize gwc files later, routing that to WhereYouGo, to add the capability to open local cartridges.

For now I'm working on #8180 to get opening map files easier for c:geo, currently struggling with the sparse documentation of intent data attributes.

[jakedot]

Do you have something PR ready so I can take a look at it?

[moving-bits]

Do you have something PR ready so I can take a look at it?

I've an early alpha version. Seems to work reasonably well on Android 8 and 10 (smoke tested in the emulator), does NOT work with Android 4.x yet (smoke tested with API levels 17, 19, 22 - none of it works).
Have not tested yet for side effects - downloading pocket queries did work at some time during development (but may be broken since), have not tested opening gpx files etc. yet. - may be broken.

If you're interested in testing you would be very welcome. I've created a PR with the described state, see #8183, so you can install the generated APK from that. - Not yet in the nightlies, though.

Be sure to make a backup of your database (and your settings, if you like) before you install the APK, using c:geo's backup routines, to be able to switch back to an older version, if needed.

[jakedot]

Will do, thanks! Maybe I can port some of it to Whereyougo. What I did there so far is also still in alpha state.

[moving-bits]

Will do, thanks! Maybe I can port some of it to Whereyougo. What I did there so far is also still in alpha state.

I propose to let us finish this in c:geo first, and then see how to add this functionality to WhereYouGo.

[moving-bits]

Update:

• does work with Android 4.x now
• does set received map as current map & adjusts map provider accordingly
• does print the received or generated file name
• if map file exists already you can chose between overwrite and save under new (random) name

To do: (reminder to myself)

• test for other local file types - those c:geo does understand and those c:geo doesn't
• test for downloading pocket queries
• (optional) differentiate between v3 and v5 OSM files depending on setting

@Lineflyer Which types of files else does c:geo consume today via download or by opening locally? (use cases like "download a pocket query", "open a local gpx file" etc.)

[jakedot]

Which types of files else does c:geo consume today via download or by opening locally?

@Lineflyer @moving-bits Maybe we should document this in the wiki?

[moving-bits]

@Lineflyer Which types of files else does c:geo consume today via download or by opening locally? (use cases like "download a pocket query", "open a local gpx file" etc.)

I started testing with different file types and on different Android versions. (If only those emulated Pixel devices had a file manager app...)

So far I have

• gpx file (local file)
• zipped gpx file (local file)
• map file (local file)
• pocket query (online)

What else do I have to look for, and can someone provide me with samples for it? (eg: ggz file)

[jakedot]

You can export to GGZ from GSAK IIRC.

[moving-bits]

You can export to GGZ from GSAK IIRC.

Thanks for the hint, but I don't have / don't use GSAK.

[jakedot]

I could provide you with two ggz samples, one with a single cache, one with multiple in different stati. Hope that would help?

[moving-bits]

I could provide you with two ggz samples, one with a single cache, one with multiple in different stati. Hope that would help?

Yes, this would be great, thanks!

[moving-bits]

BTW: Every file management app on Android seems to handle things slightly different - it's so much fun :-(

That's a good example of how much we benefit from having a lot of things standardized on Android (and having compatibility layers) - and you learn to value this again when it's not, as in this case...

[jakedot]

Waypoints.ggz contains multiple of my caches, some archived, some disabled, some unpublished, many different types.
Waypoint.ggz contains a single mystery.

Waypoints.zip

[jakedot]

BTW: Every file management app on Android seems to handle things slightly different - it's so much fun :-(

That's precisely the reason why I pretty much gave up quickly over at the WhereYouGo project...

In June I'll have much free time since I have to use 20 vacation days. Might as well do a bit more here then 😊

[moving-bits]

Waypoints.zip

Thanks, will add those to my test suite.

Edit: Both files worked without a problem.

[jakedot]

Btw, according to 7-zip the ggz files are a zipped folder structure like this:

data\GpxExportGGZ.gpx
index\com\garmin\geocaches\v0\index.xml

The index.xml seems to replicate some basic cache information also found in the gpx.

[moving-bits]

Btw, according to 7-zip the ggz files are a zipped folder structure like this:

Thanks for the added details. That's already handled inside the import handler CacheListActivity calls for reading the import file.

Here we only check for the zip file signature.

[moving-bits]

BTW if you would like to retest you can do so with the current version, should work now in more scenarios. Tested it (via emulator) with different Android versions (API level 17, 19, 22, 27, 29) and different file managers (FX explorer, Google files, Download manager that came with the system), although not all combinations are available. I also tried to test with Total Commander, but that one has a bug with applications that have a ":" in their app name, see #7313.

[Lineflyer]

Just a thought:
You should add another dialog warning that downloading offlne map files may produce a lot of network traffic. If a user does this while on a mobile connection it might be expensive.

[moving-bits]

Just a thought:
You should add another dialog warning that downloading offlne map files may produce a lot of network traffic. If a user does this while on a mobile connection it might be expensive.

I could add an extra sentence to the dialog shown in screenshot b, before the last paragraph. I'm redirecting the user to the mapsforge site, where the size of each map is listed beside the map name.

Another thing, just to clarify: I'm not downloading the map myself, it's done using the browser. Doing that from within c:geo would require much more work like parsing the webpage, creating the list views from that, and controlling the download manager. (But we can add this later, if we want and someone finds the time to implement it.)

[okainov]

d) cancellable progress dialog during transfer:

Just a side note - while I understand the proposed way is (relatively) easy from implementation side and is nobrainer, it shouldn't be like that really :) Please implement proper background downloading (#330), so people can easily download several maps and/or manage them afterwards.

[Lineflyer]

Just a side note - while I understand the proposed way is (relatively) easy from implementation side and is nobrainer, it shouldn't be like that really :) Please implement proper background downloading (#330), so people can easily download several maps and/or manage them afterwards.

AFAIK we meanwhile use the phones Download Manager, so this should be solved.

@moving-bits
In general this issue can be closed, or not?

[moving-bits]

AFAIK we meanwhile use the phones Download Manager, so this should be solved.
@moving-bits
In general this issue can be closed, or not?

Yes