LicenseMgr (CPIK Libraries)

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

Public Constructors

Methods

String

String

String

String

String

LicenseMgtInfo Object

Note on setting the AssetID

If you are activating licenses on mobile devices that may be moved from vehicle to vehicle, you first need to set the deviceID prior to activating a license using the assetID. Setting the deviceID ensures that CoPilot applies the proper Account Manager settings on that device.

You can set the deviceID in one of these two callbacks:

• onCPStartup()
• licenseMgtCredentialHook()

LicenseMgr.updateCreds(LicenseMgtInfo licMgtInfo)

Syntax

void LicenseMgr.updateCreds(LicenseMgtInfo)

Parameters

LicenseMgtInfo - Object representing the login information from Account Manager.

Sample Code

// Create the LicenseMgtInfo object
LicenseMgtInfo licMgtInfo = new LicenseMgtInfo(“AssetID”, “CompanyID”);

// Attempt login with these credentials
LicenseMgr.updateCreds(licMgtInfo);

NSString *assetID = @”AssetID”;
NSString *companyID = @”CompanyID”;
// Create the LicenseMgtInfo object
LicenseMgtInfo *licMgtInfo = [[LicenseMgtInfo alloc]initWithVals:assetID withCompanyID:companyID];

// Attempt login with these credentials
[LicensingMgr updateCreds:licMgtInfo];

Hooks and Callbacks

LicenseListener onLicenseMgtLogin

LicenseMgr.getActiveAMSUser()

Syntax

LicenseMgtInfo LicenseMgr.getActiveAMSUser()

Return Values

A LicenseMgtInfo object representing the login information from Account Manager. This object’s fields are all empty if there is no Account Manager user logged in.

Sample Code

LicenseMgtInfo licMgtInfo = LicenseMgr.getActiveAMSUSer();
if (licMgtInfo.assetID.equals(“”))
    System.out.println(“No AMS User logged in”);
if (!licMgtInfo.companyID.equals(“”))
    System.out.println(“AssetID: “ + licMgtInfo.assetID + “ | CompanyID: “ + licMgtInfo.companyID);
else
    System.out.println(“AssetID: “ + licMgtInfo.assetID + “ | ExternalAccountID: “ + licMgtInfo.externalAccountID + “ | PartnerID: “ + licMgtInfo.partnerID);

License

Public Constructors

Methods

String

Sample Code

// Create a license

try {
  License licObject = new License("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");
  // Further code related to activation after license check
} catch (LicenseException e) {
  System.out.println("Exception! :" + e.toString());
}

NSString *key = @"ABCDE-01234-FGHIJ-56789-KLMNO";
License *lic = [[License alloc] initWithLicenseKey:key];
public class LicSampleActivity
{
  // This method is necessary for generic enterprise builds
  private LicenseListener m_LicenseHook = new LicenseListener()
  {
    // Send in the map region upgrade key for generic enterprise build
    @Override
    public License mapRegionUpgradeKeyHook()
    {
      String upgradeKeyString = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX";
      try {
        return new License(upgradeKeyString);
      } catch (Exception e) { return null; }
    }
  };
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    // start CoPilot in background
    Intent intent = new Intent(this, CopilotService.class);
    bindService(intent, mCopilotServiceConnection, Context.BIND_AUTO_CREATE);
    LicenseListener.registerHook(m_LicenseHook);
  }
}

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 LicenseListener m_LicenseHook = new LicenseListener() {

    @Override
    public License mapRegionUpgradeKeyHook() {
        makeToast("mapRegionUpgradeKeyHook received");

        // You can hardcode your key here or provide the key in key.txt
        String upgradeKeyString = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX";

        try {
            makeToast("mapRegionUpgradeKeyHook returning " + upgradeKeyString);
            return new License(upgradeKeyString);
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }
};

• 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

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

boolean isLicensingReady = LicenseMgr.isLicensingReady();
if (!isLicensingReady) {  System.out.println("Licensing is not ready");
  return; }

//Do further operation i.e activate license

if ([LicensingMgr isLicensingReady])
 NSLog(@"Licensing Ready!");
else
 NSLog(@"Licensing Not Ready!");

LicenseMgr.activateLicense (License key)

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

// Create a new license, activate it, and print the result of the activation
try {
  License testLicense = new License("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");
  LicenseActivationResponse response = LicenseMgr.activateLicense(testLicense);
  if (response == LicenseActivationResponse.SUCCESS)
  System.out.println("License activation successful");
  else
  System.out.println("License activation error: " + response.toString());
} catch (LicenseException e) {
  System.out.println("Exception! : " + e.toString());
}

NSString *key = @"ABCDE-01234-FGHIJ-56789-KLMNO";
License *lic = [[License alloc] initWithLicenseKey:key];
[LicensingMgr activate:lic]

LicenseMgr.activateLicense (License Key and Device ID)

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

// Create a new license, activate it, and print the result of the activation
try {
  License testLicense = new License("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");
  String deviceID = "84a3c2116f1";// Put your device id
  LicenseActivationResponse response = LicenseMgr.activateLicense(testLicense,
deviceID);
  if (response == LicenseActivationResponse.SUCCESS)
    System.out.println("License activation successful");
  else
    System.out.println("License activation error: " + response.toString());
} catch (LicenseException e) {
  System.out.println("Exception! : " + e.toString());
}

NSString *key = @"ABCDE-01234-FGHIJ-56789-KLMNO";
License *lic = [[License alloc] initWithLicenseKey:key];
[LicensingMgr activateWithDeviceId:lic]

LicenseActivationResponse

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

Values for Account Manager Login

Used with the onLicensingMgtLogin callback

LicenseMgr.getLicenseStatus

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

// Create a new license, get its status, and print
try {
  License testLicense = new License("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");
  LicenseStatus status = LicenseMgr.getLicenseStatus(testLicense);
  switch (status) {
    case ACTIVATED: // This is Enum from LicenseStatus class
    System.out.println("Licensed and activated");
    break;
    case WILL_EXPIRE:
    System.out.println("Licensed but will expire");
    break;
    case DEACTIVATED:
    System.out.println("Licensed but not activated");
    break;
    case EXPIRED:
    System.out.println("License exists, but is expired");
    break;
    case FAILED_INVALID_LICENSE_KEY:
    System.out.println("The license key is invalid");
    break;
    case FAILED_COPILOT_NOT_STARTED:
    System.out.println("CoPilot has not yet started, so the status cannot be determined");
    break;
    default:
    System.out.println("General error");
    break;
  }
} catch (LicenseException e) {
  System.out.println("Exception! : " + e.toString());
}

License *license = [[License alloc]initWithLicenseKey:licenseKey];
CPLicenseActivationStatus status =
[LicensingMgr getLicenseStatus:license];

LicenseFeature.getFeatureStatus

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

// Print out the current status of the traffic license feature
FeatureStatus trafficStatus = LicenseFeature.TRAFFIC.getFeatureStatus();

switch (trafficStatus) {
  case LICENSED:
  System.out.println("Traffic is licensed and available");
  break;
  case UNLICENSED:
  System.out.println("Traffic is not licensed");
  break;
  case UNLIMITED:
  System.out.println("Traffic is licensed and has no expiration date");
  break;
  default:
  System.out.println("The status of traffic is not known");
  break;
}

LicenseFeature *licFeature =
[[LicenseFeature alloc]initWithLicenseFeature:CPLicenseFeatures_Traffic];
 CPFeatureStatus status = [licFeature getFeatureStatus];

FeatureStatus

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

LicenseFeature

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

LicenseFeature.getDaysRemaining

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

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

// Create a new license, deactivate it, and print the result of the activation
try {
  License testLicense = new License("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");
  LicenseActivationResponse response = LicenseMgr.deactivateLicense(testLicense);
  if (response == LicenseActivationResponse.SUCCESS)
    System.out.println("License deactivation successful");
  else
    System.out.println("License deactivation error: " + response.toString());
} catch (LicenseException e) {
  System.out.println("Exception! : " + e.toString());
}

NSString *key = @"ABCDE-01234-FGHIJ-56789-KLMNO";
License *lic = [[License alloc] initWithLicenseKey:key];
[LicensingMgr deactivate:lic]

License.getLicenseKey

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

Values

Hooks and Callbacks

Hooks and Callbacks related to Licensing can be found below.

LicenseListener

• onFeatureActivated
• onInAppPurchase
• onLicensingReady
• mapRegionUpgradeKeyHook

LicenseException

Overview

Hooks and Callbacks

Hooks and Callbacks related to Licensing can be found below.

LicenseListener

• onFeatureActivated
• onInAppPurchase
• onLicensingReady
• mapRegionUpgradeKeyHook