Linking to Your App

Users normally get your app by installing it from the gallery or because Yahoo! has preinstalled it for them. After that, if it's not a strictly contextual app (like the delicious sample), they launch it from the application list. If you'd like to direct users to your app from a website or within email, we provide a URL.

The URL is an app-specific entrypoint into Yahoo! Mail. If the user who clicks on the URL already has your app installed, Yahoo! Mail will launch your app. Otherwise, Yahoo! Mail will launch the gallery with your app highlighted so that the user can easily install it.

A Simple Link

The simplest link to your application will be of the form: mrd.mail.yahoo.com/gallery?appId=<appid>, where <appid> is replaced by your public appid. You can look up your public appid with ymdt apps. This will launch the app view that you have configured to launch on the <click> event.

Linking to a Custom View

You can have your link launch a view other than that launched by your <click> event-handler by explictly defining a <url> event in your config.xml: 

  1. <?xml version="1.0"?>
  2. <openmail_app_config version="2">
  3. <events>
  4.         <url>
  5.         <action>
  6.                 <launch>
  7.                 <view>landing.html</view>
  8.                 <target_zone>tab</target_zone>
  9.                 </launch>
  10.         </action>
  11.         </url>
  12. </events>
  13. </openmail_app_config>
<?xml version="1.0"?>
<openmail_app_config version="2">
<events>
        <url>
        <action>
                <launch>
                <view>landing.html</view>
                <target_zone>tab</target_zone>
                </launch>
        </action>
        </url>
</events>
</openmail_app_config>

Passing Launch Parameters

You may add GET parameters to your URL. When your app is launched via a URL, you can retrieve these parameters using the getParameters API. The parameter names and types must be declared in your config.xml

For example, this URL would launch your app with name, id, and notes parameter:
mrd.mail.yahoo.com/gallery?appId=<appid>&name=Joe&id=999&notes=none
That URL and parameters would be available in your landing.hmtl view if you have a config.xml like this: 

  1. <?xml version="1.0"?>
  2. <openmail_app_config version="2">
  3. <events>
  4.         <url>
  5.         <action>
  6.                 <launch>
  7.                   <view>landing.html</view>
  8.                   <target_zone>tab</target_zone>
  9.                   <params>
  10.                     <param><name>name</name><type>text</type></param>
  11.                     <param><name>id</name><type>number</type></param>
  12.                     <param><name>notes</name><type>html</type></param>
  13.                   <params>
  14.                 </launch>
  15.         </action>
  16.         </url>
  17. </events>
  18. </openmail_app_config>
<?xml version="1.0"?>
<openmail_app_config version="2">
<events>
        <url>
        <action>
                <launch>
                  <view>landing.html</view>
                  <target_zone>tab</target_zone>
                  <params>
                    <param><name>name</name><type>text</type></param>
                    <param><name>id</name><type>number</type></param>
                    <param><name>notes</name><type>html</type></param>
                  <params>
                </launch>
        </action>
        </url>
</events>
</openmail_app_config>

Supported parameter types are "number","text", and "html".

Support & Community

Ask questions and share insights on our forum.