Skip to main content

URL Launch (Single URL)

Contents

Requires CoPilot 10.26.1.345 and later

CoPilot’s URL launch feature allows you to launch and manage CoPilot from another application on the same device.

With older versions of CoPilot, URL launch tasks are completed with a series of URL commands. With CoPilot 10.26.1.345 and later, a single URL command can now be used to perform multiple actions. You can:

  • Activate a License (using an AssetID, CompanyID, ExternalAccountID, or PartnerID). This automates the process of activating licenses that you have distributed to your devices using Trimble Maps Account Manager.
  • Connect to Fleet settings. Each instance of CoPilot needs to know which Vehicle or Driver is using it at any given time. CoPilot will update its settings according to the Fleet Settings in Account Manager for the vehicle or driver associated with that instance of CoPilot.
  • Select a Vehicle Routing Profile and send a single stop or multiple stops to CoPilot to build a route. You also have the option to add a stop duration and a time window for each stop.

URL format

The format for sending multiple commands in a single URL is a base URL plus a JSON string that is encoded in Base64 format.

Base URL

copilot://options?type=TASKS&JSON=

Example with encoded JSON

(This example shows an encoded message with a single stop trip and a showConfirmation command. )

copilot://options?type=TASKS&JSON=ewogICAgInNob3dDb25maXJtYXRpb24iOiB0cnVlLAogICAgInRyaXAiOiB7CiAgICAgICJzdG9wcyI6IFsKICAgICAgICB7CiAgICAgICAgICAibG9jYXRpb24iOiB7CiAgICAgICAgICAgICJhZGRyZXNzIjogewogICAgICAgICAgICAgICJzdHJlZXRBZGRyZXNzIjogIjEgRSAxNjEgU3QiLAogICAgICAgICAgICAgICJjaXR5IjogIlRoZSBCcm9ueCIsCiAgICAgICAgICAgICAgInN0YXRlIjogIk5ZIiwKICAgICAgICAgICAgICAiemlwIjogIjEwNDUxIgogICAgICAgICAgICB9CiAgICAgICAgICB9CiAgICAgICAgfQogICAgICBdCiAgICB9CiAgfQ==

JSON formats by task

Activate a license

If you assign CoPilot licenses to your devices using Account Manager (AMS), the commands below can be used to activate a license on a device. There are two formats: One for fleets who purchase and install CoPilot directly, and one for ELD providers and other Trimble Maps partners who resell CoPilot as an add-on for their customers.

URL Format for direct CoPilot customers

Parameter Description Type Required
AssetID The identifier for the asset to which a license is assigned in Account Manager. (Often, but not always, a Vehicle ID) alphanumeric Y
CompanyID The company account identifier assigned by Trimble Maps. alphanumeric Y

Example JSON

{
  "Ams": {
    "AssetID": "asset.id",
    "CompanyID": "trimble-defined.customer.id"
  }
}

URL format for partners reselling CoPilot

Parameter Description Type Required
AssetID The identifier for the asset to which a license is assigned in the Account Manager. (Often, but not always, a Vehicle ID) alphanumeric Y
ExternalAccountID The partner’s existing account identifier for their customer who is deploying CoPilot. alphanumeric Y
PartnerID The partner identifier assigned by Trimble Maps. alphanumeric Y

Example JSON

{
  "Ams": {
    "AssetID": "partner-defined.asset.id",
    "ExternalAccountID": "partner-defined.account.id",
    "PartnerID": "sample-partner"
  }
}

Connect to Fleet Settings (formerly FleetPortal)

URL launch can be used to set up a device so it can connect to Fleet Settings in Account Manager (formerly FleetPortal). These settings allow fleet managers to remotely configure CoPilot vehicle settings, such as vehicle routing profiles, to be used by the fleet.

Account Manager users

If you are using Account Manager to assign your CoPilot licenses to vehicles or drivers, Fleet Settings are applied automatically when you activate a license on a device.

An exception would be if you are using unique device IDs rather than vehicle or driver IDs to track your licenses in Account Manager. In that case, you would:

  • Set the AssetID to the device ID used in Account Manager when activating a license.
  • Set DeviceID (see below) to the appropriate vehicle ID used in Fleet Settings. That ensures CoPilot has the correct settings if the device is moved from vehicle to vehicle.

If you are using URL launch, but are not using Account Manager to assign CoPilot licenses, the settings below are required to connect to Account Manager’s Fleet Settings.

Parameter Description Type
DeviceID Identifies a specific CoPilot device within the direct customer or partner domain. alphanumeric
PartnerID An identifier created by Trimble Maps and supplied to the partner for use in identifying their customers’ CoPilot units within Account Manager. alphanumeric
DriverID Identifies a specific driver within a company. alphanumeric
EnableCompliance Set to true to turn on route compliance. (Requires license for RouteReporter) boolean
EnableFleetPortal Set to true to enable Account Manager’s Fleet Settings on the device. boolean
ForceSync Set to true to trigger a sync with Account Manager’s Fleet Settings without restarting CoPilot. This helps ensure CoPilot has the most current settings. boolean

Example JSON

{
  "FleetPortal": {
    "DeviceID": "customer-defined.deviceID",
    "PartnerID": "trimble-defined.partner.id",
    "DriverID": "customer-defined.driverID",
    "EnableCompliance": true,
    "EnableFleetPortal": true,
    "ForceSync": true
  }
}

Example JSON

{
  "FleetPortal": {
    "ForceSync": true
  }
}

Select a vehicle routing profile and send stops

If CoPilot does not have an active trip, you can set the Vehicle Routing Profile that CoPilot uses to generate a safe and legal route. You can also send a single stop or multiple stops to CoPilot to build a route, and optionally add a stop duration and time windows for each stop.

Parameter Description Type
RoutingProfile Sets the active vehicle routing profile. The profile is selected by name, including company profiles created in Account Manager. If a trip is dispatched and a match is not found for the vehicle routing profile, the user will be prompted to select a vehicle routing profile for the dispatched trip. alphanumeric
Stops An array that holds Location objects with information about each stop in a trip. The examples below show the format for a Location object. object array
Location An object that holds stop information such as an address, coordinates, label, or StopType. If both an address and coordinates are provided, coordinates will take precedence over the address for plotting the stop on the map. object
Address An object that holds the address information. object
AddressStreetAddress, City, State, Zip, County, Country Available fields for the Address object. We recommend that you provide as much detailed, accurate information as possible to ensure CoPilot can properly geocode the address. string
Coords An object that holds coordinate information—latitude and longitude. object
CoordsLat, Lon Fields that contain information about latitude and longitude respectively. Coordinates are entered in decimal degrees format. We recommend at least six digits after the decimal point to improve precision. string
StopType An optional field that indicates if a stop is a waypoint by setting its value to Waypoint. Otherwise, it is considered a stop by default. A waypoint modifies the route path so it passes through a specified point, without acting as a full stop for a pickup, a delivery, or a rest break. string
PlannedDuration Planned duration for the stop. This should reflect all the non-driving (dwell) time at the stop. This value is used for ETA calculations unless CoPilot is licensed for advanced optimization. integer
EarliestArrivalTime Earliest acceptable arrival time when the stop can be reached. If no date is given, the current date will be used. The value must be in ISO-8601 format. It is used for ETA calculations unless CoPilot is licensed for advanced optimization. alphanumeric
LatestArrivalTime Latest arrival time for the time window during which the stop should be reached. If no date is given, the current date will be used. The value must be in ISO-8601 format. It is used for ETA calculations unless CoPilot is licensed for advanced optimization. alphanumeric
atRiskThreshold Number of minutes prior to the end of the delivery window at which the driver is considered “at risk” for missing the window. integer
CustomPlaceID
Available in CoPilot 10.26.1.585 and Higher
An identifier assigned by your company for the Place. string

Note on added stops and current location

  • If you send a single stop, CoPilot will insert the Current (GPS) Location as the first stop (origin) of the trip on the PLAN screen and the stop you entered via URL as the destination.

  • If you send more than one stop, the device’s Current (GPS) Location will replace the first stop in your list of stops once the driver taps the navigation button to begin the trip. If you do not want the current location to replace your first stop, you can either:

    1. Send a duplicate of the first stop. CoPilot will replace the first of those stops with the current GPS position and set the second as the first stop in the trip.
    2. Send as your first stop the location where you expect the driver to begin their trip. (A depot, for example.)

Example JSON for North America This example is a multi-stop route showing multiple ways to send stops, including by Address, by Coords, and by CustomPlaceID.

{
  "showConfirmation": true,
  "Trip": {
    "Stops": [
      {
        "Location": {
          "Label": "Yankee Stadium",
          "Address": {
            "StreetAddress": "1 E 161 St",
            "City": "Bronx",
            "State": "NY",
            "Zip": "10451",
            "County": "NY"
          },
          "Coords": { "Lat": "40.829611", "Lon": "-73.926211" }
        },
        "PlannedDuration": 120,
        "AtRiskThreshold": 10,
        "EarliestArrivalTime": "2024-05-23T10:20:35-04:00",
        "LatestArrivalTime": "2024-05-23T11:20:35-04:00"
      },
      {
        "Location": {
          "Address": {
            "StreetAddress": "881 7th Avenue",
            "City": "New York",
            "State": "NY",
            "Zip": "10019",
            "County": "New York",
            "Country": "US"
          }
        },
        "PlannedDuration": 80,
        "AtRiskThreshold": 10,
        "EarliestArrivalTime": "2024-05-23T11:50:35-04:00",
        "LatestArrivalTime": "2024-05-23T12:50:35-04:00"
      },
      {
        "Location": {
          "Address": {
            "StreetAddress": "Independence Way",
            "City": "Princeton",
            "Zip": "08540",
            "State": "NJ"
          }
        },
        "PlannedDuration": 1576,
        "AtRiskThreshold": 10,
        "EarliestArrivalTime": "2024-05-24T15:16:35-04:00",
        "LatestArrivalTime": "2024-05-24T16:16:35-04:00"
      },
      {
        "Location": { "CustomPlaceID": "DOROT" }
      }
    ]
  }
}

Example for AMS activation, trip stops, and setting a vehicle routing profile

{
  "Ams": {
    "AssetID": "customer-defined.asset.id",
    "CompanyID": "trimble-defined.customer.id"
  },
  "Trip": {
    "RoutingProfile": { "Name": "routingProfileName" },
    "Stops": [
      {
        "Location": {
          "Address": {
            "StreetAddress": "881 7th Avenue",
            "City": "New York",
            "State": "NY",
            "Zip": "10019",
            "County": "New York",
            "Country": "US"
          }
        }
      },
      {
        "Location": {
          "Label": "City Hall",
          "Address": {
            "StreetAddress": "1400 John F Kennedy Blvd",
            "City": "Philadelphia",
            "State": "PA",
            "Zip": "19107",
            "County": "PA"
          },
          "Coords": {
            "Lat": "39.9527572",
            "Lon": "-75.1638264"
          }
        },
        "StopType": "Waypoint"
      },
      {
        "Location": {
          "Label": "Yankee Stadium",
          "Address": {
            "StreetAddress": "1 E 161 St",
            "City": "The Bronx",
            "State": "NY",
            "Zip": "10451",
            "County": "NY"
          },
          "Coords": {
            "Lat": "40.829611",
            "Lon": "-73.926211"
          }
        }
      }
    ]
  }
}

Testing URL launch task functionality

You can add a ShowConfirmation parameter to your JSON if you would like a message displayed in CoPilot that confirms the settings you passed have been successfully configured.

{
    "ShowConfirmation": true,
    "Trip": {
      "Stops": [
        {
          "Location": {
            "Address": {
              "StreetAddress": "1 E 161 St",
              "City": "The Bronx",
              "State": "NY",
              "Zip": "10451"
            }
          }
        }
      ]
    }
  }
Last updated February 27, 2024.