CoPilot Navigation

LicenseMgr (React Native)

Contents

Note: All React Native methods are async functions.

The APIs below allow Trimble Maps partners and customers to license CoPilot. There are different options available to meet the demands of a range of deployment sizes.

For an overview of CoPilot Licensing also see CoPilot Licensing.

Note: To receive relevant callbacks, ensure LicenseListener has been registered. Callbacks received through LicenseListener are essential for identifying license-related events within CoPilot. The following example code can be used to receive callbacks: 

const LicenseListener = NativeModules.LicenseListener;
const LicenseEventEmitter =
  Platform.OS == "android"
    ? DeviceEventEmitter
    : new NativeEventEmitter(LicenseListener);
LicenseEventEmitter.addListener("onLicensingReady", yourCBFunction);

LicenseListener.updateCreds(AssetID, CompanyID, ExternalID, PartnerID)

Attempts to log the user into CoPilot with the provided LicenseMgtInfo object. Do not call LicenseMgr.updateCreds inside of LicenseMgtCredentialHook. The hook is designed to work by simply creating and returning the LicenseMgtInfo object. The response from this call can be caught using the onLicenseMgtLogin() callback.
React Native
>=10.19
Type
Method

Syntax

void updateCreds(AssetID, CompanyID, ExternalID, PartnerID)

Parameters

AssetID - A string representing the username that was assigned to the device in Account Manager. CompanyID - A string representing the company ID assigned to the company in Account Manager. ExternalD - A string representing the external ID that was assigned to the device in Account Manager. PartnerID- A string representing the partner ID assigned to the company in Account Manager.

Return Value

None

Sample Code 

const LicenseListener = NativeModules.LicenseListener;
 LicenseEventEmitter.addListener('onLicenseMgtLogin', this.onLicenseMgtLogin);
onLicenseMgtLogin = (cbData) => {
	//Here you can see what LicenseMgtLogin object was returned
          }
//This will log you into an AMS account
await LicenseMgr.updateCreds("username", "companyid", "externalid", "partnerid");

LicenseListener.setAMSLoginInfo(UserName and CompanyID)

This API prepares CoPilot for login using the UserName and CompanyID assigned to the device in Account Manager. You must call this API before starting CoPilot. The login information will automatically be applied once Copilot starts. This API must be called with the LicenseListener licenseMgtCredentialHook hook registered.
React Native
>=10.14
Type
Method

Syntax

void setAMSLoginInfo(UserName, CompanyID)

Parameters

UserName - A string representing the username that was assigned to the device in Account Manager.
CompanyID - A string representing the company ID assigned to the company in Account Manager.

Return Value

None

Sample Code 

const LicenseListener = NativeModules.LicenseListener;
await LicenseListener.setAMSLoginInfo("username", "companyid");

const LicenseEventEmitter = Platform.OS == 'android' ? DeviceEventEmitter : new NativeEventEmitter(LicenseListener);
LicenseEventEmitter.addListener('licenseMgtCredentialHook', licenseMgtCredentialHook)

LicenseMgr.isLicensingReady

In order to activate upgrade keys, the base license must be successfully activated. Once the base license is active, users are able to pass CoPilot upgrade product keys or deactivate existing licenses that currently exist on CoPilot.

This API checks that the base license has been successfully activated. At this point, CoPilot is able to receive additional licensing.

React Native
>=10.14
Type
Method

Syntax

boolean isLicensingReady ()

Parameters

None

Return Value

Returns true if new licenses can be activated, existing licenses can be deactivated, or both.

Returns false if CoPilot is not ready for any further licensing API calls.

Sample Code 

const LicenseMgr = NativeModules.LicenseMgr;
var bReady = await LicenseMgr.isLicensingReady();

Hooks and Callbacks

Hooks and Callbacks related to Licensing can be found below.

LicenseListener
onLicensingReady
mapRegionUpgradeKeyHook

LicenseMgr.activateLicense (License Key and Device ID)

Activates additional features once CoPilot is ready to receive upgrade product keys. The product key as well as the device ID should be passed to CoPilot. Using this device ID, providing that it matches the device that receives the command and the product key is valid, the upgrade will be activated.

An internet connection is required when activating features with an expiration date. The activation may take a little while to complete, so it is recommended that this is not done on the application’s main thread.

Prior to activating a product key, it is recommended to check LicenseMgr.isLicensingReady to ensure CoPilot is ready to receive activation requests. Keys cannot be activated while a route is in progress.

When licensing map data only, one single region can be activated on a device via this API. If PAN region maps are installed, following the activation of one single key region, a second single region key cannot be activated. If upgrading to additional map data following a single region activation, this API only supports the upgrade to a PAN region.

React Native
>=10.14
Type
Method

Tip: Following the activation of a CoPilot License it is recommend that the application is restarted. This will look to ensure the license is fully activated.

Syntax

constant activateLicense(License, String)

Parameters

License – A string representing the product key

String – DeviceID to activate with

Return Value

LicenseActivationResponse - the result of activation

Sample Code 

const LicenseMgr = NativeModules.LicenseMgr;
var status = await LicenseMgr.activateLicense(
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  ""
);

LicenseMgr.getActiveAMSUser

Retrieves the currently logged in AMS user. If none is signed in then it returns null. CoPilot must be running to receive an accurate value from this API. Returns a LicenseMgtInfo object.
React Native
>=10.26
Type
Method

Syntax

getActiveAMSUser()

Return Value

Returns a LicenseMgtInfo object containing the AMS user.

Sample Code 

const LicenseMgr = NativeModules.LicenseMgr;
var amsUser = await LicenseMgr.getActiveAMSUser();

LicenseMgr.getLicenseStatus

Returns the current status of a licensed feature based on a specific provided license. In order for the API to return a status, CoPilot must be running and the product key must have already been active on the device. Return values will be one of the following:
- Licensed and activated
- Licensed but will expire
- Licensed but not activated
- License exists, but is expired
- The license key is invalid
- CoPilot has not yet started, so the status cannot be determined
- General error
If the product key for the licensed feature is not known, use LicenseFeature.getFeatureStatus. For a list of available features, see LicenseFeature.
React Native
>=10.14
Type
Method

Syntax

constant getLicenseStatus(License)

Parameters

License – A string representing the product key

Return Value

Returns a LicenseStatus detailing the status of the license.

Sample Code 

const LicenseMgr = NativeModules.LicenseMgr;
var status = await LicenseMgr.getLicenseStatus("xxxxx-xxxxx-xxxxx-xxxxx-xxxxx");

LicenseMgr.getFeatureStatus

Returns the current status of a licensed feature, when the product key for the feature is not known. CoPilot must be running to receive an accurate value from this API.

Return values provide a status specific to the requested feature and can be found within FeatureStatus.

React Native
>=10.14
Type
Method

Syntax

constant getFeatureStatus(licenseFeature)

Parameters

licenseFeature - The feature you are checking

Return Value

Returns a FeatureStatus containing the status of the feature.

Sample Code 

const LicenseMgr = NativeModules.LicenseMgr;
const LicenseFeature = NativeModules.LicenseFeature;

var featureStatus = await LicenseMgr.getFeatureStatus(LicenseFeature.FULL_NAVIGATION));

LicenseMgr.getDaysOfFeatureRemaining

Provides information relating to the remaining number of days for a licensed feature. If the feature has expired, a value of 0 will be return. A positive number represents the number of days remaining. If the feature has an unlimited number of days remaining, a MAX_VALUE value will be provided.

Once the value has been returned, you can increase the number of days or move to an unlimited period by purchasing additional licenses and upgrading CoPilot using new product keys.

React Native
>=10.14
Type
Method

Syntax

int getDaysOfFeatureRemaining(licenseFeature)

Parameters

licenseFeature - The feature you are checking

Return Value

Returns an int corresponding to the number of days remaining on this licensed feature. In the case of an UNLIMITED feature, Integer.MAX_VALUE will be returned.

Sample Code 

const LicenseMgr = NativeModules.LicenseMgr;
const LicenseFeature = NativeModules.LicenseFeature;

var days = await LicenseMgr.getDaysOfFeatureRemaining(
  LicenseFeature.FULL_NAVIGATION
);

LicenseMgr.deactivateLicense

Deactivates licenses that are currently active. The corresponding product key of the active license should be passed in with this API, allowing for CoPilot to identify the corresponding features associated with that license that are to be deactivated. Keys cannot be deactivated while a route is in progress.
React Native
>=10.14
Type
Method

Syntax

constant deactivateLicense(license)

Parameters

license - A string representing the product key

Return Value

LicenseActivationResponse - the result of deactivation

Sample Code 

const LicenseMgr = NativeModules.LicenseMgr;
var status = await LicenseMgr.deactivateLicense(
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
);

LicenseListener.setKeyForMapRegionUpgradeKeyHook(region)

(Android only)

This API prepares CoPilot for activating a map region. You must call this API before starting CoPilot. The login information will automatically be applied once Copilot starts. This API must be called with the LicenseListener mapRegionUpgradeKeyHook hook registered.
React Native
>=10.14
Type
Method

Syntax

setKeyForMapRegionUpgradeKeyHook(region)

Parameter

region - A MapRegion representing the region to activate upon activating CoPilot.

Sample Code 

const LicenseListener = NativeModules.LicenseListener;
await LicenseListener.setKeyForMapRegionUpgradeKeyHook(MapRegion.NORTH_AMERICA_United_States);

const LicenseEventEmitter = Platform.OS == 'android' ? DeviceEventEmitter : new NativeEventEmitter(LicenseListener);
LicenseEventEmitter.addListener('mapRegionUpgradeKeyHook', mapRegionUpgradeKeyHook)
Last updated June 21, 2024.
Contents