@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-howtos/references/location-and-maps.md

@@ -1,266 +1,139 @@
-# Location services and maps
+# Location & maps
 
-## 1. GPS position tracking
+Based on the [current official guide](https://titaniumsdk.com/docs/build/location.md). Examples target released SDK 13.4.1; verify the selected SDK before adopting version-specific behavior.
 
-### FusedLocationProvider (Android)
-Since TiSDK 7.1.0, Titanium supports `FusedLocationProvider` for significant battery savings. Requirement: include the `ti.playservices` module in your project.
+Location needs permission, and the permission has kinds: while-in-use or
+always, and on iOS precise or approximate. Ask for the least you need.
 
-### Accuracy configuration
-
-iOS accuracy levels:
-- `ACCURACY_BEST` - highest power (GPS)
-- `ACCURACY_NEAREST_TEN_METERS` - medium-high power
-- `ACCURACY_HUNDRED_METERS` - medium power
-- `ACCURACY_KILOMETER` - low power
-- `ACCURACY_THREE_KILOMETERS` - lowest power (cell/wifi)
-
-Key properties:
-```javascript
-Ti.Geolocation.accuracy = Ti.Geolocation.ACCURACY_BEST;
-Ti.Geolocation.distanceFilter = 10; // meters - only fire if moved X meters
-Ti.Geolocation.headingFilter = 5; // degrees - only fire if heading changed X degrees
-Ti.Geolocation.preferredProvider = Ti.Geolocation.PROVIDER_GPS; // or PROVIDER_NETWORK
-```
-
-Note: on many Android devices, a low-precision passive location provider is always enabled, even when the user disables GPS and Network providers. `Ti.Geolocation.locationServicesEnabled` may always return `true` on those devices.
-
-### Android configuration modes
-
-Simple mode (ACCURACY_HIGH/LOW):
-```javascript
-Ti.Geolocation.accuracy = Ti.Geolocation.ACCURACY_HIGH;
-```
-
-Manual mode (fine-grained control):
-```javascript
-const providerGps = Ti.Geolocation.Android.createLocationProvider({
-  name: Ti.Geolocation.PROVIDER_GPS,
-  minUpdateDistance: 0.0,
-  minUpdateTime: 0
-});
-Ti.Geolocation.Android.addLocationProvider(providerGps);
-Ti.Geolocation.Android.manualMode = true;
-```
-
-### Location permissions
-
-```javascript
-// Check permissions
-if (Ti.Geolocation.hasLocationPermissions(Ti.Geolocation.AUTHORIZATION_WHEN_IN_USE)) {
-  startTracking();
-} else {
+```js
+if (!Ti.Geolocation.hasLocationPermissions(Ti.Geolocation.AUTHORIZATION_WHEN_IN_USE)) {
   Ti.Geolocation.requestLocationPermissions(Ti.Geolocation.AUTHORIZATION_WHEN_IN_USE, (e) => {
     if (e.success) {
-      startTracking();
-    } else {
-      Ti.API.error(`Permission denied: ${e.error}`);
+      locate();
     }
   });
+} else {
+  locate();
 }
 ```
 
-iOS plist keys (tiapp.xml):
+`tiapp.xml` needs the matching usage string on iOS:
+
 ```xml
-<key>NSLocationWhenInUseUsageDescription</key>
-<string>We need your location to show nearby places</string>
-<!-- For background location: -->
-<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
-<string>We need background location for navigation</string>
+<ios>
+  <plist>
+    <dict>
+      <key>NSLocationWhenInUseUsageDescription</key>
+      <string>Show which notes were written near you.</string>
+    </dict>
+  </plist>
+</ios>
 ```
 
-Note (iOS 11+): you must include `NSLocationAlwaysAndWhenInUseUsageDescription` even when requesting "Always" permission. Users can still choose "When in Use".
+Asking for `AUTHORIZATION_ALWAYS` is a much bigger request, is reviewed harder,
+and on iOS the user is asked again later whether they meant it. Do not request
+it for a feature that works while the app is open.
 
-### One-time position
+## One position
 
-```javascript
-if (Ti.Geolocation.locationServicesEnabled) {
+```js
+function locate() {
   Ti.Geolocation.getCurrentPosition((e) => {
-    if (e.error) {
-      Ti.API.error(`Error: ${e.error}`);
-    } else {
-      const coords = e.coords;
-      // { latitude, longitude, altitude, accuracy, heading, speed, timestamp }
+    if (!e.success) {
+      Ti.API.error(`location failed: ${e.error}`);
+      return;
     }
+    const { latitude, longitude, accuracy } = e.coords;
+    Ti.API.info(`${latitude}, ${longitude} +/- ${accuracy}m`);
   });
 }
 ```
 
-### Continuous monitoring
+`accuracy` on the result is a radius in metres, and it is the number that
+decides whether a fix is usable. A first fix indoors can be several hundred
+metres wide; treat anything above your tolerance as "not yet" rather than as an
+answer.
 
-```javascript
-Ti.Geolocation.addEventListener('location', (e) => {
-  if (e.error) {
-    Ti.API.error(`Error: ${e.error}`);
-  } else {
-    Ti.API.info(`${e.coords.latitude}, ${e.coords.longitude}`);
-  }
-});
-```
-
-### Lifecycle management (critical for battery)
-
-Android Activity events:
-```javascript
-let locationAdded = false;
-const handleLocation = (e) => {
-  if (!e.error) {
-    Ti.API.info(e.coords);
-  }
-};
+## Tracking
 
-function addHandler() {
-  if (!locationAdded) {
-    Ti.Geolocation.addEventListener('location', handleLocation);
-    locationAdded = true;
-  }
-}
+```js
+Ti.Geolocation.accuracy = Ti.Geolocation.ACCURACY_HIGH;
+Ti.Geolocation.distanceFilter = 10;
 
-function removeHandler() {
-  if (locationAdded) {
-    Ti.Geolocation.removeEventListener('location', handleLocation);
-    locationAdded = false;
+function onLocation(e) {
+  if (!e.success) {
+    return;
   }
+  Ti.API.info(`moved to ${e.coords.latitude}, ${e.coords.longitude}`);
 }
 
-// Add listeners
-addHandler();
-
-const activity = Ti.Android.currentActivity;
-activity.addEventListener('destroy', removeHandler);
-activity.addEventListener('pause', removeHandler); // Stop when in background
-activity.addEventListener('resume', addHandler); // Resume when foreground
+Ti.Geolocation.addEventListener('location', onLocation);
 ```
 
-### Compass/heading
+`distanceFilter` is metres of movement before another event, and it is the
+single most effective thing you can set: without it you get an event per fix,
+which is a battery complaint waiting to happen.
 
-```javascript
-// One-time heading
-Ti.Geolocation.getCurrentHeading((e) => {
-  Ti.API.info(e.heading.magneticHeading); // degrees from magnetic north
-  Ti.API.info(e.heading.trueHeading); // degrees from true north
-});
+**Remove the listener when the screen goes away.** Location updates continue
+while a listener is attached, whether or not anything is looking at them.
 
-// Continuous heading monitoring
-Ti.Geolocation.addEventListener('heading', (e) => {
-  if (!e.error) {
-    Ti.API.info(`Heading: ${e.heading.magneticHeading}`);
-  }
+```js
+win.addEventListener('close', () => {
+  Ti.Geolocation.removeEventListener('location', onLocation);
 });
 ```
 
-The heading event object includes:
-- `heading.magneticHeading` - degrees relative to magnetic north
-- `heading.trueHeading` - degrees relative to true north (requires location)
-- `heading.accuracy` - deviation in degrees (lower is better)
-- `heading.x`, `heading.y`, `heading.z` - raw magnetometer data (microteslas)
+Set `accuracy` to the loosest value that works. `ACCURACY_HIGH` powers the GPS
+radio; a "which city" feature does not need it.
 
-## Geocoding
+## Addresses
 
-### Forward geocoding (address → coordinates)
+`reverseGeocoder` turns coordinates into an address and `forwardGeocoder` does
+the reverse. Both are network calls against a platform service, so they fail
+offline and are rate limited:
 
-```javascript
-Ti.Geolocation.forwardGeocoder('440 Bernardo Ave Mountain View CA', (e) => {
-  if (e.success) {
-    Ti.API.info(`Lat: ${e.latitude}, Lon: ${e.longitude}`);
+```js
+Ti.Geolocation.reverseGeocoder(latitude, longitude, (e) => {
+  if (e.success && e.places.length) {
+    Ti.API.info(e.places[0].address);
   }
 });
 ```
 
-With error handling:
-```javascript
-Ti.Geolocation.forwardGeocoder('1600 Amphitheatre Pkwy, Mountain View, CA', (e) => {
-  if (!e.success || e.error) {
-    Ti.API.error(`Geocoding failed: ${e.error}`);
-    return;
-  }
-  Ti.API.info(`Lat: ${e.latitude}, Lng: ${e.longitude}`);
-});
-```
-
-### Reverse geocoding (coordinates → places)
-
-```javascript
-Ti.Geolocation.reverseGeocoder(37.389569, -122.050212, (e) => {
-  if (e.success) {
-    e.places.forEach((place) => {
-      Ti.API.info(place.address); // Full address
-      Ti.API.info(place.city); // City name
-      Ti.API.info(place.country); // Country
-      Ti.API.info(place.zipcode); // Postal code
-    });
-  }
-});
-```
-
-## 2. Native maps (platform-specific details)
-
-Due to the complexity of modern native maps, refer to the detailed guides:
-
-- Google Maps v2 for Android: `google-maps-v2.md`
-- iOS Map Kit: `ios-map-kit.md`
-
-## Common map patterns
-
-### Add annotation after map creation
+## Maps
 
-```javascript
-mapview.addAnnotation(annotation);
-```
-
-### Remove annotation
-
-```javascript
-mapview.removeAnnotation(annotation);
-```
-
-### Remove all annotations
-
-```javascript
-mapview.removeAllAnnotations();
-```
+Maps are **not** in the core SDK. `ti.map` is a module, maintained by TiDev,
+and it wraps Google Maps on Android and MapKit on iOS.
 
-### Select annotation programmatically
-
-```javascript
-mapview.selectAnnotation(annotation);
 ```
-
-### Deselect annotation
-
-```javascript
-mapview.deselectAnnotation(annotation);
+<modules>
+  <module platform="android">ti.map</module>
+  <module platform="iphone">ti.map</module>
+</modules>
 ```
 
-### Set region with animation
+```js
+const Map = require('ti.map');
 
-```javascript
-mapview.setLocation({
-  latitude: 37.389569,
-  longitude: -122.050212,
-  animate: true
-});
-
-// Or for region
-mapview.setRegion({
-  latitude: 37.389569,
-  longitude: -122.050212,
-  latitudeDelta: 0.05,
-  longitudeDelta: 0.05,
-  animate: true
+const view = Map.createView({
+  mapType: Map.NORMAL_TYPE,
+  region: { latitude: 51.5, longitude: -0.12, latitudeDelta: 0.05, longitudeDelta: 0.05 },
+  annotations: [
+    Map.createAnnotation({ latitude: 51.5, longitude: -0.12, title: 'Here' })
+  ]
 });
+win.add(view);
 ```
 
-### Zoom to annotations
+Android additionally needs a Google Maps API key in `tiapp.xml`, and a build
+without one shows an empty grid rather than an error. If your map is blank grey
+squares, that is the reason.
 
-```javascript
-mapview.showAnnotations([annotation1, annotation2], true); // true = animate
-```
+See [using modules](https://titaniumsdk.com/docs/build/modules.md) for installing it, and the module's
+own reference for the full API.
+
+![A map centred on the Civic Center district of San Francisco with three annotations. The City Hall pin is selected, drawn larger than the others and labelled with its title and subtitle; the Asian Art Museum and Main Library pins sit nearby at their normal size.](https://titaniumsdk.com/docs/guides/map-callout-ios.png)
 
-### Best practices
+## Next
 
-1. Battery life: remove location listeners when not needed. Use `distanceFilter` to reduce updates.
-2. Accuracy: use the lowest accuracy that meets your needs.
-3. Permissions: check permissions before requesting location. Handle denial gracefully.
-4. Maps on Android: only one map view per application (legacy). Use `ti.map` for multiple views.
-5. API keys: Google Maps API key required for Android (debug and production).
-6. User location: requires location permissions (`NSLocationWhenInUseUsageDescription` for iOS).
+[Notifications](https://titaniumsdk.com/docs/build/notifications.md) covers local and push.