URL Launch (Multiple URLs)

This page includes instructions for URL launch using multiple URL commands to accomplish individual tasks. Starting with CoPilot 10.26.1.345, multiple tasks can be sent in a single URL command.

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

URL launch is most commonly used with our CoPilot Standalone App as a way of automating the CoPilot login process; identifying which vehicle or driver is using CoPilot; and adding a button to CoPilot that sends it to the background and returns to the mobile app from which it was launched.

Depending on your implementation, URL launch can be used for a wide range of tasks and settings. Passing information to CoPilot via URL, you can:

• Activate a license. This automates the process of activating licenses that you have distributed to your devices using the Trimble Maps Account Manager. Available in CoPilot 10.19 and Later with Account Manager Licensing Only

• Identify the vehicle and driver using CoPilot. 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 (formerly FleetPortal) for the vehicle or driver associated with that instance of CoPilot. Available in CoPilot 10.19 and Later with Account Manager Licensing Only

• Set configurations. CoPilot can be configured to meet your fleet’s specific needs. Settings are available that allow to you to customize everything from the information that appears on the CoPilot screen to the language CoPilot uses for voice guidance. Available in CoPilot 10.19 and Later

• Send a single stop or multiple stops to CoPilot to build a route. Pass a single stop or multiple stops into CoPilot, all at once, to build a full trip. Available in CoPilot 10.19 and Later with Account Manager Licensing Only

• Send a single stop to CoPilot and view it on the map. This feature, which is compatible with older versions of CoPilot, allows you add stops on an itinerary, one-by-one, as GPS coordinates.

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

• Select a Vehicle Routing Profile. 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. Available in CoPilot 10.19.4.348 and Later

Note: URL launch is only supported on our Truck licensed application.

Activate a License

Available in CoPilot 10.14 and Later with Account Manager Licensing Only

The Account Manager is a web tool that allows you to distribute and manage the product licenses your fleet has purchased for CoPilot Truck With ActiveTraffic. In the Account Manager, you can create lists of users (either vehicles, devices, or drivers), remotely distribute software licenses to those users, and then re-assign your licenses as needed when your devices or staffing change.

After the licenses are distributed, the CoPilot app itself is downloaded onto a device and requires a login. With URL launch, the login process is automated and drivers can open CoPilot and begin navigation without needing to enter login credentials.

URL Format for Direct CoPilot Customers

Available in CoPilot 10.19 and Later

copilot://options?type=CONFIG&CompanyID=trimble-defined.customer.id&AssetID=customer-defined.asset.id&showconfirmation=true

URL Format for Partners Reselling CoPilot

Available in CoPilot 10.19 and Later

copilot://options?type=CONFIG&PartnerID=sample-partner&ExternalAccountID=partner-defined.account.id&AssetID=partner-defined.asset.id&showconfirmation=true

URL Format for Activation with Product Key

Available in CoPilot 10.19.4.348 and Later

Customers using traditional enterprise and non-enterprise upgrade product keys can activate a license in CoPilot using the following URL:

copilot://options?type=Activation&ProductKey=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx

This must be sent as a separate config in URL launch. It cannot be combined with other configs and it cannot be sent with stops.

Identify the Vehicle and Driver

Available in CoPilot 10.19 and Later

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 Account Manager for the vehicle or driver associated with that instance of CoPilot. CoPilot also uses this vehicle and driver identification to populate reports in the various web tools, including add-on RouteReporter compliance reporting, and for tagging driver feedback in the MapSure web tool.

copilot://options?type=CONFIG&VehicleID=partner-defined.vehicle.id&DriverID=partner-defined.driver.id

Set Configurations

Available in CoPilot 10.19 and Later

CoPilot offers a wide variety of configuration settings that allow you to customize how the app looks and how certain features behave. With URL launch, the same settings can be deployed for each device when rolling out a deployment to multiple users.

URL Format

The format below allows you to pass as many configuration settings as you need, all at once.

copilot://options?type=CONFIG&ConfigName=ConfigValue&ConfigName=ConfigValue

Examples

Single Configuration

copilot://options?type=CONFIG&DownloadDataOnSDCard=true

Multiple Configurations

copilot://options?type=CONFIG&DownloadDataOnSDCard=true&SayWelcome=true&FlowTrafficEnabled=false

Config Names and Values

The Configname parameter can be entered as:

• The configuration name used in the user.cfg file. (Generic Style)

• The name used in passing that configuration via our CPIK libraries APIs. (CPIK Style)

• A combination of both. See a full list of configuration settings.

For example, to enable traffic on a device, you can enter either:

• &FlowTrafficEnabled=true (Generic Style)

• &FLOW_TRAFFIC_AVAILABILITY=true (CPIK Style)

The ConfigValue parameter can entered as:

• True/false, if it is a boolean value.

• One of the values used in our CPIK libraries APIs.

For example, for that same traffic setting above, you can enter either:

• &FlowTrafficEnabled=true

• &FLOW_TRAFFIC_AVAILABILITY=FLOW_TRAFFIC_ENABLED

Confirmation Message

You can add a “show confirmation” parameter to your URL if you would like a message displayed in CoPilot that confirms the settings you passed have been successfully configured.

Examples

//Generic Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&showconfirmation=true

//CPIK Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&SETTINGS_CONFIRMATION_DIALOG=true

Global Restart

Some configuration settings don’t take effect until CoPilot has been restarted. You can add a restart parameter to your URL to restart CoPilot after a configuration is set.

// Generic Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&RestartCoPilot=true

// CPIK Style
copilot://options?type=CONFIG&FLOW_TRAFFIC_AVAILABILITY=true&RESTART_COPILOT=true

Return to Previous App Button

Available in CoPilot 10.19 and later(Android Only)

A button can be added to the CoPilot user interface that allows the user to return to the application from which CoPilot was launched. Two configuration settings are required to add this button.

To enable the button:

• &EnableCustomButton=true

To set which app should be switched to when pressing the button:

• &AppLaunchBundleID=bundle.id.of.application

Select a Vehicle Routing Profile

Available in CoPilot 10.19.4.348 and Later

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.

The profile must be sent as a separate config in URL launch. It cannot be combined with other configs and it cannot be sent with stops.

copilot://options?type=VehicleProfile&SelectByName=Heavy Duty

Send Stops

Available in CoPilot 10.19 and Later

URL launch can pass a single stop or multiple stops into CoPilot, all at once, to build a full trip. All successfully geocoded stops are shown in the PLAN screen once CoPilot is launched, and driver just needs to tap the green navigate button to get started on his or her route.

The list of stops passed via URL replace any existing stops in CoPilot. Stop location information can be passed into CoPilot in any of the following ways:

• As a full address
• As lat/lon coordinates only
• As a partial address
• As an address and a single search string
• As a single string search only

URL Format

The base URL for entering multiple stops is:

copilot://options?type=STOPS

There are two parameters available to enter stops:

• stop The stop parameter allows you to enter details about a location as individual “fielded” values—name, address, city, ZIP/postcode, etc. CoPilot will geocode the location using the map data stored on the device before adding it to a route.

• query The query parameter allows you to enter details about a location as a single string of text, similar to how you query an internet search engine. CoPilot will query our single search web service to geocode the location before adding it to a route. This method requires a reliable internet connection on the device.

Using the Stop Parameter

A stop is entered using the following format:

copilot://options?type=STOPS&stop=name|address1|city1|zip1|juris1|state1|lat1|long1&stop=name|address2|city2|zip2|juris2|state2|lat2|long2

Each field in a stop is segmented with a “|” (Pipe) and an ampersand (&) is used to separate the stops from each other. In addition, you can add a name field for each stop to help differentiate them.

• 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.)

Note: There is no limit on the number of stops you can pass when sending them in an Android or iOS environment. Some web browsers, however, limit URIs to 2,000 characters. Also, the following characters should not be included in the name of a stop as they are used as delimiters when parsing the “STOP” parameter for a URL.

• & This is used as a delimiter for separating URL parameters.
• = This is used as a delimiter immediately following “STOP”.
• | This is used as a delimiter for separating stop fields.

Stop Fields

Stop Examples

There are no required fields when passing a location, although we recommend entering as much information as possible to improve location accuracy.

Full Address

copilot://options?type=STOPS&stop=City Hall|1400 John F Kennedy Blvd|Philadelphia|19107|PA|PA|39.9527572|-75.1638264&stop=Yankee Stadium|1 E 161 St|The Bronx|10451|NY|NY|40.829611|-73.926211&externalTripId=SampleExternalTripId

Partial Address

Partial address information can be passed by leaving empty the fields you are not including.

copilot://options?type=STOPS&stop=Old Office|||WC1A 2RP||GB||

Lat/Lon Coordinates Only

Coordinates can be sent in a decimal format (ex. 51.518220, -0.122805,) or as long integers (+51518220, -122805). When entering latitude and longitude, “+” is optional however “-“ is mandatory where required.

copilot://options?type=STOPS&stop=Old Office||||||51.51880|-0.122805&stop=New Office||||||51.51883|-0.122890

Note: When you pass a latitude and longitude value as well as the street address, CoPilot will prioritize the information provided.

• Scenario 1 – Only the full address is passed - CoPilot will try to geocode the address.
  
  
• Scenario 2 – Only lat/long is passed - CoPilot will try to use lat/long to provide the route.
  
  
• Scenario 3 – Both Address and lat/long are passed
  • CoPilot will geocode the address and compare the air distance between the address location and the input lat/lon. If the input street name is within 1 mile of the input lat/lon, then CoPilot will route to a point closest to the lat/lon on that input street. If the input street name is not within 1 mile of the input lat/lon, CoPilot will route to a point on the closest street to the input lat/lon. It will also send “ERROR_STREET_NOT_FOUND.”

Tip: When passing UK Postcodes, please note they will be used as the sole location for geocoding an address. UK postcodes are simply lat/long points and are a useful tool to quickly geocode an address. As a result, when passing a UK postcode and a lat/long, CoPilot will geocode the postcode not the lat/long. It is not advised that both UK postcode and lat/long coordinates are passed together. We recommend the following:

• If you have lat/long for a destination, pass the lat/long. Optional extras include House Number, Street Name, City Name, Country. Do not include UK Postcode if you have a lat/long for a destination.

• If you pass a UK postcode, optional extras include House Number, Street Name, City Name, Country.

Using the Query Parameter

A single string location query can be sent on its own or in addition to address information.

Search Query Alone

copilot://options?type=STOPS&query=Rogers Centre|1 Blue Jays Way, Toronto, ON M5V 1J1, Canada

Combination Address and Single Search

Combining address information with a single string query can help narrow and improve your results. For example:

copilot://options?type=STOPS&stop=Old Office|||WC1A 2RP|||GB||&query=Office|29 Bloomsbury Square, London

In the example above, the search engine will only look for a match to “29 Bloomsbury Square” in the “WC1A 2RP” postal code in the country of “GB” (Great Britain).

Similarly, if you add a lat/lon to the search, it will be set as the center of the search area. If a street matching the address you entered is found nearby, the address will be used. If a street match is not found, the lat/long is reverse geocoded and the address portion of the string is returned as the street.

Send stops using a customPlaceID

(Available in CoPilot 10.26.1.585 and Later)

Stops can be sent using a customPlaceID, which is an identifier assigned by your company for a Place. The query must follow the format below:

copilot://options?type=STOPS&query=customPlaceID&IncludeCustomPlaceIdOnly=true

Send a Single Stop

With older versions of CoPilot (below 10.9), URL launch was used only to launch CoPilot, send in a single stop on a route, or view a single location on the map. These features are still available with the latest versions of CoPilot.

A single location is passed via URL with one of three actions:

• VIEW: Show the location on the map.

• GOTO: Clear the current trip and set the location as the only destination.

• ADDNEXTSTOP: Add the location as a new stop ahead of any stops currently in the trip itinerary.

The location can be entered as GPS coordinates or as a street address. If both are entered, the coordinates will be used. Once the location has been identified, CoPilot will perform the corresponding action passed in by the action parameter. If a location cannot be found, CoPilot will ignore the location and no action will be taken.

URL Format

copilot://mydestination?type=LOCATION&action=%act&lat=%la&long=%lo&name=%name&address=%addr&city=%city&juris=%jurisdiction&state=%state&zip=%zip

This format is supported on Android, iOS and Windows platforms. For CoPilot 9, the base URL copilotv9:// can also be used.

Example Strings

copilot://mydestination?type=LOCATION&action=VIEW&lat=+40388249&long=-74654724
copilot://mydestination?type=LOCATION&action=ADDNEXTSTOP&address=1000HerrontownRoad&city=Princeton&state=NJ&zip=08540
copilot://mydestination?type=LOCATION&action=GOTO&lat=+40388249&long=-74654724

URL Parameters

Notes on Parameters

1. When latitude and longitude values are sent as long integers, they are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, our London office is located at 0.122805W & 51.518220N so it should be passed as a -122805 longitude & +51518220 latitude. Conversion to long integers is not mandatory as coordinates sent in a decimal format are also supported within CoPilot.
2. When entering latitude and longitude, “+” is optional however “-“ is mandatory where required.
3. Query names are case sensitive.
4. To best find a destination, you should supply one of the two following combinations of data:
   • Latitude and Longitude
   • Address, City, State/Jurisdiction, ZIP
5. GOTO and ADDNEXTSTOP will work as described if user is on navigation mode. If user is in planning mode they may get different result.
6. The Name field is limited to 164 characters.
7. When a stop is passed to CoPilot with action command ADDNEXTSTOP, the device’s GPS fix status may affect this command:
   • With a GPS fix, action commands will take effect as described above.
   • Without a GPS fix and gpssave.dat/gpstrip.trp files in CoPilot folders: Next Stop function will not add a stop but replace the existing one.
   • With a GPS fix and a stop set: When a house number is included with an address, the CoPilot UI ask to set the stop as the destination, but when you use the ADDNEXTSTOP action it will be added as the next stop, not the destination.

Legacy Format

Some existing Android implementations may use the copilotlive.com format below for URL launch. It will continue to be supported, but we recommend that all new implementations use the copilot:// format listed above. The copilotlive.com format is also not fully compatible with devices running Android 12 and later. See note below.

http://www.copilotlive.com/copilot/android?type=LOCATION&action=%act&lat=%la&long=%lo&name=%name&address=%addr&city=%city&juris=%jurisdiction&state=%state&zip=%zip

Example Strings

http://www.copilotlive.com/copilot/android?type=LOCATION&action=VIEW&lat=+40388249&long=-74654724
http://www.copilotlive.com/copilot/android?type=LOCATION&action=ADDNEXTSTOP&address=1000 Herrontown Road&city=Princeton&state=NJ&zip=08540
http://www.copilotlive.com/copilot/android?type=LOCATION&action=GOTO&lat=+40388249&long=-74654724

Android 12 and Later

Some customers use the http: or https: format to create “clickable” URLs to send to a driver’s device. If a device is running Android 12 or later, you must:

• Upgrade CoPilot to 10.19.3.48 or later.
• Use as the base URL either https://copilotgps.com/copilotgps? or http://copilotgps.com/copilotgps? instead of the copilotlive.com base URL. So, for example: https://copilotgps.com/copilotgps?type=CONFIG&CompanyID=myCompanyId&AssetID=myAssetId&showconfirmation=true

Geo URI Format

CoPilot also supports the use of the Geo URI scheme on the Android platform. Coordinates as well as an address can be passed in this format. If lat/long is provided, the address is ignored. The exact lat/long should be passed using a decimal place and a comma to separate.

Example Strings

geo:0,0?q=35 Network Dr, Burlington, 01803, MA
geo:42.496652,-71.228454?q=35 Network Dr, Burlington, 01803, MA

@ Character

Available in CoPilot 10.14.0.368 and Later

Geo URIs also support usage of the ‘@’ character to separate coordinates and address. When using the ‘@’ character, the coordinates provided after “geo:” should be “0,0”. See below for examples. Note how the order of the address and the coordinates before or after the ‘@’ character does not matter. Both methods are supported.

geo:0,0?q=42.496652,-71.228454@35 Network Dr, Burlington, 01803, MA
geo:0,0?q=35 Network Dr, Burlington, 01803, MA@42.496652,-71.228454

Using the Address as a Stop Label Available in CoPilot 10.19.0.1360 and Later

If a GEO URI includes an address in addition to the GPS coordinates of a stop, the address will be used as the stop name label shown in CoPilot.

Example

geo:0,0?q=123 Main St Seattle@131.6565232,-50.4546454 // "123 Main St" will be used as the stop label

Adding Your Own Stop Label

Available in CoPilot 10.19.0.1715 and Later

You can pass stops into CoPilot using the following Geo URI format: geo:0,0?q=lat,long(label). The label is the name of the stop that will be displayed in CoPilot.

Example

geo:0,0?q=40.42650604248047,-74.32408599853515(Headquarters) // "Headquarters" will be used as the stop label

Connect to Account Manager Fleet Settings (formerly FleetPortal)

Available in CoPilot 10.9.0.1098 and Later

URL launch can be used to set up a device so it can connect to Account Manager’s Fleet Settings feature (formerly FleetPortal). Account Manager allows fleet managers to remotely create CoPilot vehicle settings, such as vehicle routing profiles, to be used by the fleet and to assign specific routing profiles to vehicle and driver groups within the fleet.

Account Manager Licensing Users

If you are using URL launch and the Account Manager to assign CoPilot licenses to vehicles or drivers, Fleet Settings are applied automatically. After activating a CoPilot license via URL, a second call to the (Account Manager) FleetPortal URL below is not needed.

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:

• Call the Account Manager URL with AssetID set to the device ID used in Account Manager.
• Call the FleetPortal URL below with DeviceID set to the appropriate vehicle ID used in Account Manager (formerly FleetPortal). That ensures CoPilot has the correct settings if the device is moved from vehicle to vehicle.

Account Manager Configure Fleet Settings Users

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

URL Format

copilot://options?type=FLEETPORTAL&action=Set&DriverID=99999&DeviceID=1111&PartnerID=XYZXYZ&EnableCompliance=true&EnableFleetPortal=true&showconfirmation=false&ShowCompliancePopup=true