URL Launch¶
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 Higher 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 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. Available in CoPilot 10.19 and Higher 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 Higher
-
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 Higher 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 FleetPortal. URL launch can be used set up a device so it can connect to FleetPortal, a web tool that allows fleet managers to remotely configure CoPilot vehicle settings and vehicle routing profiles to be used by the fleet. Available in CoPilot 10.9.0.1098 and Higher
Note
The URL launch is only supported on our Truck licensed application.
Activate a License¶
Available in CoPilot 10.14 and Higher 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 Higher
copilot://options?type=CONFIG&CompanyID=trimble-defined.customer.id&AssetID=customer-defined.asset.id&showconfirmation=true
Parameter | Description | Type | Required |
---|---|---|---|
CompanyID | The company account identifier assigned by Trimble MAPS. | alphanumeric | Y |
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 |
ShowConfirmation | If set to true, a confirmation message will be shown if CompanyID and AssetID are correctly set. Default is false. | boolean | N |
URL Format for Partners Reselling CoPilot¶
Available in CoPilot 10.19 and Higher
copilot://options?type=CONFIG&PartnerID=sample-partner&ExternalAccountID=partner-defined.account.id&AssetID=partner-defined.asset.id&showconfirmation=true
Parameter | Description | Type | Required |
---|---|---|---|
PartnerID | The partner identifier assigned by Trimble MAPS. | alphanumeric | Y |
ExternalAccountID | The partner’s existing account identifier for their customer who is deploying CoPilot. | alphanumeric | Y |
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 |
ShowConfirmation | If set to true, a confirmation message will be shown if CompanyID and AssetID are correctly set. Default is false. | boolean | N |
Identify the Vehicle and Driver¶
Available in CoPilot 10.19 and Higher
Each instance of CoPilot needs to know which Vehicle or Driver is using it 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. 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
Parameter | Description | Type |
---|---|---|
VehicleID | The identifier for the vehicle as defined by the partner or direct customer. | alphanumeric |
DriverID | The identifier for the driver as defined by the partner or direct customer. | alphanumeric |
Set Configurations¶
Available in CoPilot 10.19 and Higher
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 SDK 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 SDK 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 Higher (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=1
To set which app should be switched to when pressing the button:
&AppLaunchBundleID=bundle.id.of.application
Parameter | Description |
---|---|
EnableCustomButton | Set to “1” to enable the “return to partner app” button as shown below. |
AppLaunchBundleID | The bundle ID of the mobile application you wish to return the user to. |
Send Stops¶
Available in CoPilot 10.19 and Higher
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
Thestop
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
Thequery
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 Current (GPS) Location will not be added in the PLAN screen until you tap the navigation button to begin the trip.
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.
Stop Fields¶
Parameter | Description | Example |
---|---|---|
name | The name of the location | Company Headquarters |
address | The street address of the location | 25 Main Street |
city | The city of the location | Omaha |
zip | The ZIP code or postal code for the location | GU16 7HF |
juris | The jurisdiction of the location. For the U.S., this is the state; for Canada and Mexico, the provinces; and for Australia, the territory. | ON |
state | The state of the location. (State = Country when outside of North America.) | GB |
lat | The latitude of the location, expressed as an integer value in millionth of a degree or a decimal value. | 46.813962 |
long | The longitude of the location, expressed as an integer value in millionth of a degree or a decimal value. | -71.208012 |
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
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 0.5 miles 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 0.5 miles 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 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¶
Parameter | Description | Required? |
---|---|---|
action | The action performed with the location in CoPilot. 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. | Y |
lat | Latitude, expressed as an integer value in millionth of a degree or a decimal value | Y, if no address is provided |
long | Longitude, expressed as an integer value in millionth of a degree or a decimal value | Y, if no address is provided |
name | The name of the location | N |
address | The street address of the location | Optional if latitude and longitude are supplied |
city | The city of the location | Optional if latitude and longitude are supplied |
juris | The jurisdiction of the location | Optional if latitude and longitude are supplied |
state | The state of the location. State = Country when outside of North America. | Optional if latitude and longitude are supplied |
zip | The ZIP or Postal code of the location. | Optional if latitude and longitude are supplied |
Notes on Parameters¶
- 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.
- When entering latitude and longitude, “+” is optional however “-“ is mandatory where required.
- Query names are case sensitive.
- To best find a destination, you should supply one of the two following combinations of data:
- Latitude and Longitude
- Address, City, State/Jurisdiction, ZIP
- GOTO and ADDNEXTSTOP will work as described if user is on navigation mode. If user is in planning mode they may get different result.
- The Name field is limited to 164 characters.
- 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.
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
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 Higher
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
Available in CoPilot 10.19.0.1360 and Higher
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
Connect to FleetPortal¶
Available in CoPilot 10.9.0.1098 and Higher
URL launch can be used to set up a device so it can connect to FleetPortal. FleetPortal is a web tool that extends the functionality of CoPilot. It allows fleet managers to remotely configure CoPilot vehicle settings and vehicle routing profiles to be used by the fleet and assign specific routing profiles to vehicle and driver groups within the fleet.
Account Manager Users¶
If you are using URL launch and the Account Manager to assign CoPilot licenses to vehicles or drivers, these FleetPortal settings are applied automatically. After activating a CoPilot license via URL, a second call to the 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 FleetPortal. That ensures CoPilot has the correct settings if the device is moved from vehicle to vehicle.
URL Format¶
copilot://options?type=FLEETPORTAL&action=Set&DriverID=99999&DeviceID=1111&PartnerID=XYZXYZ&EnableCompliance=true&EnableFleetPortal=true&ShowConfirmation=false&ShowCompliancePopup=true
Parameter | Description | Type |
---|---|---|
DriverID | Identifies a specific driver within a company | alphanumeric |
DeviceID | Identifies a specific CoPilot device within the 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 |
EnableCompliance | Set to true to turn on route compliance | boolean |
EnableFleetPortal | Set to true to enable FleetPortal on the device | boolean |
ShowConfirmation | Set to true for the confirmation message, “FleetPortal settings have been updated” to appear on the device | boolean |
ShowCompliancePopup | If turned on (true), the user will be asked, "Enable compliance for this route?" before the route is converted to a compliance route. This setting is off (false) by default. | boolean |