Overview¶

• Pointr Android SDK can be shared in two ways,
  • From artifactory server which serves over https. For details see.
  • If you don’t access the SDK over artifactory due to various reasons, you can also obtain the required .aar files to integrate the Pointr Android SDK
• Android Studio 3.0 or later
• Gradle 4.1 or later
• Certificate file

• SDK file, shared as either:
  • CocoaPods POINTR_SDK_TOKEN. For details see; or
  • .framework file
• XCode 11.x or later

Add using Gradle Maven¶

Step 1¶

Add pointr artifactory to your project’s top level build.gradle file.

allprojects {
    repositories {
        ... // other repositories
        maven {
            url "https://android.pointr.dev/artifactory/gradle-release-local"
            credentials {
                username 'YOUR_USER_NAME'
                password 'YOUR_ARTIFACTORY_PASS'
            }
        }

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://android.pointr.dev/artifactory/gradle-release-local"
            credentials {
                username 'YOUR_USER_NAME'
                password 'YOUR_ARTIFACTORY_PASS'
            }
        }
    }
}

However, Google official documentation still suggests to keep them in the project level “build.gradle”.

To access the Pointr Android SDK you need to update the credentials marked “YOUR_USER_NAME” and “YOUR_ARTIFACTORY_PASS”. To get the artifactory credentials, contact your project manager.

Step 2¶

Add Pointr Android SDK to your module level dependencies. You can check the latest version from here

implementation 'com.pointrlabs:pointr:<add latest version of Pointr SDK here>'

Step 3¶

Sync your project with new gradle files to start downloading the Pointr SDK and get all dependencies.

You can either use CocoaPods or Manually add the Framework to integrate with your project.

Add using Cocoapods¶

• Request an access token (POINTR_SDK_TOKEN) from your customer support team.

• Add the following to your Podfile:

# Add this line to top of your `Podfile` as a source
source "https://github.com/pointrlabs/public-podspecs.git"

# Add this in targets you want to add PointrKit
ENV['POINTR_SDK_TOKEN'] = '$YOUR_ACCESS_TOKEN'
pod 'PointrKit', ''add latest version of Pointr SDK here”

• Run pod install to integrate SDK.

Manually add the Framework¶

Download the latest Pointr iOS SDK and then drag and drop the PointrKit.xcframework and Mapbox.xcframework (Maplibre library) into your Xcode project. Select Embed & Sign on the Embed options.

Putting the PointrContent.zip inside the app (This step is optional for version 8.1.0 and later. Check Start Pointr section to learn how to start the SDK without the zip file.):¶

Please follow the steps below, to make sure that you add the PointrContent.zip correctly inside the app:

• Please visit this link: Where can I find pointrcontent.zip to see how to get the PointrContent.zip
• Remember that the suffix signifies the environment the content is connected to. The SDK will check the zip with the associated environment given to the Pointr.with method as an argument.
• Put the PointrContent zip anywhere inside the Xcode project, as long as it is included in the application’s bundle.
• Do not change the name of the Pointr Content zip to change environments.
• To switch between environments, change the Environment parameter supplied to Pointr.with

Before you use most of Pointr features you need to get it into a RUNNING state, this is done with a method called Pointr.with that takes an argument with some parameters.

The most important parameters are the license key and environment settings, those are needed to connect to Pointr Cloud. To set the url and client identifier you can either import the PointrContent.zip provided by us or you can set the values when initialising the SDK.

Example when using PointrContent.zip:

val ptrParams = PTRParams()
ptrParams.environment = PointrEnvironment.PROD
ptrParams.licenseKey = "PROD_LICENCE_KEY"
ptrParams.logLevel = PLog.LogLevel.WARNING

Example when setting the values on code (for version 8.1.0 and later):

val ptrParams = PTRParams("YOUR_CLIENT_ID", "PROD_LICENCE_KEY", "YOUR_POINTR_CLOUD_API_URL")
ptrParams.logLevel = PLog.LogLevel.WARNING

Other fields of the ptrParams class can be modified to configure your Pointr instance as needed (e.g., the path to PointrContent zip files, the path to cacert.pem file). If these are not customized, the default location will be used, which is the “Assets” folder.

Example code of Pointr.with method using the parameters created previously.

Pointr.with(
    applicationContext,
    ptrParams
)

After this, you will be able to get a valid instance of Pointr using the static Pointr.getPointr() method anywhere. The two pieces of code that were just shown should run only once, yet they should run, one possible location for them is right when the application starts, or on some event that happens only once, or only the first time, when the user is about to use Pointr.

To utilize the Pointr Managers, you need to make sure that Pointr is RUNNING. To run Pointr, call Pointr.getPointr()?.start() method and retrieve state updates by subscribing a PointrListener to Pointr. If Pointr.with wasn’t called before you attempt to use getPointr() you might cause an exception or application crash as it attempts to access a non-existing object instance.

Below is an example of how to implement this:

import android.os.Bundle
import android.support.v7.app.AppCompatActivity
import com.pointrlabs.core.management.Pointr
import com.pointrlabs.core.management.interfaces.PointrListener
import com.pointrlabs.sample.R

/**
* Activity to start Pointr
*/
class PointrLoadingActivity : AppCompatActivity() {
    private val pointrListener = object : PointrListener {
        override fun onStateUpdated(state: Pointr.State?) {
            if (state == Pointr.State.RUNNING) {
                onPointrRunning()
                Pointr.getPointr()?.removeListener(this)
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.layout_of_activity)
        val pointr = Pointr.getPointr()
        pointr?.addListener(pointrListener)
        pointr?.start()
        if (pointr?.state == Pointr.State.RUNNING) {
            onPointrRunning()
        }
    }

    private fun onPointrRunning() {
        // Do operations with Pointr Managers
        // Show map etc.
    }
}

You should replace the “R.layout.layout_of_activity” line with an actual layout that exists in your project, for example R.layout.main_activity if you are using the “Empty Activity” template. Then you should replace the “import com.pointrlabs.sample.R” with the “R” path of your project.

To start using Pointr methods, you will first need to initialize a Pointr instance. To initialize with Pointr.shared.start(with:onStateChanged:) method, you will need to create a PTRParams instance with necessary parameters.

Example when using PointrContent.zip:

let params = PTRParams()
params.mode = PointrDebugMode()
params.environment = PTREnvironment.internal
params.licenseKey = "YOUR_LICENSE_KEY"
params.loggerLevel = .info

Example when setting the values on code (for version 8.1.0 and later):

let params = PTRParams()
params.mode = PointrDebugMode()
params.baseUrl = "YOUR_POINTR_CLOUD_API_URL"
params.clientIdentifier = "YOUR_CLIENT_ID"
params.licenseKey = "YOUR_LICENSE_KEY"
params.loggerLevel = .info

Other fields of the params class can be modified to configure your Pointr instance as needed (e.g., the path to PointrContent zip files etc.). If resourceFolder is not customized, the default location will be used, which is Bundle.main.bundlePath.

To utilize the Pointr Managers, you need to make sure that Pointr State is at the Running stage. This can be achieved by using Pointr.shared.start(with:onStateChanged:) method’s onStateChanged callback. You can also validate if Pointr is Running by checking the State field (i.e., Pointr.shared.state == PointrState.running).

After confirming your Pointr state is Running; to show the maps, you need to use PTRMapWidgetFragment and PTRMapWidgetConfiguration.

PTRMapWidgetConfiguration¶

PTRMapWidgetConfiguration is a class that allows you to customize Pointr Map Widget components and their behavior. This class will be passed to PTRMapWidgetFragment initializer to define the specifications of the Pointr Map Widget.

PTRMapWidgetFragment¶

To be able to show the Pointr MapWidget, you need to have a FrameLayout fragment to serve as a container for the Pointr Map. This layout can be hosted in a fragment or an activity, that is up to the implementer.

If you created a fragment used the GUI editor, ensure you use the code below with a FrameLayout, adding a PTRMapWidgetFragment with the GUI and then using the code below will result in one Map Widget inside another, and a lot of issues and bugs.

Example Code to show the map, considering the FrameLayout has the id: R.id.fragment_container:

// This line creates a mapWidgetConfiguration to configure the Pointr Map as per your needs.
val mapWidgetConfiguration = PTRMapWidgetConfiguration.defaultConfiguration()
val mapWidgetFragment = PTRMapWidgetFragment.newInstance(mapWidgetConfiguration)
    .show(supportFragmentManager, R.id.fragment_container)

Show a Building¶

After creating the map widget instance, you can display a building in it (or map widget will display a world map, not a specific building), using building and site external identifiers which you can learn from your Pointr Cloud instance.

Example Code¶

// The call to display a building in map widget
mapWidgetFragment?.showBuilding("your_site_ext_id", "your_building_ext_id")

After confirming your Pointr state is Running; to show the maps, you need to use PTRMapWidgetViewController and PTRMapWidgetConfiguration. PTRMapWidgetConfiguration is a class that allows you to customize Pointr map widget components and their behavior.

Example Code¶

// This line creates a mapWidgetConfiguration to configure the Pointr Map as per your needs.

let configuration = PTRMapWidgetConfiguration()
let mapWidget = PTRMapWidgetViewController(configuration: configuration)

After creating the map widget instance, you can display a building in it (or map widget will display a world map, not a specific building), using building and site external identifiers which you can learn from your Pointr Cloud instance.

Example Code¶

mapWidget.showBuilding(siteExternalIdentifier: "your_site_ext_id", buildingExternalIdentifier: "your_building_ext_id")
navigationController?.present(mapWidget, animated: true, completion: nil)