diff --git a/README.md b/README.md
index 9f5bfdb..886c591 100644
--- a/README.md
+++ b/README.md
@@ -8,19 +8,16 @@ For general support or usage questions, use the [Auth0 Community](https://commun
**Do not report security vulnerabilities on the public GitHub issue tracker.** The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.
-## What is Auth0?
+---
-Auth0 helps you to:
+
+
+
+
+
+
+
-- Add authentication with [multiple sources](https://auth0.com/docs/authenticate/identity-providers), either social identity providers such as **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce** (amongst others), or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS, or any SAML Identity Provider**.
-- Add authentication through more traditional **[username/password databases](https://auth0.com/docs/authenticate/database-connections/custom-db)**.
-- Add support for **[linking different user accounts](https://auth0.com/docs/manage-users/user-accounts/user-account-linking)** with the same user.
-- Support for generating signed [JSON Web Tokens](https://auth0.com/docs/secure/tokens/json-web-tokens) to call your APIs and **flow the user identity** securely.
-- Analytics of how, when, and where users are logging in.
-- Pull data from other sources and add it to the user profile through [JavaScript Actions](https://auth0.com/docs/customize/actions).
+
Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out Why Auth0?
-**Why Auth0?** Because you should save time, be happy, and focus on what really matters: building your product.
-
-## License
-
-This project is licensed under Apache License 2.0. See the [LICENSE](LICENSE) file for more information.
+
This project is licensed under the MIT license. See the LICENSE file for more info.
diff --git a/sample/.env.example b/sample/.env.example
index 6b105e8..e6052bf 100644
--- a/sample/.env.example
+++ b/sample/.env.example
@@ -8,10 +8,5 @@ AUTH0_DOMAIN={DOMAIN}
AUTH0_CLIENT_ID={CLIENT_ID}
#
# The custom scheme for the Android callback and logout URLs.
-# Only set a value if you prefer not to use the default scheme (https).
-# If you set a value:
-# 1. Update the Android callback and logout URLs in the
-# settings page of your Auth0 application with the custom scheme value.
-# 2. Update the scheme value in android/app/src/main/res/values/strings.xml
#
-# AUTH0_CUSTOM_SCHEME=
\ No newline at end of file
+AUTH0_CUSTOM_SCHEME=com.auth0.sample
diff --git a/sample/README.md b/sample/README.md
index a302dfb..99e5c69 100644
--- a/sample/README.md
+++ b/sample/README.md
@@ -8,30 +8,56 @@ This sample app demonstrates the integration of the Auth0 Flutter SDK into a Flu
- Xcode 14.x / 15.x (for iOS/macOS)
- Android Studio 4+ (for Android)
-## Configure Auth0 Application
+> [!NOTE]
+> On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links as callback and logout URLs. auth0_flutter will fall back to using a custom URL scheme on older iOS / macOS versions.
+>
+> **This feature requires Xcode 15.3+ and a paid Apple Developer account**.
+>
+> If you do not have a paid Apple Developer account, skip **step 3** and set the `useHTTPS` parameter to `false` in the `login()` and `logout()` calls at `lib/example_app.dart`.
+
+> [!IMPORTANT]
+> On every step, if you have a [custom domain](https://auth0.com/docs/customize/custom-domains), replace the `YOUR_AUTH0_DOMAIN` and `{DOMAIN}` placeholders with your custom domain instead of the value from the settings page.
+
+## 1. Configure the Auth0 Application
### 📱 Mobile/Desktop
-Go to the settings page of your [Auth0 application](https://manage.auth0.com/#/applications/) and add the corresponding URL to **Allowed Callback URLs** and **Allowed Logout URLs**, according to the app target you want to run. If you are using a [custom domain](https://auth0.com/docs/customize/custom-domains), replace `YOUR_AUTH0_DOMAIN` with the value of your custom domain instead of the value from the settings page.
+Go to the settings page of your [Auth0 application](https://manage.auth0.com/#/applications/) and add the following URLs to **Allowed Callback URLs** and **Allowed Logout URLs**, depending on the platform you want to use.
-**Android**
+#### Android
```text
SCHEME://YOUR_AUTH0_DOMAIN/android/YOUR_PACKAGE_NAME/callback
```
-**iOS**
+#### iOS
```text
-YOUR_BUNDLE_ID://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_ID/callback
+https://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback
```
-**macOS**
+#### macOS
```text
-YOUR_BUNDLE_ID://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_ID/callback
+https://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback
```
+
+ Example
+
+If your iOS bundle identifier were `com.example.MyApp` and your Auth0 Domain were `example.us.auth0.com`, then this value would be:
+
+```text
+https://example.us.auth0.com/ios/com.example.MyApp/callback,
+com.example.MyApp://example.us.auth0.com/ios/com.example.MyApp/callback
+```
+
+
+> [!IMPORTANT]
+> Make sure that the Auth0 application type is **Native**. Otherwise, you might run into errors due to the different configurations of other application types.
+
### 🌐 Web
Go to the settings page of your [Auth0 application](https://manage.auth0.com/#/applications/) and configure the following URLs:
@@ -40,54 +66,81 @@ Go to the settings page of your [Auth0 application](https://manage.auth0.com/#/a
- Allowed Logout URLs: `http://localhost:3000`
- Allowed Web Origins: `http://localhost:3000`
-## Configure Auth0 Flutter
+## 2. Configure the SDK
+
+### 📱🌐 Mobile/Desktop/Web
-The sample app uses [flutter_dotenv](https://pub.dev/packages/flutter_dotenv) for its configuration. Rename `.env.example` to `.env` and provide the appropriate **domain** and **Client Id**. Optionally, when using Android, you can configure the scheme as well. This can be set to a custom scheme, or `https` if you want to use [Android App Links](https://auth0.com/docs/applications/enable-android-app-links). You can read more about setting this value in the [Auth0.Android SDK README](https://github.com/auth0/Auth0.Android#a-note-about-app-deep-linking).
+Rename `.env.example` to `.env` and replace the `{CLIENT_ID}` and `{DOMAIN}` placeholders with the Client ID and domain of your Auth0 application.
```sh
AUTH0_DOMAIN={DOMAIN}
AUTH0_CLIENT_ID={CLIENT_ID}
-# AUTH0_CUSTOM_SCHEME=SCHEME
+AUTH0_CUSTOM_SCHEME=com.auth0.sample # For Android
```
-### Android
+### Android: Configure the string resources
-In the sample, we are using values referenced from `android/app/src/main/res/values/strings.xml`. Rename `strings.xml.example` to `strings.xml` and fill in the respective values.
+In the sample, we are using values referenced from `android/app/src/main/res/values/strings.xml`. Rename `strings.xml.example` to `strings.xml` and replace the `{DOMAIN}` placeholder with the domain of your Auth0 application.
-- `com_auth0_domain`: The domain of your Auth0 tenant. Generally, you can find this in the Auth0 Dashboard under your application's settings in the **Domain** field. If you are using a custom domain, you should set this to the value of your custom domain instead.
-- `com_auth0_scheme`: The scheme to use. Can be a custom scheme, or `https` if you want to use [Android App Links](https://auth0.com/docs/applications/enable-android-app-links). You can read more about setting this value in the [Auth0.Android SDK README](https://github.com/auth0/Auth0.Android#a-note-about-app-deep-linking).
+```xml
+
+
+ {DOMAIN}
+ com.auth0.sample
+
+```
-### iOS/macOS
+## 3. iOS/macOS: Configure the associated domain
-The sample has already configured the required **Url Types** to ensure the callback and logout URLs can reach the app, so there is nothing to configure to run the sample on iOS and macOS.
+### Configure the entitlements
-## Run the sample
+Open `ios/Runner.xcodeproj` (or `macos/Runner.xcodeproj`, for macOS) in Xcode and go to the settings of the **Runner** target. In the **Signing & Capabilities** tab, change the default bundle identifier from `com.auth0.samples.SwiftSample` to another value of your choosing. Then, ensure the **Automatically manage signing** box is checked, and that your Apple Team is selected.
-To run the project, use the [Flutter CLI's](https://docs.flutter.dev/reference/flutter-cli) `run` command.
+Under **Associated Domains**, find the following entry:
-### 📱 Mobile/Desktop
+```text
+webcredentials:YOUR_AUTH0_DOMAIN
+```
-```sh
-flutter run
+Replace the `YOUR_AUTH0_DOMAIN` placeholder with the domain of your Auth0 application.
+
+
+ Example
+
+If your Auth0 Domain were `example.us.auth0.com`, then this value would be:
+
+```text
+webcredentials:example.us.auth0.com
```
+
-Ensure you have at least one emulator running. If you have multiple running, the CLI will prompt you to select the one to run the app on.
+### Configure the Team ID and bundle identifier
-### 🌐 Web
+Open the settings page of your Auth0 application, scroll to the end, and open **Advanced Settings > Device Settings**. In the **iOS** section, set **Team ID** to your [Apple Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/), and **App ID** to the app's bundle identifier.
+
+
+
+This will add the app to your Auth0 tenant's `apple-app-site-association` file.
+
+> [!NOTE]
+> For the associated domain to work, the app must be signed with your team certificate **even when building for the iOS simulator**. Make sure you are using the Apple Team whose Team ID is configured in the settings page of your Auth0 application.
+
+## 4. Run the sample
+
+Use the [Flutter CLI](https://docs.flutter.dev/reference/flutter-cli) to run the app.
+
+### 📱 Mobile/Desktop
```sh
-flutter run -d chrome --web-port 3000 --web-renderer html
+flutter run
```
-## Compile the sample
+Ensure you have at least one emulator/simulator running. If you have multiple running, the CLI will prompt you to select the one to run the app on.
-To compile the project, use the [Flutter CLI's](https://docs.flutter.dev/reference/flutter-cli) `build` command, including the platform you want to target.
+### 🌐 Web
```sh
-flutter build apk
-flutter build ios
-flutter build macos
-flutter build web
+flutter run -d chrome --web-port 3000 --web-renderer html
```
## Issue Reporting
@@ -96,19 +149,16 @@ For general support or usage questions, use the [Auth0 Community](https://commun
**Do not report security vulnerabilities on the public GitHub issue tracker.** The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.
-## What is Auth0?
-
-Auth0 helps you to:
-
-* Add authentication with [multiple sources](https://auth0.com/docs/authenticate/identity-providers), either social identity providers such as **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce** (amongst others), or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS, or any SAML identity provider**.
-* Add authentication through more traditional **[username/password databases](https://auth0.com/docs/authenticate/database-connections/custom-db)**.
-* Add support for **[linking different user accounts](https://auth0.com/docs/manage-users/user-accounts/user-account-linking)** with the same user.
-* Support for generating signed [JSON Web Tokens](https://auth0.com/docs/secure/tokens/json-web-tokens) to call your APIs and **flow the user identity** securely.
-* Analytics of how, when, and where users are logging in.
-* Pull data from other sources and add it to the user profile through [JavaScript Actions](https://auth0.com/docs/customize/actions).
+---
-**Why Auth0?** Because you should save time, be happy, and focus on what really matters: building your product.
+
+
+
+
+
+
+
-## License
+
Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out Why Auth0?
-This project is licensed under Apache License 2.0. See the [LICENSE](../LICENSE) file for more information.
+
This project is licensed under the MIT license. See the LICENSE file for more info.
+