You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

320 lines
9.5 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

[< Back](../readme.md)
# Integration Guide for `PenNav P&P` Native iOS Libraries in Flutter
#### Requirements
- iOS 13.0 or later
- iPadOS 13.0 or later
#### Prerequisites
- Flutter SDK installed.
- Basic knowledge of Flutter and iOS development.
- Penguin native iOS libraries (Penguin.xcframework, PenguinRenderer.xcframework, PenNavUI.xcframework).
- Mapbox Account: Register for a Mapbox account to obtain an access token for Mapbox services.
## Steps
### **Step 1 : Install Mapbox Maps SDK v10.6.4 for iOS**
To install the Mapbox Maps SDK for iOS and get authorization, follow these steps:
#### **1. Register and Get Authorization**
1. **Create a Mapbox Account:**
- Go to [Mapbox's Sign Up page](https://www.mapbox.com/signup/) and create a free account.
2. **Get Your Access Token:**
- After logging in, go to your [Mapbox account dashboard](https://account.mapbox.com/).
- Navigate to the "Access Tokens" section.
- Copy your default access token or create a new token with the desired permissions.
3. **Set Up Your Secret Token (Important)**
- For guidance on configuring your secret token, please refer to the Mapbox installation guide at: [Mapbox iOS Maps Installation](https://docs.mapbox.com/ios/maps/guides/install/).
4. **Configure your public token**
To configure your public access token, follow these steps:
- Open your project's Info.plist file
- Hover over a key and click the plus button
- Type MBXAccessToken into the key field
- Click the value field and paste in your public access token.
<video width="640" height="480" controls>
<source src="https://docs.mapbox.com/ios/assets/medias/MapsInstallPublicToken-eb2f6fbf8715def5ae8eaa35a5b562c4.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>
---
### **Step 2 : Add Native Libraries to Your Flutter Project**
1. **Create the Frameworks Folder:**
- Open Finder and navigate to your Flutter projects `ios` directory.
- Right-click inside the `ios` folder, select **New Folder**, and name the folder **Frameworks**.
2. **Move .xcframework Files:**
- Locate your `.xcframework` files in Finder.
- Select the files, right-click, and choose **Copy**.
- Navigate to the newly created **Frameworks** folder.
- Right-click inside the **Frameworks** folder and select **Paste** to move the files.
#### Update the Xcode Project
1. **Open Xcode Workspace:**
- Open the `ios/Runner.xcworkspace` file in Xcode.
2. **Add .xcframework Files to Xcode:**
- Drag and drop the `.xcframework` files into the "Frameworks" group in the Xcode project navigator.
- Ensure the **Copy items if needed** checkbox is selected.
#### Update Build Settings
1. **Configure Framework Search Paths:**
- Select the **Runner** target in Xcode.
- Go to the **Build Settings** tab.
- Add `$(SRCROOT)/Frameworks` to the **Framework Search Paths**.
2. **Verify Framework Embedding:**
- In the **General** tab of the Runner target, check that the frameworks are listed under **Frameworks, Libraries, and Embedded Content**.
- Ensure the frameworks are set to **Embed & Sign**.
---
### **Step 3 : Configuring Privacy Permissions in `Info.plist`**
In the iOS project, modify the `Info.plist` file to include the following keys. Set their data types to `String` and provide descriptive values that explain the necessity of your app's access to these privacy-sensitive resources:
- `NSLocationAlwaysAndWhenInUseUsageDescription`
- `NSLocationWhenInUseUsageDescription`
- `NSBluetoothAlwaysUsageDescription`
- `NSMotionUsageDescription`
Ensure that each key is assigned a string value detailing the purpose for which your application requires access to the respective data.
---
### **Step 4 : Modify the Podfile**
1. Navigate to your Flutter project's `ios` directory:
```sh
cd path/to/your/flutter/project/ios
```
2. Open the `Podfile` in a text editor:
```sh
open Podfile
```
3. Update your `Podfile` to include the Mapbox Maps SDK dependency and apply the necessary build setting. Your `Podfile` should look like this:
```ruby
target 'Runner' do
use_frameworks!
use_modular_headers!
pod 'MapboxMaps', '10.16.4'
flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
target 'RunnerTests' do
inherit! :search_paths
end
end
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end
```
#### **3. Install CocoaPods Dependencies**
1. Install the CocoaPods dependencies by running:
```sh
pod install
```
2. This will create or update the `Pods` directory and the `.xcworkspace` file.
#### **4. Open the Xcode Workspace**
1. Open the generated `.xcworkspace` file to make sure the Mapbox SDK is correctly integrated:
```sh
open Runner.xcworkspace
```
2. Always use this `.xcworkspace` file to open your project in Xcode, as it includes the CocoaPods dependencies.
---
#### Native iOS configuration steps
- **For detailed instructions on how to configure and initialize the Penguin SDKs, please start by checking out the [Configuration Steps](configuringPanNavUI.md#configuration-steps). It is important to begin here to ensure a proper setup.**
---
### **Step 5 : Create the Flutter Platform View Factory View**
- **Implement the View Factory:**
Create `PenguinViewFactory.swift` in `ios/Runner`.
```swift
import Flutter
import UIKit
class PenguinViewFactory: NSObject, FlutterPlatformViewFactory {
private var messenger: FlutterBinaryMessenger
init(messenger: FlutterBinaryMessenger) {
self.messenger = messenger
super.init()
}
func create(
withFrame frame: CGRect,
viewIdentifier viewId: Int64,
arguments args: Any?
) -> FlutterPlatformView {
return PenguinView(
frame: frame,
viewIdentifier: viewId,
arguments: args,
binaryMessenger: messenger)
}
public func createArgsCodec() -> FlutterMessageCodec & NSObjectProtocol {
return FlutterStandardMessageCodec.sharedInstance()
}
}
```
---
### **Step 6 : Implement the Custom View:**
Create `PenguinView.swift` in `ios/Runner`.
```swift
import Flutter
import UIKit
class PenguinView: NSObject, FlutterPlatformView {
private var _view: UIView
init(
frame: CGRect,
viewIdentifier viewId: Int64,
arguments args: Any?,
binaryMessenger messenger: FlutterBinaryMessenger?
) {
_view = UIView()
super.init()
// Initialize and configure the view using Penguin libraries
// Example:
// let penguinView = PenguinLibraryView(frame: frame)
// _view.addSubview(penguinView)
}
func view() -> UIView {
return _view
}
}
```
---
### **Step 7 : Register the Platform View in AppDelegate**
- **Modify `AppDelegate.swift`:**
```swift
import UIKit
import Flutter
@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
GeneratedPluginRegistrant.register(with: self)
let penguinFactory = PenguinViewFactory(messenger: self.registrar(forPlugin: "penguin")!.messenger())
self.registrar(forPlugin: "PenguinView")!.register(penguinFactory, withId: "penguin_lib")
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}
```
---
### **Step 8 : Use the Platform View in Flutter**
- **Modify Your Dart Code:**
```dart
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 MaterialApp(
home: Scaffold(
body: Container(
child: Platform.isIOS
? UiKitView(
viewType: viewType,
layoutDirection: TextDirection.ltr,
creationParams: creationParams,
onPlatformViewCreated: onPlatformViewCreated,
creationParamsCodec: const StandardMessageCodec(),
)
: AndroidView(
viewType: viewType,
layoutDirection: TextDirection.ltr,
creationParams: creationParams,
onPlatformViewCreated: onPlatformViewCreated,
creationParamsCodec: const StandardMessageCodec(),
),
),
),
);
}
Future<void> onPlatformViewCreated(int id) async {
// Handle platform view creation
}
}
```
### **Test Your Integration**
- Build and run your app on an iOS device or simulator.
- Verify that the custom native view appears and functions as expected.
### Tips:
- Ensure all framework dependencies are correctly resolved.
- Check that you have the appropriate permissions and entitlements if required by the native libraries.
- Debug using Xcode if you encounter any issues related to the view or integration.
[< Back](../readme.md)