@situm/flutter-wayfinding
Situm Wayfinding for Flutter. Integrate native plug&play navigation experience with floorplans, POIs, routes and turn-by-turn directions in no time. With the power of Situm.
Getting Started
There is a comprehensive tutorial on how to set-up a new application using this plugin on the Situm documentation page.
Below you will find the basic steps to install and configure the plugin on your Flutter project.
Set up your Situm credentials
Create a new config.dart
file with your Situm credentials. You can use the contents of example/config.dart.example
as example.
Follow the Wayfinding guide if you haven't set up a Situm account.
Running the example:
Check the example/README file of this repository to create your first Flutter application using Situm Wayfinding.
Android
The following steps have already been done for you in the example application of this repository, but they are required for a new project:
- Include the Situm repository in your project level
build.gradle
:
allprojects {
repositories {
...
maven { url "https://repo.situm.es/artifactory/libs-release-local" }
}
}
- Make sure AppCompat library is in your
build.gradle
dependencies:
implementation 'androidx.appcompat:appcompat:1.4.1'
- Make sure your
MainActivity
extends the providedFlutterAppCompatActivity
. This class was duplicated fromFlutterFragmentActivity
to add support to androidxAppCompatActivity
, which is not currently supported by Flutter. The WYF plugin must also be registered manually from yourMainActivity
:
...
import io.flutter.embedding.android.FlutterAppCompatActivity
class MainActivity : FlutterAppCompatActivity() {
override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
...
// Register WYF widget:
flutterEngine
.platformViewsController
.registry
.registerViewFactory(
SitumMapFactory.CHANNEL_ID,
SitumMapFactory(flutterEngine.dartExecutor.binaryMessenger, this)
)
}
}
- Review your
styles.xml
file and make sure the application theme extendsTheme.AppCompat.Light.DarkActionBar
. Also remove the action bar in your theme:
<style name="NormalTheme" parent="Theme.AppCompat.Light.DarkActionBar">
...
<item name="windowActionBar">false</item>
<item name="windowNoTitle">true</item>
</style>
- Add your Google Maps API Key to the
AndroidManifest.xml
file:
<meta-data
android:name="com.google.android.geo.API_KEY"
android:value="@string/google_api_key" />
iOS
The following steps have already been done for you in the example application of this project, but we list them as required documentation for a new project:
-
After including the dependecy on your project through Run
pod install
orpod update
to bring the dependencies to your project. -
In order for the wayfinding module to successfully activate positioning you will need to declare the following permissions in your app's
Info.plist
file:
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location is required to find out where you are</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Bluetooth is required to find out where you are</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Location is required to find out where you are</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Location is required to find out where you are</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth is required to find out where you are</string>
Once included the app will ask the user for the appropriate permissions.
How does this plugin work?
This plugin uses Platform Views for both Android
and iOS.
WYF's PlatformView
implementation ensures that only one instance of WYF can be loaded at any time.
This is great for performance because the WYF load()
is an expensive operation. Once WYF is loaded,
it will not be loaded again and instead it will display the active module.
As a consequence, there can only be one SitumMapView
widget alive at a time.
This doesn't mean that you can only implement one SitumMapView
widget in your app. It just means
that only one of them can be alive at the same time: ensure that dispose()
is called over any
SitumMapView
before initializing another one.
Navigator
Take care to keep your navigation stack clean. The following sequence will crash your application:
- State A: app displays page A containing WYF.
- Navigate to page B using
Navigator.push(routeToB)
. - Navigate again to page A:
Navigator.push(routeToA)
. - Crashes:
the view returned from PlatformView#getView() was already added to a parent view
.
To solve it:
- Fix the previous sequence calling
Navigator.pop()
instead ofNavigator.push(routeToA)
. - Or ensure that
dispose()
is called over A, for example replacingpush
withNavigator.pushReplacementNamed()
.
Versioning
Please refer to CHANGELOG.md for a list of notable changes for each version of the plugin.
You can also see the tags on this repository.
Submitting contributions
You will need to sign a Contributor License Agreement (CLA) before making a submission. Learn more here.
License
This project is licensed under the MIT - see the LICENSE file for further details.
More information
More info is available at our Developers Page.
Support information
For any question or bug report, please send an email to support@situm.com