Pointr SDK v8 Ionic-Capacitor Integration Guide¶

This guide will walk you through how to integrate the Pointr Cordova plugin to your Ionic Capacitor project.

Prerequisites¶

Android¶

Before you begin the steps below, make sure you have downloaded the Cordova Pointr Plugin v8 from the documentation center.

Also, while executing the following commands from terminal, make sure the active directory is the directory of your Ionic Capacitor project.

Step 1: Add Android Platform to your Capacitor project¶

> ionic capacitor add android

Step 2: Install the Pointr Cordova plugin¶

> npm i <cordova-plugin-pointr path>

Step 3: Make sure that jetifier is installed and ready to use. This is required because Pointr Android SDK uses support libraries.¶

> npm install jetifier

> npx jetify

> npx cap sync android

> ionic build

Step 4: Add custom repositories in android/build.gradle¶

This is the directory where the mentioned build.gradle resides

The following repositories should be added to allprojects/repositories section in the above file.

jcenter()
mavenCentral()
maven {
    url "https://android.pointr.dev/artifactory/gradle-release-local"
    // For plugins and TileView
    credentials {
        username '<username>'
        password '<password>'
    }
    maven { url 'https://jitpack.io' }
}

At the end, the allprojects section should look similar to this:

Step 5: Make sure your kotlin gradle plugin version is compatible¶

Go to the android/build.gradle file (same as step-4) and add the following line under buildscript.dependencies;

> classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.0"

At the end, the buildscript section should look like below;

You are set ! After this you should open the android directory of your Ionic project from Android Studio, and hit Run on a real device or emulator!

Troubleshooting¶

Module was compiled with an incompatible version of Kotlin. The binary version of its metadata is 1.6.0, expected version is 1.4.2.¶

Solution¶

Your project should use kotlin-gradle-plugin:1.6.0

The buildscript dependency classpath for kotlin gradle plugin should be:

> classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.0"

This should be changed from your android/build.gradle file. Check Step 5 for more details.

The final version of the buildscript in android/build.gradle should look similar to below:

I have changed the files on my Ionic project and build the platforms again, I am receiving errors.¶

Solution¶

Check the android/capacitor-cordova-android-plugins/build.gradle file, and make sure the following dependencies are included under dependencies, commented with SUB-PROJECT DEPENDENCIES START.

// Pointr Dependencies START
implementation 'com.pointrlabs:pointr:8+'
// required library to fix issue with arm64 emulators
implementation 'com.facebook.soloader:soloader:0.10.3'
// Pointr Dependencies END

I have changed some files in ionic project but they are not reflected in the app.¶

Solution¶

You need to run ‘npx cap sync android’ for the changes to be reflected on the application.

This version of the Android Support plugin for IntelliJ IDEA (or Android Studio) cannot open this project, please retry with version 2021.2.1 or newer.¶

Solution¶

You should upgrade your AS to the latest.

iOS¶

To enable ios run time on your environment you can follow the instructions given on the link https://capacitorjs.com/docs/ios

Two frameworks are needed before installing the plugin. The token to download the PointrKit will be provided by the responsible Project Manager.

1. PointrKit.xcframework for plugin ~>8
2. Mapbox.xcframework

Download and extract the frameworks from the links above. Put both libraries under cordova-plugin-pointr/libs folder.

Install the plugin using these commands:

npm i <path to cordova-plugin-pointr>
npx cap sync ios
ionic cap build ios

If it is not automatically launched, open ios/App/App.xcworkspace with Xcode. Manage application bundle identifier and signings.

Add necessary permissions related with location tracking into ios/App/Info.plist file

Required permissions¶

For different use cases different permissions are needed.

• NSLocationWhenInUseUsageDescription: To use positioning only when the app is in the foreground only.
• NSLocationAlwaysAndWhenInUseUsageDescription: To use positioning in the background. Should be used along side with NSLocationWhenInUseUsageDescription.

• NSBluetoothPeripheralUsageDescription(for iOS 12 and below only) and NSBluetoothAlwaysUsageDescription(for iOS 13+): To enable SDK to monitor Bluetooth Service State.

You can find more detailed information about permissions from /docs/8.x/Developer%20Portal/Pointr%20Mobile%20SDK/Information/Operating%20System%20Permissions/

For more information about iOS configuration, you can check the capacitor official documentation https://capacitorjs.com/docs/ios/configuration

Troubleshooting¶

No architecture found for Maps_Pod¶

Solution¶

From XCode clean your project (XCode / Product / Clean Build Folder) and run again.

Application Crash while trying to render the map on iOS simulator with M1 Mac machine.¶

Solution¶

Run XCode in Rosetta mode.

I have changed some files in ionic project but they are not reflected in the app.¶

Solution¶

You need to run ionic cap build ios for the changes to be reflected on the application.

Sample Project¶

Here is a sample code created with Node 16, Ionic 6, Angular 14, Capacitor 5. Depending on the path of the Cordova plugin you need to uninstall the plugin and install it from its location on your file system.

npm uninstall cordova-plugin-pointr
npm i <cordova-plugin-pointr path>

Some values are hardcoded in the project. These values should be replaced with appropriate ones. You can check the reference guide for the plugin to understand what parameters are required for each method.

Calls to the plugin are done under src/app/home/home.page.ts file of the project.

Note: Do not forget to sync and build the project after every change before running the app.