Launch and Param functions

Grein
06/21/2024

Applies to: Canvas apps

Launches a webpage or a canvas app and provides access to launch parameters.

Launch

Launches a webpage or a canvas app. The function supports:

Address (required), the URL of the webpage of the canvas app.
Parameters (optional), named values to pass to the webpage or canvas app. In a canvas app, parameters can be read with the Param function.
Target (optional), the browser tab in which to launch the webpage or canvas app.

Launch can only be used in behavior formulas.

Note

If the Launch formula is used to open Power Apps and the app isn't visible to the end user, it's recommended to check if the app is blocked by a browser pop-up blocker or if the browser is wait for the user's response to a dialog box that asks whether they want to navigate to a new screen.

Address

Webpages are launched via a URL address. For example:

Launch( "https://bing.com" )

You can launch canvas apps with Web link or App URI (app id prefixed with /providers/Microsoft.PowerApps/apps/). To find these values for an app:

Go to Power Apps.
Select Apps from left navigation pane.
Select your app.
Select Details from top menu.
You can also select ... (More Commands) and then select Details from the drop-down menu.
Copy Web link.

The Web link can be used in any web page and will launch the canvas app. It can also be used with the Launch function. For example:

Launch( "https://apps.powerapps.com/e/{environment id}/a/{app id}?tenantId={tenantId}" )

Native apps on a device can't be launched directly. There may be indirect options available on some platforms, such as a native app installing a custom URL scheme or registering with the web browser to offer an option for specific web sites.

Parameters

Launch can pass parameters to the webpage or canvas app. Parameters can be provided in two ways:

An argument list of name value pairs. For example:

Launch( "https://bing.com/search", "q", "Power Apps", "count", 1 )

A record of field values. For example:
```
Launch( "https://bing.com/search", { q: "Power Apps", count: 1 } )
```
This form can be easier to work with as it makes the association between name and value clearer. It's the only form that supports the optional LaunchTarget argument.

The address and parameters are URL encoded before being passed to replace certain non-alphanumeric characters with % and a hexadecimal number as if the EncodeUrl function has been used on each.

When launching a webpage, a query string of parameters can be included at the end of the URL address. Any additional parameters provided to Launch will be added to the end of the query string. Query strings don't work when launching a canvas app.

When launching an app on a mobile device where that app is already running, parameters will not be refreshed in the running app. An app reload is required for parameters to be refreshed.

Target

Use the LaunchTarget argument to specify the target browser window in which to open the webpage or app. Use one of the following LaunchTarget enum values or provide a custom window name.

LaunchTarget enum	Description
New	The webpage or app is opened in a new window or tab.
Replace	The webpage or app replaces the current window or tab.
name	Instead of an enum value, use your own text string to name the window or tab. Self is an internal only name that is only used by the Launch function. It has no impact on nor will it match the title of the window that your users see. If a window or tab with the given name already exists, its contents will be replaced. Otherwise, a new window or tab will be created. name can't begin with the underscore character "_".

New is the default enum when running in a web browser with Replace and name as available options. In a mobile player, New is the default for webpages with name as an available option; while the current canvas app will always be replaced by another canvas app.

Note

Using a LaunchTarget with any value other than New in embedded scenarios (for example, Power BI or SharePoint) is not supported and may result in unexpected behavior. In the future, this behavior may change, or may cause an error.

Param

The Param function retrieves a parameter passed to the app when it was launched. If the named parameter wasn't passed, Param returns blank.

When launching a canvas app from another canvas app, use the Parameter arguments to the Launch function. Parameter names and values will be automatically URL encoded.
When launching a canvas app from a web page, add parameters to the query string of the canvas app web link. This involves adding &parametername=parametervalue assuming the query string has already been started for the tenantId. For example, adding &First%20Name=Vicki&category=3 would pass two parameters: First Name with a value of "Vicki" and category with a value of "3" (value type is text). The parameter name and value must be URL encoded if they contain spaces or special characters, similar to using the EncodeURL function.
Param names are case-sensitive.
Param names and values will be automatically URL decoded for use in your app.
Parameter values do not change unless the app is reloaded. Using Launch on a mobile device where the app is already running does not refresh the parameters.
Even if the parameter contains a number, the type returned by Param will always be a text string. Conversion to other types will automatically occur or use explicit conversions such as the Value function to convert explicitly to a number.

Note

For custom pages, the only parameters accepted by the page are: recordId and entityName.

Syntax

Launch( Address [, ParameterName1, ParameterValue1, ... ] )

Address – Required. The address of a webpage or the ID of an app to launch.
ParameterName(s) – Optional. Parameter name.
ParameterValue(s) – Optional. Corresponding parameter values to pass to the app or the webpage.

Launch( Address, { [ ParameterName1: ParameterValue1, ... ] } [, LaunchTarget ] )

Address – Required. The address of a webpage or the ID of an app to launch.
ParameterName(s) – Optional. Parameter name.
ParameterValue(s) – Optional. Corresponding parameter values to pass to the app or the webpage.
LaunchTarget – Optional. A LaunchTarget enum value or a custom name.

Param( ParameterName )

ParameterName - Required. The name of the parameter passed to the app.

Reserved parameters

The following keywords are reserved (regardless of case) for internal use, and shouldn't be used as a custom parameter in the Param() function:

amp%3Bauthmode
amp%3Benableonbehalfof
amp%3Bhidenavbar
amp%3Blocale
appmetadataversion
authmode
channeltype
cordovapath
correlationid
debug
delegatelaunchurl
delegatelaunchurl
disablepreviewredirect
embedderorigin
enableonbehalfof
groupid
hideappsplash
hidenavbar
hint
hostclienttype
hostmode
iframecontainerid
isfullscreen
ispreviewmode
loader
loaderType
locale
location
packagekind
packageproperties
playerresourcespath
playersessionid
powerappslanguage
screencolor
sdkversion
site
skipappmetadata
skipiframecreation
skiplaunchappcache
source
sourcetime
standaloneconsent
teamid
teamtype
tenantId
theme
uselocalpackagehostresources
userteamrole

Examples

Simple Launch

From a canvas app to a web page:

Formula	Description
Launch( "http://bing.com/search", "q", "Power Apps", "count", 1 )	Opens the webpage https://bing.com/search?q=Power%20Apps&count=1. A new window or tab is opened.
Launch( "http://bing.com/search", { q: "Power Apps", count: 1 } )	The same as the previous examples using the equivalent record notation. A new window or tab is opened.
Launch( "http://bing.com/search", { q: "Power Apps", count: 1 }, LaunchTarget.Replace )	The same as the previous examples, replacing the current window or tab with the result if running in a web browser.
Launch( "http://bing.com/search", { q: "Power Apps", count: 1 }, "Search Results" )	The same as the previous example, creating or replacing the contents of the window or tab named Search Results.

From a canvas app to a canvas app

Update the app ID, screen name, and record number as appropriate.

Launch( "/providers/Microsoft.PowerApps/apps/YOUR-APP-ID",
        { Navigate: "Second Screen", Record: 34 }
)

From a web page to a canvas app

Update the app ID, tenant ID, screen name, and record number as appropriate.

<html>
  <body>
    <a
      href="https://apps.powerapps.com/play/e/YOUR-APP-ENVIRONMENT-ID/a/YOUR-APP-ID?tenantId=YOUR-TENANT-ID&Navigate=Second%20Screen&Record=34"
    >
      Launch canvas app
    </a>
  </body>
</html>

Simple Param

Simple launch examples above to launch canvas app from web page or from another canvas app show simple examples for Param function:

Formula	Description	Result
Param( "Navigate" )	The Navigate parameter was provided when the app was launched and is returned.	"Second Screen"
Param( "Record" )	The Record parameter was provided when the app was launched. Even though it was passed in as a number to the Launch function, the result from Param will be a text string that can be implicitly or explicitly converted to other types.	"34"
Param( "User" )	The User parameter wasn't provided. A blank value is returned that can be tested with the IsBlank function.	blank

Step by Step examples for Launch and Param

The Product Showcase tablet layout template was used for the following examples. To create an app with this template, follow the steps from create an app article and select the Product Showcase template. You can also use your own app.

Example - Launch

Go to Power Apps.
Select Apps from left navigation pane.
Select your app and then select Edit.
Select Insert from the menu and then select Label.
Move the label to the bottom right of the screen.
From the properties pane on the right-side, select Color as white and set Border thickness at 1.
Select the Text property from right-side and enter text as Surface tablets in news.
From property list on top left, select OnSelect.
Enter formula as Launch("https://www.bing.com/news/search","q","Microsoft Surface tablets"). You can also use any other URL, parameter, and keywords of your choice.
Save and publish the app.
Play the app.
Select label Surface tablets in news to launch news search with keywords Microsoft Surface tablets.

Tip

For scalability, you can replace the manually entered keywords in Launch function with variables.

Example - Param

Go to Power Apps.
Select Apps from left navigation pane.
Select your app and then select Edit.
Select Insert from the menu and then select Label.
Move the label to the bottom right of the screen.
Select Text property for the label from top left.
Enter formula as Param("browser"). You can also use a different parameter of your choice.
Save and publish the app.
Copy web link for your app from Power Apps.
Open a new browser.
Paste the app web link in the browser and append &browser=Microsoft%20Edge at the end.
When your app launches, the label shows the parameter value passed.
Close the app player and edit the app.
Select App from the Tree view on left navigation.
Select StartScreen property on top left.
Enter the formula as If( Param("screen") = "techspecs", TechSpecs ).

If function in StartScreen property checks if parameter equals a certain value, in this case the value techspecs. And if it matches, returns the TechSpecs screen control to the StartScreen property.

Note

Replace the TechSpecs control name in the If function with the name of a screen control in your own app if you're not using the Product Showcase app template.
Save and publish the app.
Open a new browser.
Paste the app web link in the browser and append &screen=techspecs at the end.
The app directly launches with TechSpecs as the startscreen.