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

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

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

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

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

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 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 Current (GPS) Location will not be added in the PLAN screen until you tap the navigation button to begin the trip.

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

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

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¶

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:
5. Latitude and Longitude
6. Address, City, State/Jurisdiction, ZIP
7. GOTO and ADDNEXTSTOP will work as described if user is on navigation mode. If user is in planning mode they may get different result.
8. The Name field is limited to 164 characters.
9. When a stop is passed to CoPilot with action command ADDNEXTSTOP, the device's GPS fix status may affect this command:
10. With a GPS fix, action commands will take effect as described above.
11. 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.
12. 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