Quick start

GeoFlowLive integration into a FlutterFlow project

Integrating GeoFlowLive into your FlutterFlow project is easier than you might think! This quick-start guide provides a streamlined process to get you up and running in minutes. We'll cover the essential steps, from installing the library to using your first custom action.

Step 1: Acquire and Add GeoFlowLive to Your Project

The first step is to acquire the GeoFlowLive library from the FlutterFlow Marketplace.

1. Access the Marketplace: Navigate to the FlutterFlow Marketplace within the FlutterFlow platform.

2. Search for GeoFlowLive: Use the search bar to find the GeoFlowLive library.

3. Purchase the Library: Purchase the library following the FlutterFlow Marketplace purchase flow

4. Add to Your Project: Once you've acquired GeoFlowLive, add it to your desired FlutterFlow project. Follow the instruction on this link

Note: Purchases are single-use only and non-refundable. See Marketplace Terms of Service and our Refund Policy for details.

Step 2: Configure Location Permissions in FlutterFlow

To ensure GeoFlowLive functions correctly, you need to configure the necessary location permissions within your FlutterFlow project. This involves enabling the standard FlutterFlow location permission and adding custom permissions for more advanced features.

Part 1: Enable the Default FlutterFlow Location Permission

1. Navigate to Permissions: In your FlutterFlow project, go to Settings (the gear icon in the left sidebar) and then select Permissions.

2. Enable Location Permission: Locate the Location permission. Toggle the switch to enable it.

3. Enter Permission Message: In the Permission Message field, enter a clear and concise message explaining why your app needs access to the user's location. This message will be displayed to the user when they are prompted to grant location permission. A good message could be: "This app needs to access your location to provide location-based services, such as finding nearby places and tracking your movement."

Part 2: Add Custom Permissions (Advanced)

For full functionality, GeoFlowLive requires additional custom permissions. Add the following permissions in the "Custom" section:

iOS Permission Key	Android Permission Name	Permission Message Example
NSLocationWhenInUseUsageDescription	android.permission.ACCESS_FINE_LOCATION	"This app needs to access your precise location to provide accurate location-based services."
N/A	android.permission.FOREGROUND_SERVICE	"This app uses a foreground service to track location in the background when feature X is active."
NSLocationAlwaysUsageDescription	android.permission.FOREGROUND_SERVICE_LOCATION	"This app requires constant location access to enable features like real-time location sharing and geofencing."
N/A	android.permission.WAKE_LOCK	"This app requests a wake lock to ensure continuous location tracking, even when the screen is off."

Instructions for adding Custom Permissions

1. In the "Custom" section select the + button

2. Add the "iOS Permission Key" , "Android Permission Name" and "Permission Message" in the fields

3. Press the check button to save the new permission

4. Repeat the process for each custom permission displayed on the table

Important Considerations:

• iOS Permissions: For iOS, you must provide a value for the "iOS Permission Key" field. Use the keys showed in the table.

• Android Permissions: For Android, you must provide a value for the "Android Permission Name" field. Use the names showed in the table.

• Permission Messages: Craft clear and honest permission messages. Explain exactly why your app needs each permission. Vague or misleading messages can lead to users denying permissions.

• Foreground Services: The android.permission.FOREGROUND_SERVICE and android.permission.FOREGROUND_SERVICE_LOCATION are necessary if your app needs to collect location data in the background (e.g., for geofencing or continuous tracking). Be sure to clearly explain this background usage in your permission message and in your app's description.

• Wake Lock: The android.permission.WAKE_LOCK permission is needed if you need to keep the device awake to ensure continuous location tracking. Be mindful of battery consumption when using wake locks.

By configuring these permissions, you ensure that GeoFlowLive has the necessary access to provide accurate and reliable location data in your FlutterFlow application.

Advance - iOS Background Location Configuration (Important for Background Tracking)

If your app requires location updates while in the background (e.g., for geofencing, fitness tracking, or other continuous monitoring), you must perform the following additional configuration steps in your FlutterFlow project's iOS code:

1. Enable Background Modes Capability:

   • Open your FlutterFlow project's iOS code in Xcode.

   • Select your project in the Project Navigator.

   • Select your target.

   • Go to the "Signing & Capabilities" tab.

   • Click "+ Capability" in the top left corner.

   • Search for and add "Background Modes".

   • Check the box next to "Location updates".

Warning: Failing to enable the "Location updates" background mode will prevent your app from receiving location updates when it's in the background, even if you have been granted "Always" location permission.

1. Clear Explanation in Permission Message: Ensure that your NSLocationAlwaysUsageDescription clearly explains why the app needs background location access. For example: "This app requires continuous access to your location, even when it's in the background, to provide real-time location sharing with your friends and family."

Step 3: Implement a Basic Location Monitoring Flow

FlutterFlow Page Editor

Now that you've integrated GeoFlowLive and configured the necessary permissions, you can start incorporating the provided custom actions into your FlutterFlow project's logic. The following example demonstrates a basic flow that checks if location services are enabled, requests location permissions if necessary, and then starts listening for real-time location updates. Tailor this flow to meet the specific requirements of your application.

1. Trigger: Set the trigger for this logic to "On Page Load" of your desired page

2. Check Location Service Status:

   • Add a Custom Action to the flow.

   • Select the geoFlowLiveIsLocationServiceEnabled custom action.

   • Assign the output of this action to an Action Output Variable (e.g., isServiceEnabled).

3. Conditional Branching:

   • Add a Conditional Action (the "IF/ELSE" widget in FlutterFlow).

   • Set the condition to isServiceEnabled == true. This checks if location services are enabled.

4. If Location Services Are Enabled (TRUE branch):

   • Check Location Permissions: Add a Custom Action to the TRUE branch.

     • Select the geoFlowLiveCheckLocationPermission custom action.

     • Assign the output to an Action Output Variable (e.g., locationPermission).

   • Conditional Branching (Permissions): Add another Conditional Action.

     • Set the condition to locationPermission == GeoFlowLivePermission.always || locationPermission == GeoFlowLivePermission.while_in_use. This checks if the app has the necessary location permissions.

   • Start Listening for Location Updates (TRUE branch - Permissions Granted): Add a Custom Action.

     • Select the geoFlowLiveStartListeningLocationUpdate custom action.

     • Configure the required parameters:

       • settings: Use the getDefaultSettings helper function to create the default location settings.

       • onLocationUpdate: Create a custom function to handle location updates. This function should take a GeoFlowLivePosition as input and perform the desired actions (e.g., update a page variable, display the location on a map).

       • onError: Create a custom function to handle errors. This function should take a String as input (the error message) and display an error message to the user.

       • onPermissionDenied: Create a custom function to handle permission denied events (e.g., display an alert message).

       • onLocationServiceDisabled: Create a custom function to handle location service disabled events (e.g., display an alert message).

   • Handle Denied Permissions (FALSE branch - Permissions Denied): Add an Alert Dialog action.

     • Configure the alert dialog to inform the user that location permissions are required and guide them to the app settings. You can use the geoFlowLiveOpenAppSettings custom action to open the app settings page.

5. If Location Services Are Disabled (FALSE branch):

   • Add an Alert Dialog action.

   • Configure the alert dialog to inform the user that location services are disabled and guide them to the device's location settings. You can use the geoFlowLiveOpenLocationSettings custom action to open the location settings page.

Important Considerations:

• Error Handling: Implement robust error handling in your onError callback function to gracefully handle potential issues with location updates.

• Permission Handling: Always handle the onPermissionDenied and onLocationServiceDisabled callbacks to provide a clear and informative user experience.

• Background Location: If you need background location updates, remember to configure the necessary settings in your FlutterFlow project (as described in the previous step).

• Stop Listening: Remember to call the geoFlowLiveStop action when the page is disposed of (using the "On Dispose" trigger) to prevent battery drain and potential memory leaks.

This example provides a base foundation for building location-aware features in your FlutterFlow app using GeoFlowLive. Remember to adapt this flow to your specific needs and implement appropriate error and permission handling.