Fully featured and ready to use UIView to add Mapwize Indoor Maps and Navigation in your iOS app.
And it's open-source !
For documentation about Mapwize SDK objects like MWZVenue, MWZPlace, MWZOptions... Please refer to the Mapwize SDK documentation on docs.mapwize.io.
The Mapwize UI view comes with the following components:
- Mapwize SDK integration
- Floor controller
- Follow user button
- Search module
- Direction module
- Place selection
- Universes button
- Languages button
MapwizeUI is compatible with MapwizeForMapbox 3.0.0 and above. The library won't work with lower version.
Add the MapwizeUI library to your Podfile
pod 'MapwizeUI', '~> 2.0'
Then run a pod install
All dependencies will be installed (MapwizeUI, MapwizeForMapbox, Mapbox and IndoorLocation)
- Clone the Github repository
- Copy the MapwizeUI project into your app project
You'll need a Mapwize API key to load the map and allow API requests. Simply add MWZApiKey with the key in your info.plist.
To get your own Mapwize API key, sign up for a free account at mapwize.io. Then within the Mapwize Studio, navigate to "API Keys" on the side menu.
To run Mapbox on your device, you will need to add the following elements in your info.plist file:
- MGLMapboxAccessToken -> pk.mapwize
- MGLMapboxMetricsEnabledSettingShownInApp -> YES
The first one enables Mapbox to load the Mapwize style, while the second guarantees we provide the required information for Mapbox. With these settings, a popup is shown to users when they click on the Mapwize logo (bottom left of the map).
The UIView that embeds the MWZMapwizeView must implement MWZMapwizeViewDelegate
with the followings methods :
- (void) mapwizeViewDidLoad:(MWZMapwizeView*) mapwizeView;
- (void) mapwizeView:(MWZMapwizeView*) mapwizeView didTapOnPlaceInformationButton:(MWZPlace*) place;
- (void) mapwizeView:(MWZMapwizeView*) mapwizeView didTapOnPlaceListInformationButton:(MWZPlaceList*) placeList; --> why not (id<MWZObject>) mapwizeObject
- (void) mapwizeViewDidTapOnFollowWithoutLocation:(MWZMapwizeView*) mapwizeView;
- (void) mapwizeViewDidTapOnMenu:(MWZMapwizeView*) mapwizeView;
- (BOOL) mapwizeView:(MWZMapwizeView*) mapwizeView shouldShowInformationButtonFor:(id<MWZObject>) mapwizeObject;
MWZMapwizeView can be instantiated with the constructor :
- (instancetype) initWithFrame:(CGRect)frame
mapwizeOptions:(MWZUIOptions*) options
uiSettings:(MWZMapwizeViewUISettings*) uiSettings;
- (instancetype) initWithFrame:(CGRect)frame
mapwizeConfiguration:(MWZMapwizeConfiguration*) mapwizeConfiguration
mapwizeOptions:(MWZUIOptions*) options
uiSettings:(MWZMapwizeViewUISettings*) uiSettings;
MWZMapwizeViewUISettings contains the following attribute
@property (nonatomic, retain) UIColor* mainColor;
@property (nonatomic, assign) BOOL menuButtonIsHidden;
@property (nonatomic, assign) BOOL followUserButtonIsHidden;
Once the (void) mapwizeViewDidLoad:(MWZMapwizeView*) mapwizeView
is called, you can retrieved the MWZMapView using mapwizeView.mapView
@property (nonatomic) MWZMapView* mapView;
MWZOptions* opts = [[MWZOptions alloc] init];
MWZUISettings* settings = [[MWZUISettings alloc] init];
self.mapwizeView = [[MWZMapwizeView alloc] initWithFrame:self.view.frame
mapwizeOptions:opts
uiSettings:settings];
self.mapwizeView.delegate = self;
[self.view addSubview:self.mapwizeView];
To have the map centered on a venue at start up:
MWZOptions* opts = [[MWZOptions alloc] init];
opts.centerOnVenueId = @"YOUR_VENUE_ID";
MWZUISettings* settings = [[MWZUISettings alloc] init];
self.mapwizeView = [[MWZMapwizeView alloc] initWithFrame:self.view.frame
mapwizeOptions:opts
uiSettings:settings];
To have the map centered on a place with the place selected:
MWZOptions* opts = [[MWZOptions alloc] init];
opts.centerOnPlaceId = @"YOUR_PLACE_ID";
MWZUISettings* settings = [[MWZUISettings alloc] init];
self.mapwizeView = [[MWZMapwizeView alloc] initWithFrame:self.view.frame
mapwizeOptions:opts
uiSettings:settings];
The following parameters are available for map initialization:
centerOnVenueId
to center on a venue at start.centerOnPlaceId
to center on a place at start.floor
to set the default floor when entering a venue. Floors are Double and can be decimal values. This is ignored when using centerOnPlace.language
to set the default language for venues. It is a string with the 2 letter code for the language. Example: "fr" or "en".universeId
to set the default universe for the displayed venue. If using centerOnPlace, this needs to be an universe the place is in.restrictContentToVenueId
to show only the related venue on the map.restrictContentToVenueIds
to show only the specified venues on the map.restrictContentToOrganizationId
to show only the venues of that organization on the map.
Friendly method to add new access to the map and refresh the UI
- (void) grantAccess:(NSString*) accessKey success:(void (^)(void)) success failure:(void (^)(NSError* error)) failure;
Setup the UI to display information about the selected place
Promote the place and add a marker on it
- (void) selectPlace:(MWZPlace*) place centerOn:(BOOL) centerOn;
Setup the UI to display information about the selected placelist
Add markers on places contained in the placelist and promote them
- (void) selectPlaceList:(MWZPlaceList*) placeList;
Hide the UI component, remove markers and unpromote place if needed
- (void) unselectContent:(BOOL) closeInfo;
Display a direction object and show the direction UI already configured
- (void) setDirection:(MWZDirection*) direction
from:(id<MWZDirectionPoint>) from
to:(id<MWZDirectionPoint>) to
directionMode:(MWZDirectionMode*) directionMode
When users select a Place or a PlaceList, either by clicking on the map or using the search engine, you might want to give the possibility to the user to open a page of your app about it. Think about shops or exhibitors for example for which your app probably has a page with all the details about.
The proposed solution is to display an "information" button on the bottom view in the Mapwize View.
You can use the delegate method shouldShowInformationButtonFor
to say if the button should be displayed or not. Return true to display the button for the given Mapwize object.
- (BOOL) mapwizeView:(MWZMapwizeView*) mapwizeView shouldShowInformationButtonFor:(id<MWZObject>) mapwizeObject;
Example to display the information button only for Places and not for PlaceLists:
- (BOOL) mapwizeView:(MWZMapwizeView *)mapwizeView shouldShowInformationButtonFor:(id<MWZObject>)mapwizeObject {
if ([mapwizeObject isKindOfClass:MWZPlace.class]) {
return YES;
}
return NO;
}
The same kind of methods are available to display or hide the floor controller depends of the floors list and to listen universe change event :
- (BOOL) mapwizeView:(MWZMapwizeView*) mapwizeView shouldShowFloorControllerFor:(NSArray<MWZFloor*>*) floors;
- (void) mapwizeUniverseHasChanged:(MWZUniverse*)universe; __attribute__((deprecated("Use MWZMapViewDelegate instead")));
When the information button is clicked, the delegate call one of the following methods with the selected Mapwize object.
- (void) mapwizeView:(MWZMapwizeView*) mapwizeView didTapOnPlaceInformationButton:(MWZPlace*) place;
- (void) mapwizeView:(MWZMapwizeView*) mapwizeView didTapOnPlaceListInformationButton:(MWZPlaceList*) placeList;
You can change the color of the colored UI view by using the UISettings.mainColor attribute.
The view contains some strings that you may want to translate or change.
You can override them in your strings.xml
file and add other Localizable.strings file in order to support different languages
"Direction" = "Direction";
"Information" = "Information";
"Search a venue..." = "Search a venue...";
"Entering in %@..." = "Entering in %@...";
"Search in %@..." = "Search in %@...";
"Destination" = "Destination";
"Starting point" = "Starting point";
"Current location" = "Current location";
"No results" = "No results";
"Floor %@" = "Floor %@";
"Universes" = "Universes";
"Choose an universe to display it on the map" = "Choose a universe to display it on the map";
"Languages" = "Languages";
"Choose your preferred language" = "Choose your preferred language";
"Cancel" = "Cancel";
"Direction not found" = "Direction not found"
"Search error" = "Search went wrong"
"Search" = "Search"
Be careful with strings containing placeholders. Please ensure that the exact placeholders are kept! For example, if you replace "Floor %@" with "My floor" without placeholder, your application will crash.
A demo application is available in this repository to quickly test the UI. The only thing you need to get started is a Mapwize api key. You can get your key by signing up for a free account at mapwize.io.
Once you have your API key, add it to the info.plist with the key MWZMapwizeApiKey
To test the UI further, go to ViewController and change some options or add some code in it.
Mapwize SDK and Mapwize UI do not have analytics trackers built in. This means that Mapwize does not know how maps are used in your applications, which we believe is a good thing for privacy. This also means that Mapwize is not able to provide you with analytics metrics and that, if you want any, you will have to intrument your code with your own analytics tracker.
Events and callbacks from MWZUIViewDelegate
can be used to detect changes in the interface and trigger tracking events. We believe using the following events would make sense:
venueDidEnter
venueDidExit
floorDidChange
universeDidChange
languageDidChange
didSelectPlace
didSelectPlacelist
didStartDirectionInVenue