Yet Another Salesforce Tech Blog

Building a Flutter + Salesforce Sample App: Setup (2/3)

This project consists of a Flutter frontend and a Firebase backend (Cloud Functions). Follow these steps to run install the dependencies and cloning the repository

Prerequisites

Ensure you have the following installed:

  • Flutter SDK: Install Flutter (Version 3.x+)
  • Node.js & npm: Install Node.js (Version 18 or 20 recommended for Firebase Functions)
  • Firebase CLI:
    • npm install -g firebase-tools
  • Salesforce Org: A Developer Edition org with a Connected App configured for OAuth

Google Cloud Platform Setup

Create Firebase project and enable services

  1. Go to the Firebase Console.
  2. Click Add project and follow the setup wizard.
  3. Once created, upgrade your project to the Blaze (Pay as you go) plan. This is required for Cloud Functions and Secret Manager.
  4. Go to Build > Authentication.
  5. Click Get Started.
  6. Enable Email/Password sign-in provider
    • This project uses Custom Authentication (signInWithCustomToken) to log users in after they authenticate with Salesforce.
    • You do not need to enable a specific “Custom” provider toggle in the console; the Admin SDK (used by Cloud Functions) handles this automatically.
  7. Go to Build > Firestore Database.
  8. Click Create Database.
  9. Choose a location (e.g., us-central1).
  10. Start in Production mode.
  11. Note: The Flutter app requires the cloud_firestore dependency (already included in pubspec.yaml) to interact with this database.
  12. Go to Build > Functions.
  13. Click Get Started to initialize the service.
  14. Go to Build > Hosting.
  15. Click Get Started.
  16. Follow the on-screen instructions (you can skip the CLI install steps if you already have it)
  17. This service will host your Flutter Web application

Authorized Domains

For Flutter Web apps and OAuth redirects (like the Salesforce flow), you must whitelist the domains where your app is hosted. This prevents unauthorized sites from using your Firebase project’s authentication.

  1. Navigate to Settings:
    • In the Authentication section, click on the Settings tab.
    • Select Authorized domains.
  2. Add Domains:
    Firebase automatically adds localhost and your default Firebase hosting domains (project-id.firebaseapp.com, project-id.web.app). You need to add any other domains you use.
    • Local Development:
      • Ensure localhost is present (it usually is by default).
    • Production / Custom Domains:
      • If you host your app on a custom domain (e.g., www.myapp.com), click Add domain.
      • Enter your domain name.
      • Click Add.
    • Salesforce Redirects:
      • The Salesforce OAuth flow redirects back to your app. Ensure the domain hosting your oauth2redirect.html file is listed here.
      • For local dev: localhost covers http://localhost:8686/oauth2redirect.html.
      • For production: Ensure your hosting domain is added.

Configure Secret Manager

The backend uses Google Cloud Secret Manager to securely store your Salesforce credentials

Login to Firebase with CLI

firebase login

Run these commands in your terminal to set the secrets. You will be prompted to enter the values from your Salesforce Connected App.

# Set the Salesforce Client ID
firebase functions:secrets:set client_id

# Set the Salesforce Client Secret
firebase functions:secrets:set client_secret

iOS and Android emulator setup

To run the Flutter app on mobile devices, you need to set up the respective emulators for iOS and Android.

Android Emulator
The Android Emulator is part of Android Studio.

Install Android Studio:

  1. Download and install Android Studio.
  2. During the setup wizard, ensure Android Virtual Device is selected.
  3. Create a Virtual Device (AVD):
    • Open Android Studio and go to Device Manager (usually found under the “More Actions” menu on the welcome screen, or via Tools > Device Manager inside a project).
  4. Click Create Device.
  5. Select a hardware profile (e.g., Pixel 7).
  6. Select a System Image (e.g., API 34 or API 35). Download it if necessary.
  7. Click Finish.
  8. Start the Emulator:
    • Click the Play button in the Device Manager to launch the emulator

iOS Simulator

The iOS Simulator is part of Xcode.

  1. Install Xcode:
    • Download and install Xcode from the Mac App Store.
    • Open Xcode once to accept the license agreement and install additional components.
  2. Open the Simulator:
    • You can open it directly via Spotlight Search (Cmd + Space, type “Simulator”).

Verify detection

Run flutter devices in your terminal. You should see both the iOS and Android simulator. The emulators needs to started. You can also used flutter emulators command to list (and start) the emulators

Configuring environments (with environment.json)

The example.json file serves as a template or blueprint for your application’s configuration.

You need a “Connected App” in Salesforce to get these values.

  1. Log in to Salesforce Setup.
  2. Go to App Manager -> New Connected App.
  3. Enable OAuth Settings.
  4. CLIENT_ID: Once the app is created, copy the Consumer Key. Paste it here.
  5. SCOPE: In the Connected App settings, add the scopes you need (e.g., Access your basic information (id), Access and manage your data (api), Perform requests on your behalf at any time (refresh_token)). The string in your JSON must match these selections (space-separated).
  6. CALLBACK_URL_IOS_ANDROID: Define a custom URL for your mobile app (e.g., salesforce.sample.app://oauth2redirect).
  7. CALLBACK_URL_WEB: Define a URL for the web flow (usually your Firebase Hosting URL + /oauth2redirect.html).
    • Important: You must paste BOTH of these URLs into the “Callback URL” field in your Salesforce Connected App settings (separated by a new line)
  8. CLOUD_FUNCTIONS_BASE_URL
    • Deploy your functions using firebase deploy --only functions.
    • Look at the terminal output or the Firebase Console (Functions tab).
    • Copy the base URL (e.g., https://us-central1-your-project.cloudfunctions.net).
  9. CUSTOM_URI_SCHEME:
    • This is the prefix of your mobile redirect URL (the part before ://).
    • In your example, it is salesforce.sample.app.
    • Crucial: This string must match the URL Scheme defined in your iOS Info.plist and Android AndroidManifest.xml files, or the app won’t open after login.
  10. AUTHORIZE_URL / TOKEN_URL:
    • The {domain} placeholder indicates your code will dynamically swap this value.
    • Usually, you swap it with login for Production or test for Sandbox.
    • If you use a custom domain (My Domain), you swap it with your company specific domain (e.g., mycompany).
Jani Ruohomaa
,
, , , , , , , , , ,

Leave a comment