mapbox / ios-sdk-examples

Live example code for the Mapbox iOS SDK

Mapbox iOS SDK Examples

A live Xcode project/app that provides public examples for the Mapbox Maps SDK for iOS.

How to receive help

We are not able to answer support questions in this repository — it is intended to show examples of what is possible with the Mapbox Maps SDK for iOS. If you have questions about how to use the Mapbox Maps SDK for iOS, please see our excellent documentation or ask the community at Stack Overflow.

Other helpful links

• Mapbox Maps SDK for iOS API documentation
• First steps with the Mapbox Maps SDK for iOS

Getting started

1. Run bundle install to install build/packaging dependencies.
2. Follow the instructions for installing the Maps SDK via CocoaPods in the installation guide.
3. Run bundle exec pod install to download and integrate dependencies using CocoaPods.
4. Create the mapbox_access_token file in the base directory and insert your Mapbox access token.
5. Open Examples.xcworkspace.

Adding a new example

See the instructions in Examples.h for how to add new examples.

ios-sdk-examples's Issues

Add view annotation z-ordering example

An example of mapbox/mapbox-gl-native#5287:

For example, if you want a particular view-backed annotation other than the selected annotation to appear in front of any other view-backed annotations, your MGLMapViewDelegate can hold a strong reference to the view it provides for that annotation and implement this method:

- (void)mapViewDidFinishRenderingFrame:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered {
    // Make way for Its Preeminence!
    [self.preeminentAnnotationView.superview bringSubviewToFront:self.preeminentAnnotationView];
}

This example would also need to note our support for other types of annotations, whatever that is when this is finished/published.

/cc @1ec5

Support Swift 3.2/4.0

It’s time to move to Swift 3.2/4.0. It would be nice to avoid duplicating files for different versions, but how possible that will be remains to be seen.

• Compatibility notes

/cc @jmkiley @captainbarbosa

Feature querying example

An example that uses feature querying. Punted from the initial v3.3.0 push in #23.

/cc @1ec5

How to add different type of icon in the Geo map Cluster ?

Hi All, I have implemented Map box cluster in my GeoMap. The clustering part is working charm but pointed location icon like static according my requirement that pointed location should be different type of icons see below image ( red colour and yellow colour icons ) seems like i will add different type of icons

- (void)mapView:(MGLMapView *)mapView didFinishLoadingStyle:(MGLStyle *)style { NSURL *url = [NSURL fileURLWithPath:[[NSBundle mainBundle] pathForResource:@"ports" ofType:@"geojson"]]; self.source = [[MGLShapeSource alloc] initWithIdentifier:@"clusteredPorts" URL:url options:@{ MGLShapeSourceOptionClustered: @(YES), MGLShapeSourceOptionClusterRadius: @(self.icon.size.width+50) }]; [style addSource:self.source]; // Use a template image so that we can tint it with the iconColorruntime styling property. **[style setImage:[self.icon imageWithRenderingMode:UIImageRenderingModeAlwaysTemplate] forName:@"icon"];** // Show unclustered features as icons. Thecluster` attribute is built into clustering-enabled source features.
self.ports = [[MGLSymbolStyleLayer alloc] initWithIdentifier:@"ports" source:self.source];
self.ports .iconImageName = [MGLStyleValue valueWithRawValue:@"icon"];
self.ports .iconColor = [MGLStyleValue valueWithRawValue:[[UIColor redColor] colorWithAlphaComponent:0.9]];
self.ports.predicate = [NSPredicate predicateWithFormat:@"%K != YES", @"cluster"];

self.ports.predicate = [NSPredicate predicateWithFormat:@"%K != created", @"icon"];
NSLog(@"Predicate : %@",self.ports.predicate);
[style addLayer:self.ports ];
// Color clustered features based on clustered point counts.
NSDictionary *stops = @{ @20: [MGLStyleValue valueWithRawValue:[UIColor lightGrayColor]],
@50: [MGLStyleValue valueWithRawValue:[UIColor orangeColor]],
@100: [MGLStyleValue valueWithRawValue:[UIColor redColor]],
@200: [MGLStyleValue valueWithRawValue:[UIColor purpleColor]] };
// Show clustered features as circles. The point_count attribute is built into clustering-enabled source features.
MGLCircleStyleLayer *circlesLayer = [[MGLCircleStyleLayer alloc] initWithIdentifier:@"clusteredPorts" source:self.source];
circlesLayer.circleRadius = [MGLStyleValue valueWithRawValue:@(self.icon.size.width+2 / 2)];
circlesLayer.circleOpacity = [MGLStyleValue valueWithRawValue:@0.75];
circlesLayer.circleStrokeColor = [MGLStyleValue valueWithRawValue:[[UIColor whiteColor] colorWithAlphaComponent:0.75]];
circlesLayer.circleStrokeWidth = [MGLStyleValue valueWithRawValue:@2];
circlesLayer.circleColor = [MGLSourceStyleFunction
functionWithInterpolationMode:MGLInterpolationModeInterval
stops:stops
attributeName:@"point_count"
options:nil];
circlesLayer.predicate = [NSPredicate predicateWithFormat:@"%K == YES", @"cluster"];
[style addLayer:circlesLayer];
// Label cluster circles with a layer of text indicating feature count. Per text token convention, wrap the attribute in {}.
MGLSymbolStyleLayer *numbersLayer = [[MGLSymbolStyleLayer alloc] initWithIdentifier:@"clusteredPortsNumbers" source:self.source];
numbersLayer.textColor = [MGLStyleValue valueWithRawValue:[UIColor whiteColor]];
numbersLayer.textFontSize = [MGLStyleValue valueWithRawValue:@(self.icon.size.width+3 / 2)];
numbersLayer.iconAllowsOverlap = [MGLStyleValue valueWithRawValue:@(YES)];
numbersLayer.text = [MGLStyleValue valueWithRawValue:@"{point_count}"];
numbersLayer.predicate = [NSPredicate predicateWithFormat:@"%K == YES", @"cluster"];
[style addLayer:numbersLayer];
// Add a tap gesture for zooming in to clusters or showing popups on individual features.
[self.view addGestureRecognizer:[[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleTap:)]];
}
`

User location tracking example

https://www.mapbox.com/ios-sdk/#location_services explains how to enable the user dot, but we need an example about this common developer scenario. It show not only how to display the user dot but also enable user location tracking.

/cc @friedbunny @tmcw

Use built-in JSON serialization in GeoJSON line example

We’re adding JSON serialization (mapbox/mapbox-gl-native#3630 (comment)) for MGLShape in mapbox/mapbox-gl-native#7377. This means we can ditch the manual serialization in the existing GeoJSON line example, making it much cleaner and easier to follow.

/cc @1ec5

Geocoding example

There should be an example in which the user can long-press the map to drop a pin and see its address, geocoded using the Geocoding API via MapboxGeocoder.swift.

/ref #6
/cc @friedbunny @tmcw

Custom user dot

Let’s add an example of customizing the user location annotation view, somewhere along the lines of the existing annotation view example, since it may not be entirely obvious from the MGLMapView API how to do that.

/cc @friedbunny @frederoni

flyTo example

We have a setCamera example but no flyToCamera example.

/cc @friedbunny

User tracking mode example

Until we have a set-it-and-forget-it MGLUserTrackingBarButtonItem (mapbox/mapbox-gl-native#1093), we need an example for a button that cycles among the user tracking modes.

/cc @friedbunny

Custom annotation model example

mapbox/mapbox-gl-native#3423 (comment) is asking for an example of adding custom properties to an annotation model object. You have to subclass MGLPointAnnotation or write your own implementation of MGLAnnotation. Here’s a sample example: mapbox/mapbox-gl-native#3423 (comment).

/cc @friedbunny

Add multiple annotations example

I've been getting this question frequently - might be a good idea to include this.

Drag and drop example

We’ve blogged about how to drag’n’drop in iOS 11 and the next step is to create a permanent example. Changes from the blog’d code are likely to include swapping the static API for a map snapshot, adapted to show attribution.

Potential upstream changes are tracked in mapbox/mapbox-gl-native#9350.

/cc @jmkiley @captainbarbosa @1ec5

SceneKit annotation view

Let’s add an example of using SceneKit content in an annotation view. For example, we could use an SCNView as the user location annotation view to turn the user puck into a 3D car. We could also do the same in the iOS navigation SDK’s example application as well.

This blog post shows how to sync an SCNView with an MGLMapView, although it doesn’t associate the view with an annotation. This Apple sample project provides some inspiration for using a car model to represent the user. Freely licensed 3D car models in COLLADA format aren’t easy to find, but apparently the Unity Asset Store has models in FBX format that can be converted to COLLADA using Maya or another 3D application.

/ref mapbox/mapbox-navigation-ios#402 (comment)
/cc @mapbox/ios @mapbox/navigation-ios @david-rhodes @kronick

Marker example that uses multiple images

Further explain the reuse pattern - “How do I use more than one image?” is a common question.

Discussion: 3D Objects above earth

Hi, We're investigating whether it's possible to place upright view's that are part of the map over the earth as if it was an overlay that was positioned to the earth's normal.

The goal would be to have our own views that can be placed on the map, having the map tilted to a pitch of 90 degrees, buildings turned on so that you can see the height of the buildings and terrain, and a view that sizes with it's size and distance from the latitude and longitude that it's fixed at.

This is very similar to an overlay implementation except, that the view could be adjusted to sitting
upright on the map.

Is this accomplishable?

Target tracking mode example

How to use target tracking mode to keep a destination and the user’s current location on screen at the same time.

/cc @1ec5

Animated polyline annotation

We should have an example of appending or otherwise mutating a polyline annotation on the fly, using -[MGLPolyline appendCoordinates:count:]. This would accomplish the same visual effect as “Animated line” but demonstrate an easier and more performant approach than what the runtime styling API is currently capable of.

/cc @jmkiley @incanus

Symbol layer (GeoJSON) point clustering

Per mapbox/mapbox-gl-native#320 (comment), we should have a good example of symbol layer clustering.

What I'd like to see:

• Ability to toggle all clusters on & off
• Ability to tap on a cluster to have it zoom in to the extent of the clustered points (revealing more points)
• Ability to show a callout when tapping a cluster point
  • This might require some sort of interaction between a GL-backed symbol layer and an annotation view layer

Basically, let's:

• Show what you can do now with our clustering capabilities
• Get an idea of how important mapbox/mapbox-gl-native#6181 is as a way to make this better.

Download Mapbox.framework via a package manager

Carthage, perhaps.

Add snapshotter example

Once mapbox/mapbox-gl-native#9920 officially lands

Lint examples

We should use SwiftLint to enforce coding conventions automatically, since we tend to care more about code style in our examples than in other code we write.

/cc @friedbunny

Simple offline pack example

The site should have a simple offline pack example that downloads a single pack and shepherds it to completion, based on the examples in this help document. It would likely use an MGLOfflinePackAdditionCompletionHandler and KVO on a specific MGLOfflinePack object’s progress property, but it wouldn’t need to register for notifications about packs in general.

/cc @friedbunny

Query visible features at point example

I think it would be useful to show how (-visibleFeaturesAtPoint: ) works in action - perhaps its time for an example?

Update for v9 styles

Besides refreshing the screenshots, we should:

• Deal with versioning
  • MGLStyleCurrentVersion or hard-code the latest version?
• Tielt — make sure it smoothes out with the new caching
• Move ‘simple map view’ away from NYC
• Replace Emerald with Outdoors in Custom style example
• Add appropriate tint for each style

Refs mapbox/mapbox-gl-native#4759

/cc @1ec5

Replace UIAlertView with UIAlertController

UIAlertView was deprecated in iOS 9, so ideally this should be replaced with a UIAlertController with a preferredStyle of alert.

UIAlertView is used in the callout delegate usage example. Both the Objective-C and Swift examples will need to be updated in this case.

Examples' page formatting on mobile

You can only see Swift examples when viewing the iOS Examples page on Mobile in Safari. The examples list is not present in portrait mode.

Offline pack manager example

A common use case for offline packs is a download manager–style table view controller. This use case requires some advanced NSNotification or KVO usage, so we should add an example similar to MBXOfflinePacksTableViewController.

/cc @friedbunny

Replace Mapbox iOS SDK with Mapbox Maps SDK

Per mapbox/mapbox-gl-native#10385, the Mapbox iOS SDK is being renamed to the Mapbox Maps SDK for iOS. All documentation references to the Mapbox iOS SDK in this repository will need to be changed to reflect the new name.

Rename heat map to hotspot map

The “heat map” example added in #87 actually displays a hotspot map: mapbox/DEPRECATED-mapbox-gl#27. Heat maps are a separate feature that we’re working on and will want to make a splash about in the not-too-distant future. We should rename the example to avoid confusion.

/cc @jmkiley @friedbunny @captainbarbosa @mourner

Add traffic to existing style

It’s straightforward enough to create a new style based on the Traffic Day or Traffic Night style in Studio, but if a developer wants to offer a toggleable traffic overlay, they need to write a nontrivial (but not excessive) amount of code using the runtime styling API.

The proposed example would show how to add traffic lines based on the Mapbox Traffic v1 source to an existing style using the runtime styling API. It would hard-code colors and line widths, but the developer would be free to adjust them as desired – we could even throw in some #colorLiterals in the Swift version to make the color scheme easier to tweak.

To ensure that the lines sit beneath any labels and shields in the style, we could hard-code a style layer name, put in a <#placeholder#> for that layer name, or have the developer dynamically search for the topmost layer that isn’t a symbol style layer:

for layer in style.layers.reversed() {
    if !(layer is MGLSymbolStyleLayer) {
        style.insertLayer(line, above: layer)
        // …
        break
    }
}

Along these lines, we might want to make it easy for the developer to toggle traffic lines on and off. We could similarly hard-code a list of layer identifiers, or the developer could search for relevant layers dynamically, demonstrating another aspect of the runtime styling API:

var trafficSource = style.sources
    .flatMap { $0 as? MGLVectorSource }
    .filter { $0.URL == URL(string: "mapbox://mapbox.mapbox-traffic-v1") }
    .first

for layer in style.layers {
    if let layer = layer as? MGLForegroundStyleLayer,
        layer.sourceIdentifier == trafficSource.identifier {
        layer.isVisible = showsTraffic
    }
}

/cc @friedbunny @bsudekum @mtirwin

Geofencing example

It would be great to have an example that shows how to visualize geofencing with Mapbox iOS SDK. For example, how to detect and change a map based on whether a user is in a region.

cc @captainbarbosa

Make this project publicly available

There’s been talk of how to do this for quite a while — public ticket: mapbox/mapbox-gl-native#5622

Requirements/steps:

• Should be compatible with pod try for Mapbox-iOS-SDK pod.
• Automate website example content.

Other things?

/cc @mapbox/ios @captainbarbosa @ericrwolfe

Tiptoe around border disputes

We should have an example of restyling certain sets of disputed borders. We can go a step further, using NSLocale.countryCode or CTCarrier.isoCountryCode to erase borders based on the country we detect the user is located in.

This will require iOS SDK v3.4.0 for the runtime styling API.

/cc @friedbunny @pveugen @frederoni

Fix line wrapping on examples

The line wrapping on some of the examples is too constrained, resulting in longer examples that look like this:

cc @friedbunny

Annotation view movement example

A view annotation that is animated along a looping path. Punted from the initial v3.3.0 push in #23.

/cc @pveugen

View syncing example

Even after we implement mapbox/mapbox-gl-native#1784, developers may still need to synchronize native views with the map, for example in cases where the view doesn’t quite behave like a point feature. We should add an example that exercises the geometric conversion methods in MGLMapView.

/cc @friedbunny

Fix Swiftype searching

Image Source Example

It would be great to have an example for how to use imageSource once it lands. It has been a pretty commonly requested feature.

cc @captainbarbosa @friedbunny

Use this repo to support `pod try` for the iOS SDK

Use MGLTileSet/MGLVectorSource instead of external style.json

After the tile set API stabilizes (mapbox/mapbox-gl-native#7360), we should look at converting third_party_vector_style.json for the custom vector source example to a dynamically-created MGLTileSet/MGLVectorSource object (and eliminate the need for an external file).

/cc @ericrwolfe @boundsj @1ec5

Provide Swift 3 examples

Now that Xcode 8 is in beta, we should provide Swift 3 examples or tailor the existing Swift examples to accommodate Swift 3 syntax using #if swift(3). Here are the most obvious changes that’ll affect our examples:

// Note “Center” instead of “CenterCoordinate”
mapView.setCenter(…, animated: …)
MGLMapCamera(lookingAtCenter: …, fromDistance: …, pitch: …, heading: …)

// Note the _ before mapView and “imageFor” instead of “imageForAnnotation”
func mapView(_ mapView: MGLMapView, imageFor annotation: MGLAnnotation) -> MGLAnnotationImage?

// Note the lowercase f
mapView.userTrackingMode = .followWithHeading

/cc @friedbunny @tmcw

More fill pattern example follow-up

@captainbarbosa Follow-up for #94:

1. Rename the Swift view controller to FillPatternExample_Swift so that the Jekyll plugin can regex it to ViewController.
2. Set a matching tint color.
3. Delete the Xcode 9 AppIcon entry that got added.

Add managing memory resources example (with multiple active full screen maps)

It is common for iOS applications to have many view controllers on the nav stack (think about surfing through user profiles in a social networking app where you may keep adding views like cards on a deck as you walk through a social graph).

We should consider adding an example that illustrates some approaches for keeping memory usage (RAM) streamlined in this situation.

Automatically localize to user preferred language

We should have an example that localizes a Mapbox Streets–sourced style on the fly according to the user’s preferred language. It’d be similar to the code added in mapbox/mapbox-gl-native#6819, except that a hard-coded list of layers would be unnecessary because we’d iterate over all the symbol layers.

Requires v3.4.0 for the runtime styling API. mapbox/mapbox-gl-native#7031 would completely obviate this example.

/cc @friedbunny

Datasets API

We should have examples for working with data sets authored in Mapbox Studio, specifically for using the Datasets API to populate a shape source. The example in #69 dealt with a relatively small amount of immutable data that was more appropriate for a bundled GeoJSON file, but a data set–focused example would use a larger data set containing the kind of data that would naturally vary over time.

We don’t have a client library for the Datasets API yet like we do for the Geocoding, Directions, and classic Static APIs. From the code originally pushed to #69, it looks like the developer wouldn’t have to do much with the API to display the data set. So let’s focus on display; something more advanced like modifying or deleting data can wait until we have a proper client library.

/cc @jmkiley @captainbarbosa @friedbunny

Runtime styling annotation substitute examples

If anyone needs to draw something that's geographic-based versus pixel-based, runtime styling is the way to go instead of annotation views.

A good example might be circles of a fixed distance radius around a point. This changes the circle size on zoom in a way that would be inefficient in a view on zoom/viewport change callback.

At a technical level, this would happen with these steps:

1. Determine geographic coordinates of features.
2. Encode them in GeoJSON.
3. Add an MGLGeoJSONSource to the style.
4. Add appropriate MGLStyleLayer object(s) to render the source.

We should probably do multiple examples in increasing complexity, such as with label text or animations.

/cc @boundsj @ericrwolfe

Directions route line example

We need an example for taking an MBRoute from MapboxDirections.swift and transforming it into an MGLPolyline that can be displayed on an MGLMapView. The intricacies of MapboxDirections.swift itself should go in https://www.mapbox.com/api-documentation/#directions .

/cc @bsudekum @friedbunny

Repo/project needs a license

/cc @kathleenlu09 @1ec5 @tmcw

WMS

Port https://www.mapbox.com/mapbox-gl-js/example/wms/ to the iOS SDK. Requires iOS SDK v3.4.0-alpha.1 for the runtime styling API and WMS support.

/cc @friedbunny @tmcw