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 the 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 configuration in FleetPortal 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. 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.

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. See below for examples of Base64 encoding of JSON strings in different languages and platforms.

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 (FleetPortal)

URL launch can be used to set up a device so it can connect to FleetPortal. FleetPortal is a web tool that allows fleet managers to remotely configure CoPilot vehicle settings and vehicle routing profiles and to assign specific routing profiles to vehicle and driver groups within the fleet.

Account Manager users

If you are using Account Manager to assign your CoPilot licenses to vehicles or drivers, FleetPortal 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 FleetPortal. That ensures CoPilot has the correct settings if the device is moved from vehicle to vehicle.

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 CoPilot FleetPortal.	`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 FleetPortal on the device.	`boolean`
`ForceSync`	Set to true to trigger a sync with FleetPortal 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

Parameter	Description	Type
`RoutingProfile`	Sets the active vehicle routing profile. The profile is selected by name, including company profiles created in FleetPortal/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`
`Address` → `StreetAddress`, `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`
`Coords` → `Lat`, `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`

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

{
    "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",
            "Coords": {
              "Lat": "40.829611",
              "Lon": "-73.926211"
            }
          }
        }
      ]
    }
  }

Example JSON for Europe

{
   "Trip":{
      "RoutingProfile":{
         "Name":"routingProfileName"
      },
      "Stops":[
         {
            "Location":{
               "Label":"P1",
               "Address":{
                  "StreetAddress":"16 St Cross St",
                  "City":"London",
                  "State":"",
                  "Zip":"EC1N 8EL",
                  "County":"",
                  "Country":"UK"
               },
            }
         },
         {
            "Location":{
               "Label":"Eso",
               "Address":{
                  "StreetAddress":"387 Edgware road",
                  "City":"london",
                  "State":"",
                  "Zip":"GB nw2 6",
                  "County":"",
                  "Country":"GB"
               },
               "Coords":{
                  "Lat":"51.56637",
                  "Lon":"-0.22614"
               }
            }
         },
         {
            "Location":{
              "Label":"point",
              "Coords":{
                  "Lat":"51.533867",
                  "Lon":"-0.239475"
               }
            }
         }
      ]
   }
}

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"
            }
          }
        }
      ]
    }
  }

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION

INTERACTIVE MAPS

URL Launch (Single URL)

URL format

JSON formats by task

Activate a license

URL Format for direct CoPilot customers

URL format for partners reselling CoPilot

Connect to fleet settings (FleetPortal)

Account Manager users

Select a vehicle routing profile and send stops

Added stops and current location

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

Testing URL launch task functionality