Getting Started
Getting started with MapsGL is quick and easy and requires that you have an active Xweather Flex subscription (opens in a new tab).
Supported Mapping Libraries
MapsGL SDK for Apple Platforms current supports integration with the following third-party mapping libraries:
Library + Version | Controller | Adapter Library |
---|---|---|
Mapbox Maps (opens in a new tab), v10.0.0+ | MapboxMapController | MapsGLMapbox |
Mapbox Maps (opens in a new tab), v10.x.x | Mapbox10MapController | MapsGLMapbox10 |
Installing
Follow the series of steps outlined below for your desired method to get started using the Xweather MapsGL SDK for Apple Platforms:
Install using Swift Package Manager
Create an Xweather account
Sign up for an Xweather Flex subscription (opens in a new tab) and setup your access keys as described in our Xweather Weather API's getting started guide (opens in a new tab). We offer a free developer account (opens in a new tab) for you to give our weather API a test drive.
Add the MapsGL SPM Package
In your iOS app Xcode project or workspace:
- Run File menu ❯ Add Package Dependencies….
Or alternatively, navigate to your project settings' Package Dependencies section. - In the top-right “Search or Enter Package URL” field, type
https://github.com/vaisala-xweather/mapsgl-apple-sdk
.
Note: The mapsgl-apple-sdk (opens in a new tab) GitHub repo contains stable releases of MapsGL for Apple Platforms, so it is safe to set the “Dependency Rule” to “Branch: master” in order to use the latest release. - Click Add Package in the bottom-right.
- In the “Choose Package Products for mapsgl-apple-sdk” dialog, ensure your app target is selected under “Add to Target”, and click Add Package.
The MapsGL package will be added to your project, along with MapboxMaps and related packages (under Package Dependencies in the Project Navigator on the left).
A MapsGL static library will be added to your app target's “Frameworks, Libraries, and Embedded Content” section, and associated dynamic binary xcframeworks for MapsGL and Mapbox will be automatically added to your built app's frameworks by Xcode's build system.
Set up a map view
Set up an interactive map instance using a Mapbox according to the Mapbox Maps SDK for iOS Installation instructions (part 3) (opens in a new tab) if your application does not have one already.
Set up MapsGL with your map
Set up your Xweather account access keys (opens in a new tab) for the SDK, create a MapsGL MapboxMapController
instance, and add a weather layer to the map. Use import MapsGLMaps
and import MapsGLMapbox
to import the primary MapsGL library and the MapsGL-Mapbox adapter.
See below for sample code to get started quickly using MapsGL with Mapbox.
You can use the following Swift sample code to get started quickly using MapsGL with Mapbox. Be sure to update the code to use your Xweather account access keys and Mapbox public access token instead.
import SwiftUI
import MapboxMaps
import MapsGLMaps
import MapsGLMapbox // Needed only if you are using SPM
//import MapsGL // Needed only if you are using CocoaPods
import Combine
let xweatherClientID = "FILL_IN_WITH_YOUR_CLIENT_ID"
let xweatherClientSecret = "FILL_IN_WITH_YOUR_CLIENT_SECRET"
let mapboxAccessToken = "FILL_IN_WITH_YOUR_MAPBOX_PUBLIC_ACCESS_TOKEN"
struct MyMapView : View
{
class Coordinator
{
/// MapsGL's controller that manages adding/removing MapsGL weather layers
/// to/from the `MapboxMaps.MapView`.
var mapController: MapboxMapController!
/// Holds Combine subscriptions to MapsGL events and other Combine subscriptions.
var eventSubscriptions: Set<AnyCancellable> = []
}
private let coordinator = Coordinator()
var body: some View {
MapReader { proxy in
Map(initialViewport: .camera(
center: CLLocationCoordinate2D(latitude: 50.0, longitude: 10.0),
zoom: 2.5
))
.mapStyle(.dark)
.ignoresSafeArea()
.onAppear {
guard let map = proxy.map else { return }
try! map.setProjection(.init(name: .mercator)) // Set 2D map projection
// Set up the MapsGL `MapboxMapController`, which will handle
// adding/removing MapsGL weather layers to the `MapboxMaps.MapView`.
let mapController = MapboxMapController(
map: map,
window: UIWindow?.none,
account: XweatherAccount(id: xweatherClientID, secret: xweatherClientSecret)
)
coordinator.mapController = mapController
// Once the map has completed initial load…
mapController.subscribe(to: MapEvents.Load.self) { _ in
// Add the wind particles layer.
do {
var layerConfig = WeatherService.WindParticles(service: mapController.service)
layerConfig.layer.paint.particle.density = .extreme
try mapController.addWeatherLayer(config: layerConfig)
} catch {
NSLog("Failed to add weather layer: \(error)")
}
}
.store(in: &coordinator.eventSubscriptions)
}
}
}
private static let _staticInit: Void = {
MapboxOptions.accessToken = mapboxAccessToken
}()
private let _staticInit: Void = Self._staticInit
}
#Preview {
MyMapView()
}
A full example of how to set up MapsGL with Mapbox with SwiftUI can be found in the mapsgl-apple-sdk repository's Demo directory (opens in a new tab), particularly in this view: https://github.com/vaisala-xweather/mapsgl-apple-sdk/blob/master/Demo/SwiftUI/ContentView.swift (opens in a new tab)