Skip to content

Commit

Permalink
Enhance README in flutter_custom_tabs
Browse files Browse the repository at this point in the history
  • Loading branch information
droibit committed Dec 6, 2023
1 parent eb1c295 commit 3330e75
Show file tree
Hide file tree
Showing 4 changed files with 35 additions and 14 deletions.
37 changes: 29 additions & 8 deletions flutter_custom_tabs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@
[![pub package](https://img.shields.io/pub/v/flutter_custom_tabs.svg)](https://pub.dartlang.org/packages/flutter_custom_tabs)

A Flutter plugin for mobile apps to launch a URL in Custom Tabs.
This plugin allows you to add the browser experience that Custom Tabs provides to your mobile apps.
The plugin allows you to add the browser experience that Custom Tabs provides to your mobile apps.

In version 2.0, the plugin expands the support for launching a URL in mobile apps:
- Launch a URL in an external browser.
- Launch a deep link URL.

| | Android | iOS | Web |
|-------------|---------|-------|-------|
Expand All @@ -24,7 +28,7 @@ dependencies:
- Android Gradle Plugin v7.4.0 and above.
- Kotlin v1.7.0 and above.
```diff
```groovy
// your-project/android/build.gradle
buildscript {
ext.kotlin_version = '1.7.0' // and above if explicitly depending on Kotlin.
Expand Down Expand Up @@ -52,7 +56,7 @@ void _launchURL(BuildContext context) async {
final theme = Theme.of(context);
try {
await launchUrl(
Uri.parse('https://flutter.dev'),
Uri.parse('https://flutter.dev'),
customTabsOptions: CustomTabsOptions(
colorSchemes: CustomTabsColorSchemes.defaults(
toolbarColor: theme.colorScheme.surface,
Expand Down Expand Up @@ -85,8 +89,8 @@ See the example app for more complex examples.
This package supports a wide range of Custom Tabs customizations,
but we have experimentally introduced a lightweight URL launch for users who don't need as much in v2.0.0.

> [!TIP]
> On Android, **the lightweight version** prioritizes launching the default browser that supports Custom Tabs over Chrome.
> [!NOTE]
> On Android, **the lightweight version** prefers launching the default browser that supports Custom Tabs over Chrome.
```dart
import 'package:flutter/material.dart';
Expand Down Expand Up @@ -136,12 +140,13 @@ Support status in `flutter_custom_tabs`:
## Advanced Usage

### Deep Linking
Supports launching deep link URLs.
Supports launching a deep link URL.
(If a native app that responds to the deep link URL is installed, it will directly launch it. otherwise, it will launch a custom tab.)

```dart
import 'package:flutter/material.dart';
import 'package:flutter_custom_tabs/flutter_custom_tabs.dart';
// or import 'package:flutter_custom_tabs/flutter_custom_tabs_lite.dart';
Future<void> _launchDeepLinkURL(BuildContext context) async {
final theme = Theme.of(context);
Expand All @@ -161,8 +166,22 @@ Future<void> _launchDeepLinkURL(BuildContext context) async {
}
```

## Launch in an external browser
By default, if no mobile platform-specific options are specified, a URL will be launched in an external browser.

> [!TIP]
> Android: `CustomTabsOptions.externalBrowser` supports HTTP request headers.
```dart
import 'package:flutter_custom_tabs/flutter_custom_tabs.dart';
Future<void> _launchInExternalBrowser() async {
await launchUrl(Uri.parse('https://flutter.dev'));
}
```

### Show as a bottom sheet
You can launch URLs in Custom Tabs as a bottom sheet.
You can launch a URL in Custom Tabs as a bottom sheet.

Requirements:
- Android: Chrome v107 and above or [other browsers](https://developer.chrome.com/docs/android/custom-tabs/browser-support/#setinitialactivityheightpx)
Expand Down Expand Up @@ -204,14 +223,16 @@ Future<void> _launchURLInBottomSheet(BuildContext context) async {
```

### Prefer the default browser over Chrome
On Android, the default browser to launch is Chrome, which supports all Custom Tabs features.
On Android, the plugin defaults to launching Chrome, which supports all Custom Tabs features.
You can prioritize launching the default browser on the device that supports Custom Tabs over Chrome.

> [!NOTE]
> Some browsers may not support the options specified in CustomTabsOptions.
> - See: [Custom Tabs Browser Support](https://developer.chrome.com/docs/android/custom-tabs/browser-support/).
```dart
import 'package:flutter_custom_tabs/flutter_custom_tabs.dart';
Future<void> _launchURLInDefaultBrowserOnAndroid() async {
await launchUrl(
Uri.parse('https://flutter.dev'),
Expand Down
4 changes: 2 additions & 2 deletions flutter_custom_tabs/example/lib/main.dart
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ class MyApp extends StatelessWidget {
child: const Text('Show flutter.dev (lite ver)'),
),
FilledButton(
onPressed: () => _launchDeepLinkingURL(context),
onPressed: () => _launchDeepLinkURL(context),
child: const Text('Deep link to platform maps'),
),
FilledButton(
Expand Down Expand Up @@ -149,7 +149,7 @@ Future<void> _launchUrlLite(BuildContext context) async {
}
}

Future<void> _launchDeepLinkingURL(BuildContext context) async {
Future<void> _launchDeepLinkURL(BuildContext context) async {
final theme = Theme.of(context);
final uri = Platform.isIOS
? 'https://maps.apple.com/?q=tokyo+station'
Expand Down
4 changes: 2 additions & 2 deletions flutter_custom_tabs_android/example/lib/main.dart
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ class MyApp extends StatelessWidget {
child: const Text('Show flutter.dev in bottom sheet'),
),
FilledButton.tonal(
onPressed: () => _launchDeepLinkingURL(context),
onPressed: () => _launchDeepLinkURL(context),
child: const Text('Deep link to Google Maps'),
),
FilledButton.tonal(
Expand Down Expand Up @@ -138,7 +138,7 @@ Future<void> _launchURLInBottomSheet(BuildContext context) async {
}
}

Future<void> _launchDeepLinkingURL(BuildContext context) async {
Future<void> _launchDeepLinkURL(BuildContext context) async {
final theme = Theme.of(context);
try {
await CustomTabsPlatform.instance.launch(
Expand Down
4 changes: 2 additions & 2 deletions flutter_custom_tabs_ios/example/lib/main.dart
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ class MyApp extends StatelessWidget {
child: const Text('Show flutter.dev in bottom sheet'),
),
FilledButton(
onPressed: () => _launchDeepLinkingURL(context),
onPressed: () => _launchDeepLinkURL(context),
child: const Text('Deep link to Apple Maps'),
),
FilledButton(
Expand Down Expand Up @@ -107,7 +107,7 @@ Future<void> _launchURLInBottomSheet(BuildContext context) async {
}
}

Future<void> _launchDeepLinkingURL(BuildContext context) async {
Future<void> _launchDeepLinkURL(BuildContext context) async {
final theme = Theme.of(context);
try {
await CustomTabsPlatform.instance.launch(
Expand Down

0 comments on commit 3330e75

Please sign in to comment.