large Flutter Favorite logosmall Flutter Favorite logo

url_launcher 6.1.2 icon indicating copy to clipboard operation
url_launcher: ^6.1.2 copied to clipboard

Flutter plugin for launching a URL. Supports web, phone, SMS, and email schemes.

url_launcher #

pub package

A Flutter plugin for launching a URL.

AndroidiOSLinuxmacOSWebWindows
SupportSDK 16+9.0+Any10.11+AnyWindows 10+

Usage #

To use this plugin, add url_launcher as a dependency in your pubspec.yaml file.

Example #

import 'package:flutter/material.dart';
import 'package:url_launcher/url_launcher.dart';

final Uri _url = Uri.parse('https://flutter.dev');

void main() => runApp(
      const MaterialApp(
        home: Material(
          child: Center(
            child: RaisedButton(
              onPressed: _launchUrl,
              child: Text('Show Flutter homepage'),
            ),
          ),
        ),
      ),
    );

void _launchUrl() async {
  if (!await launchUrl(_url)) throw 'Could not launch $_url';
}

See the example app for more complex examples.

Configuration #

iOS #

Add any URL schemes passed to canLaunchUrl as LSApplicationQueriesSchemes entries in your Info.plist file.

Example:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>https</string>
  <string>http</string>
</array>

See -[UIApplication canOpenURL:] for more details.

Android #

Starting from API 30 Android requires package visibility configuration in your AndroidManifest.xml otherwise canLaunchUrl will return false. A <queries> element must be added to your manifest as a child of the root element.

The snippet below shows an example for an application that uses https, tel, and mailto URLs with url_launcher. See the Android documentation for examples of other queries.

<queries>
  <!-- If your app opens https URLs -->
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="https" />
  </intent>
  <!-- If your app makes calls -->
  <intent>
    <action android:name="android.intent.action.DIAL" />
    <data android:scheme="tel" />
  </intent>
  <!-- If your sends SMS messages -->
  <intent>
    <action android:name="android.intent.action.SENDTO" />
    <data android:scheme="smsto" />
  </intent>
  <!-- If your app sends emails -->
  <intent>
    <action android:name="android.intent.action.SEND" />
    <data android:mimeType="*/*" />
  </intent>
</queries>

Supported URL schemes #

The provided URL is passed directly to the host platform for handling. The supported URL schemes therefore depend on the platform and installed apps.

Commonly used schemes include:

SchemeExampleAction
https:<URL>https://flutter.devOpen <URL> in the default browser
mailto:<email address>?subject=<subject>&body=<body>mailto:smith@example.org?subject=News&body=New%20pluginCreate email to <email address> in the default email app
tel:<phone number>tel:+1-555-010-999Make a phone call to <phone number> using the default phone app
sms:<phone number>sms:5550101234Send an SMS message to <phone number> using the default messaging app
file:<path>file:/homeOpen file or folder using default app association, supported on desktop platforms

More details can be found here for iOS and Android

URL schemes are only supported if there are apps installed on the device that can support them. For example, iOS simulators don't have a default email or phone apps installed, so can't open tel: or mailto: links.

Checking supported schemes #

If you need to know at runtime whether a scheme is guaranteed to work before using it (for instance, to adjust your UI based on what is available), you can check with canLaunchUrl.

However, canLaunchUrl can return false even if launchUrl would work in some circumstances (in web applications, on mobile without the necessary configuration as described above, etc.), so in cases where you can provide fallback behavior it is better to use launchUrl directly and handle failure. For example, a UI button that would have sent feedback email using a mailto URL might instead open a web-based feedback form using an https URL on failure, rather than disabling the button if canLaunchUrl returns false for mailto.

Encoding URLs #

URLs must be properly encoded, especially when including spaces or other special characters. In general this is handled automatically by the Uri class.

However, for any scheme other than http or https, you should use the query parameter and the encodeQueryParameters function shown below rather than Uri's queryParameters constructor argument for any query parameters, due to a bug in the way Uri encodes query parameters. Using queryParameters will result in spaces being converted to + in many cases.

String? encodeQueryParameters(Map<String, String> params) {
  return params.entries
      .map((e) => '${Uri.encodeComponent(e.key)}=${Uri.encodeComponent(e.value)}')
      .join('&');
}

final Uri emailLaunchUri = Uri(
  scheme: 'mailto',
  path: 'smith@example.com',
  query: encodeQueryParameters(<String, String>{
    'subject': 'Example Subject & Symbols are allowed!'
  }),
);

launchUrl(emailLaunchUri);

URLs not handled by Uri #

In rare cases, you may need to launch a URL that the host system considers valid, but cannot be expressed by Uri. For those cases, alternate APIs using strings are available by importing url_launcher_string.dart.

Using these APIs in any other cases is strongly discouraged, as providing invalid URL strings was a very common source of errors with this plugin's original APIs.

File scheme handling #

file: scheme can be used on desktop platforms: Windows, macOS, and Linux.

We recommend checking first whether the directory or file exists before calling launchUrl.

Example:

var filePath = '/path/to/file';
final Uri uri = Uri.file(filePath);

if (await File(uri.toFilePath()).exists()) {
  if (!await launchUrl(uri)) {
    throw 'Could not launch $uri';
  }
}

macOS file access configuration

If you need to access files outside of your application's sandbox, you will need to have the necessary entitlements.

Browser vs in-app Handling #

On some platforms, web URLs can be launched either in an in-app web view, or in the default browser. The default behavior depends on the platform (see launchUrl for details), but a specific mode can be used on supported platforms by passing a LaunchMode.