
[< Back](ios.md)

## Integrating and Configuring PenNavUI

### Importing PenNavUI

Start by importing the PenNavUI framework into your project:

```swift
import PenNavUI
```

### Conforming to `PenNavInitializationDelegate`

Implement the `PenNavInitializationDelegate` protocol in your view controller to handle initialization events:

```swift
extension ViewController: PenNavInitializationDelegate {
    func onPenNavSuccess() {
        // Handle successful initialization
    }
    
    func onPenNavInitializationError(errorType: PenNavUIError, errorDescription: String) {
        // Handle initialization error
    }
}
```

### Configuring `PenNavUIManager`

Set up `PenNavUIManager` with the configuration values provided by our Customer Success Team:


```swift
PenNavUIManager.shared
    .setClientKey("Your Client Key")
    .setClientID("Your Client ID")
    .setBaseURL(dataURL: "Your Data URL", positionURL: "Your Position URL")
    .setServiceName(dataServiceName: "Your Data Service Name", positionServiceName: "Your Position Service Name")
    .build()
```

- Example with more configuration :
```swift
        PenNavUIManager.shared
            .setClientKey("UGVuZ3VpbklOX1Blb")
            .setClientID("ClientA")
            .setUsername("UserA")
            .setSimulationModeEnabled(isEnable: true)
            .setBaseURL(dataURL: "https://temp.client.penguinin.com", positionURL: "https://temp.client.penguinin.com")
            .setServiceName(dataServiceName: "api", positionServiceName: "pe")
            .setIsShowUserName(false)
            .setEnableReportIssue(enable: false)
            .setLanguage("en")
            .build()
```

### Presenting the Map

After successful initialization, present the map by calling:

```swift
PenNavUIManager.shared.present(root: self, view: view)
```

Ensure the `onPenNavSuccess` method includes this call:

```swift
extension ViewController: PenNavInitializationDelegate {
    func onPenNavSuccess() {
        PenNavUIManager.shared.present(root: self, view: view)
    }
    
    func onPenNavInitializationError(errorType: PenNavUIError, errorDescription: String) {
        // Handle initialization error
    }
}
```

### Configuring the Location Delegate

To get notified when the user is off campus, conform to the `PILocationDelegate` protocol:

```swift
extension ViewController: PILocationDelegate {
    func onLocationOffCampus(location: CLLocationCoordinate2D) {
        // Handle user location being off campus
    }
}
```

Set the `locationDelegate` of `PenNavUIManager`:

```swift
PenNavUIManager.shared.locationDelegate = self
```

### Configuring the Events Delegate

To handle map dismissal events, conform to the `PIEventsDelegate` protocol:

```swift
extension ViewController: PIEventsDelegate {
    func onPenNavUIDismiss() {
        // Handle map dismissal
    }
}
```

Set the `eventsDelegate` of `PenNavUIManager`:

```swift
PenNavUIManager.shared.eventsDelegate = self
```

### Reporting Issues

Enable issue reporting and handle it using the `PIEventsDelegate` protocol:

```swift
PenNavUIManager.shared.setEnableReportIssue(enable: true)

extension ViewController: PIEventsDelegate {
    func onReportIssue(_ issue: PenNavUI.IssueType) {
        // Handle issue reporting
        Instabug.show()
    }
}
```

Set the `eventsDelegate` of `PenNavUIManager`:

```swift
PenNavUIManager.shared.eventsDelegate = self
```

### Navigating to Places

- **Using Reference IDs:**

  Navigate to a place using its reference ID:

  ```swift
  PenNavUIManager.shared.navigate(to: "referenceID", completion: { success, error in
      // Handle navigation result
  })
  ```

- **Using Deep Links:**

  Configure deep linking to share places:

  ```swift
  PenNavUIManager.shared.setDeepLinkScheme("app://", deepLinkDomain: "www.penguinin.com")
  PenNavUIManager.shared.setDeepLinkData(data: "YourDeepLinkData")
  ```

### Simulating User Location

Enable simulation mode for testing purposes:

```swift
PenNavUIManager.shared
    .setClientKey("Your Client Key")
    .setClientID("Your Client ID")
    .setBaseURL(dataURL: "Your Data URL", positionURL: "Your Position URL")
    .setServiceName(dataServiceName: "Your Data Service Name", positionServiceName: "Your Position Service Name")
    .setSimulationModeEnabled(isEnable: true)
    .setUsername("Your Username")
    .build()
```

### Dismissing the PenNav SDK

When the PenNav SDK is no longer needed, dismiss it to free up resources:

```swift
PenNavUIManager.shared.dismiss()
```

### Deprecated Methods

Avoid using the following deprecated methods:

- `setOutdoorEnable(isEnable:)`
- `setStepDetectionEnable(isEnable:)`
- `setTransitionEnable(isEnable:)`

### Handling Map Initialization Errors

Here are common errors and their descriptions:

| **Error**                        | **Description**                                                        |
|----------------------------------|------------------------------------------------------------------------|
| Missing Base URL                  | Specify a valid base URL.                                               |
| Missing Data Service Name         | Provide the required data service name.                                 |
| Missing Position Service Name     | Provide the required position service name.                             |
| Missing Client ID                 | Ensure a valid client ID is provided.                                   |
| Invalid Client Key                | Verify and provide a valid client key.                                  |
| Missing Root Controller           | Ensure a valid root controller is provided.                             |
| Missing View Container            | Provide a valid view container.                                         |
| Unauthorized                      | Check your authorization for the requested action.                     |
| Loading Data Error                | Retry loading data.                                                     |
| OS Not Supported                  | Ensure the operating system is supported.                               |
| No Internet Connection            | Verify your internet connection.                                        |
| Sensors Initialization Error      | Check sensor settings and retry.                                        |
| Permissions Not Granted           | Grant all necessary permissions.                                        |
| Location Permission Not Granted   | Grant location permission.                                              |
| Bluetooth Permission Not Granted  | Grant Bluetooth permission.                                             |
| Location Services Turned Off      | Enable location services.                                               |
| Bluetooth Turned Off              | Enable Bluetooth.                                                        |

### User Guide for the Demo App

Before installing and running the Demo App, configure `PenNavConfigurations.plist` with the values provided by our Customer Success Team:

| **Key**                    | **Value**                         |
|----------------------------|-----------------------------------|
| ClientKey                  | Provided by the Customer Success Team |
| ClientId                   | Provided by the Customer Success Team |
| DataUrl                    | Provided by the Customer Success Team |
| PositionUrl                | Provided by the Customer Success Team |
| DataServiceName            | Provided by the Customer Success Team |
| PositionServiceName        | Provided by the Customer Success Team |

---

[< Back](README-ios.md)