![\"SearchBar](\"https://www.lordcodes.com/img/d_W4hk63eV-814.webp "\\"SearchBar")
For many apps, search is a key part of creating a seamless and intuitive user experience. When it comes to building Android UIs with Compose, this can be achieved using the Material 3 SearchBar. The search bar component allows us to build a bar that, when focused, expands into a search view to display suggestions or search results.
When used as it comes, the SearchBar works nicely by itself and for large screens there is also a DockedSearchBar. Most Android screens, however, include a TopAppBar that has a background colour that changes when content scrolls behind it.
In this article, we will explore how to build a search experience and then how to embed it seamlessly into a TopAppBar. This allows us to create a polished UI that's perfect for including search into any screen.
As a starting point, we have a screen within our navigation hierarchy showing a list of projects. The projects list includes a TopAppBar containing a navigation icon and title. We would like to be able to search across these projects, using a persistent search bar within the top bar, below the title.
When we add the search bar below our TopAppBar, it is positioned correctly, however it is visually separate from the top bar.
![\"SearchBar](\"https://www.lordcodes.com/img/r3sxExqCjZ-750.webp "\\"SearchBar")
There are various changes we need to make so that it appears within the bar:
SearchBar that matches the TopAppBar.TopAppBar.SearchBar expands into a search view.Let's start by building our SearchBar.
@Composable\n@OptIn(ExperimentalMaterial3Api::class)\nfun EmbeddedSearchBar(\n onQueryChange: (String) -> Unit,\n isSearchActive: Boolean,\n onActiveChanged: (Boolean) -> Unit,\n modifier: Modifier = Modifier,\n onSearch: ((String) -> Unit)? = null,\n) {\n var searchQuery by rememberSaveable { mutableStateOf(\"\") }\n // 1\n val activeChanged: (Boolean) -> Unit = { active ->\n searchQuery = \"\"\n onQueryChange(\"\")\n onActiveChanged(active)\n }\n SearchBar(\n query = searchQuery,\n // 2\n onQueryChange = { query ->\n searchQuery = query\n onQueryChange(query)\n },\n // 3\n onSearch = onSearch,\n active = isSearchActive,\n onActiveChange = activeChanged,\n // 4\n modifier = modifier\n .padding(start = 12.dp, top = 2.dp, end = 12.dp, bottom = 12.dp)\n .fillMaxWidth(),\n placeholder = { Text(\"Search\") },\n leadingIcon = {\n Icon(\n imageVector = Icons.Rounded.Search,\n contentDescription = null,\n tint = MaterialTheme.colorScheme.onSurfaceVariant,\n )\n },\n // 5\n colors = SearchBarDefaults.colors(\n containerColor = MaterialTheme.colorScheme.surfaceContainerLow,\n ),\n tonalElevation = 0.dp,\n ) {\n // Search suggestions or results\n }\n}onActiveChanged function. Note: if we wanted to keep the search term we wouldn't clear it here.onQueryChange function.onSearch. For now we are updating results whenever the query changes so are simply deactivating the search mode. If we were using a search API request we would perform the search here instead.The top of the screen is a TopAppBar we have extracted out to ProjectsTopAppBar, which is configured with a back button and title.
Show code for ProjectTopAppBar
@Composable\n@OptIn(ExperimentalMaterial3Api::class)\nprivate fun ProjectsTopAppBar(\n onBackClick: () -> Unit,\n modifier: Modifier = Modifier,\n scrollBehavior: TopAppBarScrollBehavior? = null,\n) {\n TopAppBar(\n title = { Text(\"Projects\") },\n modifier = modifier,\n navigationIcon = {\n IconButton(onClick = onBackClick) {\n Icon(\n imageVector = Icons.AutoMirrored.Rounded.ArrowBack,\n contentDescription = \"Back\",\n )\n }\n },\n colors = TopAppBarDefaults.topAppBarColors(\n navigationIconContentColor = MaterialTheme.colorScheme.primary,\n ),\n scrollBehavior = scrollBehavior,\n )\n}When using the Material 3 Scaffold we can use a Column to position the SearchBar below the bar.
var isSearchActive by rememberSaveable { mutableStateOf(false) }\nval scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()\nScaffold(\n modifier = modifier,\n topBar = {\n Column {\n ProjectsTopAppBar(\n onBackClick = onBackClick,\n scrollBehaviour = scrollBehavior,\n )\n EmbeddedSearchBar(\n onQueryChange = onQueryChange,\n isSearchActive = isSearchActive,\n onActiveChanged = { isSearchActive = it },\n )\n }\n },\n) { contentPadding ->\n // Search suggestions or results\n}We now have a SearchBar showing below our TopAppBar, we next need to add a surface behind it so that it appears visually within the TopAppBar.
The TopAppBar is built with a surface that adapts its container colour based on the scroll behaviour applied to it. We can create a surface to display behind the SearchBar that uses the same styling.
@OptIn(ExperimentalMaterial3Api::class)\n@Composable\nprivate fun TopAppBarSurface(\n modifier: Modifier = Modifier,\n // 1\n colors: TopAppBarColors = TopAppBarDefaults.topAppBarColors(),\n // 2\n scrollBehavior: TopAppBarScrollBehavior? = null,\n content: @Composable () -> Unit,\n) {\n // 3\n val colorTransitionFraction = scrollBehavior?.state?.overlappedFraction ?: 0f\n val fraction = if (colorTransitionFraction > 0.01f) 1f else 0f\n val appBarContainerColor by animateColorAsState(\n targetValue = lerp(\n colors.containerColor,\n colors.scrolledContainerColor,\n FastOutLinearInEasing.transform(fraction),\n ),\n animationSpec = spring(stiffness = Spring.StiffnessMediumLow),\n label = \"TopBarSurfaceContainerColorAnimation\",\n )\n Surface(\n modifier = modifier.fillMaxWidth(),\n color = appBarContainerColor,\n content = content,\n )\n}TopAppBarColors we used in the ProjectsTopAppBar above should be applied to this surface.TopAppBarScrollBehavior we pass into the TopAppBar should be provided to the surface.TopAppBar uses internally.We can now wrap our search bar in the new TopAppBarSurface, passing in the same scroll behaviour.
topBar = {\n Column(verticalArrangement = Arrangement.spacedBy((-1).dp)) {\n ProjectsTopAppBar(\n onBackClick = onBackClick,\n scrollBehavior = scrollBehavior,\n )\n TopAppBarSurface(scrollBehavior = scrollBehavior) {\n EmbeddedSearchBar(\n onQueryChange = onQueryChange,\n isSearchActive = isSearchActive,\n onActiveChanged = { isSearchActive = it },\n )\n }\n }\n}It seems to render with a tiny 1dp gap between the two bars, so spacedBy((-1).dp) is included for vertical arrangement. If anyone can work out the cause of the 1dp gap please reach out.
When the SearchBar becomes active it expands to form a search view. We need to hide the TopAppBar whilst search is active and also alter its appearance. We will make a few changes to the call to SearchBar(...).
modifier = if (isSearchActive) {\n modifier\n .animateContentSize(spring(stiffness = Spring.StiffnessHigh))\n} else {\n modifier\n .padding(start = 12.dp, top = 2.dp, end = 12.dp, bottom = 12.dp)\n .fillMaxWidth()\n .animateContentSize(spring(stiffness = Spring.StiffnessHigh))\n}When active, we can replace the leading search icon with a back button to dismiss the search view.
leadingIcon = {\n if (isSearchActive) {\n IconButton(\n onClick = { activeChanged(false) },\n ) {\n Icon(\n imageVector = Icons.AutoMirrored.Rounded.ArrowBack,\n contentDescription = stringResource(R.string.navigation_action_back_cd),\n tint = MaterialTheme.colorScheme.primary,\n )\n }\n } else {\n Icon(\n imageVector = Icons.Rounded.Search,\n contentDescription = null,\n tint = MaterialTheme.colorScheme.onSurfaceVariant,\n )\n }\n}After a query has been entered into the search view, we can show a clear button.
trailingIcon = if (isSearchActive && searchQuery.isNotEmpty()) {\n {\n IconButton(\n onClick = {\n searchQuery = \"\"\n onQueryChange(\"\")\n },\n ) {\n Icon(\n imageVector = Icons.Rounded.Close,\n contentDescription = stringResource(R.string.search_text_field_clear),\n tint = MaterialTheme.colorScheme.primary,\n )\n }\n }\n} else {\n null\n}We can tweak the background colour of the search view when it's active.
colors = SearchBarDefaults.colors(\n containerColor = if (isSearchActive) {\n MaterialTheme.colorScheme.background\n } else {\n MaterialTheme.colorScheme.surfaceContainerLow\n },\n)As the search view is shown instead of the TopAppBar, we need to apply its window insets.
windowInsets = if (isSearchActive) {\n SearchBarDefaults.windowInsets\n} else {\n WindowInsets(0.dp)\n}This completes our customisation of the active search view.
Show full EmbeddedSearchBar code
@Composable\n@OptIn(ExperimentalMaterial3Api::class)\nfun EmbeddedSearchBar(\n onQueryChange: (String) -> Unit,\n isSearchActive: Boolean,\n onActiveChanged: (Boolean) -> Unit,\n modifier: Modifier = Modifier,\n onSearch: ((String) -> Unit)? = null,\n) {\n var searchQuery by rememberSaveable { mutableStateOf(\"\") }\n val activeChanged: (Boolean) -> Unit = { active ->\n searchQuery = \"\"\n onQueryChange(\"\")\n onActiveChanged(active)\n }\n SearchBar(\n query = searchQuery,\n onQueryChange = { query ->\n searchQuery = query\n onQueryChange(query)\n },\n onSearch = onSearch ?: { activeChanged(false) },\n active = isSearchActive,\n onActiveChange = activeChanged,\n modifier = if (isSearchActive) {\n modifier\n .animateContentSize(spring(stiffness = Spring.StiffnessHigh))\n } else {\n modifier\n .padding(start = 12.dp, top = 2.dp, end = 12.dp, bottom = 12.dp)\n .fillMaxWidth()\n .animateContentSize(spring(stiffness = Spring.StiffnessHigh))\n },\n placeholder = { Text(\"Search\") },\n leadingIcon = {\n if (isSearchActive) {\n IconButton(\n onClick = { activeChanged(false) },\n ) {\n Icon(\n imageVector = Icons.AutoMirrored.Rounded.ArrowBack,\n contentDescription = stringResource(R.string.navigation_action_back_cd),\n tint = MaterialTheme.colorScheme.primary,\n )\n }\n } else {\n Icon(\n imageVector = Icons.Rounded.Search,\n contentDescription = null,\n tint = MaterialTheme.colorScheme.onSurfaceVariant,\n )\n }\n },\n trailingIcon = if (isSearchActive && searchQuery.isNotEmpty()) {\n {\n IconButton(\n onClick = {\n searchQuery = \"\"\n onQueryChange(\"\")\n },\n ) {\n Icon(\n imageVector = Icons.Rounded.Close,\n contentDescription = stringResource(R.string.search_text_field_clear),\n tint = MaterialTheme.colorScheme.primary,\n )\n }\n }\n } else {\n null\n },\n colors = SearchBarDefaults.colors(\n containerColor = if (isSearchActive) {\n MaterialTheme.colorScheme.background\n } else {\n MaterialTheme.colorScheme.surfaceContainerLow\n },\n ),\n tonalElevation = 0.dp,\n windowInsets = if (isSearchActive) {\n SearchBarDefaults.windowInsets\n } else {\n WindowInsets(0.dp)\n }\n ) {\n // Search suggestions or results\n }\n}![\"Active](\"https://www.lordcodes.com/img/vkFWHiyf2w-646.webp "\\"Active")
We have built a SearchBar that appears embedded within a TopAppBar that expands into a full-screen search view when focused. The SearchBar is a very customisible component and Jetpack Compose makes it easy to achieve the design we want. This search bar component can now be used throughout our apps to add search to any screen we want.
Working on Swift projects often involves using tools to help with tasks such as linting using SwiftLint or generating code using Sourcery. When running tools we want to ensure all developers of the project are using the same version and that a specific version can be chosen to ensure compatibility. For most Swift tools there is the choice of many different installation methods, each with its own benefits and drawbacks, so for many people it might not be obvious what the best option is.
Before we look at the installation methods, let's consider what we would like to be able to do:
Homebrew is a popular package manager for Mac and is useful for installing tools and apps, even allowing use of a Brewfile. Unfortunately, unless a particular version is provided as a formula we cannot install a specific version, instead we would need to require team members to update to the latest version. On top of this some tools may not be published to Homebrew and releases can take longer to arrive.
SPM has support for command and build-time plugins, linking to specific versions. Unfortunately, adding them to Xcode projects only allows running command plugins via the UI, so we would need an SPM package with a Package.swift to run them from the command-line. Depending on the tool we are running we may need to build our own plugin.
Many tools offer installation via Cocoapods and running them from the Pods directory. Although we can pin to a specific version, not all tools will be available via Cocoapods. The main issue is that it requires the project to already be using Cocoapods or to add Cocoapods to it, which is Ruby-based.
Swift tools can be built and installed using Mint, where we can enforce versions using a Mintfile. We will of course need another method for installing Mint at the right version itself. Many people use Mint happily, however it can be very slow building tools from sources when the version changes, particular on CI where we will need caching to avoid this happening for every build.
Instead of using a package manager, we could download the tool as a binary from the GitHub release or clone the repository and build it for ourselves. It will be difficult to ensure developers keep tools up-to-date and so the approach will likely involve maintaining some scripts.
For many teams one of these installation methods may be the right approach, however they do come with some potential drawbacks:
For a while I have been successfully using binaries wrapped with scripts to manage download, installation and execution. For developers it is much quicker than any method that builds from sources, it ensures consistent versions and it isn't dependent on use of any external package managers.
First, we need to create a folder in the project to store the tools and then a script for the tool in question, such as swiftlint.sh. We start the script by specifying the version at the top where it is easy to update.
VERSION=\"0.54.0\"We need to calculate the installation directory based on the script location. Make sure to add BuildTools/Tools to the gitignore to avoid binaries or sources being added to source control.
BASEDIR=$(dirname \"$0\")\nINSTALL_DIR=\"${BASEDIR}/Tools/SwiftLint\"\nEXECUTABLE=\"${INSTALL_DIR}/swiftlint\"SwiftLint is provided as a binary on the GitHub release so we can download the version we need.
DOWNLOAD_URL=\"https://github.com/realm/SwiftLint/releases/download\"\nDOWNLOAD_URL+=\"/$VERSION/portable_swiftlint.zip\"We can now write our install function which will download and unzip the binary, before marking it as safe to execute on Mac.
function install_tool {\n mkdir -p $INSTALL_DIR\n curl -LO $DOWNLOAD_URL --output-dir $BASEDIR\n unzip $BASEDIR/portable_swiftlint.zip -d $INSTALL_DIR\n rm -rf $BASEDIR/portable_swiftlint.zip\n xattr -dr com.apple.quarantine $EXECUTABLE\n}If the executable is not already installed, we use our function to install it.
if [[ ! -f $EXECUTABLE ]]\nthen\n echo \"$EXECUTABLE not found, installing…\"\n rm -rf $INSTALL_DIR\n install_tool\nfiIf the executable is already installed, we check if it is the right version and re-install it if not.
INSTALLED_VERSION=$(./$EXECUTABLE --version)\nif [[ $VERSION != $INSTALLED_VERSION ]]\nthen\n echo \"Version out-of-date, re-installing…\"\n rm -rf $INSTALL_DIR\n install_tool\nfiFinally, we run the executable, passing any arguments to it.
./$EXECUTABLE ${@:1}An installable version of the full script is available on GitHub.
Whenever a binary can be linked to for a particular version by URL, such as GitHub releases, it will be compatible with this approach. If no binary is available the script could be adapted to obtain it via cloning and building from the Git tag as a backup.
I have been using this approach to run:
The installable versions also include details of using them witin Fastlane, which is great for projects that are using Fastlane for automation.
Using scripts to install and run our tools combines the best of the options, whils keeping performance high:
It would be unfair if we didn't also consider the drawbacks, in that we have to maintain a script for each tool and the approach only works best when there is a binary available for download.
Hopefully eventually SPM command plugins will be executable from the command-line for Xcode projects in a performant way. This would make that the preferred approach due to being built-in and not involving maintaining custom scripts to run.
", "date_published": "2023-12-21T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/authorization-for-okhttp-retrofit/", "url": "https://www.lordcodes.com/articles/authorization-for-okhttp-retrofit/", "title": "Authorization and retrying of web requests for OkHttp and Retrofit", "content_html": "Are you trying to set up authorization for your OkHttp or Retrofit web requests but aren't sure of the best way to do it? Have you explored Interceptor and Authenticator but aren't sure which to use or how best to use them? We will explore these concepts within OkHttp, how to sign web requests and also how to retry them if they fail due to a failed authorization attempt.
When setting up networking in our apps, authorization is almost always required, as not many remote APIs are completely un-authenticated. OAuth is a common system to use, relying on access tokens to protect our endpoints and refresh tokens to obtain new access tokens once they have expired. The idea is that the access token is added as an Authorization HTTP header on requests to let the API know we have access to a particular resource.
OkHttp provides Interceptors which can alter web requests before they are sent out and Authenticators that allow us to re-sign and retry requests that have failed due to authorization. It is very common, particularly on Android, to use Retrofit for networking, which uses OkHttp internally and so the same techniques apply to Retrofit as well.
Let's have a look at how we set this up and how it all works!
We will start by setting up our AuthorizationInterceptor that adds the Authorization header to all web requests that are sent off to our remote API.
Our access tokens are provided by AuthorizationRepository, which either provides a stored access token or obtains a new one if the stored one has already expired. How this process works depends on the authorization each particular API uses, the important part here is that AuthorizationInterceptor has a function it can call to get an access token to sign the web request with.
Our Interceptor implementation needs to provide an intercept function that can extract the current Request, transform it and then pass this new request back into the chain. The transformation we need to apply involves adding an Authorization header that signs the request with our access token. It is worth noting that the exact format of the header may change depending on what type of tokens each API uses, in our example Bearer tokens are used which are pretty common.
class AuthorizationInterceptor(\n private val authorizationRepository: AuthorizationRepository\n) : Interceptor {\n override fun intercept(chain: Interceptor.Chain): Response {\n val newRequest = chain.request().signedRequest()\n return chain.proceed(newRequest)\n }\n\n private fun Request.signedRequest(): Request {\n val accessToken = authorizationRepository.fetchFreshAccessToken()\n return newBuilder()\n .header(\"Authorization\", \"Bearer ${accessToken.rawToken}\")\n .build()\n }\n}Registering our interceptor just involves adding it to the builder we are using to create our OkHttpClient for either use directly or with Retrofit.
fun okHttpClient(authorizationInterceptor: AuthorizationInterceptor) =\n OkHttpClient.Builder()\n .addInterceptor(authorizationInterceptor)\n .build()All outgoing web requests will now be signed with our access token.
It is possible that our requests may fail with 401 Unauthorized due to an issue with the access token we provided. This will usually be due to the access token having expired or being revoked on the server-side. To handle this situation we can build an OkHttp Authenticator, that allows us to catch this case, add a new token and then retry the request.
We will start by extracting an extension function to set the Authorization header on a request.
fun Request.signWithToken(accessToken: AccessToken) =\n newBuilder()\n .header(\"Authorization\", \"Bearer ${accessToken.rawToken}\")\n .build()We will build in a limit on the number of retries to avoid an infinite loop if authorization for a particular endpoint fails entirely. We can determine how many times a request has been retried from the response.
private val Response.retryCount: Int\n get() {\n var currentResponse = priorResponse\n var result = 0\n while (currentResponse != null) {\n result++\n currentResponse = currentResponse.priorResponse\n }\n return result\n }The implementation of Authenticator receives the response that failed with 401 Unauthorized and has to optionally provide a new request to be triggered. If our request has already been retried twice we will simply allow it to fail to avoid an infinite loop. Signing the request is done in the same way as in our AuthorizationInterceptor above.
class TokenRefreshAuthenticator(\n private val authorizationRepository: AuthorizationRepository\n) : Authenticator {\n override fun authenticate(\n route: Route?,\n response: Response\n ): Request? = when {\n response.retryCount > 2 -> null\n else -> response.createSignedRequest()\n }\n\n private fun Response.createSignedRequest(): Request? = try {\n val accessToken = authenticationRepository.fetchFreshAccessToken()\n request.signWithToken(accessToken)\n } catch (error: Throwable) {\n Logger.error(error, \"Failed to re-sign request\")\n null\n }\n}Registering our authenticator involves adding it to the builder alongside our interceptor.
OkHttpClient.Builder()\n .addInterceptor(authorizationInterceptor)\n .authenticator(tokenRefreshAuthenticator)\n .build()Web requests that fail with authorization issues will now be re-signed and retried!
In the above AuthorizationInterceptor and TokenRefreshAuthenticator we obtain an access token using fetchFreshAccessToken. This function has been built to return the stored access token if it hasn't expired yet or to obtain a new one if it has.
An important note is that the function signatures of both Interceptor and Authenticator require the request to be created or transformed synchronously. The process of refreshing an access token is likely asynchronous due to requiring its own web request to an OAuth API. We therefore need to call this asynchronous token refresh process synchronously, exactly how will depend on how on it is implemented.
In our implementation so far we have assumed that all requests need to be signed in the same way, however, in reality this likely won't be the case. For example, there will likely be requests that need to be performed before a user has signed in such as the account creation request or maybe fetching some form of configuration.
To incorporate this, we can use the OkHttp Tag API, which can also be used in our Retrofit calls. We will tag our web requests with an AuthType enum that specifies which type of authorization to be used.
enum class AuthType {\n ACCESS_TOKEN,\n CLIENT_CREDENTIALS,\n NONE;\n\n companion object {\n fun fromRequest(request: Request): AuthType =\n request.tag(AuthType::class.java) ?: ACCESS_TOKEN\n }\n}With OkHttp the tag can be specified in the request builder and with Retrofit it can be added using an annotation for a particular call.
interface CreateAccountRemoteApi {\n @POST(\"user/identity\")\n suspend fun createAccount(\n @Body request: CreateAccountRemoteDto,\n @Tag authorization: AuthType = AuthType.CLIENT_CREDENTIALS\n ): AccountCreatedRemoteDto\n}The AuthType can now be extracted and used within our AuthorizationInterceptor and TokenRefreshAuthenticator, to decide how to sign the request.
class AuthorizationInterceptor(\n private val authorizationRepository: AuthorizationRepository\n) : Interceptor {\n override fun intercept(chain: Interceptor.Chain): Response {\n val newRequest = chain.request().signedRequest()\n return chain.proceed(newRequest)\n }\n\n private fun Request.signedRequest() = when (AuthType.fromRequest(this)) {\n AuthType.ACCESS_TOKEN -> signWithFreshAccessToken()\n AuthType.CLIENT_CREDENTIALS -> signWithClientCredentialsToken()\n AuthType.NONE -> this\n }\n}Using this approach we can easily control the exact type of authorization each individual endpoint requires, giving us a great level of flexibility.
Adding authorization to web requests for OkHttp and Retrofit can be done without too much complexity, however, without knowing which parts of the API to use it may not be immediately obvious. By using an Interceptor we can avoid requests failing due to being unauthorized and then we can combine this with an Authenticator to also handle the cases where it does unfortunately fail.
Now that we have Swift Package Manager for including framework dependencies, wouldn't it be great if we could use it to install and run our command line tool dependencies as well? What if I told you that this was already possible, allowing you to add tools like SwiftLint to your project within Package.swift and run automation tasks easily and with minimal configuration.
When working on software projects there are usually a set of different scripts for running project automation, or maybe a selection of different command line tools all the developers install on their system. For a Swift project many of these tools are written in Swift, yet we still end up installing them with other package managers such as Homebrew or Mint. These package managers are fantastic and perfect for installing our tools, however when we already have Swift Package Manager (SPM) it would be great if we could use that directly.
We will explore setting up all of our command line tool dependencies using Swift Package Manager, discuss how to run them and then move onto how to write automation tasks using a small CLI within our project.
Swift command line tools can be added to our project by simply adding them as a dependency within Package.swift, alongside framework dependencies we may already be using. We will be running the tools directly and so there is no need to add them as dependencies to any of our targets, we just need SPM to download them for us.
let package = Package(\n name: \"Uploader\",\n products: [\n .executable(name: \"uploader-cli\", targets: [\"Uploader\"])\n ],\n dependencies: [\n .package(\n url: \"https://github.com/realm/SwiftLint\",\n from: \"0.39.1\"\n ),\n .package(\n url: \"https://github.com/nicklockwood/SwiftFormat\",\n from: \"0.44.4\"\n ),\n .package(\n url: \"https://github.com/apple/swift-argument-parser\",\n from: \"0.0.1\"\n )\n ],\n targets: [\n .target(\n name: \"Uploader\",\n dependencies: [\"Uploader\", \"ArgumentParser\"]\n )\n ]\n)For our Uploader Package.swift alongside ArgumentParser which we are using as a dependency on our main target, we can include tools: SwiftLint and SwiftFormat. As they are added just like other dependencies, we can specify the version of the command line tool to use, allowing all developers on the project to use the same version. This is especially important for tools that are linting or formatting code, as it means the same rules will be applied for all developers.
Running our tools is now as simple as using swift run, simple! The same process can be used locally and on CI, which means we get the same versions of the tools in both places!
swift run swiftlint\nswift run swiftformat .\nOn top of running command line tools as we have done so far, it would be great if we could also run all of our project automation in the same way. We could of course simply use Swift scripts, however, if any of them need dependencies this would need to be managed and having a bunch of different scripts may not be as discoverable as it could be.
An alternative is that we create a small CLI within Package.swift that provides a set of automation tasks via subcommands that can then be called in a similar way to the lanes in Fastlane for those who are familiar with it.
The first step to creating our CLI is adding a target that will contain the code for our automation tasks.
targets: [\n ...\n .target(\n name: \"UploaderTasks\",\n dependencies: [\"ArgumentParser\", \"ShellOut\"]\n )\n]The next step is adding an executable product that uses the new target. Make sure to use a simple name for the executable so that it is easy to run, a personal preference being task. Our automation tasks will now be ran using swift run task TASK_NAME.
products: [\n ...\n .executable(name: \"task\", targets: [\"UploaderTasks\"])\n]Our task executable is developed just like any other CLI, although it will be a simple one containing very little code. We could do it manually within main.swift, however, as we will need to run different tasks as arguments to the main command we will need to be parsing these arguments and making it easy for users to find the tasks they can run. To make this really easy there is the ArgumentParser framework from Apple.
Within the main.swift file we create a struct for our main command. This configures the command name, offers text for the help message and provides our tasks as subcommands. We will be providing lint, install and uninstall. To execute our program we call Tasks.main() at the bottom of the main.swift.
struct Tasks: ParsableCommand {\n static let configuration = CommandConfiguration(\n commandName: \"tasks\",\n abstract: \"An automation task runner for Uploader.\",\n subcommands: [Linting.self, Install.self, Uninstall.self]\n )\n}\n\nTasks.main()Before creating our first subcommand, we need to make sure it is easy for our subcommands to execute shell commands such as running other CLI tools or scripts. For doing this there is a great framework called ShellOut. Rather than calling it directly we can write a small wrapper function that handles errors, streams output as output from our CLI and allows execution to continue after an error.
func runShell(_ command: String, continueOnError: Bool = false) throws {\n do {\n try shellOut(\n to: command,\n outputHandle: .standardOutput,\n errorHandle: .standardError\n )\n } catch {\n if !continueOnError {\n throw ShellError()\n }\n }\n}\n\nstruct ShellError: Error, CustomStringConvertible {\n var description: String {\n \"Failed when running shell command\"\n }\n}If the outputHandle and errorHandle weren't connected to standard output and standard error, we would need to print the output of the shellOut call. By using these handles it will appear in the terminal we are running our task from as it is produced. This means we don't need the output from shellOut or the error it throws as the information has already been shown to the user by the point it is received.
For each task we want to add, we create a subcommand to our main Tasks command. We already registered these above and will now work through creating each of the subcommands, starting with the lint task. We are running SwiftFormat in lint mode and then SwiftLint, allowing execution to continue on error so that we get all of the failures out of both tools.
extension Tasks {\n struct Linting: ParsableCommand {\n static var configuration = CommandConfiguration(\n commandName: \"lint\",\n abstract: \"Lint the Uploader codebase, such as static analysis.\"\n )\n\n func run() throws {\n try runShell(\"swift run swiftformat . --lint\", continueOnError: true)\n try runShell(\"swift run swiftlint\")\n }\n }\n}This task is ran using swift run task lint.
We can create another subcommand to format code using SwiftLint auto-correct and SwiftFormat in its regular mode, feel free to add this to your project in the same way as writing our Linting struct.
If our Swift project is itself a CLI, our users will need to install and uninstall it, both tasks either being provided by a script or a Makefile. We can offer these tasks via subcommands in our task runner.
extension Tasks {\n struct Install: ParsableCommand {\n static var configuration = CommandConfiguration(\n commandName: \"install\",\n abstract: \"Install Uploader for running globally.\"\n )\n\n func run() throws {\n try runShell(\"swift build -c release\")\n try runShell(\n \"install .build/release/uploader-cli /usr/local/bin/uploader\"\n )\n }\n }\n}Users can now clone our repository and then run swift run task install to install the application globally on their system. We can also provide an uninstall task, in case they wish to remove our application.
extension Tasks {\n struct Uninstall: ParsableCommand {\n static var configuration = CommandConfiguration(\n commandName: \"uninstall\",\n abstract: \"Uninstall Uploader and remove from system.\"\n )\n\n func run() throws {\n try runShell(\"rm -f /usr/local/bin/uploader\")\n }\n }\n}A really nice feature of ArgumentParser is that it generates a help message from the command structs we have created. This aids discovery of the tasks that can be executed on our project by using swift run task -h or --help.
OVERVIEW: A task runner for Uploader.\n\nUSAGE: tasks \n\nSUBCOMMANDS:\n lint Lint the Uploader codebase, such as static analysis.\n install Install Uploader for running globally.\n uninstall Uninstall Uploader and remove from system. Now that our command line tools and automation tasks are managed using SPM, using our project on CI services such as GitHub Actions and Bitrise couldn't be easier. We simply call the same commands we use locally and SPM will handle checking out the correct versions, building and executing our tools.
swift build\nswift test\nswift run task lintMost CI services will also come with built-in support for caching, so we could speed things up by caching the SPM dependencies for future runs.
Swift Package Manager is a really great way to manage our Swift projects and it is nice being able to use the first-party official build tool and dependency manager. Now we can manage all of our automation and project command line tools using SPM as well, bringing all the project configuration together with one tool.
By building our automation tasks using a CLI within the project, it keeps everything together and easily discoverable. It is also great to be able to build all of this in Swift, meaning the source code and automation is all based on the same language and technologies.
", "date_published": "2020-03-08T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/the-power-of-lazy-properties-in-kotlin/", "url": "https://www.lordcodes.com/articles/the-power-of-lazy-properties-in-kotlin/", "title": "The power of lazy properties in Kotlin", "content_html": "Do you have properties in your Kotlin types that you want to create later after initialization? You may want to avoid making them nullable, avoid using lateinit or delay an expensive set up process to a later point. In Kotlin this is where delegated properties and lazy properties in particular can be used, allowing properties to be initialized when they are needed and even keep our main type's initialization simpler and cleaner.
The idea of making a property lazy is not new to Kotlin and many developers having been doing it in other languages or doing it themselves for ages. There were common approaches to a form of lazy creation in Java, it was hard to live in the Java world without coming across a getInstance() function at some point!
When it comes to defining lazy properties in Kotlin, they have been brought into being part of the language. There is some new syntax, some different options for initializing them and various situations in which they can be really useful. Let's take a look!
Creating a lazy property in Kotlin is pretty simple, we define it using by lazy and provide a function initializer. At a later point, when the property is first accessed it will be initialized using the function we provided and then on future accesses the cached value will be returned instead. Nifty!
private val bindingController by lazy {\n FilesBindingController(viewModel::onFileOpened)\n}Our bindingController property needs to access the viewModel property in order to be created and so by making it lazy, this can be deferred until it is first used. After bindingController has been initialized, the value will simply be returned every time from then on.
Creating our property may not always be as simple as just calling an initializer and more code may be needed to set it up. In these situations we may wish to move the contents of the lazy function initializer to a factory method on the outer class.
class TeamRepository(appSchedulers: AppSchedulers) {\n private val viewState by lazy(::createViewStateLiveData)\n\n private fun createViewStateLiveData(): LiveData<ViewState> =\n teamRepository.teamMembersStream()\n .map(::mapPresentingState)\n .onErrorReturn(::mapErrorState)\n .startWith(ViewState.Loading)\n .subscribeOn(appSchedulers.io)\n .observeOn(appSchedulers.main)\n .toLiveData()\n}Moving the initialization code to a factory method can keep the top of our class cleaner and we may find we prefer to keep this set up code out of the way. In some situations we may even be able to use a separate factory object to move the initialization logic to another type or file if we wanted to.
Across our codebase there will be common situations for using lazy properties and so to simplify the call sites we may decide to use an extension function. For example, when using Android ViewModel, each of our Activities will need to retrieve their View Model, which can be done using an extension function on a common base class.
inline fun <reified ViewModelT : ViewModel> ComponentActivity.bindViewModel() =\n bindViewModel(ViewModelT::class, viewModelFactoryProvider)\n\n@PublishedApi\ninternal fun <ViewModelT : ViewModel> ComponentActivity.bindViewModel(\n viewModelType: KClass<ViewModelT>\n): Lazy<ViewModelT> = lazy {\n ViewModelProvider(this).get(viewModelType.java)\n}Using our new lazy extension function cleans up the initialization call site.
class TeamActivity : FragmentActivity() {\n private val viewModel: TeamViewModel by bindViewModel()\n}This particular example is now provided by the AndroidX Activity library.
Delegated properties work as their name suggests, delegating the property's getter and maybe setter to another type. There are a selection of different delegated property types provided and then on top of this we can write our own. The expression we place after the by keyword is what specifies the delegate that will be used.
In the case of by lazy, a Lazy delegate type will control access to our property, initializing it on first access and then returning the cached value on subsequent accesses. Users of the property don't need to change how they call it, meaning the read-write behaviour of our property can be changed at the property definition without affecting code that uses it.
The lazy function has an argument with a default value that controls its synchronization behaviour. If a lazy property is accessed from multiple threads concurrently, synchronization will need to be handled by choosing an appropriate LazyThreadSafetyMode.
private val messageId by lazy(LazyThreadSafetyMode.NONE) { createMessageId() }The default value SYNCHRONIZED will ensure only a single thread can initialize the property using locks. If we are sure the property will only be accessed by a single thread we can switch to NONE to avoid the overhead of performing the synchronization. There is also the option of using PUBLICATION which allows multiple threads to call the initializer, but only the first returned value being used.
Most UI code, such as in an Activity or Fragment, will run on the UI thread and so properties that are only used here can use the LazyThreadSafetyMode.NONE. We could even add an extension to avoid specifying this each time.
Lazy is useful wherever we want to delay initialization to a later point, rather than doing it straight away. Without it other options may include a lateinit property which simply "promises" to be initialized before it is used or a nullable property which can have a value or not.
When we just want to delay initialization, lazy can be a nicer approach to the alternatives. It can be especially helpful for obtaining dependencies whose initialization is out of our control, such as Android View Models from an Activity or Fragment.
There are times when we need to read a value from somewhere, but don't want it to be retrieved again each time it is needed. An example is reading Bundle extras from an Intent, where using a lazy property would mean on first access the value is read from the Intent and then cached for quicker access in the future.
class OrderDetailActivity : FragmentActivity() {\n val orderId by lazy {\n intent.getParcelableExtra<OrderId>(EXTRA_ORDER_ID)\n }\n}Delegated properties and lazy properties in particular are a great feature to have at our disposal. The give us flexibility over how our properties are initialized and accessed. It is really nice to be able to make a property lazy without having to alter how it is used in calling code.
", "date_published": "2020-03-01T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/uploading-a-file-with-progress-in-kotlin/", "url": "https://www.lordcodes.com/articles/uploading-a-file-with-progress-in-kotlin/", "title": "Uploading a file with progress in Kotlin", "content_html": "Do you want to upload a file using the clean Retrofit syntax, but aren't sure how to receive the result as well as the upload progress? We will be using Retrofit to perform the file upload, building an implementation that is able to receive the completion progress at intervals and then complete with the remote API response.
Whilst long-running operations are happening, it is nice for the user to see that activity is occurring, such as a progress view being displayed. For the case of a file upload we can show the real progress, which can be represented by the number of bytes transmitted out of the total file size.
We will use the APIs available to us in Retrofit, OkHttp and Okio to build a class that can be used whenever we want a request to publish its progress to whoever wishes to observe it!
We are developing a messaging application that is able to attach a file to a message thread. It is worth noting that we are using Kotlin Coroutines, however, it can be altered to use regular callbacks or a reactive framework such as RxJava.
Our endpoint is a POST request that contains a multipart body, consisting of the filename, file MIME type, file size and the file itself. We can define it using Retrofit, specifying the required parts.
@Multipart\n@POST(\"file\")\nsuspend fun uploadFile(\n @Part(\"name\") filename: RequestBody,\n @Part(\"type\") mimeType: RequestBody,\n @Part(\"size\") fileSize: RequestBody,\n @Part filePart: MultipartBody.Part,\n): FileUploadedRemoteDtoIf we just wanted to upload the file without any progress, we would simply convert the file to a request body and send it in the request.
fun createUploadRequestBody(file: File, mimeType: String) =\n file.asRequestBody(mimeType.toMediaType())Monitoring upload progress can be achieved by using our own CountingRequestBody which wraps around the file RequestBody that would have been used before. The data that is transmitted is the same as before, allowing the raw file RequestBody to be delegated to for the content type and content length.
class CountingRequestBody(\n private val requestBody: RequestBody,\n private val onProgressUpdate: CountingRequestListener,\n) : RequestBody() {\n override fun contentType() = requestBody.contentType()\n\n @Throws(IOException::class)\n override fun contentLength() = requestBody.contentLength()\n\n ...\n}Transmitting the request body is performed by writing it to a Sink, we will wrap the default sink with our own one that counts the bytes that are transmitted and reports them back via a progress callback.
typealias CountingRequestListener = (\n bytesWritten: Long,\n contentLength: Long,\n) -> Unit\n\nclass CountingSink(\n sink: Sink,\n private val requestBody: RequestBody,\n private val onProgressUpdate: CountingRequestListener,\n) : ForwardingSink(sink) {\n private var bytesWritten = 0L\n\n override fun write(source: Buffer, byteCount: Long) {\n super.write(source, byteCount)\n\n bytesWritten += byteCount\n onProgressUpdate(\n bytesWritten,\n requestBody.contentLength(),\n )\n }\n}Within CountingRequestBody we can wrap the default sink into our new CountingSink and write to a buffered version of that, in order to both transmit the file and observe its progress.
class CountingRequestBody(\n private val requestBody: RequestBody,\n private val onProgressUpdate: CountingRequestListener,\n) : RequestBody() {\n override fun contentType() = requestBody.contentType()\n\n @Throws(IOException::class)\n override fun contentLength() = requestBody.contentLength()\n\n @Throws(IOException::class)\n override fun writeTo(sink: BufferedSink) {\n val countingSink = CountingSink(sink, this, onProgressUpdate)\n val bufferedSink = countingSink.buffer()\n\n requestBody.writeTo(bufferedSink)\n\n bufferedSink.flush()\n }\n}Whilst observing the upload progress, there will either be progress or a completed response, the perfect candidate for a sealed class. This will allow CountingRequestResult to be the return type and callers can handle both progress updates and the completed result.
sealed class CountingRequestResult<ResultT> {\n data class Progress<ResultT>(\n val progressFraction: Double\n ) : CountingRequestResult<ResultT>()\n\n data class Completed<ResultT>(\n val result: ResultT\n ) : CountingRequestResult<ResultT>()\n}Now that we have a way of uploading a file and receiving the upload progress, we can write our FileUploader. Creating the request body for our upload request involves using a CountingRequestBody that reports progress and completion to a MutableStateFlow (or another reactive type).
private fun createUploadRequestBody(\n file: File,\n mimeType: String,\n progressEmitter: MutableStateFlow<Double>,\n): RequestBody {\n val fileRequestBody = file.asRequestBody(mimeType.toMediaType())\n return CountingRequestBody(fileRequestBody) { bytesWritten, contentLength ->\n val progress = 1.0 * bytesWritten / contentLength\n progressEmitter.update { progress }\n }\n}The upload request consists of using the Retrofit function we implemented at the beginning, providing the file details and the created request body that will count progress. The Retrofit definition and the format of the request parts will depend on how each particular API is put together. Here we are using a request that contains various plaintext parts for the file details and then one for the file to be uploaded.
private suspend fun performFileUpload(\n filename: String,\n file: File,\n mimeType: String,\n progressEmitter: MutableStateFlow<Double>,\n): FileUploadedRemoteDto {\n val requestBody = createUploadRequestBody(file, mimeType, progressEmitter)\n return remoteApi.uploadFile(\n filename = filename.toRequestBody(\"text/plain\".toMediaType()),\n mimeType = mimeType.toRequestBody(\"text/plain\".toMediaType()),\n fileSize = file\n .length()\n .toString()\n .toRequestBody(\"text/plain\".toMediaType()),\n filePart = MultipartBody.Part.createFormData(\n name = \"files[]\",\n filename = filename,\n body = requestBody,\n )\n )\n}Our main upload function can put together all of these parts to create a single result flow. We will be able to collect this to get progress updates as well as the final result.
fun uploadFile(\n filename: String,\n file: File,\n mimeType: String\n): Flow<FileUploadRemoteResult> {\n val progressEmitter = MutableStateFlow(0.0)\n val progressStream = progressEmitter\n .transformWhile<Double, FileUploadRemoteResult> { progress ->\n emit(CountingRequestResult.Progress(progress))\n progress < 1.0\n }\n val resultStream = flow {\n val uploadResult = performFileUpload(\n filename,\n file,\n mimeType,\n progressEmitter,\n )\n emit(CountingRequestResult.Completed(uploadResult.result))\n }\n return merge(progressStream, resultStream)\n}\n\ntypealias FileUploadRemoteResult = CountingRequestResult<FileUploadedRemoteDto>We can now upload a file to our API and update a view as the request progresses, which is nice for noticeably long operations like uploading larger files.
uploader.uploadFile(request.filename, request.file, request.mimeType)\n .distinctUntilChanged()\n .collect { uploadResult ->\n // Update progress in UI\n fileUploadingState.update { inProgressState(uploadResult) }\n\n // Get uploaded file\n if (uploadResult.status is CountingRequestResult.Completed) {\n uploadedFileState.update { uploadResult.status.result }\n }\n }Monitoring the progress of a web request may not be immediately obvious when reading through the Retrofit API, however, the powerful APIs of OkHttp and Okio can get the job done nicely. The solution we have developed can be used for any web request, as the counting process can be wrapped around any RequestBody that needs to be sent in a request.
Extension functions are really great for making life easier, allowing us to add functionality to types that aren't our own. One area we can use an extension is for launching Android Activities more easily.
We can build an extension that allows all Activities to be launched via a generic type argument. An optional request code can be passed to the function, which controls whether startActivity or startActivityForResult is used to launch the Activity. By providing an intent builder function, the Intent that is fired can be customised.
inline fun <reified ActivityT : Activity> Activity.startActivity(\n requestCode: Int? = null,\n intentBuilder: Intent.() -> Unit = {}\n) {\n val intent = Intent(this, ActivityT::class.java)\n .apply { intentBuilder() }\n if (requestCode == null) {\n startActivity(intent)\n } else {\n startActivityForResult(intent, requestCode)\n }\n}\n\nfun startContactCreation(fromActivity: Activity, requestCode: Int) {\n fromActivity.startActivity<ConnectionCreationActivity>(requestCode) {\n putExtra(\"source\", ConnectionCreationSource.CONNECTIONS)\n }\n}Would you like to include secrets such as API keys into your Android project, but also want to protect them and keep them safe? We can use features of Gradle, environment variables, obfuscation and encryption, to keep them out of Git and to keep them secure.
When developing apps we will often need to use secret values that we don't want anyone to get access to, such as tokens, IDs and API keys. There are many reasons they may be needed in our source code and in Gradle scripts, the most common being when we are asked to provide one to authenticate with a third-party API.
We will examine a selection of techniques that we can apply, providing protection for our secrets and preventing them from sitting in plaintext, in plain sight!
When following the set up instructions to integrate a new library, we are usually told to put the API key in the AndroidManifest.xml, in the source code or in a Gradle file. These suggestions will result in the secrets being added to source control and to be easily obtainable in plaintext by decompiling our app.
There are more secure ways of managing our secrets and through these tips we can make them significantly harder to obtain. It is worth remembering that our app is published and installed, meaning people will be able to take it apart and try and find secret values within it. All we can do as developers is to apply an appropriate level of security and do our best to keep these secrets safe. When it comes to API keys and tokens, there are also techniques that can be applied on the backend-side to detect fraudulent use and block access using those credentials.
Gradle allows values to be passed in via Gradle properties, these can be passed on the command line or stored in a project-level or user-level properties file. A great way to handle our secrets is to use the user-level file on our filesystem, keeping them out of the project and out of source control. If we were to remove the project from our system and then re-clone it the secrets would still be there and we also have the possibility to include the same secrets into multiple projects without requiring extra set up.
By storing them at a user-level and keeping them out of Git, it means everyone with read-access to the source code doesn't automatically receive the secrets and if our source control system was compromised the attackers wouldn't obtain all of our secrets alongside the source code.
The file is stored within our user directory:
/Users/<you>/.gradle/gradle.propertiesC:\\Users\\<you>\\.gradle\\gradle.propertiesWe add a property for each secret to the file, keeping in mind it is user-level and so we will want something to signify which app or project the secret corresponds to.
GameCatalogueApp_UploadKeystore_KeyPassword=aaaabbbbcccc\nGameCatalogueApp_AuthClientSecret=123456789\nGameCatalogueApp_Pusher_APIKey=ksldjalksdjskaldAccessing the values within our Android project is as simple as reading them as a Gradle property and using them how we wish. If the value is needed within a Gradle script, such as to pass in a keystore password, it can just be read and used as it is. We are using a handy extension to get the property and return an empty string if it isn't present, to avoid the null value. If our secrets are set up correctly, they won't be missing.
signingConfigs {\n create(\"upload\") {\n storePassword = propertyOrEmpty(\n \"GameCatalogueApp_UploadKeystore_KeyPassword\"\n )\n }\n}\n\nfun Project.propertyOrEmpty(name: String): String {\n val property = findProperty(name) as String?\n return property ?: \"\"\n}Using the values from our source code requires them to be passed through using either resValue or buildConfigField, depending on whether we want them as an Android resource or as a property on the BuildConfig object. One quirk with buildConfigField is the String containing the property value needs to have quotes within it, in order for BuildConfig to be correctly generated.
defaultConfig {\n buildConfigField(\n \"String\",\n \"AUTH_CLIENT_SECRET\",\n buildConfigProperty(\"GameCatalogueApp_AuthClientSecret\")\n )\n\n resValue(\n \"string\",\n \"pusher_key\",\n propertyOrEmpty(\"GameCatalogueApp_Pusher_APIKey\")\n )\n}\n\nfun Project.buildConfigProperty(name: String) = \"\\\"${propertyOrEmpty(name)}\\\"\"It would be very common for our project to be built on a continuous integration (CI) system or service, such as Bitrise or Jenkins. If this is the case we will need our secrets to be available on CI and passed through to the build environment. A handy trick here is that we can set the secrets as environment variables that use the same names as the Gradle properties. The functions we use to read their values within Gradle can then check for both a Gradle property or an environment variable and use whichever is found.
fun Project.propertyOrEmpty(name: String): String {\n val property = findProperty(name) as String?\n return property ?: environmentVariable(name)\n}\n\nfun environmentVariable(name: String) = System.getenv(name) ?: \"\"Of course, this means environment variables can also be used locally if we would prefer, however, using Gradle properties is a very simple process.
Even though our secrets are now usable and kept separate to the source code, it would still be fairly simple to decompile the app and extract our secrets in plain text. We can take our solution further by encrypting the values before they are stored and then decrypting them at runtime.
There are various options for encryption, including built-in options or third-party libraries. One possibility is Themis, which is easy to use and provides strong cryptographic techniques, along with a unified API between Android and iOS. Unless there is a skilled cryptographer working on the project, it may be a good idea to use a higher-level encryption API to avoid mistakes being made which weaken applied security measures.
In order to encrypt our data we will need an encryption key.
GameCatalogueApp_EncryptionKey=super_secret_key\n\nbuildConfigField(\n \"String\",\n \"ENCRYPTION_KEY\",\n buildConfigProperty(\"GameCatalogueApp_EncryptionKey\")\n)We can provide some obfuscation and protection to our key by applying runtime transformations to it, resulting in the "real" key we will actually use. By doing this an attacker would need to decompile the source code and work out from the obfuscated code which operations were applied to the key.
fun generateKey(): ByteArray {\n val rawKey = buildString(5) {\n append(byteArrayOf(0x12, 0x27, 0x42).base64EncodedString())\n append(500 + 6 / 7 * 89)\n append(BuildConfig.ENCRYPTION_KEY)\n append(\"pghy^%£aft\")\n }\n return rawKey.toByteArray()\n}\n\nfun ByteArray.base64EncodedString() = Base64.encodeToString(this, Base64.NO_WRAP)Here we have only applied some fairly simple operations onto the key to demonstrate the idea, the concept could be taken much further and make the key harder to crack.
Now that we have our encryption key ready to go, we can use a Themis SecureCell to turn our raw String data into an encrypted byte string.
fun encrypt(message: String): ByteArray {\n val encryptionKey = generateKey()\n val cell = SecureCell(encryptionKey, SecureCell.MODE_SEAL)\n val protectedData = cell.protect(\n encryptionContext, message.toByteArray()\n )\n return protectedData.protectedData\n}\n\nprivate val encryptionContext: ByteArray? = nullTo store our encrypted secret we can encode the produced ByteArray into a base 64 encoded string. The same key generation code could be added to a script or we could just run the app, encrypt the secret and print out the value for us to copy.
val encypted = EncryptionEngine().encrypt(\"raw_secret_value\")\nLog.d(\"ENCRYPTED\", encypted.base64EncodedString())The Gradle properties or our CI environment variables can now be replaced with encrypted versions.
At runtime we will first need to convert the base 64 encoded version into an encrypted ByteArray.
val encryptedDaya = Base64.decode(secretAsBase64, Base64.NO_WRAP)The encrypted ByteArray now needs to be turned into the raw string versions, using the same encryption key as was used for the encryption process earlier. We will need to handle a failed decryption in some way, which would mean something had been set up incorrectly or an invalid value was passed in.
fun decrypt(encryptedData: ByteArray): String? {\n val encryptionKey = generateKey()\n val cell = SecureCell(encryptionKey, SecureCell.MODE_SEAL)\n return try {\n val cellData = SecureCellData(encryptedData, null)\n val decodedData = cell.unprotect(encryptionContext, cellData)\n String(decodedData)\n } catch (error: SecureCellException) {\n Log.e(\"EncryptionEngine\", \"Failed to decrypt message, error)\n null\n }\n}Our unencrypted secrets can now be used as they were before. It can be a good practice to decrypt them when they need to be used rather than storing them in an unencrypted state during an app session.
Protecting our API keys and other secrets is a good practice to avoid someone accessing them and causing us harm. This is particularly true if the keys are used for authentication or for accessing our own API that serves up user data. Using various techniques, we have removed the secrets from source control, kept them out of the project, encrypted them and applied protection to our encryption key.
On top of what has been discussed there are further practices that can be applied, some requiring more significant changes. It is best to evaluate the security needs of a particular application, based on what type of data it uses and the level of security a user would expect. Clearly a banking app will need to be much more security concious than a timer app, however, a good-level of security should be applied regardless to protect access to a user's data.
", "date_published": "2020-02-16T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/enforcing-type-safety-of-ids-in-kotlin/", "url": "https://www.lordcodes.com/articles/enforcing-type-safety-of-ids-in-kotlin/", "title": "Enforcing type safety of IDs in Kotlin", "content_html": "For codebases with many different entities, most of us will at some point have hit a bug due to the wrong ID being assigned to a property or passed to a function. Why don't we use the type system to give all of our IDs their own type and ensure this never happens again.
It is very common for objects to need a form of identifier or ID, frequently the reason being to refer to entities when communicating with a remote API or a database. We can easily implement this by giving our classes an ID property with an appropriate type, such as String, UUID or Long. An issue here is that imagine User and Team both have a String ID, it would be perfectly possible to pass a User ID to a function when we were meant to provide a Team ID instead.
Let's explore the idea of enforcing type safety by giving our IDs their own types.
One option for our IDs is to use the String type, especially if they are in an unexpected format. Another common type of ID is a UUID, an implementation of which is provided by the Java standard library. UUID is designed for storing IDs and is a 128-bit value, which can be easily converted to and from a String.
data class Team(val id: UUID, val size: Int)\n\ndata class TeamMember(val id: String, val name: String)Rather than relying on the general types, we can easily create a dedicated one.
data class Identifier(val rawValue: UUID)If we require different raw types, we can either create extra ID types that contain different raw types or use a single one with a generic type parameter. Using a generic version allows us to have properties or function arguments that require a particular type of ID.
data class Identifier<RawT>(val rawValue: RawT)We can add helpful extensions to Identifier for use with common raw types, such as pulling out the raw String value:
val Identifier<UUID>.uuidString: String\n get() = rawValue.toString()There are some issues that can appear when using these general types internally. Say Team has a UUID ID and Member has a String ID:
Team ID is a UUID, but not every UUID refers to a valid Team.Member ID could have the same value as the raw String backing a Team ID, even though they refer to different entities.Mixing and matching two different IDs that use the same raw type is perfectly valid and not prevented by the compiler. We can do better than this!
By adding a second generic type parameter to our Identifier we can limit its use for a particular entity.
data class Identifier<EntityT, RawT>(\n val rawValue: RawT\n)\n\ndata class Room(val id: Identifier<Room, UUID>)\ndata class Meeting(val id: Identifier<Meeting, UUID>)\n\nfun bookMeeting(id: Identifier<Meeting, UUID>) {}\n\n// ❌ Compile error: Type mismatch.\nbookMeeting(room.id)Due to EntityT not actually being used within Identifier we will likely get a warning about it being unused, which can be ignored using @Suppress("unused").
When our codebase has a variety of entities, the number of IDs will grow and we are likely to get fed up with typing out the Identifier signature. We can rely on type aliases to simplify this task. A nice organisation tip is to store these alongside the entity they identify, making them easy to find.
// Team.kt\n\ntypealias TeamId = Identifier<Team, UUID>\n\ndata class Team(val id: TeamId)Specifying IDs in properties and functions is now so much simpler.
fun Team.inviteMember(id: MemberId) {}\n\n// ❌ Compile error: Type mismatch.\nteam.inviteMember(team.id)\n\n// ✅ Compiles.\nteam.inviteMember(member.id)If we wanted to avoid the generic type arguments, we could rely on the brevity of Kotlin data classes and simply have a separate tiny type for each ID.
data class MessageId(val raw: UUID)\ndata class ChatId(val raw: String)\ndata class PersonId(val raw: Long)The advantage is they are significantly simpler due to being just basic data classes, they could even be inline classes. A possible downside is that with Identifier we can write code that automatically converts Identifier to other types for tasks such as storing in a Bundle to pass to an Activity or to a format Room can store in a SQLite database. We will have to weigh up the pros and cons of each approach and decide what is best for our particular situation.
By using a type that enforces type safety of our entity IDs, we can make our model code safer to work on and avoid bugs due to an incorrect ID being used. Our code will also be more readable as when we see an ID we will know which entity it refers to. There may even be ways to extend this solution to make it even more powerful!
", "date_published": "2020-02-09T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/the-power-of-sealed-classes-in-kotlin/", "url": "https://www.lordcodes.com/articles/the-power-of-sealed-classes-in-kotlin/", "title": "The power of sealed classes in Kotlin", "content_html": "Wouldn't it be great if you could represent a single type that can come in different forms, each able to be constant or carry their own data? If programming in Kotlin, we are in luck as that is exactly what a sealed class is perfect for!
Enums or enumerated types have existed in many different programming languages for years and allows us to represent a type whose value is taken from a limited set of values. Kotlin takes this concept and evolves into something much more powerful, known as sealed classes. They are a really useful addition to the language, enabling powerful use cases and can help us build some really nice APIs. Let's have a look at how sealed classes can be used, their benefits and some example situations in which they can be the perfect tool for the job.
Both enums and sealed classes allow us to represent a type that can be one value from a set of possibilities. An enum consists of a set of constant values and the instance is assigned one of these constants. Sealed classes instead rely on a set of sub-classes, allowing us to have multiple instances of each sub-class and for them to have their own state.
Sealed class sub-classes can carry their own state
Let's say we have an AuthenticationState that keeps track of which state a user's account is in within our app. The user can be: signed in with a user identifier, signed out with some credentials stored or fully signed out.
sealed class AuthState {\n data class SignedIn(val userGuid: UUID) : AuthState()\n data class StoredCredentials(val credentials: Credentials) : AuthState()\n object SignedOut : AuthState()\n}By using a sealed class, a property of type AuthenticationState has to have one of the sub-classes assigned to it. We can use a data class to give the sub-class its own properties or an object and make it constant.
Unlike with an enum, the sub-classes do not need to be kept in the body of the sealed class, only within the same file.
// AuthState.kt\n\nsealed class AuthState\ndata class SignedIn(val userGuid: UUID) : AuthState()\ndata class StoredCredentials(val credentials: Credentials) : AuthState()\nobject SignedOut : AuthState()The way we choose to structure our sealed classes affects how they are referenced, the above examples resulting in AuthState.SignedOut or SignedOut. We can therefore place the sub-classes within the sealed class to create a namespace for our type.
One of the situations sealed classes really stand out is within a when expression. Using when as an expression, assigning or returning the result, allows the compiler to determine if all possible cases have been handled, without needing an else branch.
fun onAuthStateChanged(newState: AuthState) = when (newState) {\n is AuthState.SignedIn -> showSignedIn(newState.userGuid)\n is AuthState.StoredCredentials -> showSignedIn(newState.credentials)\n AuthState.SignedOut -> showSignedOut()\n}The compiler can determine if all cases have been handled
By using sealed classes within our APIs we can make it really easy for consumers to handle all of the possible states. When used within our own code, if we add an extra sub-class then any when statements used as an expression have to handle it.
In Android apps (or other GUI applications), we need a way to connect the logic that controls our UI to the views themselves. One part of this process may involve modelling the state of the view, such as if it is loading, showing an error or showing data.
sealed class ViewState\nobject LoadingState : ViewState()\ndata class PresentingState(val viewData: ContactsViewData) : ViewState()\ndata class ErrorState(val message: String) : ViewState()Imagine we are developing a screen that displays a list of contacts loaded from a local database. Our view layer will receive the ViewState and can then render the correct views based on which sub-class of the sealed class is received.
fun renderViewState(viewState: ViewState) = when (viewState) {\n LoadingState -> showLoadingViews()\n is PresentingState -> showPresentingViews(viewState.viewData)\n is ErrorState -> showErrorViews(viewState.message)\n}Using a sealed class allows us to update our views for all the possible view states, along with each state carrying a different set of data:
LoadingState can just be an object with no dataPresentingState brings with it ContactsViewData to render the contactsErrorState contains an error message to be shownWithout a sealed class, we would need a class that contains all of the data as nullable properties and an enum to represent which state it was in.
We will often need to work out how people are using our apps or verify the effectiveness of certain actions through the use of analytics. This usually boils down to firing off events after specific actions have been taken within the app. These analytics events will be reported in the same way, but may have different properties attached to them, this is a perfect candidate for a sealed class. Code that needs to handle the event can do this easily using a when expression, for example, mapping each event to its map of properties.
sealed class AnalyticsEvent {\n object AccountCreated : AnalyticsEvent()\n data class MessageSent(val conversation: Conversation) : AnalyticsEvent()\n data class ProfileOpened(val participant: Participant) : AnalyticsEvent()\n\n fun parameters(): Map<Parameter, String> = when (this) {\n AccountCreated -> mapOf()\n is MessageSent -> mapOf(\n Parameter.PARTICIPANT_COUNT to\n conversation.participants.size.toString(),\n Parameter.IS_ARCHIVED to\n conversation.isArchived.toString()\n )\n is ProfileOpened -> mapOf(\n Parameter.HAS_ACCOUNT to\n participant.hasCreatedAccount.toString()\n )\n }\n\n enum class Parameter {\n HAS_ACCOUNT,\n IS_ARCHIVED,\n PARTICIPANT_COUNT,\n }\n}We could instead model an analytics event as a simple data class with a name and map of properties. An issue with this approach is it can spread the event names, property names and creation of events all over the codebase. The advantage of the sealed class approach is that we can keep the definition of all our events in one place, ensuring they are correct and that they report the correct properties. It is really great that sealed classes allow us the flexibility to have an AnalyticsEvent type that can be passed around, even though it can come in many different forms.
Sealed classes are a really powerful feature of Kotlin, allowing the flexibility to model a single type that can come in a finite set of different forms. We have only explored a few of the use cases for them, I am sure you will find many more in your codebase!
", "date_published": "2020-02-02T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/using-kotlin-to-bind-android-views/", "url": "https://www.lordcodes.com/articles/using-kotlin-to-bind-android-views/", "title": "Using Kotlin to bind Android views", "content_html": "When working in the UI layer of an Android app, it won't be long before we need to perform an operation upon one of our views. In order to do this, we first need to retrieve it via findViewById. Although using the API can seem simple, it does introduce a block of boilerplate to our Activities. On top of this the code to bind all the views usually ends up in onCreate, completely separate from the view properties themselves.
Now that Kotlin has entered the scene with new features we didn't previously have access to it seems like the perfect time to look for a new way of doing things. We will explore how some different approaches, including lazy initialisation and Kotlin Android Extensions, can be used to solve this problem.
To set the scene and to demonstrate how Kotlin can help we first need to look at how these tasks are achieved in Java. To bind views to a field, we would use findViewById, historically casting the resulting view to the correct subclass. For an activity, the views would commonly be bound within onCreate, however, this may be elsewhere if views are retrieved at another time.
public class PlanningActivity extends AppCompatActivity {\n private TextView planningText;\n private ImageView appIcon;\n\n @Override\n protected void onCreate(Bundle savedInstanceState) {\n super.onCreate(savedInstanceState);\n\n setContentView(R.layout.activity_planning);\n // Before: Needed to cast\n planningText = (TextView) findViewById(R.id.planningText);\n // Now: No longer need to\n appIcon = findViewById(R.id.appIcon);\n\n planningText.setText(\"Hello!\");\n }\n}The example here is very simple, containing only two views, whereas in reality many different views may need to be accessed. To avoid this repetitive boilerplate ButterKnife was created, which uses annotation processing to aid the binding of views.
public class PlanningActivity extends AppCompatActivity {\n @BindView(R.id.planningText) TextView planningText;\n @BindView(R.id.appIcon) ImageView appIcon;\n\n @Override\n protected void onCreate(Bundle savedInstanceState) {\n super.onCreate(savedInstanceState);\n\n setContentView(R.layout.activity_planning);\n ButterKnife.bind(this);\n planningText.setText(\"Hello!\");\n }\n}The Kotlin programming language has many new features and so it feels natural that it may offer a better solution to what we were using before. A new concept in the language is that of delegated properties, specifically the lazy delegated property. The way it works is that when the property is first accessed it will be initialized via the provided function and on future accesses the value will just be returned. This sounds perfect for binding views as the first access can call findViewById and then subsequent calls can just provide the stored view.
private val planningText by lazy {\n findViewById<TextView>(R.id.planningText)\n}A lazy delegated property is initialised on first access
To avoid typing all of this each time we want to bind a view, an extension function on Activity can be created. We can also optimise performance slightly by disabling thread safety, due to the fact that the views will only be accessed from the main UI thread.
fun <ViewT : View> Activity.bindView(@IdRes idRes: Int): Lazy<ViewT> {\n return lazy(LazyThreadSafetyMode.NONE) {\n findViewById<ViewT>(idRes)\n }\n}\n\nclass PlanningActivity : AppCompatActivity() {\n private val planningText by bindView<TextView>(R.id.planningText)\n // or\n private val planningText: TextView by bindView(R.id.planningText)\n}We now have a succinct and clear call site, with full control over the view binding and no generated code required. As bindView is essentially a wrapper around findViewById it can be applied elsewhere in the codebase, beyond just in Activity.
Applying to views, such as in a RecyclerView.ViewHolder is as simple as creating a similar extension function to give us access to the same API we had within Activities.
Where our technique encounters some issues is when used within a Fragment due to differences in their lifecycle. Without alterations the lazy property can refer to an old view instance after the Fragment view has been recreated. We can either avoid lazy view binding in Fragments or put together a solution using the Lifecycle Architecture Component. By creating our own version of Lazy we can reset the stored value in onDestroyView, causing the next access to call findViewById again. An example implementation demonstrating this idea can be found within the sample code for the article.
As an alternative to implementing our own solution, especially if the situation with Fragments makes the lazy binding approach undesirable, we can use the Kotlin Android Extensions. The plugin automatically generates properties that match the IDs of the views in our layout file. Views no longer need to be stored manually as properties, as they are instead accessed via synthetic properties generated by the plugin.
Automatically generated properties that bind to our views
We first need to apply the plugin within our Gradle configuration.
build.gradle
apply plugin: 'kotlin-android-extensions'build.gradle.kts
apply(plugin = \"kotlin-android-extensions\")Once applied the plugin will generate synthetic properties for us to access views that are specified within our layout XML files, with names matching the IDs. To access the properties we need to add an import statement for each layout file. It is recommended to use the star syntax for the import, with Android Studio already having this specified within the default code style settings. The IDE should also add the import automatically when you try to reference one of the properties.
import kotlinx.android.synthetic.main.activity_planning.*\n\nclass PlanningActivity : AppCompatActivity() {\n override fun onCreate(savedInstanceState: Bundle?) {\n super.onCreate(savedInstanceState)\n\n setContentView(R.layout.activity_planning)\n planningText.text = \"Hello\"\n }\n}The plugin comes with other features such as applying to other custom containers and customising the view caching. Any features that are still considered experimental can be enabled within our Gradle configuration. Please find all the details of the other features on the plugin website.
androidExtensions {\n experimental = true\n}Using Kotlin Android Extensions is a very clean approach, requiring practically no extra code. To previous users of ButterKnife it feels like an evolution to that approach. As with any potential solution it is best to try it out, see how it works and whether it fits with all the use cases a particular project has.
When this article was originally written I recommended the lazy property approach due to us being able to strike a great balance between brevity, avoidance of boilerplate and reducing reliance on generated code. Since this time I have found that my preferred solution has shifted towards the Kotlin Android Extensions plugin due to its simplicity and not having to worry if there will be issues with lazy binding in situations such as that of Fragments.
", "date_published": "2019-01-30T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/android-signing-using-gradle-properties/", "url": "https://www.lordcodes.com/articles/android-signing-using-gradle-properties/", "title": "Android signing keystore details from Gradle properties", "content_html": "We may want to keep our Android project keystore details out of our source code and Git by passing them in. Aided by a handy function, these can be referenced from Gradle in Groovy or Kotlin.
import org.gradle.api.Project\n\nfun Project.propertyOrEmpty(name: String): String {\n return findProperty(name) as String? ?: \"\"\n}\n\nandroid {\n signingConfigs {\n create(\"upload\") {\n storeFile = file(\"upload.keystore\")\n storePassword = propertyOrEmpty(\"UPLOAD_STORE_PASSWORD\")\n keyAlias = \"keyname\"\n keyPassword = propertyOrEmpty(\"UPLOAD_KEY_PASSWORD\")\n }\n }\n}When working on a software project, particularly in a team, a common workflow involves branching from the main branch, often master or develop. The created branch is where changes for a particular feature or issue are applied. One way of managing this branch would involve committing all work for a large feature to this branch and then merging it back once it has been completed. This means the branch lives for a relatively long time and we will likely find the integration process to be a painful process.
Continuous Integration, commonly referred to as CI, is a popular development practice that instead involves integrating changes back into the main branch regularly. By integrating regularly the aim is that the cost of doing so will go down and errors will be detected more quickly. An important part of this process is that before changes are merged, the code is automatically built and tested. By testing before the merge instead of afterwards, integration issues are visible earlier and issues can hopefully be fixed more easily.
![\"Continuous](\"https://www.lordcodes.com/img/LGKkzI87Wg-1000.webp)
Many people will agree that CI provides many benefits in a team environment, including in-house teams and open source projects with many different contributors. What is spoken about less often are the benefits of using CI in a solo environment. By having CI building and testing our code before it is merged, we can integrate code more safely and monitor it over time.
In order to build and test code automatically, it is a good idea to have the process running on a CI server of some kind. This server monitors the codebase for changes, such as via a Pull Request using web-hooks, and then triggers the test suite to be executed. By ensuring the CI server is separate to the development machines verifies that it builds correctly in a clean and consistent environment.
A pull request can automatically trigger a test run
When it comes to setting up and running a CI server, there are a huge number of services to choose from. We will have a look at a few that work differently to give an idea of what is available.
Circle CI is a cloud-based service that uses either Linux or MacOS virtual machines as the build environment. For Android, Linux is the best option due to the pricing being much more favourable with a free tier. Configuring the build jobs involves a YAML file within the project, resulting in a process that is very customisable.
![\"Circle](\"https://www.lordcodes.com/img/Lsr2yAgao5-300.webp)
Bitrise is similar to Circle CI in that it is a cloud-based service, however, it is tailored to the individual needs of mobile development. This means it has many mobile specific integrations, including deploying to Google Play alongside services such as TestFairy and Firebase Test Lab. As with Circle CI there is a free tier, although it is fairly limited in terms of build minutes allowed. Configuring the build jobs can be done either via a YAML file in the project or using the workflow editor directly within the web UI, giving an increased level of flexibility.
![\"Bitrise](\"https://www.lordcodes.com/img/DeEkOx5Fmj-430.webp)
Jenkins is the leading self-hosted automation server that we install, configure and maintain ourselves on our own hardware or cloud infrastructure. Jenkins is perfect for people who want to maintain the full CI set up themselves. It is incredibly customisable, where we can essentially make it do whatever we want, boasting a huge number of plugins and integrations from the community. It does come at the cost of doing all this, where the other cloud-based solutions are managed for you.
![\"Jenkins](\"https://www.lordcodes.com/img/dc0yTPuWkn-490.webp)
There are many other CI solutions that haven't been mentioned here including: Travis CI, CodeMagic, GitLab CI, TeamCity and Bitbucket Pipelines.
The best solution isn't the same for everyone. The best solution depends on individual requirements, the features we want and also personal preference. To explore the process of setting up CI, we will look at getting a simple workflow running in both Circle CI and Bitrise via the web UI, for comparison.
Once our Circle CI account has been created and integrated with our source control, such as GitHub or Bitbucket, we can start creating our CI config. For Circle CI, this needs to be a YAML file at .circleci/config.yml.
version: 2.0\n\njobs:\n build:\n working_directory: ~/workspace\n docker:\n - image: circleci/android:api-28\n\n steps:\n - checkout\n\n - run:\n name: Run tests\n command: ./gradlew lintDebug testDebugUnitTest\n\n - store_artifacts:\n path: app/build/reports\n destination: reports\n - store_test_results:\n path: app/build/test-resultsThis example only covers the very basics and there is much more we can do with our configuration. An example showing a more advanced workflow including caching and sharing the workspace between workflow steps can be found as a gist.
![\"Circle](\"https://www.lordcodes.com/img/PQfS5_G_cR-1000.webp)
After creating our Bitrise account, we can add our app to Bitrise by following through the full set up wizard. Bitrise is specifically designed for mobile, the detailed wizard helping with pretty much all of the heavy lifting. Once complete and on the dashboard page for our project, the navigation banner should be visible, giving us access to all of the customisation we need.
![\"Bitrise](\"https://www.lordcodes.com/img/BKEuGXkWDY-1440.webp)
Entering into the 'workflow' area, we will be able to fine tune the default generated workflow as well as add any extra workflows we will need. Each workflow can be triggered at different times, so we could have one that runs for pull requests and another for tagged commits as an example.
![\"Bitrise](\"https://www.lordcodes.com/img/ZMKfJyy0G0-1440.webp)
For our build we will need:
lintDebug.testDebugUnitTest.This covers a basic workflow that matches the one we created for Circle CI above. More advanced workflows can easily be put together using the many steps available, which are open source and viewable on GitHub.
Both Circle CI and Bitrise are very powerful and capable CI tools that apply well to Android development. Both solutions also work well for iOS development, allowing teams that develop for both platforms to use the same tool and subscription.
Circle CI has a more generous free tier in terms of usage, is highly customisable and will be very familiar with those used to configuring CI with a YAML file. Bitrise has more mobile specific plugins available out-of-the-box, allows configuration via the web UI and has a much more user-friendly interface.
It is important to find the right CI tool for the job by trying out the different options. When it comes to CI everyone will have a personal preference and this plays an important role in the decision of which one to use. It is even worth thinking about using CI for solo projects, although there is a set up and maintenance cost, it is still very valuable knowing that the project builds and that all tests are passing.
", "date_published": "2019-01-24T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/kotlin-source-directory-gradle-kotlin-dsl/", "url": "https://www.lordcodes.com/articles/kotlin-source-directory-gradle-kotlin-dsl/", "title": "Set up Kotlin source directory from Gradle Kotlin DSL", "content_html": "When converting Android Gradle files from Groovy to Kotlin, one thing that may not be clear is how to keep Kotlin sources within src/main/kotlin. We simply need to get the source sets by name and call java.srcDirs() as a function call. Works like a dream!
sourceSets {\n getByName(\"main\").java.srcDirs(\"src/main/kotlin\")\n getByName(\"test\").java.srcDirs(\"src/test/kotlin\")\n getByName(\"androidTest\").java.srcDirs(\"src/androidTest/kotlin\")\n}There are different ways of representing a type of file, two popular ones being file extensions and another being Uniform Type Identifiers (UTIs) from the UIKit APIs. When working with a UIKit API such as UIDocumentPickerViewController we may need to distinguish between these types.
We can create independent types to hold file extensions and type identifiers, this makes it really clear which one is required for a particular piece of functionality.
struct FileExtension {\n let rawValue: String\n\n func asTypeIdentifier() -> TypeIdentifier {\n let identifierCreated = UTTypeCreatePreferredIdentifierForTag(\n kUTTagClassFilenameExtension, rawValue as NSString, nil\n )\n if let typeIdentifier = identifierCreated?.takeRetainedValue() {\n return TypeIdentifier(rawValue: typeIdentifier as String)\n }\n return TypeIdentifier(rawValue: \"public.data\")\n }\n}\n\nstruct TypeIdentifier {\n let rawValue: String\n}When it comes to logging in Swift and iOS applications in particular, the APIs that first come to mind might be print and NSLog. More recently, however, Apple has introduced a new standard for logging in the form of unified logging, accessed via OSLog. It is the current recommended way of logging, providing an efficient way to capture information across our applications.
Unified logging provides a number of improvements over previous techniques and also some differences to what we are used to.
Using unified logging from Swift is as simple as using the os_log function, which we will quickly notice takes a StaticString as an argument rather than a regular String. The easiest way to log messages, is to place the String constant directly in the function call. Extracting the message to a property is possible, however, we will need to define it's type as StaticString.
os_log(\"User signed in\")\n\nlet errorMessage: StaticString = \"404 - NOT FOUND\"\nos_log(errorMessage)Due to the StaticString requirement, instead of using string interpolation we will need to use format arguments. This may feel jarring initially, however, it isn't too hard to adapt to and it provides benefits to user privacy that we will discuss a bit later on. We have access to all of the standard format arguments, as well as a number of extra value type decoders. The idea is that the logging system handles as much formatting for you as possible, to make the system even more efficient.
let responseCode = \"404 - NOT FOUND\"\nos_log(\"HTTP response: %@\", responseCode)\n\nlet logMessage = \"HTTP response: \\(responseCode)\"\nos_log(\"%@\", logMessage)\n\n// error: cannot convert value of type 'String'\n// to expected argument type 'StaticString'\nos_log(\"HTTP response: \\(responseCode)\")Calls to os_log can specify an OSLog to use, containing a specific subsystem and category. This information is invaluable when filtering, searching and trying to understand our logs later. When the log argument isn't specified a default one is used, which has no subsystem or category configured.
let uiLog = OSLog(subsystem: \"com.lordcodes.chat.ChatApp\", category: \"UI\")\nos_log(\"Contact selected\", log: uiLog)\n\nlet networkLog = OSLog(\n subsystem: \"com.lordcodes.chat.ChatKit\",\n category: \"Network\"\n)\nos_log(\"HTTP response: %@\", log: networkLog, responseCode)The subsystem groups all the logs for a particular app or module, allowing us to filter for all of our own logs. From evaluating Apple's logs, the convention for subsystem is a reverse domain style, such as the Bundle Identifier of the app or framework itself. If the app is modularised into frameworks, it is a good idea to use the Bundle Identifier of the framework to split logs into their corresponding components.
Categories are used to group logs into related areas, to help us narrow down the scope of log messages. The convention for categories is to use human-readable names like UI or User. We could group logs into layers across multiple subsystems or features, such as Network or Contacts. Alternatively, we could group all the logs for a particular class, such as Contacts Repository. It would be perfectly acceptable to combine both approaches in the same project, we should simply use the most appropriate categories to allow us to understand the context of the project's log messages.
We can add our different categories and subsystems as an extension of OSLog, making them easily accessible across the app. Storing them in one place avoids creating OSLog instances all over the codebase and helps keep the different categories in use nicely organised.
extension OSLog {\n private static var subsystem = Bundle.main.bundleIdentifier!\n\n static let ui = OSLog(subsystem: subsystem, category: \"UI\")\n static let network = OSLog(subsystem: subsystem, category: \"Network\")\n}\n\nos_log(\"Contact selected\", log: .ui)\nos_log(\"HTTP response: %@\", log: .network, responseCode)The unified logging system employs a set of different logging levels at which we can target different types of messages. The levels control how messages are displayed to us, how and when they are persisted and whether they are captured in different environments. How the system handles each level can even be customised through the command-line on our machine. It is a good idea to use the most appropriate logging level for each message, to get the most we can out of the logging system.
Default: To capture anything that might result in a failure and essentially a fall-back if no other level seems appropriate. Unless changed, messages are stored in memory buffers and persisted when they fill up.
Info: To capture anything that may be useful, but is not directly used to diagnose or troubleshoot errors. Unless changed, no persistence is used, messages are just stored in memory buffers and purged as they fill up.
Debug: To capture information during development to diagnose a particular issue, whilst actively debugging. They aren't captured unless enabled by a configuration change.
Error: To capture application errors and failures, in particular anything critical. Messages are always persisted, to ensure they are no lost.
Fault: To capture system-level or multi-process errors only, likely not of use in our app code. As with the error level, messages are always persisted.
Logging at each level is as simple as specifying the corresponding OSLogType as an argument to the os_log call.
os_log(\"Contact selected\", log: .ui, type: .info)\nos_log(\"Saving contact failed\", log: .database, type: .error)To ensure private user data is not accidentally persisted to application logs, which may be shared with other people, the unified logging system has a public and private argument process. By default, only scalar (boolean, integer) values are collected and dynamic strings or complex dynamic objects are redacted. If it is necessary, dynamic string arguments may be declared public and scalar arguments could also be declared private.
os_log(\"Contact %ld selected\", 2)\nos_log(\"Contact %{private}ld selected\", 2)\n\nos_log(\"HTTP response: %@\", responseCode)\nos_log(\"HTTP response: %{public}@\", responseCode)It is important we resist making all arguments public, as it could easily result in private company or user data being exposed within device logs.
Whilst the debugger is attached, log messages will be shown in the Xcode console. The best way to read our logs, however, is with the Console MacOS application. Here we will be able to sort, filter and search our logs, as well as view them more easily.
Unified logging is a promising and powerful logging solution, especially when it comes to performance and filtering your log messages. Initially it might seem like it has quirks or differences to what you may be used to from NSLog and print. After looking a bit more and providing os_log with subsystems, categories and making good use of logging levels, you will find it makes working with logs significantly easier. If you want more log coverage with better performance, you can ditch NSLog and print statements and start integrating os_log into your apps.
", "date_published": "2019-01-14T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/simpler-categories-when-using-oslog/", "url": "https://www.lordcodes.com/articles/simpler-categories-when-using-oslog/", "title": "Simpler categories when using OSLog", "content_html": "OSLog is Apple's current recommended logging approach
Organised logging in Swift that can be searched is simple thanks to the built-in os_log. By storing our categories as an extension on OSLog we can access them using a short syntax.
This makes categories so much easier to specify and helps with auto-completion!
extension OSLog {\n static let logAuthentication = OSLog(\n subsystem: \"com.myapp.App\",\n category: \"Auth\"\n )\n static let logDatabase = OSLog(\n subsystem: \"com.myapp.App\",\n category: \"Database\"\n )\n static let logNetwork = OSLog(\n subsystem: \"com.myapp.App\",\n category: \"Network\"\n )\n}\n\nos_log(\"User signed in: %@\", log: .logAuthentication, type: .default, email)\nos_log(\"Chat messages sync complete\", log: .logNetwork, type: .info)\nos_log(\"Chat messages saved successfully\", log: .logDatabase, type: .debug)Something all Xcode users will be familiar with is the process of creating new files. When the new file command is triggered, we are presented with a window containing a selection of templates to base our new file upon. These new templates often contain lines of code we immediately delete or code that needs to be changed to fit into our preferred style.
Many people may be unaware that instead of relying solely on the provided templates, we can create our own and have Xcode present them to us. This can simplify the process of creating new files and allow them to match more specific requirements.
The process of creating templates can seem a bit confusing at first, but the end result can be really useful. We are going to explore the process of writing our own Xcode file templates, before delving into how we might go about sharing these with other developers on a particular project.
When Xcode launches, it looks for file templates within a specific location: ~/Library/Developer/Xcode/Templates/File Templates. To get started, we need to create a directory within here that will house all of our file templates.
mkdir -p ~/Library/Developer/Xcode/Templates/File\\ Templates/CustomWithin this directory, a quick way to get started is by copying one of the built-in templates and then altering it. They can be found within the Xcode application bundle, with a good option for Swift-based templates being the one for a new Swift file, Source/Swift File.xctemplate.
/Applications/Xcode.app/Contents/\n > Developer/\n > Library/\n > Xcode/\n > Templates/\n > File Templates/After copying the files, we find the xctemplate contains 4 different files.
TemplateIcon.png and TemplateIcon@2x.png are the thumbnails that are presented within the new file window. We could use these for all of our Swift templates or create specific ones of our own.TemplateInfo.plist is where we configure our template.___FILEBASENAME___.swift contains the Swift source that forms the basis of the template.We will start by creating a template for a new Swift struct, called Swift Struct.xctemplate, that is based upon the Swift File.xctemplate mentioned above.
→ TemplateInfo.plist
Within the property file we can change the Description and Summary keys to clearly describe the template within Xcode.
<key>Description</key>\n<string>A Swift struct.</string>\n<key>Summary</key>\n<string>A Swift struct.</string>→ ___FILEBASENAME___.swift
By calling the file ___FILEBASENAME___.swift, the resulting Swift file will be named according to what is entered into the new file window. This same argument can be used within the template using ___FILEBASENAMEASIDENTIFIER___. This means that if we enter Contact into the new file window, the generated file will be Contact.swift, containing the struct Contact.
struct ___FILEBASENAMEASIDENTIFIER___ {\n}Once completing the template, starting up Xcode and requesting a new file, we can find our template being offered within a section called 'Custom'. The name of the section is controlled by the directory name we used within ~/Library/Developer/Xcode/Templates/File Templates.
![\"Xcode](\"https://www.lordcodes.com/img/yi8z7Ti_rI-1470.webp "\\"Our")
Although they can start very basic, there are some more significant things we can do with templates.
UsersRepositoryTests if UsersRepository is entered.Some example file templates can be found on GitHub, demonstrating some of the options available.
As we explore the possibilities that file templates provide us, one problem becomes extremely clear. It would be really great if we could create project-specific templates and share them with the other developers on the project. Although templates for a specific project are not supported automatically by Xcode, it can be done through a clever use of symbolic links.
We should place all templates in a directory within our project, such as FileTemplates. It is likely the project is kept in source control, which will ensure the templates are tracked and shared with everyone else in the team.
The directory Xcode expects to find our templates should already exist if the steps were followed above. If not then we need to ensure it does.
mkdir -p ~/Library/Developer/Xcode/Templates/File\\ TemplatesOnce the directory exists, the symbolic link can be created here that points to the templates within our Xcode project. It is worth mentioning that if we delete the project or move it, the symbolic link can simply be deleted and recreated.
ln -s [Project Location]/FileTemplates \\\n ~/Library/Developer/Xcode/Templates/File\\ Templates/[ProjectName]For example:
ln -s ~/projects/github/chatapp/FileTemplates \\\n ~/Library/Developer/Xcode/Templates/File\\ Templates/ChatAppAfter restarting Xcode, any project templates will now be presented within the 'New File' window. It would obviously be great if Xcode could offer a solution without the extra work, however, for now it works nicely.
Xcode file templates can be a great way to get started quickly when creating new files. They are very powerful, although quite under-documented and there is much more they can do than discussed here.
", "date_published": "2018-12-14T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/map-dictionary-keys-to-different-type/", "url": "https://www.lordcodes.com/articles/map-dictionary-keys-to-different-type/", "title": "Map the keys of a dictionary to a different type", "content_html": "The Swift standard library includes functions to transform the values of a Dictionary, we need to add one ourselves to do the same to the keys.
There are situations this can come in handy such as converting a Dictionary of analytics event parameters from using an internal enum for the keys to using Strings for reporting to our analytics API.
This neat little extension will allow us to do just that!
extension Dictionary {\n func mapKeys<NewKeyT>(\n _ transform: (Key) throws -> NewKeyT\n ) rethrows -> [NewKeyT: Value] {\n var newDictionary = [NewKeyT: Value]()\n try forEach { key, value in\n let newKey = try transform(key)\n newDictionary[newKey] = value\n }\n return newDictionary\n }\n}Swift extensions are really great, including when working with Auto Layout. We can make a child view fill its superview using constraints, as well as having insets between them. This is very useful when adding a child view controller to its parent within a subview.
extension UIView {\n func attachAnchors(to view: UIView, with insets: UIEdgeInsets = .zero) {\n NSLayoutConstraint.activate([\n topAnchor.constraint(\n equalTo: view.topAnchor,\n constant: insets.top\n ),\n rightAnchor.constraint(\n equalTo: view.rightAnchor,\n constant: -insets.right\n ),\n bottomAnchor.constraint(\n equalTo: view.bottomAnchor,\n constant: -insets.bottom\n ),\n leftAnchor.constraint(\n equalTo: view.leftAnchor,\n constant: insets.left\n )\n ])\n }\n}When animating the addition of cells to a UICollectionView, we may notice that text and background colours aren't animating when using UIView.animate. Using UIView.transition instead works perfectly!
UIView.transition(with: commentContainer, duration: 0.6,\n options: .transitionCrossDissolve, animations: {\n commentContainer.backgroundColor = UIColor(red: 17, green: 215, blue: 198)\n})\n\nUIView.transition(with: commentLabel, duration: 0.6,\n options: .transitionCrossDissolve, animations: {\n commentLabel.textColor = UIColor(red: 143, green: 155, blue: 174)\n})In Swift, many APIs take a TimeInterval instead of just a Double, you need to know they are in seconds. Instead we can add functions that provide them with explicit units and allow us to convert them. It makes for a really readable call site!
extension TimeInterval {\n // Hide the calculations from the call site\n private static var secondsPerHour: Double { return 60 * 60 }\n private static var secondsPerMinute: Double { return 60 }\n\n // Functions to provide time intervals with explicit units\n static func hours(_ value: Double) -> TimeInterval {\n value * secondsPerHour\n }\n\n static func minutes(_ value: Double) -> TimeInterval {\n value * secondsPerMinute\n }\n\n static func seconds(_ value: Double) -> TimeInterval {\n value\n }\n}\n\n// They make very readable call sites\nTimeInterval.hours(3)\nTimeInterval.minutes(46)\nTimeInterval.seconds(35)JUnit 4 has always been the standard unit testing framework for Android development, however, a production version of JUnit 5 has been available for quite a while. JUnit 5 is the next generation of JUnit testing and has quite a new structure. From a user-perspective it offers a number of useful new features and various other benefits. Often Android developers are used to waiting a while for new things from the Java-world to be an option on Android. In the case of JUnit 5, with some changes to your Gradle dependencies, you can use it right now from your Java and Kotlin unit tests.
![\"JUnit](\"https://www.lordcodes.com/img/FalfGKh-ji-700.webp "\\"Testing")
The architecture of JUnit 5 is quite a significant change from before, with the framework being split into three major components.
As users of the testing framework, it's likely that the most interesting part is the new features we get access to. Nested tests allow us to put our tests into groups, increasing readability and allowing us to reduce repetition within test names. Parameterised tests are really powerful and can also reduce duplicating tests to give different inputs, the parameters can even be provided through a variety of mechanisms. Dynamic tests offer an API to generate tests on the fly using a test factory, rather than hard-coding each of the tests.
Parameterised tests run tests with different inputs
The JUnit 5 extension model allows us to extend the test framework and is the evolution of concepts from JUnit 4 such as @Rule and custom runners. The extension model will allow JUnit 5 to evolve with all developers and tool makers having the same public extension API. There are many more features beyond those listed here, all of which can be found in the user guide.
Now, let's get JUnit 5 running in our Android project.
Thanks to Marcel Schnelle (mannodermaus) there is an easy-to-use Gradle plugin that will configure all the testing tasks to use JUnit 5. The plugin has a few minimum requirements that our project needs to meet, at the time of writing this is the Android Gradle plugin 3.2.0+, Gradle 4.7+ and Java 8+.
We will start by adding the plugin to our root build.gradle file using the latest version, which at time of writing is 1.3.2.0.
→ /build.gradle
buildscript {\n dependencies {\n classpath \"de.mannodermaus.gradle.plugins:android-junit5:1.3.2.0\"\n }\n}After a successful Gradle sync, we will be ready to apply the plugin to any Android modules we wish to use JUnit 5 in.
→ /app/build.gradle
apply plugin: 'de.mannodermaus.android-junit5'\n\ndependencies {\n testImplementation \"org.junit.jupiter:junit-jupiter-api:5.3.2\"\n testRuntimeOnly \"org.junit.jupiter:junit-jupiter-engine:5.3.2\"\n testImplementation \"org.junit.jupiter:junit-jupiter-params:5.3.2\"\n}If there are JUnit 4 tests in the project we are configuring, then we will also need to keep the JUnit 4 dependency and enable the JUnit vintage test engine mentioned above.
testImplementation \"junit:junit:4.12\"\ntestRuntimeOnly \"org.junit.vintage:junit-vintage-engine:5.3.2\"Once the plugin and the Gradle dependencies have been configured, we can run tests in the same way as we were previously using the same Gradle tasks and run configurations in Android Studio.
If we need them, there are some options for configuring the test environment within Gradle. Our settings go in a junitPlatform block within the existing testOptions, where we may already be doing some configuration. The most common use-case would be for filtering which tests are executed. We could use the filters to divide our tests into unit and integration and then have them run for different variants, as an example.
android {\n testOptions {\n junitPlatform {\n filters {\n includePattern \"^(tests_to_include_regex)$\"\n excludePattern \"^(tests_to_exclude_regex)$\"\n\n includeTags \"slow\"\n excludeTags \"integration\"\n }\n debugFilters {\n includeTags \"integration\"\n }\n }\n }\n}For any more information on the plugin, all the setup and usage instructions can be found on GitHub.
If our unit tests are only going to be ran on the JVM, no Robolectric or Android required, then we can get away without the Gradle plugin. To do this we can remove the plugin classpath entry from the root build.gradle and the line where the plugin is applied within the app module build.gradle. Instead we need to add some configuration to testOptions to enable running with JUnit 5.
→ /app/build.gradle
android {\n testOptions {\n unitTests.all {\n useJUnitPlatform()\n }\n }\n}We lose the per-variant filters that were demonstrated above if we go down this route. However, for most Android projects that aren't using Robolectric this should definitely be sufficient.
Let's write some tests to explore the new features of JUnit 5 and how we should go about using it in our apps. We will be using AssertJ for our assertions, mainly for readability within the samples. We will be testing a very simple repository that allows us to look up contacts using their IDs, starting with the JUnit 4 version.
import org.assertj.core.api.Assertions.assertThat\nimport org.junit.Test\n\nclass ContactsRepositoryTest {\n private val repository = ContactsRepository()\n\n @Test\n fun findContact_givenExistingId() {\n val id = 2\n val expectedContact = Contact(id, \"Melanie\")\n\n val actualContact = repository.findContact(id)\n\n assertThat(actualContact)\n .isEqualTo(expectedContact)\n }\n}Converting this test to JUnit 5 is as simple as changing the import for @Test. Projects with many more tests, using more features of JUnit 4, may have more changes that are required. As mentioned above, we can start new tests in JUnit 5 and then either leave the JUnit 4 ones as is, or convert them gradually.
// Before\nimport org.junit.Test\n\n// After\nimport org.junit.jupiter.api.TestA common structure for tests is breaking them into given, when and then.
This structure is fairly clear within the body of the test function, however, in the naming of the function some issues may start to arise.
@Test\nfun givenContactsLoadedAndIdMatches_whenFindContact_thenContactReturned()\n\n@Test\nfun givenContactsNotLoadedAndIdMatches_whenFindContact_thenNoContactReturned()Some approaches could be taken to reduce the length, such as using shorter wording in the given clauses and potentially removing the then clause from the name. This does result in losing some detail, which can be really useful in test names to quickly see in the test report what is going on and to demonstrate what a test is supposed to do. It is also much easier to read a descriptive sentence than the camel-case seen in function names.
JUnit 5 introduces the @DisplayName annotation, which can be used to provide a descriptive name for the test report. The same result can be achieved in Kotlin through the use of back-ticks around the function name. The advantage of the @DisplayName approach is that we keep the searchable and familiar function name, whereas the back-tick approach avoids the need to maintain both the function name and annotation.
@Test\n@DisplayName(\n \"Given contacts are loaded but the ID is invalid, When we find a contact, Then no contact is returned.\"\n)\nfun findContact_givenExistingId()\n\n@Test\nfun `Given contacts are loaded but ID invalid, When we find a contact, Then no contact returned`()A common reason for test names growing in length is having multiple tests with the same starting condition. Beyond naming, a similar starting condition can cause test bodies to grow in length as well! To solve the issue, JUnit 5 introduces @Nested, allowing you to group a set of tests into an inner class. The group can have a shared starting state and can also have a display name specified, reducing the length of individual test function names. The nested structure is shown within the test report, making it very readable.
@Nested\n@DisplayName(\"Given valid contact ID\")\ninner class ValidContactId {\n private val id = 2\n\n @Test\n @DisplayName(\"When find contact, then correct contact returned\")\n fun findContact_givenExistingId() {\n val expectedContact = Contact(id, \"Melanie\")\n\n val actualContact = repository.findContact(id)\n\n assertThat(actualContact)\n .isEqualTo(expectedContact)\n }\n\n ...\n}After fleshing out the tests for this repository more, with a few tests in each group, we can peek at the test report to see how it all looks. 👀
![\"Android](\"https://www.lordcodes.com/img/wpj62nUvka-1024.webp "\\"Android")
The code we have written is available on GitHub.
We have been discussing unit tests only and as we all know instrumentation tests, usually using Espresso, are also very important. Currently, our Espresso tests will be using JUnit 4, which can be left as it was previously. This means using the JUnit 4 test runner, as opposed to adding the JUnit 5 vintage engine and using the new infrastructure.
Instrumentation tests using the JUnit 5 Gradle plugin are still considered experimental
The Gradle plugin we used to introduce JUnit 5 on Android has support for instrumentation tests, which at the time of writing is considered experimental. From checking the GitHub issues page for the plugin, many people have had problems using JUnit 5 for their instrumentation test suite. When the situation changes this article will be updated with the current details of using it.
Since JUnit 5 is built upon Java 8, to use it we need a minSdkVersion of 26 or above. Before we start freaking out, this can be achieved by running the tests with a product flavour that has the minimum SDK increased to this level.
To write and run our instrumentation tests using the JUnit 5 framework, we will need some Gradle configuration. A little bit more is required than for unit tests, due to needing to tell the system to to use the plugin's runner builder and ensuring tests running on the device work correctly.
→ /app/build.gradle
android {\n defaultConfig {\n testInstrumentationRunner \"android.support.test.runner.AndroidJUnitRunner\"\n testInstrumentationRunnerArgument \"runnerBuilder\", \"de.mannodermaus.junit5.AndroidJUnit5Builder\"\n }\n}\n\ndependencies {\n androidTestImplementation \"org.junit.jupiter:junit-jupiter-api:5.3.2\"\n androidTestImplementation \"de.mannodermaus.junit5:android-instrumentation-test:0.2.2\"\n\n androidTestRuntimeOnly \"org.junit.jupiter:junit-jupiter-engine:5.3.2\"\n androidTestRuntimeOnly \"org.junit.platform:junit-platform-runner:1.3.2\"\n androidTestRuntimeOnly \"de.mannodermaus.junit5:android-instrumentation-test-runner:0.2.2\"\n}It is noteworthy that instrumentation tests tend to have less need for JUnit 5, due to there being less tests and fewer variants of similar tests, in general. This will of course depend heavily from project to project though! To find out more, please check out the plugin's GitHub page.
We have only considered a few small aspects of writing JUnit 5 tests, as there is simply so much to look at. To find out more, there is a detailed user guide covering all parts of the framework and how to go about writing tests and customising the test process.
By using JUnit 5 in our Android app testing we are using the latest evolution of the JUnit framework. It gives us access to more features, helps us make tests as readable as possible, reduce duplication within our tests and extending the test framework has never been easier. Hopefully it will catch on more in the Android community and become the "standard" for Android development sooner rather than later.
", "date_published": "2018-11-30T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/a-modular-analytics-layer-in-swift/", "url": "https://www.lordcodes.com/articles/a-modular-analytics-layer-in-swift/", "title": "A modular analytics layer in Swift", "content_html": "There is a saying, "if a tree falls in a forest and no one is around to hear it, does it make a sound?" Monitoring user behaviour is a bit like that; if people are using your app in a particular way, but you don't know about it, then how can you work out how to improve it.
There are many different options available to us in order to monitor user behaviour, such as user testing, collecting surveys and analytics. Here we are going to be discussing the topic of analytics, specifically using it within a Swift app.
When building and improving your apps, knowing how it is being used by real users in the wild can be very valuable. It allows you to make data-informed decisions rather than just estimating what you think is a good idea. You can also use it to verify and test out ideas once they have been released to your users.
Whilst adding analytics to an app can be quick and easy, ensuring the implementation is easy to use, alter and extend can be more complex. The implementation should be able to stand the test of time and give us the flexibility to make changes to the analytics data we are reporting in the future. We are going to look through one way of building an analytics layer in Swift, that is both modular and extensible.
When analytics data is captured within our apps, we would normally want to submit this to our preferred backend. This allows data to be collected over time and analysis to be ran over the data.
It is very common for this backend to be a third-party SDK such as: Firebase Analytics or MixPanel. You may also want to use a tool such as Segment, to control where the data is sent and have the flexibility to change the destination whenever you want.
Your backend may be an in-house analytics system, reporting data to your own backend API or pumping data into a data warehouse of some kind. This can be beneficial if your data is specialised or you need to do something with it that the third-party destinations don't support.
Whichever backend solution has been settled on, it is good to wrap its API in one of your own, to avoid the codebase being littered with a specific analytics API. Doing this will give you the flexibility to change the solution more easily and help make your code more maintainable.
We are going to build a layer that avoids using a static API, puts any backend APIs behind a protocol, uses the power of Swift enums and pairs each event with the pieces of data it needs to contain.
More specifically it should:
There are a few different components that make up our analytics layer, each covering part of the process.
The events themselves can be modelled through our AnalyticsEvent enum.
enum AnalyticsEvent: Equatable {\n case addContactTapped\n case contactSelected(index: Int)\n case messageSent(threadType: ThreadType, length: Int)\n case userSignedIn\n}The enum contains a case for each event we want to fire, with associated values for any pieces of data that need to be attached to the event. When we report an event, we are required to provide any data it needs. By writing events in this way we can reduce the amount of code required to report an event, whilst checking for correctness at compile time.
When the event is passed further it provides the set of parameters that are attached to it. These parameters use an enum for their names, to allow them to be mapped differently later on, similar to the events themselves.
extension AnalyticsEvent {\n var parameters: [Parameter: String] {\n switch self {\n case .addContactTapped,\n .userSignedIn:\n return [:]\n case let .case contactSelected(index):\n return [\n .contactIndex: String(describing: index)\n ]\n case let .messageSent(threadType, length):\n return [\n .threadType: threadType.rawValue,\n .messageLength: String(describing: length)\n ]\n }\n }\n\n enum Parameter: String, Equatable {\n case contactIndex\n case messageLength\n case threadType\n }\n}For writing the switch statement over the AnalyticsEvent enum it is best to avoid using a default case, as this enforces that each new event is handled.
Each backend you wish to report data to will conform to our AnalyticsProvider protocol. This will document the different analytics operations we can perform.
protocol AnalyticsProvider {\n func report(event: AnalyticsEvent)\n}The report(event:) function is taking our event enum as an argument. This allows each provider to map the event to whichever format they need it in. For example, Firebase Analytics requires events to contain underscores (_) instead of hyphens (-). Once the event has been mapped, it would then be reported to the destination for that particular provider, often calling through to the provider's SDK.
A final solution may also report screens, user properties, preferences and more. These would be added to the AnalyticsProvider protocol.
Making our backend conform to the provider protocol is relatively simple, let's start by building one for Firebase Analytics. The event name and parameters are mapped to strings, before being passed through to the Firebase Analytics SDK logEvent function.
class FirebaseAnalyticsProvider: AnalyticsProvider {\n private let eventMapper = AnalyticsEventMapper()\n\n func report(event: AnalyticsEvent) {\n let name = eventMapper.eventName(for: event)\n let parameters = eventMapper.parameters(for: event)\n Analytics.logEvent(name, parameters: parameters)\n }\n}The flexibility of the solution means we can easily build another provider to log events to the console.
class LoggingAnalyticsProvider: AnalyticsProvider {\n private let eventMapper = AnalyticsEventMapper()\n\n func report(event: AnalyticsEvent) {\n let name = eventMapper.eventName(for: event)\n print(\"Event reported: \\(name)\")\n }\n}We can create a provider for whichever destination we wish to use.
Each provider needs to convert the event enum into a reporting format. Most analytics SDKs require events in a string format and so it an be a good idea to provide a default mapper that does this.
If a particular app doesn't need the flexibility for each provider to control the mapping, we can instead return data in the correct format directly within the AnalyticsEvent.
For now we will give ourselves full flexibility, by using a separate mapper.
class AnalyticsEventMapper {\n func eventName(for event: AnalyticsEvent) -> String {\n ...\n }\n\n func parameters(for event: AnalyticsEvent) -> [String: String] {\n ...\n }\n}The first part to the mapping process is to get a name for the event. This is as simple as using a switch statement to map each event case to a String.
func eventName(for event: AnalyticsEvent) -> String {\n switch event {\n case .addContactTapped:\n return \"addContact_tapped\"\n case .contactSelected:\n return \"contact_selected\"\n case .messageSent:\n return \"message_sent\"\n case .userSignedIn:\n return \"user_signedIn\"\n }\n}The second part is getting a dictionary of event parameters.
func parameters(for event: AnalyticsEvent) -> [String: String] {\n var newParameters = [String: String]()\n event.parameters.forEach { key, value in\n let newKey = parameterName(for: key)\n newParameters[newKey] = value\n }\n return newParameters\n}\n\nfunc parameterName(for parameter: AnalyticsEvent.Parameter) -> String {\n switch parameter {\n case .contactIndex:\n return \"contact_index\"\n case .messageLength:\n return \"message_length\"\n case .threadType:\n return \"thread_type\"\n }\n}The parameters(for:) function is simply converting the dictionary keys from an enum to a String. If used in multiple places, it can be easily extracted to a generic extension on Dictionary.
We now need to bring together all of the components we have built and create the API for our analytics layer, the AnalyticsReporter. The reporter is the dependency you will be injecting and using throughout your app to report events.
class AnalyticsReporter {\n private let providers: [AnalyticsProvider]\n\n init(providers: [AnalyticsProvider]) {\n self.providers = providers\n }\n\n func report(event: AnalyticsEvent) {\n providers.forEach {\n $0.report(event: event)\n }\n }\n}This reporter allows multiple analytics providers to be used, obviously if an app only required a single provider we could decide whether this was worth supporting or not. Due to each analytics backend being wrapped with our provider, the reporter is pretty simple.
As with the provider, a final solution may also include reporting of other entities such as screens and user properties.
We can now put our implementation into practice to see how it is to use.
class ContactsViewModel {\n private let coordinator: ContactsCoordinator\n private let analyticsReporter: AnalyticsReporter\n\n init(coordinator: ContactsCoordinator, analyticsReporter: AnalyticsReporter) {\n self.coordinator = coordinator\n self.analyticsReporter = analyticsReporter\n }\n\n func contactSelected(at index: Int) {\n analyticsReporter.report(event: .contactSelected(index: index))\n coordinator.startContactThreads(at: index)\n }\n\n func addContactTapped() {\n analyticsReporter.report(event: .addContactTapped)\n coordinator.startContactCreation()\n }\n}The AnalyticsReporter can be injected wherever we wish to use it, in the case above in a ContactsViewModel. Using the API is as simple as selecting the correct event and providing any values it requires.
If we need to report a new event, we just need to add it to the AnalyticsEvent enum, provide its parameters and update any mapping code. ⚒
It is very important that our analytics code be testable and that it doesn't make any other code more difficult to test. To verify the correct events have been reported, we can create a TestingAnalyticsProvider within our unit test sources. The test provider stores reported events so that they can be asserted on afterwards.
class TestingAnalyticsProvider: AnalyticsProvider {\n var eventsReported = [AnalyticsEvent]()\n\n func report(event: AnalyticsEvent) {\n eventsReported.append(event)\n }\n}That wraps up implementing, using and testing our new analytics layer. In general the approach we have put forward is flexible and can be altered where necessary to suit a particular app's needs.
We have seen that:
Enabling Java 8 compatibility via the compileOptions block only works for Java sources. To do the same for Kotlin you need to use kotlinOptions on any KotlinCompile Gradle tasks. Interesting…
For Kotlin
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {\n kotlinOptions {\n jvmTarget = JavaVersion.VERSION_1_8\n }\n}For Java
android {\n compileOptions {\n sourceCompatibility JavaVersion.VERSION_1_8\n targetCompatibility JavaVersion.VERSION_1_8\n }\n}Using Kotlin to maintain our Gradle dependencies within the buildSrc directory can be really great.
Sweet!
→ /buildSrc/src/main/java/com/myapp/Versions.kt
package com.myapp\n\nobject Versions {\n object AndroidX {\n const val appCompat = \"1.0.2\"\n }\n const val kotlin = \"1.3.10\"\n ...\n}→ /buildSrc/src/main/java/com/myapp/Libs.kt
package com.myapp\n\nobject Libs {\n object AndroidX {\n const val appCompat = \"androidx.appcompat:appcompat:${Versions.AndroidX.appCompat}\"\n }\n const val kotlinStdlib = \"org.jetbrains.kotlin:kotlin-stdlib:${Versions.kotlin}\"\n}→ /src/app/build.gradle
import com.myapp.Libs\n\ndependencies {\n implementation Libs.kotlinStdlib\n implementation Libs.AndroidX.appCompat\n}Being able to specify default parameter values in Swift allows us to reduce the number of function overloads in our code. For protocols it is still possible as long as we use an extension and delegate to the version without the default values.
protocol ErrorController {\n func showError(_ error: String, delegate: ErrorViewControllerDelegate?)\n}\n\nextension ErrorController {\n func showError(_ error: String, delegate: ErrorViewControllerDelegate? = nil) {\n showError(error, delegate: delegate)\n }\n}\n\nclass ContactsViewController: UIViewController, ErrorController {\n func showError(_ error: String, delegate: ErrorViewControllerDelegate?) {\n print(error)\n }\n}\n\nlet contacts: ErrorController = ContactsViewController()\ncontacts.showError(\"I don't need a delegate.\")Accessing information about the call site of a function is surprisingly simple in Swift by simply using #file, #function and #line. This can be a great help when we want to put assertions within a shared function or print text without losing the original context.
extension XCTestCase {\n struct UnexpectedNilError: Error {}\n\n func unwrapAssert<ValueT>(_ value: ValueT?,\n message: String = \"Unexpected nil\",\n file: StaticString = #file,\n line: UInt = #line) throws -> ValueT {\n guard let value = value else {\n XCTFail(message, file: file, line: line)\n throw UnexpectedNilError()\n }\n return value\n }\n}We can make some great things with extensions in Swift, as well as subscript functions. This one allows us to safely access collection elements by index, getting back an optional instead of errors being thrown!
extension Collection {\n subscript(safe index: Index) -> Element? {\n indices.contains(index) ? self[index] : nil\n }\n}\n\nlet numbers = [1, 2, 3, 4]\nnumbers[safe: 3] // 4\nnumbers[safe: 10] // nil, no errorWhen defining the dependencies for a Gradle project, such as an Android app, there are situations that call for duplicated information. A common case is that libraries or plugins can often come with multiple dependencies, which are usually released together with matching versions. Maintaining these dependencies requires the version to be duplicated and then kept up-to-date as new versions are released.
Another case is that it is common to have a multi-module project, where we may want a dependency to be added to multiple modules. Similarly to the case with versions, the dependency definition would be duplicated for each module and then kept in-sync moving forward.
It is clear that in both cases we may want to define the dependencies in one place and then access this location from wherever the dependency definition is needed.
There is a mechanism for sharing your dependency configuration using Groovy, by adding some extra properties in our root build.gradle file, similar to below.
→ /build.gradle
buildscript {\n ext.versions [\n 'kotlin': '1.3.10',\n 'dagger': '2.19'\n ]\n\n ext.deps [\n 'kotlin': [\n 'stdlib': \"org.jetbrains.kotlin:kotlin-stdlib:${versions.kotlin}\",\n 'test': \"org.jetbrains.kotlin:kotlin-test-common:${versions.kotlin}\"\n ],\n 'dagger': [\n 'runtime': \"com.google.dagger:dagger:${versions.dagger}\",\n 'compiler': \"com.google.dagger:dagger-compiler:${versions.dagger}\",\n 'androidRuntime': \"com.google.dagger:dagger-android:${versions.dagger}\",\n 'androidCompiler': \"com.google.dagger:dagger-android-processor:${versions.dagger}\",\n ]\n ]\n}→ /app/build.gradle
dependencies {\n implementation deps.kotlin.stdlib\n\n implementation deps.dagger.runtime\n implementation deps.dagger.androidRuntime\n kapt deps.dagger.compiler\n kapt deps.dagger.androidCompiler\n\n testImplementation deps.kotlin.test\n}Sharing the configuration via the root build.gradle achieves the goal of having a single location to maintain. Only needing to update dependency versions in a single file is a great time-saver as well. Unfortunately from practice, when using the Groovy Gradle DSL auto-complete is often missing or incomplete in this situation, making it awkward to use.
On top of this, Gradle 5.0 is now available which includes the production-ready Kotlin Gradle DSL. When we convert the above solution to Kotlin it isn't as nice to use in Kotlin as it is in Groovy. The map syntax can be achieved using mapOf, but reading the data to pass to implementation requires some casting to fit with the statically typed language.
As many developers have found with their main app source code, Kotlin can help with defining our dependency configurations as well, from both Groovy and Kotlin Gradle scripts.
![\"Kotlin](\"https://www.lordcodes.com/img/yxUelyoALR-1400.webp "\\"Kotlin")
When ran, Gradle will check for a buildSrc directory in the root of the project, placing any code that is found into the classpath of our build. This is really handy and allows us to put Kotlin code into buildSrc and then reference it from our Gradle scripts. To get started we just need a little bit of structure.
→ /buildSrc/build.gradle.kts
plugins {\n `kotlin-dsl`\n}\nThe Kotlin DSL plugin needs to be specified for buildSrc.
→ /buildSrc/src/main/kotlin/Versions.kt
Our source files need to be placed within the standard sources directory structure. To use inner objects, for now we need to include the sources within a package, e.g. 'com.ourapp'.
object Versions {\n const val dagger = \"2.21\"\n const val ktlint = \"0.29.0\"\n const val kotlin = \"1.3.11\"\n}→ /buildSrc/src/main/kotlin/Dependencies.kt
object Plugins {\n const val kotlin = \"org.jetbrains.kotlin:kotlin-gradle-plugin:${Versions.kotlin}\"\n const val ktlint = \"com.github.shyiko:ktlint:${Versions.ktlint}\"\n}\n\nobject Libs {\n const val kotlinStdlib = \"org.jetbrains.kotlin:kotlin-stdlib:${Versions.kotlin}\"\n\n const val daggerRuntime = \"com.google.dagger:dagger:${Versions.dagger}\"\n const val daggerCompiler = \"com.google.dagger:dagger-compiler:${Versions.dagger}\"\n const val daggerAndroidRuntime = \"com.google.dagger:dagger-android:${Versions.dagger}\"\n const val daggerAndroidCompiler = \"com.google.dagger:dagger-android-processor:${Versions.dagger}\"\n}Once Gradle has been synced, we can now reference our dependencies within our Gradle scripts. This is pretty much the same as we used with the Groovy extra properties solution above.
→ /app/build.gradle
dependencies {\n implementation Libs.kotlinStdlib\n\n implementation Libs.daggerRuntime\n implementation Libs.daggerAndroidRuntime\n kapt Libs.daggerCompiler\n kapt Libs.daggerAndroidCompiler\n\n ktlint Plugins.ktlint\n}Using buildSrc and Kotlin sources achieves the goal of having a single location to maintain and we can even reduce it to a single Kotlin source file if it makes sense to. The solution can be used in the same way from both Groovy and Kotlin Gradle DSL without being altered, which frees us up to change our Gradle scripts to Kotlin if we want to.
The best thing about defining dependencies in this way is that we get access to effective auto-complete and being able to click through to where a dependency is defined from our Gradle scripts, super useful.
A good tool to look into is Ben Manes' Gradle Versions Plugin, which will inform us of any dependencies with new versions. Once we have the latest versions, we can simply update them in Versions.kt.
Naturally, for the reasons given I prefer to use the buildSrc and Kotlin source approach in my Android projects. It is really nice to use with both Groovy Gradle scripts and those written using the Gradle Kotlin DSL.
Almost all iOS apps need private values, such as API keys, secrets and passwords. Some of these may need to be used in the source code, to setup third-party SDKs or backend APIs. Some secrets may be needed during the build process or to use developer tools, such as communicating with an Apple Developer account.
Simple approaches for including secrets into an app would include: putting values directly into the code, placing them into build scripts or keeping them in the Info.plist file. Unfortunately, these approaches mean the secrets are committed to source control and are visible to anyone with access to the the code. Furthermore, scripts and plist files added to the app bundle can be extracted from the compiled app.
We are going to look through some more secure ways of managing secrets within our iOS projects, in order to access them from code. It is worth noting that it is practically impossible to keep anything within an app 100% secret, as apps are "out in the wild" on users' devices. A good approach is to enforce a suitable level of protection for the situation, for example a banking app should probably have a higher level of security than a to-do list app.
It is important to keep secrets out of source control for both open and closed source projects for various reasons.
Git allows us to include a .gitignore file, where we can list files (or expressions) that should be kept out. If these files are required by our app, each developer just creates these files and adds any required values. We could include template versions of these files in Git or a guide for what is needed in documentation, including contact details for who to provide secrets if they are required.
As most iOS developers are aware, many iOS projects use Cocoapods as a dependency manager. Cocoapods includes a plugin system that allows its processes to be hooked into. One such plugin that can be used to manage your app secrets securely is cocoapods-keys.
Not only does cocoapods-keys keep the secrets out of the project sources, it holds them securely in your system keychain. When pods are installed or updated, the developer is asked for each key that has no value already stored. An Objective-C class is generated that contains obfuscated versions of keys and their values. As this class is built by running Cocoapods, the Pods/CocoaPodsKeys directory can be added to the .gitignore.
The plugin has many advantages:
Incorporating cocoapods-keys into our project is very simple and starts with including the plugin into our Podfile.
plugin 'cocoapods-keys', {\n :project => \"ChatApp\",\n :target => \"ChatApp\",\n :keys => [\n \"ChatAPIClientSecretProd\",\n \"ChatAPIClientSecretTest\",\n \"AnalyticsWriteKey\"\n ]\n}After we next run pod install, we will be asked to enter the value for each of our keys listed above. Once all keys are configured, the plugin will generate a source file that can be referenced in our code to read the keys.
import Keys\n\nlet keys = ChatAppKeys()\nAnalytics.setup(with: keys.analyticsWriteKey)For values like our backend API secret, where we may want it to be different for debug and release, we can include both keys and then read a different one at runtime. There are obviously many different ways of handling this, depending on the exact use case we have. Therefore, we aren't going to discuss all possible options here and will simply look at switching based on whether the app is built in the debug configuration.
var apiClientSecret {\n #if DEBUG\n return keys.chatApiClientSecretTest\n #else\n return keys.chatApiClientSecretProd\n #endif\n}If you are using Cocoapods in your project, I would recommend looking into cocoapods-keys over other options, due to it being a secure and easy-to-use way to solve the problem.
Many projects don't use Cocoapods or we may not want to use a plugin and so we can also consider implementing a solution ourselves. Secrets will be passed into the build process, where they will be made available as environment variables. We can then read these variables and use them to generate a source file that will give our code access to our secret values.
We can have different values for different environments
Xcode offers xcconfig files that can be linked to a particular build configuration in order to load in settings specified within them. An xcconfig file can be specified for each build configuration, allowing us to have different values for each environment. We may wish to point our app at our production API for release apps, but a test backend for debug apps.
Note that if a particular app doesn't need different values depending on the build configuration, we can use a shell script instead of the xcconfig files and source the file into our final build phase later on.
We start off by creating example versions of our xcconfig files. If we place these files within a directory such as BuildConfig it will keep them separate from other project files. It is recommended to include these files into the project, so that they appear within Xcode, but we should ensure they aren't added to any targets within the Target Membership area of the File Inspector.
→ debug.example.xccconfig
CHAT_API_CLIENT_SECRET = CHAT_API_CLIENT_SECRET_TEST\nANALYTICS_WRITE_KEY = ANALYTICS_WRITE_KEY→ release.example.xccconfig
CHAT_API_CLIENT_SECRET = CHAT_API_CLIENT_SECRET_PROD\nANALYTICS_WRITE_KEY = ANALYTICS_WRITE_KEYBy duplicating and renaming the example files we can easily create the real files that will be used by the project. As with the example files, we want these files in the project, but not attached to any targets.
→ debug.xccconfig
CHAT_API_CLIENT_SECRET = 123456789\nANALYTICS_WRITE_KEY = abcdefgh→ release.xccconfig
CHAT_API_CLIENT_SECRET = 987654321\nANALYTICS_WRITE_KEY = abcdefghTo avoid the real xcconfig files being added to source control, they should be listed in the .gitignore file. We can use a regular expression in the rule to catch the files for all configurations.
BuildConfig/*.example.xcconfig\nThe final step, is telling Xcode to use our xcconfig files, which is specified within the project file under Info → Configurations. Make sure to select an xcconfig for each build configuration and for the target you need.
When Xcode builds your project, the values in the xcconfig files are made available as environment variables. You could simply use these values in your Info.plist file if you wished with the form $(CHAT_API_CLIENT_SECRET). We have already discussed that putting secrets into plist files isn't very secure, but have mentioned it for completeness.
We are going to generate a source file using a tool called Sourcery and then reference this source file in our code to access our secrets. Needless to say, we will need to start by adding Sourcery to our project, for example including a standalone version within our repository or using Cocoapods.
Sourcery uses a template system, where we create a stencil file to show the tool how to generate our code. We will create AppSecrets.stencil including some syntax to substitute in the secret values when the file is generated from the template.
struct AppSecrets {\n static let chatApiClientSecret=\"{{ argument.chatApiClientSecret }}\"\n static let analyticsWriteKey=\"{{ argument.analyticsWriteKey }}\"\n}We next need to add a build phase to our project by selecting the project file, then selecting the correct target and going to the Build Phases tab.
Tools/Sourcery/bin/sourcery\n --sources Sources\n --templates Templates/AppSecrets.stencil\n --output Generated\n --args chatApiClientSecret=\\\"$CHAT_API_CLIENT_SECRET\\\",\n analyticsWriteKey=\\\"$ANALYTICS_WRITE_KEY\\\"mkdir -p Generated at the start of the build phase.arg1=one,arg2=two. It is a good idea to escape as above incase the secret values contain any special characters.We can use a more complex script instead of manually specifying secrets within the build phase. This can be beneficial if there are more than a couple of secrets or the build phase is hard to maintain.
After adding the build phase, we can build the app as normal and then add the generated AppSecrets.swift file to the project so that it is compiled and linked to the project target. As with the xcconfig files, we should add AppSecrets.swift to our .gitignore file to keep it out of Git.
Using secrets within our code is as simple as referencing our generated struct.
Analytics.setup(with: AppSecrets.analyticsWriteKey)The goal we wanted to achieve was being able to reference secret values within our source code, without these values themselves needing to be kept in source control. The two solutions we have looked at are quite different, but both achieve the same goal.
By using cocoapods-keys, we can avoid the manual setup and also avoid the values being stored in plain-text anywhere in the project. However, our solution using Sourcery can be used without Cocoapods and will still require very little maintenance. There will definitely be even more solutions available online for more use cases, it will come down to using the most appropriate solution for the situation.
", "date_published": "2018-11-20T00:00:00Z" } , { "id": "https://www.lordcodes.com/articles/sharing-accessibility-ids-app-and-tests/", "url": "https://www.lordcodes.com/articles/sharing-accessibility-ids-app-and-tests/", "title": "Sharing accessibility identifiers between app and tests", "content_html": "For identifying views within UI tests we can use accessibility identifiers, which are String values. We can register all of our identifiers within an enum, using an extension to set them on our views. By adding the enum to the app target and the UI test target, an extension can be added to find views within tests suing our ID enum. It's really nice to use an enum, avoiding duplicating the strings and avoiding errors!
App sources
extension UIAccessibilityIdentification {\n var viewAccessibilityIdentifier: ViewAccessibilityIdentifier? {\n get { fatalError(\"Not implemented\") }\n set {\n accessibilityIdentifier = newValue?.rawValue\n }\n }\n}\n\naddContactButton.viewAccessibilityIdentifier = .addContactButtonTest sources
extension XCUIElementQuery {\n subscript(key: ViewAccessibilityIdentifier) -> XCUIElement {\n self[key.rawValue]\n }\n}\n\nXCUIApplication().buttons[.addContactButton].tap()We may find situations in which we want a protocol function to return the current type, here the metatype Self can come in handy. In these situations rather than just returning the protocol type, we likely want to return the type that conforms to the protocol. An associated type can be added to the protocol that defaults to Self to achieve this. Pretty handy!
protocol ChatThreadsRobot {\n associatedtype ChatThreadsType: ChatThreadsRobot = Self\n\n func tapCreateThread() -> ChatThreadsType\n}\n\nextension ConnectionThreadsRobot: ChatThreadsRobot {\n func tapCreateThread() -> ConnectionThreadsRobot {\n app.buttons[\"createThreadButton\"].tap()\n return self\n }\n}A helpful keyword in Swift is Self, which is a metatype that represents the current type. The current type may be the class, subclass or current implementer of a protocol, depending on where it is used.
A handy use-case for it is to avoid specifying generic placeholder types. Neat!
class ThreadRobot<CallerT: CallerRobot> {\n private let app = XCUIApplication()\n\n func tapCompleteButton() -> Self {\n app.otherElements[\"actionButtonRail\"].buttons[\"Complete\"].tap()\n return self\n }\n}When a UIViewController is added within one of it's parent's subviews, there can be an issue where it doesn't expand to fill it. This can often happen when we only tested on a specific device size.
The fix involves preventing the auto-resizing mask from being turned into constraints and ensuring the child view controller's anchor constraints are all attached to the edge's of its container view.
addChild(child)\ncontainerView.addSubview(child.view)\nchild.view.translatesAutoresizingMaskIntoConstraints = false\nchild.view.attachAnchors(to: containerView)\nchild.didMove(toParent: self)After a long wait, Android Studio 3.0 has finally been released to the stable channel. This means everyone should be updating their IDE to the latest and greatest version. There are so many new features and improvements it is just a no brainer! I will go over the new features later on, but for now I will discuss the process of updating and cover the breaking changes in the new Gradle plugin.
![\"Android](\"https://www.lordcodes.com/img/UpsHHDZZCH-1200.webp "\\"Android")
Android Studio should have prompted you to update to 3.0, if not then go to Check for updates in the menu to do so.
Once you launch your project in 3.0 for the first time, you will be told there is a new version of the plugin to update to. You can continue to use your project as it is, but you will miss out on many of the new features and improvements until you update. Simply, follow the prompts to have your project updated to version 3 of the Gradle plugin and to use the latest version of Gradle 4.
If for some reason you need to do this manually:
gradle-wrapper.propertiesbuild.gradle in the root of the projectPreviously, when defining dependencies you would use compile.
compile 'com.android.support:support-compat:27.0.0'This has now been deprecated in favour of implementation and api. In general, you can simply update all dependencies to use implementation. However, if your project is a library and it leaks one its module’s interfaces you may need to use api for that instead.
To understand the difference, please read this detailed guide.
Variants are now automatically matched, which means an app’s debug variant will automatically use a library module debug variant. The same happens for product flavours as well, such as demo and trial.
To ensure this mechanism works correctly, it is now required that all product flavours are assigned to a particular flavour dimension. If you don’t need to use different dimensions, you can simply create one and assign all the flavours to it.
flavorDimensions \"default\"\n\nproductFlavors {\n prod {\n dimension \"default\"\n ...\n }\n\n dev {\n dimension \"default\"\n ...\n }\n}If you use a build type or flavour that doesn’t exist in one of your library modules, a fallback will need to be specified. This isn’t required for debug or release as they are present in all modules automatically. The plugin will select the first fallback from the list which is found.
debug { ... }\nrelease { ... }\nstaging {\n matchingFallbacks = ['debug', 'release']\n ...\n}If you are still using the android-apt plugin for annotation processing support, you should remove that and use the built-in annotationProcessor. The third party plugin is no longer supported.
Similarly, many people have been using retrolambda for Java 8 features support. This is no longer required and will simply be provided automatically, so you should remove the retrolambda dependency. ✂️
You may find that there are Gradle API changes that remove certain functionality. One area that has some differences is the variant API, which mean you will no longer be able to manipulate variant outputs. This is due to variant-specific tasks no longer being created at configuration time.
If you are using the following Gradle syntax, you should check it is still functioning correctly.
android.applicationVariants.all { variant ->\n ...\n}There is a known issue with the Firebase plugin causing a Guava dependency mismatch. It can be easily fixed by excluding Guava from the Firebase plugin. Only add this if it is needed within your project.
dependencies {\n classpath ('com.google.firebase:firebase-plugins:1.1.0') {\n exclude group: 'com.google.guava', module: 'guava-jdk5'\n }\n ...\n}This won’t affect everyone, however, if you are using Robolectric you may find there is a problem with missing resources. To fix this simply add the following to the build.gradle for your module.
testOptions {\n unitTests {\n includeAndroidResources = true\n }\n}There is an endless list of new features and improvements in Android Studio 3.0 and in the new Gradle plugin.
Since starting my career as a software developer, I have been to interviews at various companies. I have, however, more often been on the other side of the process: reviewing CVs, analysing code submissions and conducting interviews. On a few different occasions, I have been asked how I think the recruitment process should be structured and what is best to look for in Android developers. These questions don't have a simple answer that applies to all situations.
Hiring (and unfortunately not hiring) many developers across my working life has helped me to shape the way I approach it. I am by no means an expert and still have plenty to learn from others on the topic, but I believe (and hope) I have some valuable insights that may help other people hiring developers. Therefore, I will attempt to write down some different steps you could include in your hiring process.
![\"A](\"https://www.lordcodes.com/img/vqWLu8uk_F-600.webp "\\"The")
This stage shouldn’t come as a surprise to anyone, as obviously you will need some way for candidates to apply for the position. This is the first opportunity for the candidate to tell you why they think they are right for the job.
For some people a CV might be self explanatory, but it is pretty amazing how varied CVs can be. Over time I must have reviewed hundreds of CVs and almost every single CV is different in length, style, format and content. I have seen a few killer CVs and unfortunately some that weren’t as good.
![\"One](\"https://www.lordcodes.com/img/KRHgyJ-A9k-490.webp "\\"CVs")
When reviewing CVs, it is crucial that you be as fair and objective as possible, avoiding any biases you may have. A good way to achieve this is to compare each CV to the same set of requirements that you have decided are needed to do the job. For an Android developer these may include things like:
If possible try to look for a skill rather than its specific application. For example, knowledge of how to consume a REST API, rather than just whether they mention Retrofit and OkHttp. Obviously if a candidate already knows the libraries you use, this can be a great bonus. The focus should, however, be on spotting their level of experience and their ability to learn new skills quickly.
The next stage in the process for many companies can involve some form of online test or screening process such as Codility. These tools might make sense for some positions, for example a job that requires intense problem solving or coding quickly under pressure. However, from my experience:
I'm not saying these online tests are wrong and should never be used. My preference is just to use other ways to find the right person for the role.
Once you find a candidate that looks promising it is important to meet them as soon as possible. If the number of applications you are receiving is fairly low you could consider going straight to the on-site interview at this stage. In most situations though you will want a remote interview to take place first.
![\"A](\"https://www.lordcodes.com/img/wWPm5FGRP7-800.webp "\\"The")
Remote interviews are usually much shorter than their on-site counterpart, preferably something in the region of 30 minutes or less. The shorter length and the fact they are remote can make them much quicker and easier to schedule with the person applying. They can be a good way to quickly gauge the candidate’s experience, their interest in the position and how well they would fit into the team. By having a conversation, it allows them to form a connection with you and the company. Without this having taken place, if another offer comes from elsewhere they would have a lot less driving them to continue the process with you.
Importantly, this shouldn’t feel like an interview and should be as informal as you can manage, allowing the candidate to relax. Some potential talking points:
You may also be recruiting for a completely remote position or prefer to do your interviews entirely remotely for ease.
You are looking to hire an Android developer and so the best way to check their technical proficiency is by looking at how they program an Android application. This might seem obvious, but you will find many recruitment processes that rely on object-oriented or functional programming challenges and whiteboard exercises. I gave my stance on online testing earlier, however, there is a key difference here in that the candidate will be programming in Android, using the tools they are familiar with and often in their own time.
The candidate applying may already have examples of their Android development skills via open source app(s) on GitHub, you could consider looking at these instead to make the hiring process quicker for the candidate.
If you do decide to ask the candidate to work on an app project of yours, the app should either be very simple so that they can complete it in a reasonable amount of time or it should already be partially developed. You should also make it clear that they can use whatever approach they want and use whichever libraries they wish. This will allow you to see how they think an Android app should be developed.
There are many advantages to seeing applicant’s Android code before they come in to interview. You can gain insights into their development processes and how they would work as an Android developer. An important consideration though is that completing an app test does increase the amount of effort they have to put in. Therefore, you will have to decide if you think it makes sense for your company to include this in the recruitment process.
This will make up the meat of your hiring process and will likely consist of various stages. The main areas you should consider covering are behavioural (team fit) and technical (skill and experience). Before getting started it is a good idea to describe the general format and timings to the candidate. This helps them to understand how much time they have got and what to expect.
One way of running an interview is that the candidate sits in front of you and is asked a set of different questions, delivering an answer after each one. This approach would only give you answers to your specific questions and would be unnecessarily stressful for the person you are interviewing.
Alternatively, I try to make my interviews as conversational as possible. This means leading things in a certain direction using questions, but allowing the candidate to discuss what they want on the topic. This really shows you how the developer would communicate with other team members and allows them to demonstrate their experience and knowledge to you. By making the questions as open as possible, it will expel the notion that there is a single correct answer you are looking for. Instead the candidate should relax and open up, telling you their opinion freely on a particular topic. You will even find you learn about new things during these conversations.
These types of interviews can often be labelled soft skills or team fit interviews. This should in no way diminish the importance of this area of questioning. If you have put the candidate through the app test already the behavioural component could actually be considered the most important part.
![\"Tell](\"https://www.lordcodes.com/img/D5mvA1kfc9-500.webp "\\"Behavioural")
You will ask questions which check the candidate fits with your company culture and the team’s way of working. It will also give the applicant some insight into how the company works. As with reviewing CVs, you should decide which characteristics are most important to you when deciding on your behavioural questions. For example:
![\"What](\"https://www.lordcodes.com/img/EakkPaAXXB-539.webp "\\"Asking")
Please don’t ask all the obvious questions we all read about online, such as asking about their strengths and weaknesses.
Instead finding out about situations where they:
How to run effective technical interviews is a very large and heavily discussed topic. You will also find people have many different opinions of how to go about it.
It is very common for interviewers to ask you to write solutions to problems on a whiteboard. Personally, I have never understood this approach as developers don’t generally spend their days finding substrings, detecting palindromes and writing code by hand on the wall.
Any coding you ask the candidate to do should match what they would do if they got the job. This doesn’t mean you have to get them working on the app they would actually work on. It does, however, mean that they work on an Android app, using the tools they would use and in the environment they would work in.
In reality, developers don’t remember absolutely everything and recall it perfectly on the spot. They sometimes forget the signature for a Compose modifier or the name of the Retrofit annotation they need to use. I think it's a good idea to tell candidates that they can use StackOverflow or the API documentation if they wish.
When working on an Android app, people use libraries like Coroutines, Retrofit and Dagger. This means when they are coding in the interview I think we should make it clear they can use whatever libraries they want to use. You could choose to force them to write plain Android code so you can check they know how to do it. However, I think it's most valuable to see how they would code in a real-world situation. You may even be able to ask why they chose a particular library or particular approach.
As I mentioned earlier, any technical questioning should be as conversational as possible. I generally write down a few topics I would like to find out about and then nudge the conversation in the right direction using my questions. For example:
It is very important that you leave time for candidates to ask you any questions they might have. If the interview was fairly conversational, this may already have been covered. However, if not then it is good to prompt them at the end just to make sure they get the chance to ask any. It is important to remember that you are trying to find the right developer for the team, but they are also trying to find the right company for them.
As I have said a few times, there are various different ways you can check candidates are right for the position. The techniques you choose to use and the questions you choose to ask, won’t be the same as other interviewers. If carefully put together, the process will help you find some really great developers who are a good fit for the team and for the company.
", "date_published": "2017-07-03T00:00:00Z" } ] }