16 KiB
Integration Guide for PenNav P&P Native Android Libraries in Flutter
Requirements
- The device must be running Android 7.0 or later.
- The minimum supported Android version is 24.
Prerequisites
- Flutter SDK installed.
- Basic knowledge of Flutter and Android development.
- PenNav native Android libraries (
Penguin.aar,PenguinRenderer.aar,PenNavUI.aar) ready. - Mapbox Account: Register for a Mapbox account to obtain an access token for Mapbox services.
Steps
Step 1: Install Mapbox Maps SDK v10.16.6 for Android
To integrate the Mapbox Maps SDK for Android and obtain authorization, follow these steps:
-
Register and Obtain Authorization
- Create a Mapbox Account:
- Visit the Mapbox Sign Up page and register for a free account.
- Get Your Access Token:
- Log in to your Mapbox account and access your dashboard.
- Navigate to the "Access Tokens" section.
- Copy your default access token or create a new token with the required permissions.
- Create a Mapbox Account:
-
Configure Your Access Token
- For detailed instructions on setting up your access token in your Android project, refer to the Mapbox Android Maps Installation guide.
-
Configure your public token
One way to provide your public token to Mapbox SDK is by adding it as an Android string resource.
To add the
<string>entry to yourstrings.xml:<string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">[Your-token-key]</string> -
Add Mapbox Repository
1- Open your
settings.gradle.ktsfile (top-level file) and add the Mapbox Maven repository to thedependencyResolutionManagement.repositoriesblock:dependencyResolutionManagement { repositories { mavenCentral() // Add the Mapbox Maven repository maven { url = uri("https://api.mapbox.com/downloads/v2/releases/maven") credentials { username = "mapbox" // The username field should always be "mapbox" password = project.findProperty("mapbox_access_token") as String? } } } }2- Configure Credentials
Ensure you have a valid Mapbox username and password. You should configure the credentials in your
gradle.propertiesfile, which is typically located in the root of your project or the~/.gradle/directory. Add the following properties to yourgradle.propertiesfile:mapbox_access_token= [Enter-your-token]3- Add Mapbox SDK Dependency
Open your
build.gradle.ktsfile (module-level) and add the Mapbox Maps SDK dependency. You will need to include this in thedependenciesblock:dependencies { implementation("com.mapbox.maps:android:10.16.6") }4- Sync Gradle: Click on "Sync Now" in Android Studio or run
./gradlew syncfrom the command line to update your project with these dependencies.
Step 2: Add Native Libraries to Your Flutter Project
-
Copy Libraries:
- Create a
libsdirectory if it does not already exist:android/app/libs. - Copy your
.aarfiles (Penguin.aar,PenguinRenderer.aar,PenNavUI.aar) into thislibsdirectory.
- Create a
-
Update Gradle Files:
-
In
android/build.gradle: Add the following to theallprojectssection to include thelibsdirectory as a repository:allprojects { repositories { google() mavenCentral() flatDir { dirs 'libs' } } } -
In
android/app/build.gradle:Add the dependencies for your
.aarfiles:dependencies { // Embeding the aar files (Penguin libraires) implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar']) // Pre-request Libraries - Important! implementation 'com.squareup.okhttp3:logging-interceptor:4.9.3' implementation 'com.squareup.retrofit2:retrofit:2.9.0' implementation 'com.squareup.retrofit2:converter-gson:2.9.0' implementation 'com.squareup.retrofit2:adapter-java8:2.4.0' implementation 'com.google.code.gson:gson:2.8.9' implementation 'com.google.android.gms:play-services-location:21.3.0' implementation 'com.squareup.okhttp3:okhttp:4.10.0' implementation 'androidx.test.ext:junit:1.1.5' implementation 'com.android.volley:volley:1.2.1' def room_version = "2.4.0-alpha04" implementation "androidx.room:room-runtime:$room_version" annotationProcessor "androidx.room:room-compiler:$room_version" implementation 'net.zetetic:android-database-sqlcipher:4.5.2' implementation 'com.intuit.ssp:ssp-android:1.1.0' implementation 'com.intuit.sdp:sdp-android:1.1.0' implementation 'com.github.bumptech.glide:glide:4.12.0' annotationProcessor 'com.github.bumptech.glide:compiler:4.12.0' implementation 'com.mapbox.maps:android:10.16.6' // Added before // Add other dependencies if needed } -
Enabling View Binding To enable View Binding in your Android project, follow these steps:
Open your project's build.gradle file.
Inside the android block, add the following buildFeatures configuration:
android { // Other configurations... buildFeatures { viewBinding true } } -
ProGuard Configuration
-
it's crucial to configure ProGuard to ensure that the library's classes and interfaces are not obfuscated or removed during the optimization process. Follow these steps to add the necessary ProGuard rules:
-
Open your ProGuard configuration file (proguard-rules.pro) in your Android project.
-
Add the following lines to the file:
-dontwarn penguin.com.pennav.Model.Navigation.NearLandmark -keep,includedescriptorclasses class net.sqlcipher.** { *; } -keep,includedescriptorclasses interface net.sqlcipher.** { *; } -keep class retrofit2.** { *; } -keep class okhttp3.** { *; } -dontwarn retrofit2.** -keep class com.google.gson.** { *; } -dontwarn com.google.gson.** # Penguin classes -keep class com.peng.pennavmap.models.** { *; } -keep class com.peng.pennavmap.db.** { *; } ```
-
-
Sync Gradle: Click on "Sync Now" in Android Studio or run
./gradlew syncfrom the command line to update your project with these dependencies.
4. add permissions
To ensure the smooth operation of the Plug & Play (P&P) module, a list of permissions must be granted. These permissions allow the P&P module to access certain resources and functions on the device, and are necessary for the P&P module to function properly.
Following is the permissions that must be added to AndroidManifest.xml
<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.BLUETOOTH" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" /> <uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />The request permission the purpose of requesting each one of the outlined in the table below
Permission Why What if dismissed INTERNET To access the internet and connect to remote servers is required in order to access remote servers and provide a seamless and reliable experience for our users. By granting this permission, you'll be able to fully utilize the features and functionality of our app ACCESS_NETWORK_STATE To check the status of the device's network connection is necessary for checking the status of the device's network connection. This helps ensure that our app is able to function properly, even when the network connection is unstable or unavailable. By granting this permission, you'll be able to use our app with confidence, knowing that it will work even under challenging network conditions ACCESS_FINE_LOCATION
ACCESS_COARSE_LOCATION
To access the device's precise location (GPS and network-based) and it used for calculate turn-by-turn directions and show location on map
To access the device's approximate location (network-based)
permissions are essential for providing location-based services and features. By granting these permissions, you'll be able to take full advantage of our app's ability to provide turn-by-turn directions, show your location on a map, and more. We take the privacy of your location data very seriously, and will always handle it with the utmost care and respect BLUETOOTH
BLUETOOTH_ADMIN
BLUETOOTH_CONNECT
BLUETOOTH_SCAN
To access the device's Bluetooth functionality and improve wayfinding inside buildings
To configure the device's Bluetooth settings
To connect to Bluetooth devices
To scan for nearby Bluetooth devices
permissions are needed to access and utilize the device's Bluetooth functionality. This allows our app to connect to Bluetooth devices, configure Bluetooth settings, and scan for nearby devices. you'll be able to more easily find your way around and make the most of our app's indoor navigation capabilities HIGH_SAMPLING_RATE_SENSORS To access high-sampling rate sensors, such as the device's accelerometer and gyroscope, at a higher frequency rate is needed to access high-sampling rate sensors, such as the device's accelerometer and gyroscope, at a higher frequency rate. This is necessary for certain features and functionality of our app, such as tracking motion and providing precise measurements. By granting this permission, you'll be able to fully utilize the capabilities of our app Overall, by granting these permissions, you'll be able to fully take advantage of the features and functionality of our app. We appreciate your trust in our app and will always handle your data with the at most care and respect.
-
Native Android configuration steps
- For detailed instructions on how to configure and initialize the PenNav libraries, please start by checking out the Configuration Steps. It is important to begin here to ensure a proper setup.
Step 3: Create the Flutter Platform View Factory View
2.1 Implement the View Factory
-
Create a new Kotlin or Java file in
android/app/src/main/kotlin/com/yourcompany/yourapp/.- Kotlin (PenguinViewFactory.kt):
class PenguinViewFactory(
private val messenger: BinaryMessenger,
private val mainActivity: MainActivity
) : PlatformViewFactory(StandardMessageCodec.INSTANCE) {
override fun create(context: Context, viewId: Int, args: Any?): PlatformView {
val creationParams = args as Map<String?, Any?>?
return PenguinView(context, viewId, creationParams, messenger,mainActivity)
}
}
- Java (PenguinViewFactory.java):
public class PenguinViewFactory extends PlatformViewFactory {
private final BinaryMessenger messenger;
private final MainActivity mainActivity;
public PenguinViewFactory(BinaryMessenger messenger, MainActivity mainActivity) {
super(StandardMessageCodec.INSTANCE);
this.messenger = messenger;
this.mainActivity = mainActivity;
}
@Override
public PlatformView create(Context context, int viewId, Object args) {
@SuppressWarnings("unchecked")
Map<String, Object> creationParams = (Map<String, Object>) args;
return new PenguinView(context, viewId, creationParams, messenger, mainActivity);
}
}
2.2 Implement the Custom View
-
Create a new Kotlin or Java file in
android/app/src/main/kotlin/com/yourcompany/yourapp/.-
Kotlin (PenguinView.kt):
internal class PenguinView( context: Context, id: Int, creationParams: Map<String?, Any?>?, messenger: BinaryMessenger, activity: MainActivity ) : PlatformView, MethodChannel.MethodCallHandler, PenNavUIDelegate { // Review the sample app for full implemntation ... } -
Java (PenguinView.java):
public class PenguinView implements PlatformView, MethodChannel.MethodCallHandler, PenNavUIDelegate { public PenguinView(Context context , int id , Map<String?, Object?> creationParams , BinaryMessenger messenger , MainActivity activity) { //.... } // Review the sample app for full implemntation ... }
-
2.3 Register the Platform View in MainActivity
-
Update
MainActivityto register the platform view factory.-
Kotlin:
import io.flutter.embedding.android.FlutterActivity import io.flutter.embedding.engine.FlutterEngine class MainActivity : FlutterActivity() { override fun configureFlutterEngine(flutterEngine: FlutterEngine) { super.configureFlutterEngine(flutterEngine) flutterEngine.platformViewsController.registry.registerViewFactory( "penguin_lib", PenguinViewFactory(flutterEngine.dartExecutor.binaryMessenger, this) ) } } -
Java:
import io.flutter.embedding.android.FlutterActivity; import io.flutter.embedding.engine.FlutterEngine; public class MainActivity extends FlutterActivity { @Override public void configureFlutterEngine(FlutterEngine flutterEngine) { super.configureFlutterEngine(flutterEngine); flutterEngine.getPlatformViewsController().getRegistry().registerViewFactory( "penguin_lib", new PenguinViewFactory(flutterEngine.getDartExecutor().getBinaryMessenger(), this) ); } }
-
Step 4: Use the Platform View in Flutter
-
Modify your Dart code to use the custom platform view.
import 'package:flutter/material.dart'; import 'package:flutter/services.dart'; void main() { runApp(MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { const viewType = 'penguin_lib'; final creationParams = <String, dynamic>{}; return Container( child: Platform.isIOS ? UiKitView( // Display the Penguin Map for iOS viewType: viewType, layoutDirection: TextDirection.ltr, creationParams: creationParams, onPlatformViewCreated: onPlatformViewCreated, creationParamsCodec: const StandardMessageCodec(), ) : AndroidView( // Display the Penguin Map for Android viewType: viewType, layoutDirection: TextDirection.ltr, creationParams: creationParams, onPlatformViewCreated: onPlatformViewCreated, creationParamsCodec: const StandardMessageCodec(), ), ); } Future<void> onPlatformViewCreated(int id) async { } }
5. Test Your Integration
-
Build and Run Your App:
- Compile and run your Flutter app on an Android device or emulator.
-
Verify the Custom View:
- Ensure the custom native view is displayed correctly and interacts as expected.