Developer Blog

Connect IQ 2: Intents and Persisted Content

11/01/16 @ 10:34 AM

Connect IQ 2.2 adds Intent objects, which allow a Connect IQ app to launch another app or a native activity from a running app. It also opens up access to the device’s native content like the user’s waypoints and courses, as well as adds the ability to download native content from the cloud to a device. This allows developers to create Connect IQ apps that curate content, and launch into the native activity. This post provides an overview of these new features and how to use them.

Intents

The new System.Intent class is used with System.exitTo to exit your app and launch into another Connect IQ app.

//! Intents can be used to send content to a URI. URIs can be another app.
//! Examples:
//!    manifest-id://[manifest id in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]
//!    store-id://[store id in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]
class Intent
{
    var uri;
    var arguments;
 
    //! Create an Intent
    //! @param [String] aURI URI that specifies receiver of intent
    //! @param [Dictionary] aArgs Parameters to pass to the target URI
    //! @since 2.2.0
    function initialize(aURI, aArgs);
}
  
//! Exit the current app and launch a new app. This is an asynchronous request.
//! If the user chooses to launch the Intent then the app will be shut down. Otherwise
//! the app will continue to run. This can only be called by watch-apps and widgets.
//! @param [Intent] content The Intent to trigger
//! @throws [UnexpectedAppTypeException] If the app requested is not a watch-app or widget
//! @throws [AppNotInstalledException] If the application requested is not installed
//! @throws [PreviousOperationNotCompleteException] If exitTo is called a second time before completing
function exitTo(content)

An Intent is created by passing in a URI and an optional Dictionary that is passed to the target apps onStart method. The URI is the target app’s manifest ID or store ID. The manifest ID can be obtained from an app’s manifest.xml file and can be used if you’re the author of the target app. If the target app is not one you wrote you can launch it using the store ID, which is found in the app store URL for the app: https://apps.garmin.com/en-US/apps/fc9c1ad4-9377-05f9-b53d-ed61f480c3ff.

An Example

Let’s say the store app given above is a navigation app that points the user to Location. This app has a way to allow a user to input the desired location but it also accepts launch arguments using System.exitTo. The app developer has published that it accepts a Dictionary containing the String keys of “latitude” and “longitude” each with a Float value in the degrees coordinate format. If your app contains a list of waypoints it could use the store app to do the actual navigation:

var intent = new Sys.Intent("store-id://fc9c1ad4-9377-05f9-b53d-ed61f480c3ff", {"latitude"=>38.855567, "longitude"=>-94.799817});
Sys.exitTo(intent);

When System.exitTo is called the device will display a prompt asking if the user would like to launch the target app. If the user chooses not to launch the app then your app will continue to run. If the user chooses to launch the app then your app will be shut down and the target app started, passing the provided arguments to onStart. While the prompt is displayed your app will continue to run in the background. It will continue to receive any updates from the Sensor and Position modules and any active Timer objects will continue to fire.
Prompt

While this is a simple example it highlights the possibilities opened up with the new Intent class.

There are a couple of things to know about using System.exitTo. An app can only exit to a watch-app or a widget. Trying to exit to a watch face or data field will lead to an UnexpectedAppTypeException being thrown. If the target app is not installed an AppNotInstalledException is thrown. Finally, if System.exitTo is called multiple times before the user responds to the launch app prompt a PreviousOperationNotCompleteException will be thrown.

Persisted Content

Connect IQ 2.2 allows access to the stored Waypoints, Courses, Routes, Tracks, and Workouts on a device through the PersistedContent module. Here is an excerpt from the module that defines a Course.

module PersistedContent {
    //! Content iterator for the persisted content
    //! @since 2.2.0
    class Iterator {
        //! Get the next item in the list
        //! @since 2.2.0
        //! @return [Object] The next item, or null if end of list
        function next();
    }
  
    //! Get the courses installed on the system
    //! @return [Iterator] Iterator of courses
    function getCourses();
  
    class Course {
        //! Gets a readable name for the content
        //! @return [String] Readable name
        function getName();
  
        //! Gets a unique serializable id
        //! @return [Number] Unique serializable id
        function getId();
  
        //! Gets a system intent for the content
        //! @since 2.2.0
        //! @return [Intent] System.Intent for the content
        function toIntent();
    }
}

The Waypoint, Route, Track, and Workout classes are used the same as Course. For simplicity we’ll only talk about courses. Each Course has a name and an unique ID available and can be obtained by calling getName and getId respectively. The toIntent function can be used with System.exitTo to launch into the devices native experience for that type of content. On an Edge 1000, exiting to a course will present the user with a prompt to choose how they would like to ride it:

The same rules for exiting to a Connect IQ app apply here as well. Your app will continue to run in the background until the user either launches the Course or cancels the launch.

Retrieving the courses on the device is done with PersistedContent.getCourses. This returns a PersistedContent.iterator that allows for stepping through the courses on the device one at a time. The next function must be called to retrieve the first Course. If no courses are on the device then null will be returned.

Devices that support the PersistedContent module may not support each type of content. On the Edge series Waypoint, Course, and Workout are available while on the Oregon series Waypoint, Route, and Track are available.

Downloadable Content

The Communications.makeWebRequest API has been expanded to allow downloading of FIT and GPX files. These files can be downloaded by specifying the :responseType option for makeWebRequest. When one of these response types are specified once the FIT or GPX file is downloaded it will be processed by the device; note that the EDGE devices support FIT content, and the Oregon/Rino products support GPX content. Once the contents of the file have been saved to the device the callback provided to makeWebRequest will be called with a PersistedContent.Iterator as the data argument. This Iterator will contain all the saved content types from the file that was downloaded. If the file contained a two courses, a workout, and then a waypoint the Iterator will contain all four entries.

Categories: Connect IQ SDK