LicenseMgr (CPIK Libraries)

Contents

The below APIs 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.

LicenseMgtInfo #

Overview
Description Account Manager is a web tool that allows you to distribute and manage the product licenses your fleet has purchased for CoPilot. With Account Manager, you can log in to CoPilot and activate a license by passing a userName and a companyId, rather than a product key— the traditional method of CPIK licensing. This object is used to send and receive that login information.
Supported on Android Since Version 10.14.0.368
Type Object
Package com.alk.cpik.licensing

Public Constructors

Name Description
LicenseMgtInfo(String assetId, String companyId) Constructs a LicenseMgtInfo object with the specified assetId and companyId.

assetId is the identifier for the asset you assigned a license to in the Account Manager. (It could be a company issued device ID, driver ID, email address, phone number, device descriptor, or vehicle number.)

companyId is the Company ID assigned by Trimble MAPS to a company deploying CoPilot directly.

LicenseMgtInfo(String assetId, String externalAccountId, String partnerId)

Available in CoPilot 10.19.0.1405 and Higher

Constructs a LicenseMgtInfo object with the specified assetId and externalAccountId and partnerId.

assetId is the identifier for the asset you assigned a license to in the Account Manager. (It could be a company issued device ID, driver ID, email address, phone number, device descriptor, or vehicle number.)

externalAccountId is a partner’s ID for their end customer using CoPilot.

partnerId is the Partner ID assigned by Trimble MAPS to a partner whose customers are deploying CoPilot.

Methods

Method Name Return Type Description
getAssetID() Available in CoPilot 10.19.0.1405 and Higher
String
Gets the login asset ID, which is the identifier for the asset you assigned a license to in the Account Manager.
getExternalAccountID() Available in CoPilot 10.19.0.1405 and Higher
String
Gets the partner’s ID for their end customer using CoPilot
getPartnerID() Available in CoPilot 10.19.0.1405 and Higher
String
Gets the Partner ID assigned by Trimble MAPS to a partner whose customers are deploying CoPilot
getCompanyID()
String
Gets the login Company ID, which is assigned by Trimble MAPS to a company deploying CoPilot directly.
setUserName(String userName) Deprecated in CoPilot 10.19.0.1405
void
Sets the login username
getUserName() Deprecated in CoPilot 10.19.0.1405
String
Gets the login username
setCompanyID(String companyID) Deprecated in CoPilot 10.19.0.1405
void
Sets the login company name

License #

If you are not using Account Manager, CoPilot licenses can be activated with a 25-character product key, which is arranged into five groups of five alphanumeric characters separated by dashes. Upgrade keys use the same format to activate features that require separate licenses, including additional map regions or ActiveTraffic.

The product key may also be referred to as a license key or an upgrade key. Depending upon the key type, they will be one-time use or enterprise keys. A single enterprise key can be activated on multiple devices, as long as contractual terms are followed. To activate a licensed attribute LicenseMgr.activateLicense should be used. When using the mapRegionUpgradeKeyHook method to activate an upgrade key, the key should be hard coded in the application.

In the provided sample application, product keys were put in a text file named key.txt within the CoPilot directory.

Android Support
>=9.6.0.821
iOS Support
>=10.9
Type
Class
Package
com.alk.cpik.licensing
Note
To receive relevant hooks and callbacks, ensure LicenseListener.registerHook and LicenseListener.registerListener have been registered. Hooks and callbacks received are essential for identifying license-related events within CoPilot.

Public Constructors

Name Description
License (java.lang.String productKey) throws LicenseException Construct a License object with specified product key string argument of the form: “XXXXX-XXXXX-XXXXX-XXXXX-XXXXX”. If the license key provided to the constructor is in invalid format, it will throw LicenseException.

Methods

Method Name Return Type Description
getLicenseKey()
String
Returns 25-character product key associated with this License. Please note the return string is 29 characters long as it includes the 4 dashes.

Sample Code

Hooks and Callbacks

Hooks and Callbacks related to Licensing can be found below.

LicenseListener

  • onFeatureActivated
  • onInAppPurchase
  • onLicensingReady
  • mapRegionUpgradeKeyHook

Licensing Use Cases #

This section outlines a use case of CPIK Licensing on CoPilot’s first start to illustrate how CPIK licensing APIs are used. Two separate cases are also defined within these steps depending on platform and map deployment method.

Use Case 1 – First Start Process #

Step 1

On first start, the CopilotListener.onCPStartup callback will be received. Non-licensing API calls should not be made until CoPilot receives this callback.

Step 2

Next, the LicenseMgr.onLicensingReady callback will be received. After receiving this callback, upgrade keys not related to map regions can be activated. Note that this callback will be fired at each startup. A check should always be performed if the key is already activated. Sample code can be found below:

private LicenseListener m_LicenseListener = new LicenseListener()
{
  @Override
  public void onLicensingReady()
  {
    String trafficKeyString = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX";
    try {
      License trafficLic = new License(trafficKeyString);
      if (LicenseMgr.getLicenseStatus(trafficLic) != LicenseStatus.ACTIVATED ||
        LicenseMgr.getLicenseStatus(trafficLic) != LicenseStatus.WILL_EXPIRE)

      {
        LicenseMgr.activateLicense(new License(trafficKeyString));
      }
    } catch (Exception e) {}
  }
};

// In your application....
LicenseListener.registerListener(m_LicenseListener);

Step 3

The map region upgrade key can then be applied.

  1. For users on an iOS platform, this key must be activated in the onLicensingReady callback. Then, CoPilot will have to be restarted. After restarting, proceed to Step 4.

  2. For users on Android, Xamarin or Linux platform, see Cases A or B below depending on if the system has pre-installed map data.

Case A – Map Data will always be pre-installed on the device #

  • Set the following configuration setting to prevent data download on the device. This ensures that data will not be corrupted and licensing will not fail. This configuration can be set in product.cfg as:
 [Download]
 "PreventDataDownload"=1

This can also be set via the Configuration APIs in onCPStartup as follows. If this method is used, CoPilot should be restarted. Sample code illustrating how to set this configuration value can be found below:

private CopilotListener m_CopilotListener = new CopilotListener(){
  @Override
  public void onCPStartup(){
    try {
      ConfigurationSetting allowMapDataDownloads = ConfigurationSetting.create(ConfigurationSetting.PREVENT_DATA_DOWNLOAD, ConfigurationSetting.PREVENT_ALL_DOWNLOADS);
      CopilotMgr.setConfigurationSetting(allowMapDataDownloads);
    } catch (Exception configExc)
  }
}

// In your application....
CopilotListener.registerListener(m_CopilotListener);
  • Implement the mapRegionUpgradeKeyHook method to return the correct upgrade key for the pre-installed region. Sample code is shown below:
private LicenseListener m_LicenseListener= new LicenseListener()
{
  @Override
  public License mapRegionUpgradeKeyHook() {
    // Customers - hard code your upgrade key here
    // Proceed immediately to returning this value through the hook
    String upgradeKeyString = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX";

    try {
      return new License(upgradeKeyString);
    } catch (Exception e) { return null; }
  }
}

// In your application....
LicenseListener.registerHook(m_LicenseListener);

  • If there are any errors activating this upgrade key, they will be shown in CoPilot. At this point CoPilot will need to be restarted. This error code will be returned as -755.

  • If the region upgrade key was activated successfully the end user will be taken to the map dialog and CoPilot will be ready to use. Proceed to step 4.

Case B – Map Data is not pre-installed on the device #

  • Set the configuration value in product.cfg to allow data download on the device. It should be set as:
 [Download]
 "PreventDataDownload"=0

Or, it can be set via the Configuration APIs in onCPStartup as following. If this method is used, a restart may be required.

private CopilotListener m_CopilotListener = new CopilotListener(){
  @Override
  public void onCPStartup()  {
    try {
      ConfigurationSetting allowMapDataDownloads = ConfigurationSetting.create(ConfigurationSetting.PREVENT_DATA_DOWNLOAD, ConfigurationSetting.ALLOW_ALL_DOWNLOADS);
      CopilotMgr.setConfigurationSetting(allowMapDataDownloads);
    } catch (Exception configExc) { }
  }
}

// In your application....
CopilotListener.registerListener(m_CopilotListener);

  • Implement the mapRegionUpgradeKeyHook method to return the correct upgrade key for the region you wish to license. Sample code can be found below:
private MapDataListener m_MapDataListener = new MapDataListener(){
  @Override
  public void onReadyToDownloadInitialMapData() {
    // Download NA Eastern and NA South as the initial regions
    // This list can be one map, or many...
    ArrayList<MapRegion> regionsToDownload = new ArrayList<MapRegion>();
    regionsToDownload.add(MapRegion.NORTH_AMERICA_Eastern);
    regionsToDownload.add(MapRegion.NORTH_AMERICA_South);
    MapDataMgr.downloadMap(regionsToDownload, null, true);
  }
};

// In your application....
LicenseListener.registerHook(m_LicenseListener);
  • If there are any errors activating this upgrade key, they will be shown in CoPilot. At this point CoPilot will need to be restarted. Error Code: -755

  • Once the region upgrade key successfully activates, the user will be taken to the map download dialog and the callback MapDataMgr.onReadyToDownloadInitialMapData will be called. The implementation of this callback can then use the standard map download APIs to download initial map data. An example implementation is shown below:

private MapDataListener m_MapDataListener = new MapDataListener(){
  @Override
  public void onReadyToDownloadInitialMapData() {
    // Download NA Eastern and NA South as the initial regions
    // This list can be one map, or many...
    ArrayList<MapRegion> regionsToDownload = new ArrayList<MapRegion>();
    regionsToDownload.add(MapRegion.NORTH_AMERICA_Eastern);
    regionsToDownload.add(MapRegion.NORTH_AMERICA_South);
    MapDataMgr.downloadMap(regionsToDownload, null, true);
  }
};

// In your application....
MapDataListener.registerListener(m_MapDataListener);
  • Upon completion of the initial map download, the user will be taken to the navigation view and CoPilot is ready to use. Proceed to step 4.

Step 4

Map Data is installed, licensed and CoPilot is ready to use. This can be verified by receiving the UIListener.onShowNavigationScreen() callback.

LicenseMgr.isLicensingReady #

Overview
Description 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.

Supported on Android Since Version 9.6.0.821
Supported on iOS 10.9
Type Method
Package com.alk.cpik.licensing
Note
To receive relevant hooks and callbacks, ensure LicenseListener.registerHook and LicenseListener.registerListener have been registered. Hooks and callbacks received are essential for identifying license-related events within CoPilot.

Syntax

boolean isLicensingReady ()

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

LicenseMgr.activateLicense (License key) #

Overview
Description Activates additional features once CoPilot is ready to receive upgrade product keys. 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.

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.

Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.licensing
Note
To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.
Note
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. Keys cannot be activated while a route is in progress.

Syntax

LicenseActivationResponse LicenseMgr.activateLicense(License)

Parameters

License – Object representing the License which contains the product key

Return Value

Contains the result of activation. It returns the object of LicenseActivationResponse.

Sample Code

LicenseMgr.activateLicense (License Key and Device ID) #

Overview
Description 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.

Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.licensing
Note
To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

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

LicenseActivationResponse LicenseMgr.activateLicense(License, String)

Parameters

License – Object representing the License which contains the product key

String – DeviceID to activate with.

Return Value

Contains the result of activation. In Java, it returns the object of LicenseActivationResponse.

Sample Code

LicenseActivationResponse #

Overview
Description An enum that holds the list of all possible values that can be returned following a request to activate or deactivate a license through either LicenseMgr.activateLicense or LicenseMgr.deactivateLicense.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Values for Product Key Login

Value Description
SUCCESS The activation or deactivation was successful.
FAILED_DEVICEID_TOO_LONG The license activation failed because the device ID was too long.
FAILED_LICENSE_EXPIRED The license activation failed due to an expired license.
FAILED_COPILOT_NOT_STARTED The license activation failed because CoPilot was not started.
FAILED_LICENSING_NOT_READY The license activation failed because licensing is not ready.
FAILED_GENERAL_ERROR The license activation failed due to a general error.
FAILED_INVALID_LICENSE_KEY The activation failed due to an invalid license key.
FAILED_ROUTE_IN_PROGRESS The license activation failed because CoPilot currently has a route. Keys cannot be activated while CoPilot is routing.

Values for Account Manager Login

Available in CoPilot 10.14.0.368 and Higher.

Used with the onLicensingMgtLogin callback

Value Description
FAILED_AMS_IN_USE The license activation failed because an AMS account is currently in use.
FAILED_LOGIN_CANT_REACH_SERVER The license activation failed because we couldn’t communicate with the server.
FAILED_LOGIN_WILL_EXPIRE The license activation failed because we couldn’t connect to the server. Currently logged in, but will eventually expire.
FAILED_LOGIN_INVALID_CREDS The license activation failed because login credentials are invalid.
FAILED_LOGIN_DEVICE_LIMIT_REACHED The license activation failed because the user is already logged into maximum number of devices.
FAILED_LOGIN_NO_ACTIVE_LICENSES The license activation failed because the user has no active licenses

LicenseMgr.getLicenseStatus #

Overview
Description 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.

Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Syntax

LicenseStatus LicenseMgr.getLicenseStatus(License)

Parameters

license – Object representing the License. Contains the product key.

Return Value

Returns a LicenseStatus detailing the status of the license.

Sample Code

LicenseFeature.getFeatureStatus #

Overview
Description 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.

Supported on Android Since Version 9.6.0.821
Type Method
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Syntax

FeatureStatus getFeatureStatus()

Return Value

Returns a FeatureStatus containing the state of the feature.

Sample Code

FeatureStatus #

Overview
Description An enum that holds the list of all possible values that can be returned from LicenseFeature.getFeatureStatus().
Supported on Android Since Version 9.6.0.821
Type Enum
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Values

Value Description
LICENSED The feature is licensed and available.
UNLICENSED The feature is not licensed on this device.
UNLIMITED The feature is licensed and has no expiration date.
UNKNOWN The status of the feature is not known, or no such feature exists.

LicenseFeature #

Overview
Description An Enum that holds the list of all possible values that can be returned from LicenseFeature.getFeatureStatus().
Supported on Android Since Version 9.6.0.821
Type Enum
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Values

Value Description
FULL_NAVIGATION CoPilot is able to provide guidance and turn-by-turn instructions. Without Full Navigation, it may be possible to plan a trip to be displayed, but CoPilot will not navigate the user with turn instructions.
TRAFFIC CoPilot receives live Traffic updates from Trimble MAPS servers providing notifications of delays and impact to the planned route.
UNKNOWN This indicates an additional unknown feature.
ADVANCED_OPTIMIZATION The Advanced Optimization feature allows for enhanced optimization of routes with multiple stops. The optimization takes into account any time restrictions required to meet a stop’s needs.
MAJOR_REGION Map data attribute indicating that a full region has been licensed on CoPilot.
TRUCK_HEAVY_DUTY This truck attribute allows CoPilot to use heavy-duty routing profiles.
TRUCK_MEDIUM_DUTY This truck attribute allows CoPilot to use medium-duty routing profiles.
TRUCK_LIGHT_DUTY This truck attribute allows CoPilot to use light-duty routing profiles.

LicenseFeature.getDaysRemaining #

Overview
Description 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.

Supported on Android Since Version 9.6.0.821
Type Method
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Syntax

LicenseFeature.getDaysRemaining()

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

// Print the number of days remaining for traffic
int daysOfTrafficRemaining = LicenseFeature.TRAFFIC.getDaysRemaining();

if (daysOfTrafficRemaining == Integer.MAX_VALUE)
  System.out.println("Unlimited days of traffic remaining");
else if (daysOfTrafficRemaining == 0)
  System.out.println("No days of traffic remaining");
else
  System.out.println(String.valueOf(daysOfTrafficRemaining) + " days of traffic remaining");

LicenseMgr.deactivateLicense #

Overview
Description 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.
Supported on Android Since Version 9.6.0.821
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Syntax

LicenseActivationResponse deactivateLicense(License license)

Parameters

license - Object representing the License. Contains the product key

Return Value

Contains the result of deactivation.

In Java, it returns the object of LicenseActivationResponse.

Sample Code

License.getLicenseKey #

Overview
Description Returns the 29-character product key (including 4 dashes) from a license in the format XXXXX-XXXXX-XXXXX-XXXXX-XXXXX.
Supported on Android Since Version 9.6.0.821
Type Method
Package com.alk.cpik.licensing

Note: To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Syntax

String getLicenseKey( )

Parameters

None

Return Value

In Java, Returns a String representing the License key.

Sample Code

// Print out the value of a license key
try{
  License testLicense = new License("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");
  String keyString = testLicense.getLicenseKey();
  System.out.println("License key is: " + keyString);
}catch (LicenseException e){
  System.out.println("Exception! : " + e.toString());
}

LicenseStatus #

Overview

An enum that holds the list of all possible values that can be returned from LicenseMgr.getLicenseStatus(License).
Android Support
>=10.9.0.821
Type
Enum
Package
com.alk.cpik.licensing
Note
To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Values

Value Description
ACTIVATED Licensed and activated.
WILL_EXPIRE Licensed and activated, but the license will expire.
DEACTIVATED Licensed but not activated.
EXPIRED The license exists, but is expired.
FAILED_INVALID_LICENSE_KEY The provided license key is invalid.
FAILED_COPILOT_NOT_STARTED Cannot retrieve the status because CoPilot is not started.
UNKNOWN Other.

Hooks and Callbacks

Hooks and Callbacks related to Licensing can be found below.

LicenseListener

  • onFeatureActivated
  • onInAppPurchase
  • onLicensingReady
  • mapRegionUpgradeKeyHook

LicenseException #

Overview

An exception that is thrown when a licensing error occurs.
Android Support
>=10.9.0.821
Type
Class
Package
com.alk.cpik.licensing
Note
To receive relevant hooks and callbacks ensure LicenseListener.registerHook() and LicenseListener.registerListener() have been registered. Hooks and callbacks received through these are essential for identifying license-related events within CoPilot.

Hooks and Callbacks

Hooks and Callbacks related to Licensing can be found below.

LicenseListener

  • onFeatureActivated
  • onInAppPurchase
  • onLicensingReady
  • mapRegionUpgradeKeyHook
Last updated July 20, 2021.