Without any intention, some of the applications that I have published to the Google Play Store are being used by a considerable amount of people (to my sheer astonishment).

After patting myself on the back, I started looking at the data of the users who are interacting (or just downloaded) with my application(s). One of the insights available in the Google Play console is the country of origin of users. There, I found out that some of my applications have a loyal audience in some non-English-speaking countries.

A people pleaser by heart, I figured the best course of action would be to add support to the spoken languages at the top 3 or 4 countries on that list. That is where I discovered the wonderful world of Internationalizing a Flutter application.

And that leads us to the purpose of this article: helping you understand how to add multiple language support in your Flutter application.

Table of Contents

• How to Set Up Localization in Flutter

• Localizations With Dynamic Values

• Testing With Localization

• References

How to Set Up Localization in Flutter

First and foremost, you need to include two packages in your pubspec.yaml file:

1. flutter_localizations

2. intl

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

After doing this, head over to the bottom of your pubspec.yaml file and under the flutter section, make sure to have the generate attribute set to true:

flutter:
  generate: true

To support this, you will need to create another .yaml file called l10.yaml with these configurations:

arb-dir: lib/l10n   /// This is where our translation files are located at
template-arb-file: app_en.arb       /// Sets the English template
output-localization-file: app_localizations.dart  /// Output file where the generate command will generate localizations

☝️ Head over here to read about more configuration options in the l10.yaml file

To allow your application support multiple languages, add the following to your MaterialApp widget:

return const MaterialApp(
  title: 'My Application',
  localizationsDelegates: [                    /// From here
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: [             
    Locale('en'), 
    Locale('hi'),
  ],                                           /// To here
  home: MainScreen(),
);

Having defined the languages we want to support, we need to create the files with the translations for these languages.

Create a folder called l10 under your lib directory:

Inside the folder, you need to place files with an .arb extension that will hold key-value pairs of translations. So, for example, if your application needs to support English and Hindi, you will need to create two files:

• app_en.arb

• app_hi.arb

The contents of these files look like this:

{
        "appTitle": "Birthday Calendar",
        "settings": "Settings",
        "addBirthday": "Add Birthday",
        /...
}

{
        "appTitle": "जन्मदिन कैलेंडर",
        "settings": "सेटिंग्स",
        "addBirthday": "जन्मदिन जोड़ें",
        /...
}

Basically, you have a JSON object, with key value pairs, where the keys are the same across all JSON files, but the values are written in a different language.

The following command is used to generate the files associated with the contents of the .arb files:

flutter gen-l10n

In files where you intend to use translations, you need to add the following import:

import 'package:flutter_gen/gen_l10n/app_localizations.dart';

To access one of the keys from the .arb files, you need to use this code:

AppLocalizations.of(context)!.appTitle //Or another key name from the .arb file

✋ Each time that you add more key-value pairs to your .arb files, you will need to run the command in the terminal to generate those translations. Otherwise, you won’t be able to access them through the code

Localizations With Dynamic Values

Seems straightforward up to this point, right? Well, what if you have places in your application that depend on data that is dynamic and not static? For example, in one of my applications, I have a string that includes an error and that error may change depending on the invocation of an API.

AlertDialog alertDialog = AlertDialog(
      title: const Text("Update Failed To Install ❌"),
      content:
          Text("Birthday Calendar has failed to update because: \n $error"),
      actions: [alertDialogTryAgainButton, alertDialogCancelButton],
    );

In order to use localized strings here, we need to create a key-value pair in our .arb file that has a placeholder for the error:

"updateFailedToInstallDescription": "Birthday Calendar has failed to update because: {error}"

And we can use it by doing this:

AlertDialog alertDialog = AlertDialog(
      title: Text(AppLocalizations.of(context)!.updateFailedToInstallTitle),
      content:
          Text(AppLocalizations.of(context)!.updateFailedToInstallDescription(error)),  /// <--- HERE
      actions: [alertDialogTryAgainButton, alertDialogCancelButton],
    );

Testing With Localization

So you added localizations to your application, but now you realize that your unit tests need to be revamped in order to accommodate for this change. We’ll break this section down into two types of tests you may have:

• Unit tests

• Integration tests

For one of my applications, I had a utility class that was paired with a unit test class. So far, so good. When I added localization support to that application, one of the utility methods changed, since it now had to return a value based on the localization. To do that, I had to pass over the AppLocalizations object as an argument to the method. That argument relied on the BuildContext:

 static String convertAndTranslateMonthNumber(
      int month, AppLocalizations appLocalizations) {
    switch (month) {
      case JANUARY_MONTH_NUMBER:
        return appLocalizations.january;
      case FEBRUARY_MONTH_NUMBER:
        return appLocalizations.february;
      case MARCH_MONTH_NUMBER:
        return appLocalizations.march;
      case APRIL_MONTH_NUMBER:
        return appLocalizations.april;
      case MAY_MONTH_NUMBER:
        return appLocalizations.may;
      case JUNE_MONTH_NUMBER:
        return appLocalizations.june;
      case JULY_MONTH_NUMBER:
        return appLocalizations.july;
      case AUGUST_MONTH_NUMBER:
        return appLocalizations.august;
      case SEPTEMBER_MONTH_NUMBER:
        return appLocalizations.september;
      case OCTOBER_MONTH_NUMBER:
        return appLocalizations.october;
      case NOVEMBER_MONTH_NUMBER:
        return appLocalizations.november;
      case DECEMBER_MONTH_NUMBER:
        return appLocalizations.december;
      default:
        return "";
    }
  }

This didn’t fare so well in my corresponding unit test class, since I had to create a BuildContext. Since doing that in a unit test class is problematic, there is a different way to get the AppLocalizations object without having to rely on a BuildContext.

final appLocalizations = lookupAppLocalizations(const Locale('en'))

This way, we state the locale we want and then we can use it in any of our tests. My unit test looks like this after the revision:

test("DateService convert month number 8 to August", () {
    final int monthNumber = 8;
    final String monthName =
        BirthdayCalendarDateUtils.convertAndTranslateMonthNumber(
            monthNumber, appLocalizations);
    expect(monthName, "August");
  });

As for integration tests, you will need to wrap your widget inside of a Localizations widget.

testWidgets("Your test description",
      (WidgetTester tester) async {
    await tester.pumpWidget(
        Localizations(
          delegates: [
            //localization delegates
          ],
          locale: Locale('en'),
          child: Widget(),
        );
    );
    //Your logic here
  });

To see how all of this is implemented inside of an application, you can go here.

And if you want to download the application, you can head here.

If you would like to read other articles I have written, you can find them here.

References

• Official Flutter Documentation

At the time, there was no built-in composable to display tooltips and there were several alternative solutions circling online. The problem with those solutions was that once Jetpack Compose released newer versions, those solutions might break. So it wasn’t ideal and the community was left hoping that sometime in the future, support would be added for tooltips.

I’m glad to say that since version 1.1.0 of Compose Material 3, we now have built in tooltip support. 👏

While this in itself is great, more than a year has passed since that version was released. And with subsequent versions, the API related to tooltips changed drastically as well.

If you go over the changelog, you will see how the public and internal APIs have changed. So bear in mind, that when you read this article, things may have continued to change as everything related to Tooltips is still marked by the annotation ExperimentalMaterial3Api::class.

❗️ The version of material 3 used for this article is 1.2.1, which was released on March 6th, 2024

Tooltip Types

We now have support for two different types of tooltips:

1. Plain tooltip

2. Rich media tooltip

Plain Tooltip

You can use the first kind to provide information about an icon button that wouldn’t be clear otherwise. For example, you can use a plain tooltip to indicate to a user what the icon button represents.

To add a tooltip to your application, you use the TooltipBox composable. This composable takes several arguments:

fun TooltipBox(
    positionProvider: PopupPositionProvider,
    tooltip: @Composable TooltipScope.() -> Unit,
    state: TooltipState,
    modifier: Modifier = Modifier,
    focusable: Boolean = true,
    enableUserInput: Boolean = true,
    content: @Composable () -> Unit,
)

Some of these should be familiar to you if you have used Composables before. I’ll highlight the ones that have a specific use case here:

• positionProvider - Of PopupPositionProvider type, and is used to calculate the position of the tooltip.

• tooltip - This is where you can design the UI of how the tooltip will look like.

• state - This holds the state that is associated with a specific Tooltip instance. It exposes methods like showing/dismissing the tooltip and when instantiating an instance of one, you can declare if the tooltip should be persistent or not (meaning if it should keep displaying on the screen until a user performs a click action outside the tooltip).

• content - This is the UI that the tooltip will display above/below.

Here is an example of instantiating a BasicTooltipBox with all the relevant arguments filled in:

@OptIn(ExperimentalFoundationApi::class, ExperimentalMaterial3Api::class)
@Composable
fun BasicTooltip() {
    val tooltipPosition = TooltipDefaults.rememberPlainTooltipPositionProvider()
    val tooltipState = rememberBasicTooltipState(isPersistent = false)

    BasicTooltipBox(positionProvider = tooltipPosition,
        tooltip =  { Text("Hello World") } ,
        state = tooltipState) {
        IconButton(onClick = { }) {
            Icon(imageVector = Icons.Filled.Favorite, 
                 contentDescription = "Your icon's description")
        }
    }
}

Jetpack Compose has a built in class called TooltipDefaults. You can use this class to help you instantiate arguments that make up a TooltipBox. For instance, you could use TooltipDefaults.rememberPlainTooltipPositionProvider to correctly position the tooltip in relation to the anchor element.

Rich Tooltip

A rich media tooltip takes more space than a plain tooltip and can be used to provide more context about the functionality of an icon button. When the tooltip is shown, you can add buttons and links to it to provide further explanation or definitions.

It is instantiated in a similar way as a plain tooltip, inside of a TooltipBox, but you use the RichTooltip composable.

TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {
                        Text("This is where a description would go.")
                  }
        },
        state = tooltipState) {
        IconButton(onClick = {
            /* Icon button's click event */
        }) {
            Icon(imageVector = tooltipIcon,
                contentDescription = "Your icon's description",
                tint = iconColor)
        }
    }

A few things to notice about a Rich tooltip:

1. A Rich tooltip has support for a caret.

2. You can add an action (that is, a button) to the tooltip to give users an option to find out more information.

3. You can add logic to dismiss the tooltip.

Edge Cases

When you choose to mark your tooltip state as persistent, it means that once the user interacts with the UI that shows your tooltip, it will stay visible until the user presses anywhere else on the screen.

If you looked at the example of a Rich tooltip from above, you might have noticed that we have added a button to dismiss the tooltip once it’s clicked.

There is a problem that happens once a user presses that button. Since the dismiss action is performed on the tooltip, if a user wants to perform another long press on the UI item that invokes this tooltip, the tooltip won’t be shown again. This means that the state of the tooltip is persistent on it being dismissed. So, how do we go about and resolve this?

In order to “reset” the state of the tooltip, we have to call the onDispose method that is exposed through the tooltip state. Once we do that, the tooltip state is reset and the tooltip will be shown again when the user performs a long press on the UI item.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun RichTooltip() {
    val tooltipPosition = TooltipDefaults.rememberRichTooltipPositionProvider()
    val tooltipState = rememberTooltipState(isPersistent = true)
    val scope = rememberCoroutineScope()

    TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = TooltipDefaults.caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()  /// <---- HERE
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {

                  }
        },
        state = tooltipState) {
        IconButton(onClick = {  }) {
            Icon(imageVector = Icons.Filled.Call, contentDescription = "Your icon's description")
        }
    }
}

Another scenario where the tooltip state does not reset is if instead of calling ourselves for the dismiss method per a user’s action, the user clicks outside of the tooltip, causing it to be dismissed. This calls the dismiss method behind the scenes and the tooltip state is set to dismissed. Long pressing on the UI element to see our tooltip again will result in nothing.

Our logic that calls the tooltip’s onDispose method does not get triggered, so how can we reset the tooltip’s state?

Currently, I haven’t been able to figure this out. It might be related to the tooltip’s MutatorMutex. Maybe with upcoming releases, there will be an API for this. I did notice that if other tooltips are present on the screen and they are pressed, this resets the previously clicked upon tooltip.

If you would like to see the code featured here, you can go to this GitHub repository

If you would like to see tooltips in an application, you can check it out here.

References

• Material3 Tooltip Overview

• Tooltip Defaults

• Tooltip Source Code

I found it hard to understand how I could achieve letting a completely unrelated widget know about something that happens in another widget inside my application.

Take, for example, a feature I wanted to implement that would allow the user to choose the theme of the application (light/dark). Since I had a settings screen with this feature, I wondered how I could let the rest of the application know that the theme has changed and react to it.

Searching online for guidance, I noticed there was no shortage of solutions being offered. Each with it’s own degree of complexity. Bloc was a popular choice plenty of people online suggested, but in the same breath, it was said that the learning curve is quite steep. Wanting to deliver features to the application quicker, I chose to use GetIt.

Why did I choose GetIt? I think the package’s creator(s) pretty much sum it up best in their own words:

GetIt is:
- Extremely fast (O(1))
- Easy to learn/use
- Doesn’t clutter your UI tree with special Widgets to access your data like Provider or Redux does.

It is mentioned that GetIt is not a state management solution, but rather a tool to help you access objects inside your application.

So I headed off in the direction of using GetIt with a combination of Provider and ChangeNotifier in my application. While it wasn’t pretty, it got the job done.

During the development of features for my application and making it more robust, I knew in the back of my head that I wasn’t using the correct tools to manage state properly in my application.

Recently, I decided that it was time to learn Bloc properly and to convert the code inside my application to use it. I knew that it wasn’t going to be an easy task, but after going through it, I can admit that after a few trail and error attempts, it got easier to handle. With each use case I encountered, my understanding grew.

In this article, I’ll present some actual use cases where I used GetIt in combination with Provider and ChangeNotifier and replaced them with Bloc. Hopefully you can use these examples to better understand how to use Bloc in your applications.

Managing the Dark/Light Theme

I wanted my application to support different themes. To do that, I created a Settings screen where the user could control the theme color.

Settings Screen

Developing this was the first time I had to deal with changes in the application’s state that would be reflected in widgets that weren't directly related. So, besides creating a widget for the Settings screen,

class SettingsScreen extends StatelessWidget {

  @override
  Widget build(BuildContext context) {
    return Scaffold(
              appBar: AppBar(
                title: new Text("Settings"),
              ),
              body:
                  Column(
                      mainAxisAlignment: MainAxisAlignment.start,
                      children: [
                        Consumer<SettingsScreenManager>(
                            builder: (context, notifier, child) {
                              return  SwitchListTile(
                                  title: const Text('Dark Mode'),
                                  value: notifier.themeMode == ThemeMode.light ? false : true,
                                  secondary:
                                  new Icon(
                                      Icons.dark_mode,
                                      color: notifier.themeMode == ThemeMode.light ? Color(0xFF642ef3) : Color.fromARGB(200, 243, 231, 106)
                                  ),
                                  onChanged:notifier.handleThemeModeSettingChange
                              );
                            }
                        ),
                        //.....
                      ],
                    ),
                  )
      );
  }

I also created a manager class for it called SettingsScreenManager, where I had this method:

 void handleThemeModeSettingChange(bool isDarkModeEnabled) {
    _themeMode = _themeMode == ThemeMode.dark ? ThemeMode.light : ThemeMode.dark;
    _storageService.saveThemeModeSetting(isDarkModeEnabled);
    notifyListeners();
  }

The connection between the screen and its manager happens when the widget is created, as that is where I create the manager class. Then, throughout the widget itself, I call methods on the manager class. To make the widget redraw itself, I used the Consumer widget.

This is not the best approach, and to rectify the situation I created a Bloc to handle the theme mode:

import 'package:birthday_calendar/service/storage_service/storage_service.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

enum ThemeEvent { toggleDark, toggleLight }

class ThemeBloc extends Bloc<ThemeEvent, ThemeMode> {
  ThemeBloc(StorageService storageService, bool isDarkMode) : super(isDarkMode ? ThemeMode.dark : ThemeMode.light) {
    on<ThemeEvent>((event, emit) {
      ThemeMode themeMode = event == ThemeEvent.toggleDark ? ThemeMode.dark : ThemeMode.light;
      emit(themeMode);
      storageService.saveThemeModeSetting(themeMode == ThemeMode.dark ? true : false);
    });
  }
}

Let’s break down the components of this Bloc:

1. I have declared an enum called ThemeEvent to signify the user’s choice of light/dark theme
2. Since the state of the Bloc is directly the ThemeMode object, there was no need to create a specific State object
3. Whenever the theme changes, I emit the chosen theme mode

And I initialized this bloc inside my main.dart file in order for it to be accessible to any widget in the widget hierarchy. Also, I wanted any change that occurred due to this Bloc to be enacted on the entire application.

 @override
  Widget build(BuildContext context) {
    return MultiBlocProvider(
      providers: [
        BlocProvider(create: (context) => ThemeBloc(storageService, isDarkMode)),
        //...
      ],
      child: BlocBuilder<ThemeBloc, ThemeMode>(
        builder: (context, state) {
          return MaterialApp(
              title: applicationName,
              theme: ThemeData.light(),
              themeMode: state,
              darkTheme: ThemeData.dark(),
              home: MainPage(
                  key: Key("BirthdayCalendar"),
                  notificationService: notificationService,
                  contactsService: contactsService,
                  storageService: storageService,
                  title: applicationName,
                  currentMonth: BirthdayCalendarDateUtils.getCurrentMonthNumber()));
        },
      ),
    );
  }

Requesting Permission

There is a feature in my application that allows users to import their contacts. In order to do so, there is a requirement to first ask a runtime permission.

Initially, I handled this using the same approach as in the previous section, utilizing the SettingsScreenManager class, a Consumer, and a Provider.

Consumer<SettingsScreenManager>(
   builder: (context, notifier, child) {
    return ListTile(
      title: const Text("Import Contacts"),
      leading: Icon(Icons.contacts,
          color: !notifier.isContactsPermissionPermanentlyDenied ? Colors.blue : Colors.grey
      ),
      onTap: () {
        Provider.of<SettingsScreenManager>(context, listen: false).handleImportingContacts(context);
      },
      enabled: !notifier.isContactsPermissionPermanentlyDenied
  );
}),

Replacing this was a step up from creating the ThemeBloc since I needed to handle the different permission statuses and also to remember if the permission was permanently denied.

enum ContactsPermissionStatusEvent {
  PermissionUnknown,
  PermissionDenied,
  PermissionGranted,
  PermissionPermanentlyDenied
}

class ContactsPermissionStatusBloc
    extends Bloc<ContactsPermissionStatusEvent, PermissionStatus> {
  ContactsPermissionStatusBloc(ContactsService contactsService)
      : super(PermissionStatus.denied) {
    on<ContactsPermissionStatusEvent>((event, emit) async {
      if (event == ContactsPermissionStatusEvent.PermissionUnknown) {
        bool permissionStatus =
            await contactsService.isContactsPermissionsPermanentlyDenied();
        if (permissionStatus) {
          emit(PermissionStatus.permanentlyDenied);
          return;
        }
      }
      emit(_convertEventNameToPermissionStatus(event));
    });
  }

  PermissionStatus _convertEventNameToPermissionStatus(
      ContactsPermissionStatusEvent event) {
    switch (event) {
      case ContactsPermissionStatusEvent.PermissionDenied:
        return PermissionStatus.denied;
      case ContactsPermissionStatusEvent.PermissionGranted:
        return PermissionStatus.granted;
      case ContactsPermissionStatusEvent.PermissionPermanentlyDenied:
        return PermissionStatus.permanentlyDenied;
      default:
        return PermissionStatus.denied;
    }
  }
}

This Bloc has the following:

• A ContactsPermissionStatusEvent enum that correlates with the different permissions status the OS has
• The state for this Bloc can be easily represented with the PermissionStatus class
• I have a private helper method called _convertEventNameToPermissionStatus to help in converting the event name to it’s corresponding permission status

You might be asking yourself why I added an event called PermissionUnknown. I did this so I could get the permission status in advance of the user navigating to the SettingsScreen. In the case where the user previously chose to permanently deny the permission, I wanted to gray out the option to import contacts for them.

To achieve this, I created the Bloc in the main.dart file:

@override
  Widget build(BuildContext context) {
    return MultiBlocProvider(
      providers: [
        BlocProvider(create: (context) => ThemeBloc(storageService, isDarkMode)),
        BlocProvider(
            create: (context) => ContactsPermissionStatusBloc(contactsService)),
        BlocProvider(create: (context) => VersionBloc())
      ],
      child: BlocBuilder<ThemeBloc, ThemeMode>(
        builder: (context, state) {
          return MaterialApp(

and I sent the event inside the initState method of the widget that is the parent of the SettingsScreen.

 @override
  void initState() {
    //....
    BlocProvider.of<ContactsPermissionStatusBloc>(context)
        .add(ContactsPermissionStatusEvent.PermissionUnknown);
    super.initState();
  }

And instead of the huge chunk of code I had earlier, I now have this:

BlocBuilder<ContactsPermissionStatusBloc, PermissionStatus>(
              builder: (context, state) {
            return ListTile(
                title: const Text("Import Contacts"),
                leading: Icon(Icons.contacts, color: Colors.blue),
                onTap: () {
                  _handleImportingContacts(context);
                },
                enabled: state.isPermanentlyDenied ? false : true);
          }),

Interacting with a List

Part of my application allows users to add/remove birthdays on specific calendar dates. As with previous features, here too I created a manager class to handle the state for if a user added/removed a birthday.

Part of the logic involved the presentation of an alert dialog with fields to add a birthday. This logic proved to be the most robust when trying to migrate to Bloc, as I had to think about all of the user flows.

This is what that widget looked like:

@override
  Widget build(BuildContext context) {
    return ChangeNotifierProvider(
      create: (context) => BirthdaysForCalendarDayManager(this.birthdays, this.dateOfDay),
          builder: (context, provider) {
              return Scaffold(
              appBar: AppBar(
              title: FittedBox(
                  fit: BoxFit.fitWidth,
                  child: Text(
                      "Birthdays for ${_dateService.convertMonthToWord(this.dateOfDay.month)} ${this.dateOfDay.day}")
              )
          ),
            body: Center(
                child: Column(
                  children: [
                      Consumer<BirthdaysForCalendarDayManager>(
                          builder: (context, data, child) =>
                          Expanded(child:
                            ListView.builder(
                                  itemCount: data.birthdays.length,
                                  itemBuilder: (BuildContext context, int index) {
                                  return BirthdayWidget(
                                    key: Key(data.birthdays[index].name),
                                      birthdayOfPerson: data.birthdays[index],
                                      onDeletePressedCallback: () {
                                        Provider.of<BirthdaysForCalendarDayManager>(context, listen: false).removeBirthdayFromList(data.birthdays[index]);
                                    },
                                    indexOfBirthday: index);
                                  },
                                 ),
                           ),
                          )
                      ],
                   )
                ),
                floatingActionButton: FloatingActionButton(
                onPressed: () {
                  Provider.of<BirthdaysForCalendarDayManager>(context, listen: false).handleAddBirthdayBtnPressed(context, dateOfDay);
                  },
                child: Icon(Icons.add)),
              );
          },
    );
  }

And the manager class:

class BirthdaysForCalendarDayManager extends ChangeNotifier {

  NotificationService _notificationService = getIt<NotificationService>();
  StorageService _storageService = getIt<StorageService>();
  final List<UserBirthday> _currentBirthdays = [];
  DateTime date = DateTime.now();

  UnmodifiableListView<UserBirthday> get birthdays => UnmodifiableListView(_currentBirthdays);

  BirthdaysForCalendarDayManager(List<UserBirthday> birthdays, DateTime dateTime) {
    //....
  }

  void _handleUserInput(UserBirthday userBirthday) {
    //....
  }

  void _addBirthdayToList(UserBirthday userBirthday) {
    //....
    notifyListeners();
  }

  void removeBirthdayFromList(UserBirthday birthdayToRemove) async {
    //....
    notifyListeners();
  }

  void handleAddBirthdayBtnPressed(BuildContext context, DateTime dateOfDay) async {
    //....
  }

So how can we go about migrating all this logic to Bloc? Well, first let’s think of the different events we will need:

1. Adding an item to the list
2. Removing an item to the list
3. Presenting the dialog that allows users to add an item to the list (this is used to be able to show the dialog)

So our inner enum for events can look like:

enum BirthdayEvent { AddBirthday, RemoveBirthday, ShowAddBirthdayDialog }

But what will our BirthdaysEvent include?

class BirthdaysEvent {
  final BirthdayEvent eventName;  // 1
  final UserBirthday? birthday;   // 2
  final bool? shouldShowAddBirthdayDialog; // 3
  final List<UserBirthday> birthdays; // 4
  final DateTime? date;  //5

  BirthdaysEvent(
      {required this.eventName,
      this.birthday,
      this.shouldShowAddBirthdayDialog,
      required this.birthdays,
      this.date});
}

1. The event name
2. The birthday we will either add or remove
3. A flag to indicate if we should present the dialog
4. The whole list of birthdays for the specific date
5. The date the user wants to add/remove birthdays to/from

You may have noticed that not all fields are required to create a BirthdaysEvent. This is because not all of these fields are necessary for the different types of events. For example, when the user wants to add another birthday, the second argument (titled birthday) is irrelevant since we want to create a birthday.

Next, we need to think about what should be included in our state. Looking at the code above, it is clear that we need:

• To keep the list of birthdays, as we are either removing from or adding to it
• A flag to indicate if we should show the add birthday dialog
• The current date to add/remove birthdays to

class BirthdaysState {
  final DateTime? date;
  final List<UserBirthday>? birthdays;
  final bool showAddBirthdayDialog;

  BirthdaysState(
      {this.date, this.birthdays, required this.showAddBirthdayDialog});
}

So we got our events in place and our state as well. Now it's time to implement the logic in our bloc that handles each of these events and create a new state:

class BirthdaysBloc extends Bloc<BirthdaysEvent, BirthdaysState> {
  BirthdaysBloc(NotificationService notificationService,
      StorageService storageService, List<UserBirthday> birthdaysForDate)
      : super(BirthdaysState(
            date: DateTime.now(),
            birthdays: birthdaysForDate,
            showAddBirthdayDialog: false)) {
    on<BirthdaysEvent>((event, emit) {
      switch (event.eventName) {
        case BirthdayEvent.AddBirthday:
          _handleAddEvent(event, emit, storageService, notificationService);
          break;
        case BirthdayEvent.RemoveBirthday:
          _handleRemoveEvent(event, emit, storageService, notificationService);
          break;
        case BirthdayEvent.ShowAddBirthdayDialog:
          emit(new BirthdaysState(showAddBirthdayDialog: true));
          break;
      }
    });
  }

If we look at one event, ShowAddBirthdayDialog, you can see that we are just emitting a new BirthdayState where the showAddBirthdayDialog is set to true. But where is this handled? I had to heavily refactor the widget from above in order for it to respond for changes in the state.

  @override
  Widget build(BuildContext context) {
   return BlocProvider(                            // 1
        create: (context) =>
            BirthdaysBloc(notificationService, storageService, birthdays),
        child: BlocBuilder<BirthdaysBloc, BirthdaysState>(   // 2
            builder: (context, state) {
          return Scaffold(
            appBar: AppBar(
                title: FittedBox(
                    fit: BoxFit.fitWidth,
                    child: Text(
                        "Birthdays for ${BirthdayCalendarDateUtils.convertMonthToWord(this.dateOfDay.month)} ${this.dateOfDay.day}"))),
            body: Center(
                child: Column(
              children: [
                (state.birthdays == null || state.birthdays!.length == 0)
                    ? Spacer()
                    : Expanded(
                        child: ListView.builder(
                          itemCount: state.birthdays != null
                              ? state.birthdays!.length
                              : 0,
                          itemBuilder: (BuildContext context, int index) {
                            return BirthdayWidget(
                                key: Key(state.birthdays![index].name),
                                birthdayOfPerson: state.birthdays![index],
                                onDeletePressedCallback: () {  // 3
                                  BlocProvider.of<BirthdaysBloc>(context).add(
                                      new BirthdaysEvent(
                                          eventName:
                                              BirthdayEvent.RemoveBirthday,
                                          birthday: state.birthdays![index],
                                          birthdays: birthdays));
                                },
                                indexOfBirthday: index,
                                storageService: storageService,
                                notificationService: notificationService);
                          },
                        ),
                      ),
                BlocListener<BirthdaysBloc, BirthdaysState>(  // 4
                  listener: (context, state) {
                    if (state.showAddBirthdayDialog) {
                      showDialog(
                          context: context,
                          builder: (_) => BlocProvider.value(  // 5
                              value: BlocProvider.of<BirthdaysBloc>(context),
                              child: AddBirthdayForm(
                                  dateOfDay: dateOfDay,
                                  storageService: storageService)));
                    }
                  },
                  child: Spacer(),
                )
              ],
            )),
            floatingActionButton: FloatingActionButton(
                onPressed: () { // 6
                  BlocProvider.of<BirthdaysBloc>(context).add(BirthdaysEvent(
                      eventName: BirthdayEvent.ShowAddBirthdayDialog,
                      shouldShowAddBirthdayDialog: true,
                      birthdays: birthdays));
                },
                child: Icon(Icons.add)),
          );
        }));
  }

There is a lot to unpack here, so let’s take it one step at a time.

1. The BirthdaysBloc is created inside this widget since it is not needed anywhere else up the widget tree
2. We are using a BlocBuilder so the widget will re-draw itself when the state changes
3. When a birthday is chosen to be deleted, we create a RemoveBirthday event and pass along all the necessary information
4. We are using a BlocListener to handle the changes in the state in order to show the AlertDialog for adding a new birthday
5. Since our BirthdaysBloc is not found on the global level, it is necessary to pass it in to the AddBirthdayForm widget using BlocProvider
6. When the user presses the floating action button to signify an intent to add a birthday, we create a ShowAddBirthdayDialog event

Notice that, after all these changes, the manager class was no longer needed and therefore, the code itself is more straightforward and easier to maintain.

You are more than welcome to check out the entirety of the code shown above in the GitHub repository here:

And if you like, you can check out the application itself, here.

Update your Play Core Maven dependency to an Android 14 compatible version! Your current Play Core library is incompatible with targetSdkVersion 34 (Android 14), which introduces a backwards-incompatible change to broadcast receivers to improve user security. As a reminder, from August 31, Google Play requires all new app releases to target Android 14. Update to the latest Play Core library version dependency to avoid app crashes: https://developer.android.com/guide/playcore#playcore-migration

You may not be able to release future versions of your app with this SDK version to production or open testing.

Looks frightening, doesn’t it?

Don’t be so worried. It is actually easier than it looks.

What the Change is Actually About

Basically, Google stopped releasing new versions of the play core library back in early 2022.

The last version of play core library released

And from April 2022, they have broken down the original play core library into four separate libraries:

• Play Assets Delivery Library
• Play Feature Delivery Library
• Play In-App Reviews Library
• Play In-App Updates Library

Each library has its own functionality and responsibility.

Since the older core play library only supports up to a certain API level, you need to migrate your application to use the newer libraries that have support for the most recent API levels.

In essence, you need to figure out which functionality of the original core play library you are using and then download the correct part. For example, if you had logic to notify users when a newer version of your application was available, you need to take the Play In-App-Updates library.

We will be presenting two uses cases here:

• Native Android application
• Flutter application

Use Case – Native Android App

If you have a native Android application, whether it is written in Kotlin or Java, you need to do the following:

1. Open your application level build.gradle file
2. Most probably you will see under the dependencies block, this line:

implementation 'com.google.android.play:core-ktx:1.8.1'

3. You will need to remove it and replace it according to what you used in the previous core library

4. If you need to take the Play In-App-Updates library, then you need to add these to the dependencies block:

implementation 'com.google.android.play:app-update:2.1.0'
//Add the dependency below if you are using Kotlin in your application
implementation 'com.google.android.play:app-update-ktx:2.1.0'

5. Rebuild your application and see that everything works as it should.

✋ You might also need to change import statements from import com.google.android.play.core.tasks.*; to import com.google.android.gms.tasks.*;.

Use Case – Flutter Application

Since Flutter is a framework that caters to both Android and iOS, this scenario is a bit different from the one above. If you receive the warning to upgrade the core play library in your Flutter application, you need to have a look at the libraries you are using in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  ...
  in_app_update: ^3.0.0

As you can see above, the application depends on the in_app_update library, which has to do with notifying users when a newer version of the application is available. When we head over to in_app_update’s pub.dev changelog page, we can see that:

version 4.1.0 added the required support

So we need to update our pubspec.yaml file to use that version (at the very least).

dependencies:
  flutter:
    sdk: flutter
  ...
  in_app_update: ^4.1.0

Run Pub get and you should be good to go.

If you are unfamiliar with what a Privacy Manifest is, I suggest reading my other article.

There has been a lot of confusion regarding what developers need to do if they are using Flutter.

This is because Flutter has been marked by Apple as a “commonly used SDK” (including several other Flutter packages). This has been somewhat addressed by the Flutter community. If you are interested, you can read the following GitHub issues:

• Support Privacy Manifest and Required APIs in iOS and macOS
• Determine how to handle privacy manifests in packages

As of May 2024, things are still a bit vague. It would be preferable to have a solution that reassures us of being able to update our package and not cause applications that use it to be rejected.

We want to continue being good citizens in the Mobile ecosystem.

How to Upgrade Dependencies

Regardless of what logic you have inside your package, in order to support Apple’s changes, you have to enforce your package to use Flutter version 3.19 at the very least.

You can do this by going to your pubspec.yaml file and changing the version there:

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: "^2.0.0"   /// <--- Change this to 3.19

Then, you need to go over any dependencies you may have in your pubspec.yaml file and find out if you have packages that are listed under the “commonly used sdks”.

If so, you will need to find out if that package has released a new version with a privacy manifest file. For example, if our package’s pubspec.yaml looks like this:

dependencies:
  flutter:
    sdk: flutter
  intl: ^0.17.0
  shared_preferences: ^2.0.5
  url_launcher: ^6.0.17
  package_info_plus: ^3.1.2

our package depends on url_launcher, which as it happens, is also listed under the “commonly used sdks”.

When we go over to url_launcher’s page on pub.dev, we will be able to see that they released a new version, 6.2.6, that includes a privacy manifest.

_Screenshot of urllauncher package and its version that supports privacy manifest

So we will upgrade to that version.

Once we have gone over all our our dependencies, we can go ahead and deal with the code in our own package.

How to Add the Privacy Manifest File

The privacy manifest file needs to reside inside of the Resources folder in your project structure (under darwin).

Directory structure of iOS folder inside a Flutter package

Make sure to follow Apple’s guidelines on what data to include there. This will depend on your package’s use case. If you are unsure, you can either refer to Apple’s documentation, or check out my article that I linked to at the beginning.

Then, inside of your package’s podspec file, you need to add the privacy manifest as a resource there:

 s.resource_bundles = {'package_name_privacy' => ['Resources/PrivacyInfo.xcprivacy']}

Almost Done

As stated, things are not yet clear on whether the solutions proposed will stand the test of time.

One issue that is currently being investigated is the fact that Flutter packages are under the hood, static frameworks. This can cause issues for application developers.

When using your package, the privacy manifest file can be obscured by top level resources of the application itself. Meaning, the application’s own privacy manifest file might overshadow your package’s privacy manifest file. This in turn, will cause the application to get rejected from the Apple store since it will not perceive that your package does indeed have a privacy manifest file.

According to this GitHub issue comment, this is a known issue to Apple and they are working on fixing this.

In Apple’s April 26th announcement, they state that:

Apps won’t be accepted if they fail to meet the manifest and signature requirements.

Apps also won’t be accepted if all of the following apply:

• They’re missing a reason for a listed API.
• The code is part of a dynamic framework embedded via the Embed Frameworks build phase.
• The framework is a newly added third-party SDK that’s on the list of commonly used third-party SDKs.

It seems that things have been limited to dynamic frameworks for the time being, as Apple adds:

_I_n the future, these required reason requirements will expand to include the entire app binary.__

Conclusion

Hopefully by now you have the knowledge and the tools to make sure your Flutter package is compatible with Apple's Privacy Manifest changes.

But be sure to keep your eyes and ears peeled for any announcement Apple makes because more changes to your Flutter package could be needed.

You may have come across multi-library projects in your line of work, or you may be looking into converting your library into sub-modules for better structure and organization. No matter the case, you should be well aware of what lies in front of you before diving in.

Writing your own library in Android is neat. You get a chance to write some code that can help other developers (or even yourself).

Since libraries can’t be a standalone project by themselves, they are usually always paired in a project with an application. This allows developing the library to be a simple process where you add a feature/fix a bug and then you can test it directly with the application you have in the project. Thus, simulating (in a local way) how a developer will integrate your library.

But, what if your library relies on another library you are developing?

If you are not aware of it, you should know that a library (read aar) cannot contain another local library within it. It can rely on libraries remotely (via dependencies), but not on something local.

This is not supported in Android, and while some solutions popped up during the years (FatAar), these didn’t always solve the problem and are not up to date. There is even a Google Issue Tracker requesting this feature that has been open for quite some time and is receiving plenty of attention from the community. But let’s identify which walls we can break and which we cannot.

Imagine your project hierarchy looks like this:

-- App
|
 -- OuterLib
   |
    --- InnerLib

So, since InnerLib can’t be part of your original project, where can it reside? And also how would you be able to work locally while developing features inside InnerLib?

We are going to answer these questions in this article.

Git Submodule

For most technical problems, there isn’t always just one solution. Usually, there are more, but each solution has its drawbacks. It's all a question of which drawbacks you are more comfortable living with at the end of the day.

To answer our first question, where can InnerLib reside, we have several options:

1. Make InnerLib a submodule of our original project
2. Make InnerLib a remote dependency of its own

If you are not aware of submodules in Git, Git’s documentation is a good place to familiarize yourself with them. Quoting from it (the first paragraph):

It often happens that while working on one project, you need to use another project from within it. 👉 Perhaps it’s a library that a third party developed or that you’re developing separately and using in multiple parent projects. 👈 A common issue arises in these scenarios: you want to be able to treat the two projects as separate yet still be able to use one from within the other.

This paragraph shows us that this is exactly our use case. Using a submodule has its benefits. All your code is in one place, is easy to manage, and is easy to develop locally.

But submodules have some weaknesses. One is the fact that you must always be aware of which branch your submodule is pointing to. Imagine a scenario where you are on a release branch in your main repository and your sub-module is on a feature branch. If you don’t notice, you release a version of your code with something that is not ready for production. Whoops.

Now think about this within a team of developers. One careless mistake can be costly.

If the first option sounds problematic for you, then hosting your library in another repository is your second choice. Setting up the repository is pretty simple, but how do you work locally now?

Working Locally

Now that we've gotten our project set up properly, we will probably have a line similar to this in our OuterLib build.gradle file:

dependencies {
  implementation 'url_to_remote_inner_lib_repository'
}

How can we make the development cycle efficient and easy to work with? If we develop some feature in InnerLib, how do we test things out in OuterLib? Or in our application?

One solution that might come up is to import our InnerLib locally to our OuterLib project, while having InnerLib .gitignored in our OuterLib project. You can do so easily by right clicking on the name of the project in the left hand side menu in Android Studio and going to New → Module.

How to import a module (Step 1)

Then in the window that opens up, you can choose the Import option at the bottom left:

How to import a module (Step 2)

That sounds easy and simple so far, but what’s the catch?

Each time you modify a file that belongs to InnerLib, the changes won’t be reflected inside InnerLib since it is ignored. So, each change you want to make has to happen inside of InnerLib and then you have to import it again inside OuterLib to see the changes.

This doesn’t seem right. There must be a better way of doing this.

With just a few lines in our settings.gradle file, we can make sure our files stay in sync when we make changes in InnerLib.

When we imported InnerLib into our project, Android Studio made a copy of InnerLib and cached it. That is why we needed to re-import the library for every change we made inside of it. We can tell Android Studio where to reference the files from using the projectDir attribute.

Our settings.gradle might look something like this:

include ':outerLib', ':innerLib', ':app'

To reference our InnerLib locally, we would have to change settings.gradle into this:

include ':outerLib', ':innerLib', ':app'
project('innerLib').projectDir = new File('PATH_TO_INNER_LIB')

Using this approach, our InnerLib files will be linked to our working directory, so every change we make will be reflected immediately.

But, we would like flexibility when working locally on OuterLib with a remote version of InnerLib. What we wrote above inside the settings.gradle file will only allow us to work locally and surely we don’t want to commit that as it is.

Maven Local

If the approach above doesn’t sit quite right with you, there is a different one you can take. Just like you would publish your library publicly with maven, you can do the same thing locally with maven local. Maven local is a set of repositories that sit locally on your machine.

Below are the paths for mavenLocal depending on the operating system of your machine:

• Mac → /Users/YOUR_USERNAME/.m2
• Linux → /home/YOUR_USERNAME/.m2
• Windows → C:\Users\YOUR_USERNAME.m2

In essence you can publish your library locally and then link to it in your project. Doing it this way, we can link our project to InnerLib.

In order to allow this configuration in our project, we need to do the following things:

1. Add mavenLocal() as a repository inside our repositories clause. This is to allow our project the ability to search for repositories locally

buildscript {
    repositories {
        mavenLocal()
    }
}

...

allprojects { 
    repositories { 
        mavenLocal() 
    }
}

2. Change our implementation line inside our dependencies clause to reference our InnerLib as if it we are referencing it remotely

3. To publish InnerLib locally, we will create a file called publishingLocally.gradle that will contain the following:

apply plugin: 'maven-publish' 

project.afterEvaluate {
    publishing { 
      publications {
            library(MavenPublication) { 
                    setGroupId groupId          //your library package
                    setArtifactId artifactId              
                    version versionName         //I.E. 1.0

                    artifact bundleDebugAar

                    pom.withXml { 
                        def dependenciesNode = asNode().appendNode('dependencies')
                        def dependencyNode = dependenciesNode.appendNode('dependency')
                        dependencyNode.appendNode('groupId', 'your_group_id')
                        dependencyNode.appendNode('artifactId', 'your_artificat_id')
                        dependencyNode.appendNode('version', 'your_version')
                    } 
                }
            }
        }
}

4. Inside your application level build.gradle file, add the line:

apply from: '/.publishingLocally.gradle

If this option seems a bit too good to be true, it is. While on one hand, we can develop things locally seamlessly just as if we were working with a remote library. On the other, if we make any change inside InnerLib while working locally, it is required to publish it locally again. While this isn’t a costly task, it does create a need to perform tedious tasks over and over.

A Solution for Working Locally and Remotely

We want to avoid the constant need to re-publish our InnerLib package whenever we make a change locally. We need to figure out a way to make our project be aware of those changes.

In the Working Locally section, we found out how to do that, but we had an issue with committing the settings.gradle file. To solve this problem so we can work both locally and remotely with our InnerLib, we will use a parameter we will define in our gradle.properties file.

The gradle.properties file is a place where you can store project level settings that configure your development environment. This helps make sure that all the developers on a team have a consistent development environment.

Some settings you might be familiar with that are found inside this file are AndroidX support (android.useAndroidX=true) or the JVM arguments (org.gradle.jvmargs=-Xmx1536m).

To help us solve our situation, we can add a parameter here to indicate whether we want to work locally or not. Something along the lines of:

workingLocally = false

This parameter will grant us the ability to distinguish between which settings we are working with, either locally or with production code. First, let’s alter what we have in our settings.gradle file by wrapping it in a condition that checks if our parameter is true:

include ':outerLib', ':innerLib', ':app'
if (workingLocally.booleanValue()) {
  project('innerLib').projectDir = new File('PATH_TO_INNER_LIB')
}

This way, we indicate to the project to get the files for our InnerLib locally from our machine.

Another place where we need to change our logic is in our build.gradle file. Here, instead of getting the code to our library remotely in our dependencies block, we can indicate whether we are depending on it locally or not.

dependencies {
   if (workingLocally.booleanValue()) {
      implementation 'innerLib'
   } else {
     implementation 'url_to_remote_repository'
  }
}

⚠️ Word of warning: You should never commit the gradle.properties file when working locally.

The journey was long and may have seemed quite exhausting. But now we have a full-proof setup for working locally and remotely on a multiple library project.

If you encounter any issues or would like to give your take on this, feel free to leave a comment.

Following that, I wanted to see what it would be like to write tests for the Proto DataStore in that application using the knowledge I gained.

Searching online for guidance didn’t provide much relief, so I figured I would share my knowledge for those that might be looking for it. In the worst case, it would be for my progeny.

In my search, I did find this article, but that focuses mostly on testing the Preferences DataStore and not the Proto DataStore. It does state that:

“However, keep in mind you can use this material for setting up Proto DataStore testing, as it would be very similar to Preferences.”

But having followed it, I found out that besides the dependencies, there aren’t many similarities here and you need to introduce separate logic to test your own Proto DataStore.

Setting Things Up

In your application’s build.gradle file, add the following dependencies:

dependencies {
  ///.....
  androidTestImplementation "androidx.compose.ui:ui-test-junit4:$compose_version"
  debugImplementation "androidx.compose.ui:ui-test-manifest:$compose_version"
}

$compose_version is the variable you defined in your project level build.gradle file.

Then, go to your androidTest directory and create a new file. Usually, you would have a repository class that interacts with your Proto DataStore, so you can name this file as YourRepositoryClassNameTest. We will use the name MyRepositoryTest.

Before we delve into testing the Proto DataStore itself, we need to instantiate it. If you go online to find any documentation on this, it is kind of sparse.

Instantiating a Proto DataStore is used with the global Context like so (when not used in a testing scenario):

private val Context.myDataStore: DataStore<MyItem> by dataStore(
                 fileName = DATA_STORE_FILE_NAME,
                 serializer = MyItemSerializer
 )

Well, you can't do this inside of a test class, because, while you can copy-paste the above code, you won’t be able to access the DataStore object. You can get the application context like this:

ApplicationProvider.getApplicationContext()

but our myDataStore object won’t be available through it.

So, what can we do?

In the article linked above, there is an example of how we can create a Preference DataStore using the PreferenceDataStoreFactory.create method.

fun create(    
            corruptionHandler: ReplaceFileCorruptionHandler<Preferences>? = null,    
            migrations: List<DataMigration<Preferences>> = listOf(),
            scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()),    
            produceFile: () -> File): DataStore<Preferences>

But since we are not using a Preference DataStore, that won’t work for us. What will work is using the DataStoreFactory.create method like this:

fun <T : Any?> create(    
    serializer: Serializer<T>,   
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,    
    migrations: List<DataMigration<T>> = listOf(),    
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()),     produceFile: () -> File): DataStore<T>

There are several arguments for this method (and some have default values), but we don’t need to pass all of them in. We will be passing:

• Our serializer class
• A lambda method for creating the file for our Proto DataStore

dataStore = DataStoreFactory.create(   
        produceFile = {                    
            testContext.dataStoreFile(TEST_DATA_STORE_FILE_NAME)                    },            
        serializer = MyItemSerializer 
      )

We get the testContext by:

private val testContext: Context = ApplicationProvider.getApplicationContext()

How to Test the DataStore

Having created our Proto DataStore successfully, we can move on to writing some tests for it. Keep in mind that you have a repository class that receives the instance of the Proto DataStore as a dependency, so after creating the Proto DataStore, we need to create an instance of our repository class.

 private val repository = MyRepository(datastore)

First, let’s create a test to check our initial Proto DataStore state. The Proto DataStore itself exposes a flow which we can use.

@OptIn(ExperimentalCoroutinesApi::class)
    @Test
    fun repository_testFetchInitialState() {
        runTest {
            testScope.launch {
                val dataStoreObject = repository.myFlow.first()
                // Insert here whatever we want to assert from our
                // Proto DataStore. I.E. a flag whose initial value is false
                assert(dataStoreObject.myFlag == false)  
            }
        }
    }

☝️ You may have noticed this earlier, but we are using a OptIn annotation here. This is because (currently) the APIs which we are using are experimental and must be marked so when we use them.

Since we are accessing the flow of our DataStore, we need to wrap it in our testScope. TestScope is created by doing:

@OptIn(ExperimentalCoroutinesApi::class)
private val dispatcher = TestCoroutineDispatcher()
@OptIn(ExperimentalCoroutinesApi::class)
private val testScope = TestCoroutineScope(dispatcher)

Run it and enjoy your first Proto DataStore test.

That was fun for about two seconds.

Let’s do something more meaningful.

Imagine our Proto DataStore has a list of objects inside of it and we want to test the state of it when we add an item to it.

@OptIn(ExperimentalCoroutinesApi::class)
    @Test
    fun repository_testAdditionOfItem() {
        runTest {
            testScope.launch {
              //1
               val item: MyItem = MyItem.newBuilder().setItemId(UUID.randomUUID().toString())
                    .setItemDescription(TEST_ITEM_DESCRIPTION).build()
                //2
                repository.updateItem(item)

                //3
                val items = repository.myFlow.first().itemsList
                assert(items.size == 1)

                //4
                assert(items[0].itemDescription.equals(TEST_ITEM_DESCRIPTION))
            }
        }
    }

1. We create a test item using the exposed API from the protobuff
2. We add this item to the Proto DataStore using a method we exposed on the MyRepository class
3. We grab the list of items from the flow the Proto DataStore exposes
4. We make sure that the item found in the Proto DataStore matches the item we created earlier

Your DataStore Has a Leak in it

If you try to run the tests above in one go, you will soon receive an error during runtime:

There are multiple DataStores active for the same file: /data/user/0/com.example.app/files/datastore/dataStore_filename.pb. You should either maintain your DataStore as a singleton or confirm that there is no two DataStore’s active on the same file (by confirming that the scope is cancelled).

Well, that is problematic. We only created one DataStore instance in our test class.

What is going on here?

Because we are not using the property delegate to create our DataStore (meaning Context.datastore), it isn’t ensured that our DataStore object is a singleton whenever we access it.

To circumvent this scenario, I have found out that one approach is to delete and recreate the DataStore for each test case. To delete the DataStore, we can do this:

@After
fun cleanup() {
  File(testContext.filesDir, "datastore").deleteRecursively()
}

and before every test, we recreate it:

@Before
 fun setup() {
    dataStore = DataStoreFactory.create(
        produceFile = {
            testContext.dataStoreFile(TEST_DATA_STORE_FILE_NAME)
        },
        serializer = MyItemSerializer
    )
 }

To see a full example, you can go here.

In this article, I wanted to show the outline of a how a Proto DataStore can be tested.

While I went over two test cases, depending on your DataStore and the types you configured there, there could be more test cases and scenarios to write. The building blocks are there, you just have to adapt it to your needs.

When first announced, Apple stated that in the Spring of 2024 (read – spring is already here), having a privacy manifest is expected and will be part of the application review process. Apple also asks application developers, as well as SDK developers, to adopt the privacy manifest.

Fast forward to December 7th, 2023, Apple announced a list of “commonly used third-party SDKs” that, if included by your application, you have to have a privacy manifest for. No real explanation has been given as to why the third-party SDKs listed are the ones that have been selected, but there has been much speculation about it.

And here we stand after February 29th, 2024 (on a leap day!), when Apple announced a timeline for enforcing the required reason API section of the privacy manifest.

All of this has led to quite a bit of confusion from developers who are scrambling to understand if their application or SDK falls into a privacy manifest category.

Developers are unsure if they should add a privacy manifest to their SDK, even if it is not listed. The documentation itself, while being adept at giving an outline of everything, lacks the necessary distinctions and details developers are looking for.

Part of me wants to say that Apple is keeping things vague since the near future has coming changes that privacy manifests will bring. Another part of me says that Apple has always been this vague, and it is just their modus operandi.

In any case, you are reading this article because you want to understand how all of this affects you. So, let’s break things down.

⚠️ Disclaimer: This article won’t deal with explaining what the privacy manifest is or how to add it to your application/library, as that has been covered by Apple's documentation fairly well.

The Four Horsemen

Privacy manifest is divided into four subjects:

• NSPrivacyTracking.
• NSPrivacyTrackingDomains.
• NSPrivacyCollectedDataTypes (nutrition labels).
• NSPrivacyAccessedAPITypes (required reason APIs).

The first two are tied together and can pose the most substantial changes to your application/library, so we’ll ease into this list by starting with number three.

What are NSPrivacyCollectedDataTypes?

This section holds various categories of data collection that if your application or SDK does something with, you have to declare them.

Each type of data collected must be supplied with the reason for collecting it.

The categories range from contact information about the user (such as email/phone number), to Location and Purchases.

Inside your privacy manifest file, you will have an array of NSPrivacyCollectedDataTypes, where each item will hold:

• The type of data collected.
• Whether or not this data is linked to the user.
• Whether or not this data is used to track the user.
• The reason(s) for collecting this data.

Let’s do one as an example. Imagine your application collects the precise location of a user in order to track the user’s movement to see if the user is nearby any specific stores.

If the user is nearby such a store, you present a relevant ad to them. Factoring all that you will need to create an entry where:

• The data type will be NSPrivacyCollectedDataTypePreciseLocation.
• Mark true as we are linking the data to the user.
• Mark true as we are tracking the user with this data.
• Since we are going to display ads to the user, we will choose. NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising, NSPrivacyCollectedDataTypePurposeProductPersonalization, and NSPrivacyCollectedDataTypePurposeAppFunctionality since all of those fit for the data we collect.

What are NSPrivacyAccessedAPITypes?

As mentioned, this section gets a bit more obscure and a bit more demanding.

Here, Apple lists very specific APIs from different categories that if you happen to use, you need to declare them.

For every API listed, there are specific reasons you need to fall into in order to declare your use of it. Some reasons state clearly that even if you use the API, you cannot send the data received by this API to a server (off-device).

If you find that your application or SDK uses one of the listed APIs, then you need to list it with an appropriate reason(s). For example, if we use the example from the previous section, our application reads and writes data to user defaults that has to do with the user’s location. So, we will need to:

• List NSPrivacyAccessedAPICategoryUserDefaults as the NSPrivacyAccessedAPIType.
• Use CA92.1 inside the NSPrivacyAccessedAPITypeReasons.

If you think you don’t see the reason you are using an API for, you can let Apple know about it.

🎯 None of the APIs listed can be used for tracking the user.

At last, we come to the two most problematic categories.

What are the NSPrivacyTracking and NSPrivacyTrackingDomains?

What is tracking? Do you know? Does anyone know? It really doesn’t matter, because Apple has a definition for it:

“Tracking” refers to linking data collected from your app about a particular end-user or device, such as a user ID, device ID, or profile, with Third-Party Data for targeted advertising or advertising measurement purposes, or sharing data collected from your app about a particular end-user or device with a data broker.

So, if your application or SDK doesn’t fall into that definition, you need to mark false as the value for NSPrivacyTracking and you can exhale.

Because if you have to mark true as the NSPrivacyTracking, then you must supply all the domains your application or SDK uses for the purpose of tracking as part of NSPrivacyTrackingDomains.

By now, you must be asking yourself, why I am making a big fuss about this. Well, it has to do with the fact that Apple will block all requests to any domain listed under NSPrivacyTrackingDomains if the user doesn’t allow the application to track him/her.

Read the paragraph above again.

Get it? You will now need to re-route network requests differently based on whether the user has given consent to be tracked or not.

On the client side (application/library), this might be a small change to handle. But on the server/infrastructure side, this might require some heavy lifting as new domains (or sub domains), need to be created.

Data that has been aggregating a certain way, now needs to be aggregated from another source. You obviously also need to make sure that no tracking related data is sent to your newly created domains. You wouldn’t want to end up in a scenario where your application/library stops working entirely.

To assist you in understanding which domains fall into the tracking category, you can use Instruments. Be aware that if your domains do not fall into that category now, it doesn’t mean that they won’t fall into it later.

Conclusion

As with any new regulation or policy, many questions are still left unanswered:

• If my application has a webview, where some network requests are made, do I have to include those as domains for NSPrivacyTrackingDomains?
• Are sub domains good enough or do developers need to create completely different domains?
• If my library is not listed as part of the commonly used SDKs, is there a chance that it might be in the future? What is the criteria used for listing such SDKs?
• Do I have to include a signature to my SDK even if it is not listed under the commonly used SDKs?

Also, when looking at the current state of things in the developer community, the response is quite the same. At the time of writing this article, numerous SDKs that are listed in Apple’s list, still haven’t released a version with a privacy manifest.

As we will get closer to the date of when it will be mandatory to have a privacy manifest, hopefully more details will emerge and better clarity. Until then, brace yourselves.

This app is using a deprecated version of the Android embedding.
To avoid unexpected runtime failures, or future build failures, try to migrate this app to the V2 embedding.

Take a look at the docs for migrating an app: https://github.com/flutter/flutter/wiki/Upgrading-pre-1.12-Android-projects

Now, the document itself has the steps you need to follow to make this warning disappear, but it does not always clarify what to change and where.

This article will give you a step by step walkthrough on migrating your Flutter application to V2 Embedding so you can make that warning go away for good.

Automatic Migration – The Easy Way Out

It needs to be said that you can forego this process of migration if your application can be easily recreated. So what does that mean?

Well, if the code in your application is not complex, then you can just save the files in your lib folder and create a new project using flutter create. That way, you will have a project that is already migrated to V2 Embedding and will just need to copy paste the code you have in your lib folder.

But, if your project is more complex – let’s say it's a package that has platform specific code – you will probably be better off by migrating it manually.

Manual Migration – Follow These Steps

1. Open the MainActivity.kt (or .java) file in your application
2. You need to remove any content this file has and just leave it bare with a class declaration (unless you have specific logic there).
3. Remove all of the imports and make sure to have one import that is this:

import io.flutter.embedding.android.FlutterActivity;

The end result should be as follows:

import io.flutter.embedding.android.FlutterActivity;
public class MainActivity extends FlutterActivity {   
    // Nothing should be here
}

4. Open the AndroidManifest.xml file and change the name attribute under the application tag to ${applicationName} – so it looks like this:

<application      
    android:name="${applicationName}"> 
     .... 
</application>

5. You need to add the following meta data inside your application tags:

<meta-data           
     android:name="flutterEmbedding"       
     android:value="2" />

6. If you want a specific Splash screen behavior, you will need to remove the Splash screen meta tag:

<meta-data                     android:name="io.flutter.app.android.SplashScreenUntilFirstFrame"                android:value="true" />

7. Then head to your styles.xml file and configure the LaunchTheme there with the drawable of your liking:

<?xml version="1.0" encoding="utf-8"?>
<resources>    
     <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">        <item name="android:windowBackground">@drawable/launch_background
        </item>   
    </style>
</resources>

Your AndroidManifest.xml will look something like this after all the changes above:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"    package="PACKAGE_NAME">
<application        
    android:name="${applicationName}"    
    android:label="APPLICATION_LABEL"      
    android:icon="@mipmap/ic_launcher">     
        <activity           
            android:name=".MainActivity"
            android:exported="true"   
            android:launchMode="singleTop"     android:theme="@style/LaunchTheme"                android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"            android:hardwareAccelerated="true"            android:windowSoftInputMode="adjustResize">     
                <intent-filter>    
                    <action android:name="android.intent.action.MAIN"/>                                <category android:name="android.intent.category.LAUNCHER"/>  
                    </intent-filter>     
       </activity>     
       <meta-data       
               android:name="flutterEmbedding"         
            android:value="2" /> 
 </application>
</manifest>

AndroidX Support

Your project might also be needed to be migrated to use AndroidX libraries instead of the older support libraries. You will be alerted for this when you build and run your application:

Your app isn’t using AndroidX. To avoid potential build failures, you can quickly migrate your app by following the steps on https://goo.gl/CP92wY.

Fixing this is rather simple, as Android Studio has built in support for migrating to AndroidX.

Start by opening the Android folder of your Flutter application as a standalone project

Click on Refactor → Migrate to AndroidX:

Dropdown menu to Migrate to AndroidX

You will then be prompted to save a copy of your project and past that, the migration process will take place.

Errors You Might See

During this migration process, you might encounter several errors when building your application. The most prominent ones are:

• Unable to get mutable Windows environment variable map
• cvc-complex-type.2.4.a: Invalid content was found starting with element ‘base-extension’. One of ‘{layoutlib}’ is expected
• Warning: This version only understands SDK XML versions up to 2 but an SDK XML file of version 3 was encountered. This can happen if you use versions of Android Studio and the command-line tools that were released at different times

The first two errors are related to each other and both stem from the same root cause. It is because your project was set up with an old Gradle version and it is needed to upgrade it.

To do so, follow these steps:

1. Open the Android folder in your Flutter application as a standalone project
2. Click on File → Project Structure:

Dropdown menu to select Project Structure

3. Change the Gradle version to something more recent and that matches the current Android Studio version you are using

AGP and Gradle settings screen

You could also use the AGP Upgrade Assistant to do this as well by going to Tools →AGP Upgrade Assistant:

Dropdown menu to upgrade AGP using the AGP Upgrade Assistant

The third issue, which is a warning, might be caused by having an old version of the Android SDK Tools. To learn how to do that, you can go here.

Your project should be now fully migrated, compiling and running smoothly.

If you want to read other articles I have written, you can check them out here:

If you use or have used SharedPreferences in your applications, you might be thinking of making the switch. But as with everything, the main question here is: what is going to be the cost in development?

There are benefits for using DataStore, but only the Proto DataStore allows you to save objects while providing type safety.

If you look at the documentation for Proto DataStore, you will find that it is a bit outdated and missing some crucial steps when working with it. So that is why, in this article, we are going to go over how to integrate Proto DataStore into your application and show that it’s not that big of a hassle to use it.

What is DataStore?

Jetpack DataStore has two variants:

• Preferences DataStore
• Proto DataStore

We won’t be discussing the first, due to it’s similarity to SharedPreferences and also the fact that is has been covered widely. So now let’s understand what the Proto in Proto DataStore means.

Proto is the name Google chose to represent Protocol Buffers. These are (Google’s) mechanism that help you serialize structured data. They are not coding language-specific and in general, you define the type of data that you wish to work with and then code is generated that helps you read and write your data.

✋ We will be using the Proto 3 version in this article.

How does that definition look like?

message MyItem {
    string itemName = 1;
    int32 itemId = 2;
}

First, you define an object with the message keyword. Inside it, you list the fields associated with that object. The numbers at the end of each field are used to identify the field itself and cannot be changed once being set and the object is in use.

But what if we wanted to have multiple objects in our .proto file? Assuming the objects are related to one another, you can do this simply by adding more message objects:

message MyItem {
    string itemName = 1;
    int32 itemId = 2;
}

message MyListOfItems {
   repeated MyItem items = 1;
}

Notice that above we have added another message object that relies on the MyItem object defined above. If you want to define a list of objects, you need to use the repeated keyword.

How to Set Up Proto DataStore

To get started, you'll need to add the following dependencies to your application level build.gradle:

 implementation "androidx.datastore:datastore-preferences:1.0.0"
 implementation  "com.google.protobuf:protobuf-javalite:3.18.0"

Then, you will need to create a proto directory inside your project. This directory needs to be a sibling of the Java folder in your project structure.

Inside of the proto directory, you will be creating a .proto file. This file is responsible for generating the data types you wish to store in Proto DataStore.

Inside the proto directory, create a file with the .proto extension. Our .proto file will hold objects representing a Todo list (what else?). So we will call our file todo.proto and it will look like this:

syntax = "proto3";

option java_package = "com.yourPackageName.todo";
option java_multiple_files = true;

message TodoItem {
  string itemId = 1;
  string itemDescription = 2;
}

message TodoItems {
  repeated TodoItem items = 1;
}

Notice how we defined two message objects:

1. TodoItem – that defines a todo item
2. TodoItems – that defines a list of TodoItem objects

Next, build the project so that classes will be generated for TodoItem and TodoItems.

After our data objects have been defined, we need to create a class to serialize them. This class will tell the DataStore how to read/write our objects.

// 1
object TodoItemSerializer: Serializer<TodoItems> {
   // 2
    override val defaultValue: TodoItems = TodoItems.getDefaultInstance()
    // 3
    override suspend fun readFrom(input: InputStream): TodoItems {
        try {
            return TodoItems.parseFrom(input)
        } catch (exception: InvalidProtocolBufferException) {
            throw CorruptionException("Cannot read proto.", exception)
        }
    }
    // 3
    override suspend fun writeTo(
        t: TodoItems,
        output: OutputStream
    ) = t.writeTo(output)
}

Let’s review what we have in this class:

1. When we declare the class, we need to implement the Serializer interface with our object as the type (T)
2. We define a default value for the serializer in case the file is not created
3. We override the readFrom/writeTo methods and we make sure to have our object as the data type there

We have our .proto file with our data types and our serializer, so the next step is to instantiate the DataStore. We do this by using the property delegate created by dataStore, which requires giving a filename where our data will be saved and our serializer class (which we defined above).

private const val DATA_STORE_FILE_NAME = "todo.pb"

private val Context.todoItemDatastore: DataStore<TodoItems> by dataStore(
    fileName = DATA_STORE_FILE_NAME,
    serializer = TodoItemSerializer,
)

This piece of code needs to reside at the top of a class of your choosing above the definition of the class itself. That is:

private const val DATA_STORE_FILE_NAME = "todo.pb"

private val Context.todoItemDatastore: DataStore<TodoItems> by dataStore(
    fileName = DATA_STORE_FILE_NAME,
    serializer = TodoItemSerializer,
)

class YourClassName {

}

To access this object in the rest of our application, we will need to use a context. An example is to use the application context in your viewmodel class:

class MyViewModel(application: Application): AndroidViewModel(application) {

   val todoDataStore = application.todoItemDataStore
   //...
}

How to Use Kotlin Flow

Now that we have gone through setting up everything we need for our DataStore, we'll discuss how we are actually going to interact with it. We'll want to read and write data to/from it. But the way we can do so is different from what you may be familiar with from SharedPreferences.

The DataStore we defined above has a data field that exposes a Flow for the properties we defined in our DataStore.

🚰 If you are not familiar with flows, this is a good place to start.

val todoItemFlow: Flow<TodoItems> = todoItemDataStore.data
        .catch { exception ->
            if (exception is IOException) {
                emit(TodoItems.getDefaultInstance())
            } else {
                throw exception
            }
        }

The code above shows how you can define a Flow that collects data from the Proto DataStore. A catch block was added in case an exception occurs. You can place this logic in the class where you defined your DataStore and use it like so in your viewmodel:

val todoItemsFlow: LiveData<TodoItems> = todoItemsRepository.todoItemFlow.asLiveData()

Notice how we converted our Flow to LiveData. We did this for two reasons:

1. Flows can stay active regardless of the activity/fragment that uses them
2. LiveData is something familiar to many developers, and I wanted to make this example as approachable as possible

To be able to do this, you need to add the following dependency to your build.gradle file:

implementation "androidx.lifecycle:lifecycle-livedata-ktx:2.6.2"

In your activity/fragment class, you can observe this live data like so:

myViewModel.todoItemFlow.observe(LocalLifecycleOwner.current) { todoItems ->
                // Logic to access data from DataStore
            }

Why and When to Use DataStore

After everything we reviewed, it’s time to talk about the elephant in the room. Should you go ahead and use DataStore (either Preferences or Proto) in your existing or next project?

In my opinion, the answer should be Yes. Besides the fact that Google is moving away from SharedPreferences, DataStore offers plenty of benefits to help you focus on your application and not the persistence of your data.

It’s safe to interact with the DataStore from the UI thread (as it moves work to I/O automatically), and it forces you to use Flow (if you haven’t still) and enjoy all the benefits within. There is also an option to migrate easily from SharedPreferences to Preferences DataStore.

If you are contemplating using Room instead of Proto DataStore, well that depends on your use case. If the amount of data you are going to save (or persist) is rather small and won’t require partial updating, the Proto DataStore is the way to go. If you have a larger data set or one that may be complex, you should opt for using Room instead.

If you want to see how all this code looks like in an application, you can see it here:

If you want to read other articles I have written, you can see them here:

Thanks for reading!

References:

• Protocol Buffers Documentation (proto 3)
• Working With Proto DataStore Codelab
• DataStore Documentation

If your application depends on getting the user’s location, you want to ensure that the user has a good experience when the application requests this info. So it's crucial to handle all the edge cases and allow the user to select the option the they're most comfortable with.

With Jetpack Compose, the logic associated with getting the user’s location has changed a bit, and it’s important to know the in’s and out’s of how it can be done.

As with most things, there is a library you can use to handle getting permissions. It’s from Accompanist (read Google) and you can find it here. But you are here to learn how to do things yourself, right? So read on. 🕵️‍♀️

Before we get into the code and the logic, it is important to understand that requesting a permission from a user is a path that can have many decision points. As such, it is best described by having states that represent the current status of the permission (approved/rejected/denied) and the current status of the operating system.

The diagram below illustrates this flow:

Later on in this article, you will see how we will represent these states in variables in our code.

Save Our Souls (S.O.S)

Before we get to the logic of asking for a permission, we’ll take care of the boilerplate around it. As always, add the necessary permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Then, we’ll create a composable screen where we ask for the necessary location permissions. The first step in this screen is to check whether the user has previously granted the required permissions. You can do this with something that is not new to Jetpack Compose – using the checkSelfPermission method:

val locationPermissionsAlreadyGranted = ContextCompat.checkSelfPermission(
            this,
            Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED

If the permission is not granted, we have to request it. We will use the rememberLauncherForActivityResult object to do this. This allows us in Jetpack Compose to get a result from an Activity.

val locationPermissions = arrayOf(
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION)

val locationPermissionLauncher = rememberLauncherForActivityResult(
                contract = ActivityResultContracts.RequestMultiplePermissions(),
                onResult = { permissions ->
                    val permissionsGranted = permissions.values.reduce { acc, isPermissionGranted ->
                        acc && isPermissionGranted
                    }

                    if (!permissionsGranted) {
                       //Logic when the permissions were not granted by the user
                    }
                })

The arguments that we need to pass to rememberLauncherForActivityResult are:

1. An ActivityResultContract – specifies the input of the activity and the output
2. onResult – a callback when the result is received

In the code snippet above, we are using a multiple permissions contract, since we are requesting several location permissions. There is also a contract for requesting just one permission, ActivityResultContracts.RequestPermission().

This piece of code doesn’t not run immediately as we need to request the permissions. To do that we use the launch method to start the activity:

locationPermissionLauncher.launch(locationPermissions)

In the case the user gave all or several of the required permissions, we can continue the logic of the application.

But, if the user did not approve any of the permissions, we need to find a way to make the user understand why these permissions are necessary.

Explaining the Rationale

In case the user declined the permission, but did not select the “Deny And Don’t Ask Me Again” option, we have a way of giving the user a brief explanation on why they should grant the required permission(s).

To figure out if we should present this rationale, we use the shouldShowRequestPermissionRationale from the Activity class:

val shouldShowPermissionRationale: Boolean = shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)

Once we know that we can display this explanation, there are two ways to go about it:

1. We can present it to the user with an AlertDialog
2. We can use the Snackbar

Presenting an alert dialog is pretty straightforward. All we have to do is make sure we describe clearly to the user why it is required to approve this permission:

@Composable
    fun ShowLocationPermissionRationale() {
        AlertDialog(
            onDismissRequest = {
               //Logic when dismiss happens
            },
        title = {
            Text("Permission Required")
                },
        text = {
            Text("You need to approve this permission in order to...")
        },
        confirmButton = {
            TextButton(onClick = {
              //Logic when user confirms to accept permissions
            }) {
                Text("Confirm")
            }
        },
        dismissButton = {
            TextButton(onClick = {
              //Logic when user denies to accept permissions
            }) {
                Text("Deny")
            }
        })
    }

If we want to present the Snackbar, we need to be aware that we have to use a Scaffold container since that is the only container that supports showing a Snackbar. If we don’t use one, a Snackbar won’t appear.

Below is a snippet that shows you how to do this:

val scope = rememberCoroutineScope()
val snackbarHostState = remember { SnackbarHostState() }

Scaffold(snackbarHost = {
        SnackbarHost(hostState = snackbarHostState)
    }) { contentPadding ->
        if (shouldShowPermissionRationale) {
            LaunchedEffect(key1 = shouldShowPermissionRationale, block = {
                scope.launch {
                    val userAction = snackbarHostState.showSnackbar(
                        message ="Please authorize location permissions",
                        actionLabel = "Approve",
                        duration = SnackbarDuration.Indefinite,
                        withDismissAction = true
                    )
                    when (userAction) {
                        SnackbarResult.ActionPerformed -> {
                            //User approved to grant the permission
                            //Ask for permissions again
                        }
                        SnackbarResult.Dismissed -> {
                            //User dismissed snackbar
                        }
                    }
                }
            })
        }
}

We allowed the Snackbar itself to be dismissible using the withDismissAction attribute and listened in to the action performed by the user.

Lifecycle Observer

One thing we have glossed over is the fact that we need to make sure our permission request adheres to the composable lifecycle. This means that once a user chooses their preferences regarding the permission request, we need the UI to adapt accordingly.

If you try and put the code above inside the activity’s onCreate method, you will be surprised with the outcome, since the application will crash with the following exception:

java.lang.IllegalStateException: Launcher has not been initialized

This is because Composable functions are supposed to be side effect free. What is a side effect? According to Google’s documentation it is:

… a change to the state of the app that happens outside the scope of a composable function

So, in our use case, launching an activity for the permissions is the side effect happening here.

To circumvent this scenario, we need to use one of the side effect options. Since we don’t want to ask the user for permissions without remembering what their choices were previously, we can’t use the general SideEffect. And LaunchedEffect is used for calling suspend methods inside of a Composable, which is not our use case here.

So we are left with DisposableEffect. Reading the documentation, we can see that DisposableEffect can be combined with Lifecycle events, which is what we are after.

val lifecycleOwner = LocalLifecycleOwner.current
            DisposableEffect(key1 = lifecycleOwner, effect = {
                val observer = LifecycleEventObserver { _, event ->
                    if (event == Lifecycle.Event.ON_START && !locationPermissionsAlreadyGranted) {
                        locationPermissionLauncher.launch(locationPermissions)
                       }
                    }
                    lifecycleOwner.lifecycle.addObserver(observer)
                    onDispose {
                        lifecycleOwner.lifecycle.removeObserver(observer)
                    }
                }
            )

In the code snippet above, we are adding a lifecycle observer that runs only in the case of the onStart lifecycle event. We also combine it with the boolean we have declared at the start of this section, locationPermissionsAlreadyGranted. This is so we won’t show the dialog for asking permissions if they are already granted.

As with all lifecycle observers, we need to remove our observer once the composition ends. We have that logic inside DisposableEffect’s onDispose clause.

Location Not Found

The last case we need to deal with is when the user chooses the “Deny And Don’t Ask Me Again” option. When this happens, we cannot ask the user to grant the required permissions.

The only way the user can revert their choice is to go to the settings screen of our application and change the permissions there. So we need to direct the user to go there.

To open the settings screen of our application, we need to use an intent with the action of ACTION_APPLICATION_DETAILS_SETTINGS.

Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)).also {
            startActivity(it)
        }

Taking the logic above, we can add it to our code when we know that the user has chosen to deny the permissions and not be asked again. This happens inside our request for permissions when the user has not granted the permissions and the option to show the rationale is false.

Location Confirmed

If we take everything we discussed in this article and put it inside one file, we will get the following code:

class MainActivity : ComponentActivity() {

    @OptIn(ExperimentalMaterial3Api::class)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {

            var locationPermissionsGranted by remember { mutableStateOf(areLocationPermissionsAlreadyGranted()) }
            var shouldShowPermissionRationale by remember {
                mutableStateOf(
                    shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)
                )
            }

            var shouldDirectUserToApplicationSettings by remember {
                mutableStateOf(false)
            }

            var currentPermissionsStatus by remember {
                mutableStateOf(decideCurrentPermissionStatus(locationPermissionsGranted, shouldShowPermissionRationale))
            }

            val locationPermissions = arrayOf(
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.ACCESS_COARSE_LOCATION
            )

            val locationPermissionLauncher = rememberLauncherForActivityResult(
                contract = ActivityResultContracts.RequestMultiplePermissions(),
                onResult = { permissions ->
                    locationPermissionsGranted = permissions.values.reduce { acc, isPermissionGranted ->
                        acc && isPermissionGranted
                    }

                    if (!locationPermissionsGranted) {
                        shouldShowPermissionRationale =
                            shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)
                    }
                    shouldDirectUserToApplicationSettings = !shouldShowPermissionRationale && !locationPermissionsGranted
                    currentPermissionsStatus = decideCurrentPermissionStatus(locationPermissionsGranted, shouldShowPermissionRationale)
                })

            val lifecycleOwner = LocalLifecycleOwner.current
            DisposableEffect(key1 = lifecycleOwner, effect = {
                val observer = LifecycleEventObserver { _, event ->
                    if (event == Lifecycle.Event.ON_START &&
                        !locationPermissionsGranted &&
                        !shouldShowPermissionRationale) {
                        locationPermissionLauncher.launch(locationPermissions)
                    }
                }
                lifecycleOwner.lifecycle.addObserver(observer)
                onDispose {
                    lifecycleOwner.lifecycle.removeObserver(observer)
                    }
                }
            )

            val scope = rememberCoroutineScope()
            val snackbarHostState = remember { SnackbarHostState() }

            LocationPermissionsTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    Scaffold(snackbarHost = {
                        SnackbarHost(hostState = snackbarHostState)
                    }) { contentPadding ->
                        Column(modifier = Modifier.fillMaxSize(),
                        verticalArrangement = Arrangement.Center,
                        horizontalAlignment = Alignment.CenterHorizontally){
                            Text(modifier = Modifier
                                .padding(contentPadding)
                                .fillMaxWidth(),
                                text = "Location Permissions",
                                textAlign = TextAlign.Center)
                            Spacer(modifier = Modifier.padding(20.dp))
                            Text(modifier = Modifier
                                .padding(contentPadding)
                                .fillMaxWidth(),
                                text = "Current Permission Status: $currentPermissionsStatus",
                                textAlign = TextAlign.Center,
                                fontWeight = FontWeight.Bold
                            )
                        }
                        if (shouldShowPermissionRationale) {
                            LaunchedEffect(Unit) {
                                scope.launch {
                                    val userAction = snackbarHostState.showSnackbar(
                                        message ="Please authorize location permissions",
                                        actionLabel = "Approve",
                                        duration = SnackbarDuration.Indefinite,
                                        withDismissAction = true
                                    )
                                    when (userAction) {
                                        SnackbarResult.ActionPerformed -> {
                                            shouldShowPermissionRationale = false
                                            locationPermissionLauncher.launch(locationPermissions)
                                        }
                                        SnackbarResult.Dismissed -> {
                                            shouldShowPermissionRationale = false
                                        }
                                    }
                                }
                            }
                        }
                        if (shouldDirectUserToApplicationSettings) {
                            openApplicationSettings()
                        }
                    }
                }
            }
        }
    }

    private fun areLocationPermissionsAlreadyGranted(): Boolean {
        return ContextCompat.checkSelfPermission(
            this,
            Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
    }

    private fun openApplicationSettings() {
        Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)).also {
            startActivity(it)
        }
    }

    private fun decideCurrentPermissionStatus(locationPermissionsGranted: Boolean,
                                              shouldShowPermissionRationale: Boolean): String {
        return if (locationPermissionsGranted) "Granted"
        else if (shouldShowPermissionRationale) "Rejected"
        else "Denied"
    }
}

And this is how it looks like:

I have put all the logic in one file just for the purpose of this article. It is by no means the most esthetic and correct approach to handling the logic with requesting permissions.

You could easily refactor out the logic variables associated with holding the different state of the request for permissions to a view model class that is attached to this screen.

You can see all of the code described in this article by going to this project:

And if you would like to read more of my articles, you can go view them below:

I have also used this logic in an application that you can try out here.

Thank you for reading!

If you want your application to have this functionality, you'd usually have to build your server and its logic. But we now live in an age of technological innovation, and tools have been created to help you minimize your development time.

This tool is called Firebase Remote Config — a cloud service that enables you change different functionalities of your app without releasing updates or asking users to update the app.

Overview

You can access the Remote Config feature in your project’s Firebase console. It is usually under the Release & Monitor section on the left sidebar.

There are two ways in which you can define your remote configurations:

1. Using Firebase.
2. Using a template file that is in JSON format.

We will focus on the first option, as the second option is a less intuitive approach.

Firebase Remote Config lets you define one or more keys during configuration. Keys can be of the following type:

• String
• Number
• Boolean
• JSON

These keys are used as the configurations for your application. For example, if you have a feature in your application that you would like to control through remote configurations, you could define a Boolean key titled enableFeatureX.

Each key you set has a few other settings that may be useful to you. For example, you can define a default value for a key (for example, false can be the default value of a Boolean key) or make it use a value that you have defined in your application.

Another cool thing you can do, by clicking on the Add new button in the image above, is to set the value of a key based on certain factors. You'll see these options when you click on the button:

• Conditional value.
• Experiment.
• Personalization.

Once you are done adding a key, make sure to publish your changes so they will be deployed.

The Conditional Value Option

You can configure how a value will be set to specific users based on various conditions.

Here, you can decide on what you want to test and how. You will discover several options when you click on the “Applies if” dropdown.

To illustrate the use of this feature, let’s say that you want to target iOS users in the US. You can do that using the “Applies if” dropdown and choosing Platform and then iOS.

After that, you can press the "and" button to add a condition for Country/Region and choose United States.

Make sure to also name your condition, otherwise, the Create condition button won’t be enabled.

Notice how the last field in defining a new condition window tells you how many users will be affected by this condition? That's a pretty cool feature.

The Experiment Option

This option lets you change the behavior of a value in your remote configurations before taking effect on all your users.

You can follow these steps to configure the experiment option:

• In the first step, you have to fill in the name and description of your experiment.
• Then, you have choose which application to target and how many users will be affected (percentage-wise) in the second step.
• The third step is to set up the metrics to measure this experiment. There are two types — the primary metrics and additional metrics.
• Lastly, you can decide on the number of A/B test groups for this experiment.

The Personalization Option

Last but not least is the option to tailor a specific value of your remote configurations to a user based on their own behavior.

You can define values the algorithm may supply to the user based on their behavior. These will be chosen by an objective you define (Step 2). This objective can range from the engagement time of the user to the amount of clicks they perform. In Step 3, you define a condition that will target users so that they will become personalized. Lastly, in Step 4, you add the name and description of this personalization.

Each option has much more to offer than what I have described here, so if you want to learn more, you can use one of the reference links at the bottom. Now that we understand what Remote Config is, let’s see how we can add it to our application.

How to Setup Firebase Remote Config

Before you can do anything related to applying remote configurations, you need to make sure you've added Firebase to your Android project. This has been documented here.

After you have done that, follow these steps:

Step #1 - Add the Firebase remote configuration library to your project inside your application build.gradle file

 implementation 'com.google.firebase:firebase-config-ktx'

There is an option to also import the Firebase Analytics module, but it is not required for remote configurations. It is used in other areas of remote configurations, such as defining a condition based on a specific event happening.

Step #2 - Use the RemoteConfig Object

After syncing your project, you can access the RemoteConfig object with this command:

val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig

Step #3 - Define fetch interval

You can define how often your remote configurations will be fetched and updated. When you are still developing your application, setting this number to be relatively low is more ideal.

val remoteConfigSettings = remoteConfigSettings {                             minimumFetchIntervalInSeconds = 2000
}

If you set the **minimumFetchIntervalInSeconds** to be too low, Firebase will throw a FirebaseRemoteConfigFetchThrottledException, so use a low number only when you are testing things.

Step #4 - Set the configuration for the remote configuration

You can set the remote configuration using the code below:

remoteConfig.setConfigSettingsAsync(remoteConfigSettings)

Step #5 - Set default values

You can have application default values for your remote configurations. These can be created as an XML file inside the XML directory inside the res folder. Here’s what the code looks like:

:remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

This XML file must have an underlying element of a map to wrap all your default values. For example, let’s imagine we have defined a key in remote configurations called my_key, whose value is 1. The XML for the default values will look like this:

<?xml version="1.0" encoding="utf-8"?>
<defaultsMap>
   <entry>      
      <key>my_key</key>     
      <value>1</value>   
    </entry>
</defaultsMap>

Remote configurations need to be fetched and activated. The fetch action fetches and stores your Remote Configurations inside the Remote Config object. The activation part is to make these values available to your application. That’s why there are two API methods:

• fetch (and later use activate)

remoteConfig.fetch().addOnCompleteListener { task ->               if                if (task.isSuccessful) {     
              //Remote Configurations fetch successfully          
           }         
        }.addOnFailureListener { error ->             
                //Remote Configurations fetch failure            
       }
-------------------------
remoteConfig.activate().addOnCompleteListener { task ->  
if (task.isSuccessful) {
        //Remote Configurations activation success   
        }  
   }.addOnFailureListener { error -> 
               //Remote Configurations activation failure
  }

• fetchAndActivate

remoteConfig.fetchAndActivate().addOnCompleteListener { task ->                                if (task.isSuccessful) {     
                //Remote Configurations fetched and activated successfully                }        
       }.addOnFailureListener { error ->           
       //Remote Configurations fetched and activated failure    
     }

Step #6 - Access configurations

Now that our remote configurations have been fetched and activated, we can access and use them in our application. We can do so by accessing the remoteConfig object and using one of the getter methods per the type of the value we set:

val myRemoteConfigValue: String = remoteConfig.getString("my_key")

Conclusion

Since your application will rely on remote configurations for its operation (or parts of it), it is crucial to decide how the application will behave if it does not arrive or takes too long to receive a response.

In essence, there are two ways to handle loading the remote configurations:

1. Your application boots up and waits for the remote configurations to be activated.
2. Your application boots up and does not wait for the remote configuration to be activated. Opting instead to use the remote configurations on the second application run.

It's important to understand that there is no option that is preferable over the other. It all depends on what your use case is and how you would like the user's experience to be when using your application. The first option guarantees that once your application is loaded, all the remote configurations that you have defined will be set and the user's experience will be smooth after the initial load time. If you have critical features that rely on the remote configurations, you will have to go with this option.

On the other hand, if your remote configurations concern a specific feature of your application that doesn't necessarily need to happen on the first initial launch, you might consider going for second option. That way, your application does not need to wait for the remote configurations to be received from Firebase and the logic inside your application can happen later.

There are good and bad implications for each of these methods, and it’s up to you to decide which is better suited for your application. If you choose the first option, you may add a loading screen that times out after a certain period. If you choose option two, it is recommended to create a default mechanism for features in your application and how they should work when the configuration has not yet been received.

There is more than we have discussed in this article, and I encourage you to investigate deeper things. I recently used Firebase Remote Configurations in an application I created that helps users schedule appointments.

You can check it out on the Google Play store.

And you can see the source code here:

If you want to read other articles I have written, you can find them below:

References

• Getting Started With Firebase For Android
• Remote Config Use Cases
• Remote Config Loading Strategies
• Remote Config Personalization

We’ve all done it.

Ain’t nothing like good ol’ tabs to organize content in a complex application. So how do we go about creating a tab layout in Jetpack Compose?

In this tutorial, we’ll go over all of the basics, but also show some things that are more advanced.

How to Create Simple Tabs

To create a tab layout, you need to start with a TabRow. This will be a container element that will hold your tabs.

@Composable
@UiComposable
fun TabRow(
    selectedTabIndex: Int,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.primarySurface,
    contentColor: Color = contentColorFor(backgroundColor),
    indicator: @Composable @UiComposable (tabPositions: List<TabPosition>) -> Unit = @Composable { tabPositions ->
            TabRowDefaults.Indicator(
                Modifier.tabIndicatorOffset(tabPositions[selectedTabIndex])
            )
        },
    divider: @Composable @UiComposable () -> Unit = @Composable {
            TabRowDefaults.Divider()
        },
    tabs: @Composable @UiComposable () -> Unit
): Unit

• selectedTabIndex indicates the index of the tab that is currently selected
• indicator represents the UI that indicates which tab is currently selected
• divider is a composable that is drawn at the bottom of the TabRow under the indicator
• If you don’t have a need to custom style your tabs, you can use TabRowDefaults as it contains the default values and implementation used for TabRow (you can see it being used inside divider)

Let’s see the usage of TabRow with an example. We will create a simple layout that will have three tabs:

1. Home
2. About
3. Settings

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings")

    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
        }
    }
}

A couple things to pay attention to:

• The TabRow composable holds inside of itself a Tab composable
• After the TabRow composable, we have a when clause to handle what happens when each tab is clicked (in our specific case we are opening different screens)
• We are using a variable called tabIndex to keep track of which Tab is selected

Pretty bland, right?

Let’s spice things up with icons by using the icon attribute of the Tab composable.

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings")

    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                        }
                    }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
        }
    }
}

Looking better, but a question does arise: What if we have more tabs than the screen can show?

Luckily, the answer is simple.

There is an option to make our TabRow scrollable. Instead of using the TabRow element, you can use the ScrollableTabRow composable.

@Composable
@UiComposable
fun ScrollableTabRow(
    selectedTabIndex: Int,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.primarySurface,
    contentColor: Color = contentColorFor(backgroundColor),
    edgePadding: Dp = TabRowDefaults.ScrollableTabRowPadding,
    indicator: @Composable @UiComposable (tabPositions: List<TabPosition>) -> Unit = @Composable { tabPositions ->
            TabRowDefaults.Indicator(
                Modifier.tabIndicatorOffset(tabPositions[selectedTabIndex])
            )
        },
    divider: @Composable @UiComposable () -> Unit = @Composable {
            TabRowDefaults.Divider()
        },
    tabs: @Composable @UiComposable () -> Unit
): Unit

So if we convert our example from above, we will get this:

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings", "More", "Something", "Everything")

    Column(modifier = Modifier.fillMaxWidth()) {
        ScrollableTabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                            3 -> Icon(imageVector = Icons.Default.Lock, contentDescription = null)
                            4 -> Icon(imageVector = Icons.Default.HeartBroken, contentDescription = null)
                            5 -> Icon(imageVector = Icons.Default.Star, contentDescription = null)
                        }
                    }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
            3 -> MoreScreen()
            4 -> SomethingScreen()
            5 -> EverythingScreen()
        }
    }
}

How to Create Tabs with Swiping Enabled

Scrollable tabs are nice, but swiping between tabs is even better. Most users will feel that it's more intuitive to swipe between the tabs rather than clicking on each one. If you look at the documentation, you will notice that there are a few options to go with:

1. The swipeable modifier
2. The detectDragGestures modifier
3. The draggable modifier

Not all of these will help us in achieving our goal, each one for its own reasons. If you don’t want to go through the “hassle” of doing things yourself, there is a library from Accompanist called pager that you can use. It allows you to add the ability to either horizontally or vertically create a row/column that reacts to swipes.

Steps to implement it have been covered already and you can use the resources below to learn how to do it:

• https://johncodeos.com/how-to-create-tabs-with-jetpack-compose/
• https://www.rockandnull.com/jetpack-compose-swipe-pager/

If you are like me and you like to do things for yourself and are up for getting your hands dirty, read on.

Option 1: the Swipeable Modifier

The first thing to know about the swipeable modifier is that it is annotated with the @ExperimentalMaterialApi. This means that this API can change between versions of Jetpack Compose and that it isn’t stable.

Apart from that, we need to go over the mechanism that the swipeable modifier uses. It has 3 building blocks:

1. A swipeable state – Denoting the current state and holding data about any on going swipe or swipe related animation.
2. Anchors – A map of values (Float based) restricting the swipe action from the minimum value to the maximum value. It maps anchor points to swipeable states.
3. Thresholds – A value denoting the difference between two known anchors.

@ExperimentalMaterialApi
fun <T : Any?> Modifier.swipeable(
    state: SwipeableState<T>,
    anchors: Map<Float, T>,
    orientation: Orientation,
    enabled: Boolean = true,
    reverseDirection: Boolean = false,
    interactionSource: MutableInteractionSource? = null,
    thresholds: (from, to) -> ThresholdConfig = { _, _ -> FixedThreshold(56.dp) },
    resistance: ResistanceConfig? = resistanceConfig(anchors.keys),
    velocityThreshold: Dp = VelocityThreshold
): Modifier

Regardless of this API being experimental, it just isn’t meant to be used for the swiping gesture we are seeking.

You can. use this modifier for a switch button that the user can drag between on/off positions (as an example). But what would be our anchors in our example? How do we define the thresholds? The swipe a user performs cannot be constrained between two points. Therefore, we’ll let this one go and move on to detectDragGestures.

Option 2: the detectDragGestures Modifier

As the name implies, this modifier detects the drag gesture, which can be quite similar to swiping.

suspend fun PointerInputScope.detectDragGestures(
    onDragStart: (Offset) -> Unit = { },
    onDragEnd: () -> Unit = { },
    onDragCancel: () -> Unit = { },
    onDrag: (change: PointerInputChange, dragAmount: Offset) -> Unit
): Unit

As you can see, the onDrag callback has two arguments:

1. change – of PointerInputChange type, denoting the change in pointer when dragging
2. dragAmount – of Offset type, denoting the amount dragged in x,y values

This callback is called when:

“… waits for pointer down and touch stop in any direction and then calls onDrag for each drag event.”

The upside to use this modifier instead of the draggable one is that it provides you with information about the change in both x and y coordinates.

The downside of it is that it isn’t going to offer a smooth and elegant solution for swiping. This is because of the amount of times the onDrag callback is triggered.

When a user performs a swipe gesture, the onDrag callback is triggered multiple times. This makes it harder to discern when the “drag” gesture has ended completely.

When experimenting with this, I saw the onDrag callback being triggered three times for each swipe gesture. This won’t be a good fit for our use case so let’s check out the draggable modifier.

Option 3: the Draggable Modifier

Think of this modifier as the stripped down version of the one before. This one measures changes in the UI when the user performs a drag gesture in only one orientation (vertical/horizontal). Since we only care about horizontal swipes, this can be a good option.

fun Modifier.draggable(
    state: DraggableState,
    orientation: Orientation,
    enabled: Boolean = true,
    interactionSource: MutableInteractionSource? = null,
    startDragImmediately: Boolean = false,
    onDragStarted: suspend CoroutineScope.(startedPosition: Offset) -> Unit = {},
    onDragStopped: suspend CoroutineScope.(velocity: Float) -> Unit = {},
    reverseDirection: Boolean = false
): Modifier

Here as well there is no similarity to the two other modifiers and we will point out the things to pay attention to:

• state – Similar to the state in the swipeable modifier, only here we are talking about a drag motion.
• onDragStarted – A callback triggered when the drag motion has begun.
• onDragStopped – A callback triggered when the drag motion has ended.

Unlike detectDragGestures, here onDragStopped is called once for every swipe gesture, making this modifier the best candidate for the job.

It’s implementation as a swipe gesture detector in our example is quite robust, so let’s start with some prerequisites:

1. We will be saving the index of the tab currently being viewed in a view model class
2. This index will be of MutableLiveData so that our composables will be able to recompose when the value is changed
3. Each of our screens will add the draggable modifier to its layout
4. We will need to add the runtime-livedata library as we are going to use the observeAsState method.

We will start with #4.

Go to your application’s build.gradle file and add the following dependency:

implementation "androidx.compose.runtime:runtime-livedata:$compose_version"

where $compose_version is the version of Jetpack Compose you are using.

We have also minimized our previous example to hold three screens instead of six, as the solution works for either case and there is no need to create extra boiler plate.

Below is the view model:

class MainViewModel(application: Application) : AndroidViewModel(application) {

    private val _tabIndex: MutableLiveData<Int> = MutableLiveData(0)
    val tabIndex: LiveData<Int> = _tabIndex
    val tabs = listOf("Home", "About", "Settings")

    fun updateTabIndexBasedOnSwipe(isSwipeToTheLeft: Boolean) {
        _tabIndex.value = when (isSwipeToTheLeft) {
            true -> Math.floorMod(_tabIndex.value!!.plus(1), tabs.size)
            false -> Math.floorMod(_tabIndex.value!!.minus(1), tabs.size)
        }
    }

    fun updateTabIndex(i: Int) {
        _tabIndex.value = i
    }

}

• tabIndex is in charge of holding the currently selected index.
• index is the exposed tabIndex.
• tabs is the list of tab names.
• The method updateTabIndexBasedOnSwipe is triggered when a swipe happens and performs the calculation of where to move the tabIndex to.

Each screen is made up of the same layout:

@Composable
fun AboutScreen(viewModel: MainViewModel) {

    var isSwipeToTheLeft by remember { mutableStateOf(false) }
    val dragState = rememberDraggableState(onDelta = { delta ->
        isSwipeToTheLeft = delta > 0
    })

    Column(modifier = Modifier.fillMaxSize().draggable(
        state = dragState,
        orientation = Orientation.Horizontal,
        onDragStarted = {  },
        onDragStopped = {
            viewModel.updateTabIndexBasedOnSwipe(isSwipeToTheLeft = isSwipeToTheLeft)
        }),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center) {
        Row(modifier = Modifier.align(Alignment.CenterHorizontally)) {
            Text(
                text = "About",
                textAlign = TextAlign.Center,
                fontSize = 20.sp,
                fontWeight = FontWeight.Bold
            )
        }
    }
}

• isSwipeToTheLeft is a Boolean indicating the direction of the swipe.
• dragState holds the state of the drag being performed and updates isSwipeToTheLeft according to the delta.
• When the callback onDragStopped is called, we are calling the exposed viewModel method updateTabIndexBasedOnSwipe.

And finally, our TabLayout:

@Composable
fun TabLayout(viewModel: MainViewModel) {
    val tabIndex = viewModel.tabIndex.observeAsState()
    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex.value!!) {
            viewModel.tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex.value!! == index,
                    onClick = { viewModel.updateTabIndex(index) },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                        }
                    }
                )
            }
        }

        when (tabIndex.value) {
            0 -> HomeScreen(viewModel = viewModel)
            1 -> AboutScreen(viewModel = viewModel)
            2 -> SettingsScreen(viewModel = viewModel)
        }
    }
}

• Notice that when a tab is selected, we are updating the currently selected tab in the viewModel with updateTabIndex.

Putting it all together yields:

A few words regarding what we have accomplished. You might have noticed that there is some boilerplate we are adding for each of our screens that results in repetition. Each screen is saving the state of the drag.

To improve on that, we can move the draggableState to the view model, like so:

class MainViewModel(application: Application) : AndroidViewModel(application) {

    private val _tabIndex: MutableLiveData<Int> = MutableLiveData(0)
    val tabIndex: LiveData<Int> = _tabIndex
    val tabs = listOf("Home", "About", "Settings")

    var isSwipeToTheLeft: Boolean = false
    private val draggableState = DraggableState { delta ->
        isSwipeToTheLeft= delta > 0
    }

    private val _dragState = MutableLiveData<DraggableState>(draggableState)
    val dragState: LiveData<DraggableState> = _dragState

    fun updateTabIndexBasedOnSwipe() {
        _tabIndex.value = when (isSwipeToTheLeft) {
            true -> Math.floorMod(_tabIndex.value!!.plus(1), tabs.size)
            false -> Math.floorMod(_tabIndex.value!!.minus(1), tabs.size)
        }
    }

    fun updateTabIndex(i: Int) {
        _tabIndex.value = i
    }

}

And that reduces the boilerplate a bit, since each screen now looks like:

@Composable
fun AboutScreen(viewModel: MainViewModel) {

    Column(modifier = Modifier.fillMaxSize().draggable(
        state = viewModel.dragState.value!!,
        orientation = Orientation.Horizontal,
        onDragStarted = {  },
        onDragStopped = {
            viewModel.updateTabIndexBasedOnSwipe()
        }),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center) {
        Row(modifier = Modifier.align(Alignment.CenterHorizontally)) {
            Text(
                text = "About",
                textAlign = TextAlign.Center,
                fontSize = 20.sp,
                fontWeight = FontWeight.Bold
            )
        }
    }
}

I hope this article gave you the necessary tools to create your own tabs UI in Jetpack Compose.

The example shown above can be found here.

And if you would like to read other articles I have written, you can check them out here.

References:

• Material Design page about Tabs
• Gestures In Jetpack Compose

If you have ever worked with a database or fetching data from a server, this should all be familiar to you. If not, you have come to the right place.

In this tutorial, we will go over:

• How to setup serialization in a Jetpack Compose project
• How to serialize a data class
• How to de-serialize a data class

You might be asking yourself, what’s so special about serialization in Jetpack Compose? In essence, there isn’t a lot of difference than with a regular Kotlin Android project. The only difference is in the setup.

How to Set Everything Up

Each version of Jetpack Compose corresponds with a version of Kotiln that it is compatible with. Each version of the kotlin-serialization library is also compatible with a specific version of Kotlin. So you need to make sure that each of the three parts in this tripod are compatible with one another.

How can you that?

Your first resource you'll want to consult is the Compose to Kotlin Compatibility Map.

Here you can see which version of Jetpack Compose corresponds to which Kotlin version.

The second resource you will need is the releases page for the kotlin-serialization library. There you will find which library version is compatible with which Kotlin version.

Confused? 😕

Let’s illustrate this with an example:

• Your Jetpack Compose version is 1.1.0.
• Looking over the compatibility map, you see it is compatible with Kotlin version 1.6.10.
• Heading to the releases page of kotlin-serialization library, you see that the version of the kotlin-serialization library that you need to use is 1.3.2.

Head into your project level build.gradle file, and inside the buildscript object, in the dependencies section, put in classpath for the kotlin-serialization library with the version you need.

dependencies {
        ...
        classpath "org.jetbrains.kotlin:kotlin-serialization:X.Y.Z"
 }

Then, head over to your application build.gradle file and do these two things:

1. Add the id ‘org.jetbrains.kotlin.plugin.serialization’ inside of the plugins at the top of the file:

plugins {
   ...
   id 'org.jetbrains.kotlin.plugin.serialization'
}

2. At the bottom of the file, inside the dependencies section add implementation ‘org.jetbrains.kotlinx:kotlinx-serialization-json:X.Y.Z’:

dependencies {
   ...
   implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:X.Y.Z'
}

Sync your project and you should be good to go.

Note that we are using the json format of the library, but there are other formats that are supported as well:

• Protocol Buffers
• CBOR (Concise Binary Object Representation)
• Properties
• HOCON (Human Optimized Config Object Notation)

⚠️ If you encounter any errors, make sure the versions you put are correct

How to Build Your Data Class

In order to have something we can serialize and later de-serialize, we need to work with data classes.

Creating a data class is simple. If you are using Android Studio, just right click inside your project’s module and choose New Kotlin file. Enter your class name and then append the data keyword before it.

For the sake of this article, let's say we are working with an API that returns a list of users. Each user object has a range of attributes it can have (just to name a few):

• First name
• Last name
• Age
• Birthdate
• Id

To make our data class serializable, all you need to do is add the @Serializable annotation above the class declaration.

@Serializable
data class UserModel(
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

Pretty nifty, right?

Well, there’s more.

The variable that will hold the user’s first name is written as firstName. That means that in the response from our server, it needs to return in a field with the same name.

Sometimes, in API responses, the keys are not written in camelCase, but rather in kebab_case. That would mean that the key for first name, might be first_name. In that case, we would have to write it out like this:

@Serializable
data class UserModel(
   val first_name: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

But that is not the convention for property names in Kotlin.

So what can we do?

We can use the @SerialName annotation. This allows us to mark what the name of the field will be from the response and then write anything as the property for it.

@Serializable
data class UserModel(
   @SerialName("first_name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

How to Serialize and De-Serialize

Now that our data class is set up, let’s enjoy the fruits of our labor. Whenever we need to serialize our data class, we will use the Json.encodeToString method:

val dataAsString: String = Json.encodeToString(user)

When we run the above line of code, we will get our data class in string form.

De-serializing our data is as simple as serializing it. We will use the Json.decodeFromString method:

val user: UserModel = Json.decodeFromString<UserModel>(dataAsString)

✋ Notice that we specified which type of data we want to de-serialize to with the type parameter ().

_Photo by [Unsplash](https://unsplash.com/@macroman?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Immo Wegmann / <a href="https://unsplash.com/?utm_source=ghost&utm_medium=referral&utmcampaign=api-credit)

Time for some extra credit.

Let’s say that in your data class you have a field that you don’t want to serialize. If we take our UserModel class, imagine that we want to have a user’s actual picture (bitmap).

@Serializable
data class UserModel(
   @SerialName("first-name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long,
   var photo: Bitmap?
)

This is not something we will get from our API call, so how can we exclude it? Because if we don’t, our serialization will fail.

Here to our rescue is the @Transient annotation.

@Serializable
data class UserModel(
   @SerialName("first-name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long,
   @Transient
   var photo: Bitmap?
)

This will exclude the marked field from being serialized and de-serialized.

• If you want to see a real life example of using serialization inside a project, you can check out a project I made here
• And if you would like to read other articles I have written, you can go here
• For more information about the kotlin-serialization library, you can go here

Thank you for reading! Happy serializing.

So how can you still preserve your API keys within your application, but also hide them when you upload your code to your repository?

You probably want to be able to still use your API keys in a normal fashion inside your applications, but also not expose them.

What Are Secrets?

That’s where secrets come in. Similar to those that you keep only to yourself, but in a developer kind of way.

Secrets can represent crucial information that is required by your application to operate, but should not be visible to anyone working outside the project.

These can be API keys or authorization tokens, but in essence a secret is any piece of authorization information that should only be used by you and you alone. It's similar to how you don’t want to share your password to a website with anyone else.

🚨 Disclaimer: Be aware that the solution provided in this article works for not exposing your secrets from your version control system. But since they are part of your application, they can still be discovered by decompiling your APK.

How to Keep Your Secrets Safe

In your project, you should have a local.properties file under the root directory of your project

To make sure it is ignored by your version control system, open the .gitignore file and see that it is found there:

You will need to import to your project the Secrets Gradle plugin.

To do this, go to your project’s root build.gradle file and paste in the following line:

buildscript {
    dependencies {
        id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
    }
}

Next, go to your app’s build.gradle file and paste in the following line:

plugins {
    ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

Add your API key inside the local.properties file:

You can use your secret inside your AndroidManifest.xml file by adding a meta-data tag inside your application tag:

<application
        android:allowBackup="true" 
        .....
                                     >
    <activity>
      ....
    </activity>
      <meta-data
            android:name="YOUR_API_KEY_NAME"     /// Choose any value here
            android:value="${API_KEY_NAME}"/>    /// Write the name you gave inside your local.properties file
</application>

To access your API key, you can use the PackageManager to get the meta data:

val applicationInfo: ApplicationInfo = application.packageManager
                .getApplicationInfo(application.packageName, PackageManager.GET_META_DATA)
val apiKey = applicationInfo.metaData["YOUR_API_KEY_NAME"]

Alternatively, you can also use the BuildConfig object to get it:

BuildConfig.YOUR_API_KEY_NAME

That’s it. Now you can rest easy knowing that your secrets won’t be exposed by your version control system.

Enjoy keeping your secrets. ㊙️

I used this on one of my recent projects, and you can see the source code (sans the secrets) here.

And if you want to check out other articles that I have written, you can go here.