CoPilot 11 Licensing Guide

Trimble is moving all CoPilot users to the Account Manager licensing model, replacing the old 25-character product keys. This change is recommended for CoPilot 10.19 and later, and it is required for CoPilot 11, which no longer supports product key licensing.

Account Manager benefits

Benefits for Trimble ELD/telematics partners:

• Track usage precisely for accurate, contract-based billing.
• Assign licenses to specific vehicles, devices, or drivers with ease.
• Manage multiple customer accounts from a single web application.

Benefits for fleets:

• Remotely create and assign vehicle routing profiles, map sets, and custom location content.
• Transfer app licenses to new assets quickly when equipment or staff changes occur.
• Customize CoPilot settings for your fleet, including safety alerts, warnings, and driver preferences.

Understanding the Account Manager model

With Account Manager, asset identification and management rely on distinct parameters rather than a shared 25-character activation code.

• Asset Identification: Account Manager identifies assets using Company ID + Asset ID/Vehicle ID/Driver ID (for fleets) or Partner ID + External Account ID + Asset ID/Vehicle ID/Driver ID (for Trimble ELD/telematics partners and their customers).
• Licensing Types: Choose one type when subscribing to Account Manager: Vehicle-based, Mobile-based, or Driver-based.
• Asset Uniqueness: The Asset ID, Vehicle ID, or Driver ID must be unique within each customer’s account.

Step 1: Contact Trimble support

Contact our support team to begin converting your product key accounts to Account Manager. The team will:

1. Confirm your fleet setup details, including your licensing type: Vehicle-based, Mobile-based, or Driver-based.
2. (For partners) Create a Development/Test sandbox to ensure that active drivers are not impacted during testing.
3. Help you set up your unique asset IDs through Account Manager API integration (or manually via the Account Manager web tool or import).
4. Ensure that fleet accounts are properly aligned so that trip and compliance data remain accessible from your existing fleet account in RouteReporter.

Step 2: CoPilot CPIK code changes

Updating the CoPilot application to support the new authentication only requires changing a few lines of licensing code.

1. First, review your assets and licenses in Account Manager. Log in to Account Manager to verify that your assets have been added and assigned licenses for CoPilot.

2. Deactivate legacy product key licenses. Use the LicenseMgr.deactivateLicense(License) API to deactivate currently active product key licenses. Pass the old product key as a parameter. Note: Keys cannot be deactivated while a route is actively in progress.

// Deactivate a product key license, and print the result of the deactivation
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());
}

3. Remove legacy licensing methods. This includes all existing implementations of LicenseListener.mapRegionUpgradeKeyHook and all calls to LicenseMgr.activateLicense, as these methods are no longer supported in Account Manager.
4. Set your Account Manager credentials. These credentials are AssetID (or DeviceID, DriverID, VehicleID, Username) and the 6-character CompanyID that Trimble generates when your account is created.

public static final String AMS_ASSET_ID = "YOUR_ASSET_ID";
public static final String AMS_COMPANY_ID = "YOUR_COMPANY_ID";

5. Create a LicenseMgtInfo object to contain login credentials.

LicenseMgtInfo licMgtInfo = new LicenseMgtInfo("AssetID", "CompanyID");

6. Login with these credentials.

LicenseMgr.updateCreds(licMgtInfo);

7. Implement callbacks. Add the onLicenseMgtLogin callback, which will fire to provide either confirmation of a successful license activation or the appropriate error code. Also add licenseMgtCredentialHook, which CoPilot calls automatically when it needs Account Manager credentials. It must return a LicenseMgtInfo instance.

8. Provide or refresh credentials from app code (if needed). If your application needs to supply or refresh Account Manager credentials explicitly (for example, during onCPStartup()), call LicenseMgr.updateCreds(...) with a LicenseMgtInfo instance. Do not call LicenseMgr.updateCreds(...) from inside licenseMgtCredentialHook() or call licenseMgtCredentialHook() directly.

9. Manage maps (optional). You may optionally choose to use Account Manager Map Sets to manage map data and updates, which allows you to completely remove legacy map management code from your application.

Step 3: Production setup and cutover (for partners)

Once sandbox testing is complete, proceed with the production rollout following these steps:

1. Create Customer Accounts. Trimble will provision production customer accounts for each of your end-customers.
2. Provision Assets. Verify that every asset exists in Account Manager and has an active Licensing SKU assigned.
3. Cutover from product keys. Migrate client devices to the new mobile app and CPIK incrementally. Before migrating each device, confirm that its unique AssetID exists in Account Manager with an assigned license.