Cross-App Launching

From WebOS101

Revision as of 20:57, 16 January 2012 by DataJog (Talk | contribs)
Jump to: navigation, search

Contents

Introduction

One of the more powerful features of webOS is the ability to send information back and forth between applications. The Application Manager service acts as the intermediary for passing messages between applications. It is up to developers to support launch detection. Some discussion already exists in the developer forums and on the developer reference page for alarms. This document lists the various interfaces available to non-native apps for handling cross-app launching and message passing. The interface for applications which ship on the phone are documented in the Services page. The interface for known 3rd-party services are documented on the 3rd-party Services page.

Example launch code

The following code snippet shows how to launch Palm's Facebook app to post a status.

var request = new Mojo.Service.Request("palm://com.palm.applicationManager", {
method: 'launch',
parameters: {
id: 'com.palm.app.facebook',
params: { status: "Check this out: " + this.storyFeed.stories[this.storyIndex].title +
" - " + this.storyFeed.stories[this.storyIndex].url }
}
});

For Multiple Version of Apps

Here's a function to run through an array of app ids (different app versions):

function callApp(serviceParams, onFailure) {
 
var appids = ['com.funkatron.app.spaz-sped', 'com.funkatron.app.spaz', 'com.funkatron.app.spaz-beta'], index = 0;
//just change your app ids if you are using a different app.
function makeCall() {
if (index < appids.length) {
 
Mojo.Log.info('Trying to launch with appid %s', appids[index]);
 
var request = new Mojo.Service.Request("palm://com.palm.applicationManager", {
method: 'launch',
parameters: {
id: appids[index],
params: serviceParams
},
onFailure: function() {
Mojo.Log.info('Failed to launch with appid %s', appids[index]);
index++; // go to next appid
makeCall(); // retry
}.bind(this)
});
 
} else {
Mojo.Log.error('Failed to launch');
if (onFailure) {
onFailure(serviceParams);
}
// or alternatively you can prompt the user to download the app in question
var currentScene = this.controller.stageController.activeScene();
currentScene.showAlertDialog({title: $L("No MapTool installed"),
onChoose: function(value) {
if (value == "INSTALL") {
this.controller.serviceRequest("palm://com.palm.applicationManager", {
method: "open",
parameters: {
id: 'com.palm.app.browser',
params: {target: "http://developer.palm.com/appredirect/?packageid=com.funkatron.app.spaz"}
}
});
}
}.bind(this),
message: $L("Please install the free Spaz application from the App Catalog."),
choices: [
{label:$L('Install'), value:"INSTALL"},
{label:$L('Continue'), value:"CLOSE"}
]
});
}
 
}
makeCall();
}

Apps which support launch parameters

Twitter Apps

Bad Kitty

Bad Kitty (version 1.5+) is a twitter client that supports the following launch parameters:

Parameter Required Description Code
action yes The flag that tells Bad Kitty what to expect Available Methods: "user", "tweet"
name no The username of the profile you want to view { action: "user", name: "MyUsername" }
tweet no The text you want to tweet { action: "tweet", tweet: "Text to pass to Bad Kitty" }

AppID: com.superinhuman.badkitty

Carbon

dots & lines' Carbon is a multi-panel Twitter client and supports the following launch parameters as of v.1.2:

Compose a New Tweet

Using this method will open a Compose Card in Carbon in order to send a tweet with the parameters as shown below.

Parameter Required Description
action yes "compose" - This is to indicate that Carbon is supposed to open up a Compose Card
body yes Text to be passed to Carbon as Tweet body
Search Twitter using Carbon

Using this method will open a Search Card in Carbon that starts searching Twitter with the keyword(s) that are passed as parameters as shown below.

Parameter Required Description
action yes "search" - This is to indicate that Carbon is supposed to open up a Search Card
keywords yes Search keyword(s) that Carbon will use to launch a Search card for

AppID: com.dotsandlines.carbon or com.dotsandlines.carbonbeta

Spaz

Spaz added launch params in v1.5.+

Post a status
Parameter Required Description
action yes "prepPost" or "post"
msg yes the message text
account no an account hash used by Spaz; otherwise last logged-in account is used

For compatibility, you can also send

Parameter Required Description
tweet yes the message text
View a user
Parameter Required Description
action yes "user"
userid yes "username"

For compatibility, you can also send

Parameter Required Description
user yes "username"
Search
Parameter Required Description
action yes "search"
query yes "search query string"
View a status
Parameter Required Description
action yes "status"
statusid yes "STATUS_ID"

AppID: com.funkatron.app.spaz OR com.funkatron.app.spaz-beta

Twee

Twee by Delicious Morsel is a Twitter client which supports two actions:

Tweet:

Parameter Required Description
tweet yes Text of tweet

Follow:

Parameter Required Description
follow yes Name of user to follow

AppID: com.deliciousmorsel.twee

Quick Post

Quick Post allows users to post to multiple Twitter and Facebook accounts.

With the following launch parameter, post message to the default account(s) set up in the Quick Post app. If the "quickPost" param starts with "z ", the text following the "z " will be sent to all accounts set up in the Quick Post app (not just the default ones):

Parameter Required Description
quickPost yes Status message to post to the default account(s)

AppID: com.hedami.quickpost

Tachyon

Tachyon is a Twitter app for HP webOS by Pocket Imagination which supports a variety of launch actions. Developers that implement cross-app launching support for Tachyon are entitled to a free copy of the app (either for themselves to test with, or to redistribute to a user). See here for details.

Search
Parameter Values Required Description
action search Yes Informs Tachyon you wish to Search
query Any string No The search term. If unprovided, Tachyon will open the Search & Trends scene showing the user current global trends.
searchType "global", "nearby", "people" or unprovided No The type of search you wish to take place.
  • global: search all tweets worldwide for $query
  • nearby: search all tweets for $query using geolocation. If $geoCode is unprovided, Tachyon will autolocate the user. It is recommended that you provide your own $geoCode if possible in order to ensure a smooth user experience.
  • people: search all users for $query. If there is only one result, the user will automatically be taken to that profile.
  • If unprovided, the user will be taken to the Search & Trends scene pre-populated by $query with the ability to choose which type of search they wish to make.
geoCode Any string in the format lat,long,dist No Recommended if using "nearby" as $searchType; ignored for other search types. Must be in the format lat,long,dist (no spaces) where lat and long are valid latitudes/longtitudes respectively. Distance must be in the format of a positive integer followed by either "mi" or "km" to indicate miles or kilometers respectively. A valid example would be 55.86246,-4.253709,25mi which would search within 25 miles of Glasgow, Scotland.
View Profile
Parameter Values Required Description
action user Yes Informs Tachyon you wish to view a profile.
screen_name Any valid Twitter screen_name No Takes the user to the profile provided. If left blank, the user will be taken to the profile of the currently logged-in user.
View a Tweet
Parameter Values Required Description
action status Yes Informs Tachyon you wish to view a tweet.
id Any valid Twitter status ID, in string format Yes Shows the user the status specified.
View a List
Parameter Values Required Description
action list Yes Informs Tachyon you wish to view a Twitter list.
id Any list ID Yes, if viewing by ID The ID of the list to be viewed.
slug Any list slug Yes, in conjunction with $screen_name The slug (name) of the list to be viewed.
screen_name Any Twitter screen_name Yes, in conjunction with $slug The screen_name of the list owner. The owner must own a list with $slug as a valid slug.


Compose a Tweet
Parameter Values Required Description
action tweet Yes Informs Tachyon you wish to compose a tweet.
text Any string No The body of the tweet. Can be any length. If over 140 characters, the user will be presented with the option to post via TwitLonger assuming they are posting from an unprotected account.
account Any valid Twitter screen_name No If set, Tachyon will attempt to post from the account provided. If the user has no account by that name in Tachyon, it will default to the currently logged in account.
geo "force_locate", "last_known" or [Object] No
  • force_locate: forces Tachyon's geolocation feature to request the user's location.
  • last_known: will tag the location as the user's last known location, or switch off if user prefers to not be located.
  • JSON object: provide your own location to tag the user with. This is recommended if known as it provides a smoother user experience. See the definition for 'geo' below for valid objects.
onPost "view" or "return" No If set to "view", Tachyon will show the user the Tweet they have just posted. If set to "return", then Tachyon will close the app and return to the calling application to ensure a smooth user experience. If Tachyon was open before crosslaunching, then Tachyon will ignore a "return" value. If the parameter is undefined or ignored, the user will be returned to whatever they were doing before crosslaunching.
geo

The 'geo' object for the tweet action takes a pair of values. If either possible pair is incomplete or invalid, the geo preference will revert to last_known. Valid pairs:

  • A lat/long pair: Pass as {lat: "", long: ""} -- will tag the tweet with this location, after determining that Twitter recognises the location.
  • A Twitter place name/id pair: This is the recommended pair as it is the quickest, although unlikely to be known by any application that does not interact with the Twitter API. Pass as {place_id: "", place_name: ""} where place_id is a valid Twitter place_id. place_name will appear on the UI, so ensure it is a valid and recognisable place name.


Sparrow

Sparrow is a TouchPad twitter client supporting the following launch parameters:

Parameter Required Description Code
windowType yes The flag so Sparrow knows what to do "newTweet"
tweetText no The text you want to tweet { windowType: "newTweet", tweetText: "Text to have the user tweet" }

AppID: com.appstuh.sparrow

Other Social Networking Apps

Facebook

Palm's Facebook app supports the following launch parameters:

Parameter Required Description
status yes? Text of status update

TODO: Find other launch parameters

AppID: com.palm.app.facebook

Foursquare

Launch Foursquare with passed 4sq.com URL:

(launches into Venue View if it's a venue URL, otherwise opens the URL in the web browser)

Parameter Required Description
action yes "url"
url yes 4SQ.COM URL (e.g http://4sq.com/1rNJ8N)


Set the notification alert sound

Parameter Required Description
action yes "saveAlertFile"
alertFile yes fullPath to local audio file
alertName yes name of the file


Launch Foursquare into User View:

Parameter Required Description
action yes "user"
user yes user ID (not username)


Launch Foursquare into Venue View:

Parameter Required Description
action yes "venue"
venue yes venue ID

View the source code at http://github.com/foursquare/foursquare-palmpre/

AppID: com.foursquare.foursquare

Glimpse

Glimpse gives you the ability to run several mini apps (aka widgets) at the same time using a split screen interface:

Load a url in the Web Widget:

Parameter Required Description
query yes Pass the following as the value: "web/" + url (where url is the link you want to open)

Search for video in the Youtube Widget:

Parameter Required Description
query yes Pass the following as the value: "youtube/" + string (where string is what you what to search )

Post a tweet with the Twitter Widget:

Parameter Required Description
query yes Pass the following as the value: "tweet/" + text (where text is the text you want to tweet )

Add a url to Read It Later using the Read It Later Widget:

Parameter Required Description
query yes Pass the following as the value: "read/" + url + "," + title (where url is the link, and title is the page title )

Load a url in the Advanced Browser Widget:

Parameter Required Description
query yes Pass the following as the value: "ab/" + url (where url is the link you want to open)

AppID: com.ingloriousapps.glimpse or com.palm.ingloriousapps.glimpseunrateddevcut (for the Developer's Cut)

For example, to launch a url in the web widget, you can use the following code.

var url = "www.something.com";
this.controller.serviceRequest(“palm://com.palm.applicationManager”, {
method: “launch”,
parameters: {
id: “com.ingloriousapps.glimpse,
params: {query: "web/" + url }
},
});

Lithium Messenger

Lithium Messenger is the first application that allows you to create a link between your various social networks, email & SMS

Parameter Required Description
query yes "Check that great Website !"
url yes "http://bit.ly" Provide a short URL

AppID: com.scienceapps.lithium

In order to pass a URL and a status, you can use the following code.

this.controller.serviceRequest(“palm://com.palm.applicationManager”, {
method: “launch”,
parameters: {
id: “com.scienceapps.lithium,
params: {query:”hello”,url:”http://bit.ly/"}
},
});

Ping.fm for webOS

A simple and free client for the popular Ping.fm service.

View the source code at http://vc.thauvin.net/svn/webos/Ping.fm/.

Parameter Required Description
method No The service, trigger or group to post to. (e.g.: microblog, @tt, #group, etc.)
title No Title of the posted message, if required or supported. (e.g.: blog)
message No The message body.

AppID: net.thauvin.erik.webos.pingfm

In order to post to Ping.fm, you can use the following:

var args = {
appId: "net.thauvin.erik.webos.pingfm",
name: "main"
}
var params = {
method: "blogs",
title: "This is a test title",
message: "This is a test message"
}
this.controller.stageController.pushScene(args, params);

Location and Maps

Go To Tool

Display Map:

Parameter Required Description
import-waypoints yes Array with data (sendArray in this example)

sendArray.unshift({ latitude: latitude, longitude: longitude, time: time, name: name, desc: desc });

AppID: com.longbeachit.gototooldemo (Demo) or com.longbeachit.gototool (Full Version)

See the FAQ at http://gototool.com/index.php?option=com_content&view=category&layout=blog&id=31&Itemid=91

MapTool

MapTool (free or pro) by Henk Jonas is a tool to display maps with POIs and tracks.

You can either send a query, a position or a list of POIs which are displayed on the map.

The query directly opens the search dialog with the query prefilled.

The location is a string containing lat and lon in decimal coords: "35.12345, 56.12345". Even a format like this is allowed: "Location: 23.3456, -23.45623". After launch, the view is centered around this position.

The POIs are saved in MapTool's target list and the initial view is zoomed to fit all POIs on the screen. The parameters are actually an array with objects as follows:


Parameter Required Description
name yes the name of the spot
lat yes latitude
lon yes longitude
image no an optional image url for the symbol displayed on the map
id no an optional id from geocaching.com
url no an optional url to read more about this target
case "do-maptool":
var params = [{
// convert the coordinates (from German into international format)
lat: this.lat.replace(/,/g, "."),
lon: this.lng.replace(/,/g, "."),
// give the spot a name and optional specify an url and icon
name: this.title,
url: this.Url
}];
// var params = {"query": "56.2345, 12.3456"}
// var params = {"query": "Housten, TX"}
// first try maptoolpro if not found try maptool (free)
this.controller.serviceRequest("palm://com.palm.applicationManager", {
method: "open",
parameters: {
id: 'de.metaviewsoft.maptoolpro',
params: params
},
onFailure: function() {
this.controller.serviceRequest("palm://com.palm.applicationManager", {
method: "open",
parameters: {
id: 'de.metaviewsoft.maptool',
params: params
},
onFailure: function() {
var currentScene = this.controller.stageController.activeScene();
currentScene.showAlertDialog({title: $L("No MapTool installed"),
onChoose: function(value) {
if (value == "INSTALL") {
this.controller.serviceRequest("palm://com.palm.applicationManager", {
method: "open",
parameters: {
id: 'com.palm.app.browser',
params: {target: "http://developer.palm.com/appredirect/?packageid=de.metaviewsoft.maptool"}
}
});
}
}.bind(this),
message: $L("Please install the free MapTool application from the AppCatalog."),
choices: [{label:$L('Install'), value:"INSTALL"},
{label:$L('Continue'), value:"CLOSE"}]
});
}.bind(this)
});
}.bind(this)
});
break;

You can read more details about it here: http://metaviewsoft.de/wordpress/?p=352

Music Apps

Koto Player

Koto Player is a music player for the platform. As of version 0.6.3, it supports one launch method, "getNowPlayingData". Apps can call Koto to get what the user is currently listening to. For example, Spaz has a button to get the currently playing music for people to tweet.

Get Now Playing Data
Parameter Required Description
action yes send "getNowPlayingData"
callback.id yes app id, typically Mojo.Controller.appInfo.id
callback.action yes the action for Koto to callback on

This will "callback" your app with a launchMethod of the following object:

Parameter Value Description
action string this will be the action you sent in your callback object
returnValue boolean true for success, false for failure. (no music playing is false)
nowPlaying.title string Title of Now Playing track.
nowPlaying.artist string Artist of Now Playing track.
nowPlaying.album string Album of Now Playing track.
nowPlaying.path string Path to Now Playing track file.

If returnValue is false, the nowPlaying object will not be passed.

AppIDs in order of precedence: "com.tibfib.app.koto.alt", "com.tibfib.app.koto", "com.tibfib.app.koto.lite"

Some sample code

//sample sent launch params
var params = {
action: "getNowPlayingData",
callback: {
id: Mojo.Controller.appInfo.id,
action: "tweetNowPlaying"
}
}
//sample returned launch params
var returnedLaunchParams = {
"returnValue": true,
"nowPlaying": {
"title": "Activation Theme",
"artist": "Bit Shifter",
"album": "Information Chase",
"path": "/media/internal/music/Information Chase/2 - Activation Theme.mp3"
},
"action": "tweetNowPlaying",
}

To-Do/Notes/Lists

Outline Tracker

Outline Tracker is a task list (to-do list) manager and outliner. http://outlinetracker.com/outlinetracker/index.html

Parameter Required Type Description
quickAction yes string Creates a new Task or Note; splits text into summary and content; attempts to extract date from first part of text

or

Parameter Required Type Description
searchStr yes string Switches to All Items view and displays all matching items.

AppID: com.outlinetracker.outlinetracker/com.outlinetracker.outlinetrackerfree


Notes

Notes (version 1.1.7+) is an app for taking notes and adding media (pictures, video clips, audio clips) to your notes:

Parameter Required Description
newNote yes Launches the app and creates a new note containing the text passed
media no an optional array of media to attach to the note. This is the local path to the media on the phone (e.g. [ "/media/internal/pic1.jpg", "/media/internal/pic2.png"...])

AppID: com.ingloriousapps.notes

TapNote

TapNote is a Dropbox-synchronized note-taking app, and allows you to create new notes or append text to existing notes (as of version 1.3). It is a "fat app" that is available on all WebOS devices (including TouchPad).

New document

This method will create a new document in TapNote and open it in a new card.

Parameter Required Description
action yes "new"
text no The string that will be used as the contents of the new note
title no The string that will be used as the title for the new note (if omitted, title will be automatically generated based on the first few words of the text)
Append to document

This method will open a card prompting the user to choose a TapNote document to append with the passed text.

Parameter Required Description
action yes "append"
text no The string that will be appended to an existing note

AppID: com.onecrayon.tapnote

You can use Quick Text abbreviations to insert the current date and/or time automatically in your text or title. Although the list of options may grow, currently you can use @d (date), @t (time), or @dt (datetime). For instance, if you pass "@t: Did something great in another app!" what will show up in TapNote is something like "9:30 AM: Did something great in another app!"

Relego

Relego is the webosRoundup Community Hackathon app. It is a Read It Later client which allows you to save URLs to the client and read them later.

Parameter Required Description
action yes Must be 'addtorelego'
url yes URL of the page to save for reading later
title no Title of the webpage or Descriptive Name

Read More on the official Hackathon Cross App Page: http://webos101.com/HackathonCrossApp

DataJog

DataJog is a cross-platform data transfer app. It allows the user to enter data from another device and move it to their webOS device. It can also send data from webOS to the other device.

Parameter Required Value Description
action yes send send the data to the other device
save save the data to the DataJog item list
data yes text URL or text to send or save

AppID: com.datajog.webos


Uncategorized (Help us out!)

Pack 'n' Track

Pack 'n' Track (version 1.1.27+) is a shipment tracking application that supports the following launch parameters:

Track A Package:

Parameter Required Description
action yes "addPackage"
trackingNumber yes Tracking number of the package
packageTitle no Optional title for package, if not provided tracking number is used

AppID: com.gosyntactix.paid.packntrack


neato!

Send text data from phone to user's PC via neato!:

Parameter Required Description
send yes {"a":"text","c":"text to send via neato!"}
send yes {"a":"url","c":"url to send via neato!"}

AppID: com.zhephree.neato

In order to pass a URL from the browser the following code can be used:

// Lets Neato! that URL
try{
this.neatoappid = "com.zhephree.neato";
this.controller.serviceRequest("palm://com.palm.applicationManager", {
method: 'open',
parameters: {
id: this.neatoappid,
params: {send: '{"a":"url","c":"'+this.currentUrl+'"}'}
},


Anonymous Texter

Anonymous Texter is an app that allows you to send a text message to anyone on any network, anonymously.

Parameter Required Description
action yes Must be 'sendText'
txtNumber no The Phone Number to send the Text Message to
txtCarrier no The carrier that the phone number is on
txtMessage no The actual message that is to be sent

AppID: com.jamesharris.anonymoustexter


Internalz

You can open files in Internalz very easily:

Parameter Required Description
target yes Can be a local filepath or an online URL.

If the target is an online URL image file, it will stream the image in the Image Viewer (with a Download image menu option available). All other online URL files will be downloaded.

Local image files load in the Internalz Image Viewer. All other files Internalz can handle (aka plain text files) will open in the Internalz Text Editor.

AppID: ca.canuckcoding.internalz


Internalz Pro

You can open files in Internalz Pro very easily:

Parameter Required Description
target yes Can be a local filepath or an online URL.

If the target is an online URL image file, it will stream the image in the Image Viewer (with a Download image menu option available). All other online URL files will be downloaded.

Local image files load in the Internalz Pro Image Viewer. Ipk files load into the Internalz Pro Ipk Installer. Patch and diff files load into the Internalz Pro Text Editor with patching options. All other files Internalz Pro can handle (aka plain text files) will open in the Internalz Pro Text Editor.

Lastly, if the target uses the view-source:// URI scheme, that webpage source will open read-only in the Internalz Pro Text Editor.

AppID: ca.canucksoftware.internalz



Scale Tool

Lazy tool for scaling dimensions. Formula is c * b / a = d ... a:b is scaled up/down to c:d.

Parameter Required Description
a yes integer
b yes integer
c yes integer

Basic Ping

Send a simple HTTP GET to a URL and see if it was successful.

Parameter Required Description
url yes It should include an http:// in the front

Voogle

Voogle is a native Google Voice client for webOS.

Parameter Required Description
action yes Currently only supports 'dial'
number yes The number you want the user to call

AppID: com.kandutech.voogle

Sports Live!

The Sports Live! suite offers real-time scores in the dashboard area or a full scoreboard for many of the most popular sports.

Parameter Required Description
action yes "saveAlertFile"
alertFile yes The path to a file to use as a score alert ringtone
alertName yes The name of the ringtone to display to the user

Goo.gly

Goo.gly (version 1.2+) is a goo.gl URL shortener that supports the following launch parameters:

Parameter Required Description Code
action yes The flag that tells Goo.gly what to do Available Methods: "shorten"
url yes The url to be shortened { action: "shorten", url: "http://www.somesite.com/somefile.html" }
onshorten no A single action to be taken once the URL has been shortened { action: "shorten", url: "http://www.somesite.com/somefile.html", onshorten:"actionID" }

The onshorten parameter can be any one of the following values: detailweb, copylink, tweet, detailshare, detailsharesms, facebookshare, sendneato, getqrcode, sendrelego, sendsparetime.

AppID: com.nelsun.googly


Mundu IM

An instant messaging client for Yahoo, MSN, AIM, Gtalk XMPP and Facebook. Supports multiple accounts.

Parameter Required Type Description
[pass a string instead of an object] yes string Service:Username:Buddyname
Common name Service value
Yahoo yah
GTalk jab
MSN msn ("msn:username@hotmail.com:yourbuddy@hotmail.com")
AIM aim
Facebook xmpp
XMPP xmpp

AppId: com.geodesic.im

Example: If you are using Yahoo service, you can use the following code in your assistant file to launch mundu IM:

this.controller.serviceRequest('palm://com.palm.applicationManager',
{
method: 'open',
parameters:
{
id: 'com.geodesic.im',
params: "yah:username:buddyname"
}
});

Also, the application needs to be running and the buddy must be logged into the IM account in order to push the particular buddy's chat window. If the application is not running or not logged into any IM accounts, then passing parameters will launch the application showing just the home screen.

Note: The current version of mundu IM mandates to use "IM Service:Username:Buddyname" format. Hence, you will need to know the username with which the user has logged into mundu IM.

Multiple App Launcher

Multiple App Launcher allows you to start multiple applications at once, avoiding tap, flick and gestures.

Parameter Required Description
message yes "App group number"

AppID: com.scienceapps.multipleapplauncher

In order to launch app group number 1, you can use the following code.

this.controller.serviceRequest(“palm://com.palm.applicationManager”, {
method: “launch”,
parameters: {
id: “com.scienceapps.multipleapplauncher,
params: {message:”1”}
},
});

WikiXplorer

WikiXplorer allows to browse, download and share articles from Wikipedia and Wiktionay (english, spanish, german, french).

Parameter Required Description
query yes "your query"

AppID: com.scienceapps.wikibrowseshare

You can use the following code for a query.

this.controller.serviceRequest(“palm://com.palm.applicationManager”, {
method: “launch”,
parameters: {
id: “com.scienceapps.wikibrowseshare,
params: {query:”enter your query”}
},
});
Personal tools