Skip to content

Intents

Intents are messaging objects used to start activities. An activity represents a single screen in an application. PTV Navigator G2 supports intents for triggering different actions. An intent targeted to PTV Navigator G2 starts the Navigator if it is not already running, brings it to the foreground and switches the Navigator to the intro screen. A currently running navigation will be cancelled.

An Intent object contains information about what activity to start and additional instructions about how this activity should perform an action. The following information is used to define an Intent:

  • Component name

    The name of the component (i.e. an activity) to start. The component name is optional. If you define an component name, only the application component defined will process the Intent. If you do not define a component name, the operating system decides which application component should receive the Intent. Usually you will get a dialog containing a list of applications that are able to process the Intent.

  • Action

    A string that specifies the generic action to perform. Defining an action is not necessary for PTV Navigator G2.

  • Data

    The URI that references the data to process and the MIME type of the data.

  • Category

    A string containing additional information about the kind of component that should handle the intent. Defining a category is not necessary for PTV Navigator G2.

  • Extras

    Key-Value pairs carrying additional information for processing the rrquested action. Defining extras is currently not necessary for PTV Navigator G2.

  • Flags

    Flags act as metadata for the Intent. They may instruct the operating system how to launch an activity and how to treat it after launch.

Building and Sending an Intent

Using an Intent for PTV Navigator G2 is absolutely straightforward. Just create the Intent object and pass the URI in the constructor, add some flags and send the Intent. We recommend to add the flags FLAG_ACTIVITY_REORDER_TO_FRONT, FLAG_ACTIVITY_NEW_TASK, FLAG_ACTIVITY_CLEAR_TASK and FLAG_ACTIVITY_SINGLE_TOP to your Intent: 

// Create a string containing the Intents URI
String uri = "google.navigation:49.02,8.44";

// Create the Intent.
// As an action, we define ACTION_VIEW, because the targeted activity should show something to the user.
// As the URI, we pass the parsed uri string.
Intent intent = new Intent(android.content.Intent.ACTION_VIEW, Uri.parse(uri));

// We add a flag so that the targeted activity will be brought to the front of its tasks history stack - if it is already running.
intent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);

// We add another flag so that the targeted activity will become the start of a new task on this history stack.
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);

// This flag should also be set, to clear the targeted activity
intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK);

// This flag ensures that the activity will not be launched if it is already running at the top of the history stack.
intent.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);

// Now simply send the Intent and start the targeted activity
startActivity(intent);

Supported intents

The follwing Intents are supported by PTV Navigator G2. You can use them like in the example above, you only have to define the URI as described in each Intent.

  • Start Navigation by providing a position with a Geo/PTV Intent

    The data URI has to be in the following format:
    geo:<latitude>,<longitude> or geo:0,0?q=<latitude>,<longitude>(<label>)
    or
    ptv:<latitude>,<longitude> or geo:0,0?q=<latitude>,<longitude>(<label>)

    <latitude> The geodecimal latitude as floating point type

    <longitude> The geodecimal longitude as floating point type

    <label> The name with which the destination will be saved in the previous destinations list.

    Code example: 

        double latitude = 49.022308;
    double longitude = 8.446573;
    String uri = "geo:0,0?q="+ latitude + "," + longitude;

  • Start Navigation by providing a position with a Google/PTV navigation Intent

    The data URI has to be in the following format:
    google.navigation:<latitude>,<longitude>?<someOptionalStuff> or google.navigation:q=<latitude>,<longitude>?<someOptionalStuff>
    or
    ptv.navigation:<latitude>,<longitude>?<someOptionalStuff> or google.navigation:q=<latitude>,<longitude>?<someOptionalStuff>

    <latitude> is the geodecimal latitude as floating point type

    <longitude> is the geodecimal longitude as floating point type

    <someOptionalStuff> is ignored by PTV Navigator

    Code example: 

        double latitude = 49.022308;
    double longitude = 8.446573;
    String uri = "google.navigation:"+ latitude + "," + longitude;

  • Start Navigation by providing a position with a http/https navigation Intent

    The data URI has to be in the following format:
    http://maps.google.com/maps?daddr=<latitude>,<longitude>&<someOptionalStuff>
    or
    http://navigator.ptvgroup.com/maps?daddr=<latitude>,<longitude>&<someOptionalStuff>

    You can also use https instead of http for the URLs.

    <latitude> is the geodecimal latitude as floating point type

    <longitude> is the geodecimal longitude as floating point type

    <someOptionalStuff> is ignored by PTV Navigator

    Code example: 

        double latitude = 49.022308;
    double longitude = 8.446573;
    String uri = "http://maps.google.com/maps?saddr=49.0,8.4&daddr="+ latitude + "," + longitude;

  • Start Navigation by providing an address with a Geo/PTV Intent

    The data URI has to be in the following format:
    geo:0,0?q=<countrycode>,<postcode>,<town>,<street>,<housenumber>
    or
    ptv:0,0?q=<countrycode>,<postcode>,<town>,<street>,<housenumber>

    <countrycode> The country code string as the international country symbol or as the 2 character ISO 3166-2 code.

    <postcode> The post code string. This field is optional, partial post codes are supported.

    <town> The town name string. This field is optional, partial and substrings are supported.

    <street> The street name string. This field is optional, partial and substrings are supported.

    <housenumber> The house number string. This field is optional, only numerical house numbers are supported.

    The address string has to contain always four commas for seperating the single address criterias, even if you leave out single criterias. For example: D,,Karlsruhe,Haid-und-Neu-Straße,.
    The more precise you specify the address, the more likely it is that you will be navigated to the correct address. Imprecise address definitions (like incomplete post code, only the first characters of a street name, ...) will be matched to the first possible target that comes along. If geocoding of the given address is not possible, the PTV Navigator will show an appropriate notice dialog.

    Code example: 

        String address = "DE,76131,Karlsruhe,Haid,15";
    String uri = "geo:0,0?q=" + address;

  • Start a Tour

    This Intent loads an existing BCR file and fills the target stations and their flags with those found in the BCR. If loading of the BCR is successful, the PTV Navigator G2 shows the route overview of the calculated tour.

    The data URI has to look like this:
    file:<filename>

    The file name of the BCR file on the Android device including an absolute path.

    The file has to exist in the Android file system, has to be accessible for the PTV Navigator G2 and has to be a valid BCR file. Otherwise this Intent won't do anything. The imported tour from the BCR file will be stored permanently in the Tours menu of PTV Navigator G2.

    Code example: 

        String fileName = "/storage/emulated/0/tour.bcr";
    String uri = "file://" + fileName;

  • Set a license key

    This intent allows you to set a license key to the PTV Navigator G2. The data URI has to look like this:
    licensekey:<yourLicenseKey>

    <yourLicenseKey> The license key you like to set to the Navigator. Usually this is a 92 characters long string.

    After starting the Activity with this intent, the PTV Navigator G2 checks the given license key against the license server. If the check is successful and the license is valid, the license key will be set to the Navigator permanently.

    Please note:
    - The license key check is also successful, if the limit of allowed active devices per license key is exceeded.
    - The license key check fails, if the key is invalid or if the license server cannot be reached by the Navigator.

    After a successful license key check, the given key will overwrite any previous key on your PTV Navigator G2. In case of an unsuccessful check, the given key will NOT be set to the Navigator. The previous key (if there is one) will stay the active license key.

    Code example: 

        String licenseKey = "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz01234567890123"
    String uri = "licensekey:" + licenseKey;