URL Launch (Single URL)

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

Example JSON

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

URL format for partners reselling CoPilot

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.

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.

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": {
    "ExternalTripId" : "SampleExternalTripId",
    "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"
            }
          }
        }
      ]
    }
  }