DEV Community: Codemagic

Self-hosted live updates for Capacitor with Codemagic Patch

Codemagic — Mon, 02 Nov 2026 10:26:14 +0000

Codemagic Patch is a new self-hosted tool to ship live updates of HTML, CSS, and JavaScript to Capacitor, Ionic, and Cordova-on-Capacitor apps, without a new store binary.

Say a checkout button stops working on some Android 15 devices, and the fix turns out to be four lines of TypeScript. In a Capacitor app, those four lines live in the web layer, inside a WebView, nowhere near native code. Without over-the-air (OTA) updates, they still have to go the long way round: new binary, store submission, review, and then a slow trickle of users who eventually update. Some never do.

That's what OTA updates solve through tools such as Live Updates on Appflow, and what you can do with Patch.

Patch v0.6.0 ships with two new packages: @codemagic/capacitor-patch, the SDK that goes into your app, and @codemagic/capacitor-patch-cli, a command line made for publishing and managing Capacitor releases. They use the same server, dashboard, and delivery protocol as our React Native SDK.

Below, we’ll go through what you get with Patch, , how you can self-host Patch, and where to find the docs to get your first release out.

Replacing Appflow’s Live Updates Before the Sunset

Ionic has announced that all Appflow features and services will be sunset on December 31, 2027, a little over a year from now. They'll keep Appflow up to date with its dependencies until then. After that, Ionic warns that apps still depending on Appflow may hit failed builds and failed live updates, and users may end up looking at a blank white screen.

A year can feel like plenty of time, but you'll need to make sure no users are on a native version relying on the Appflow SDK for live updates by the time it's sunset.

We've been building, signing, and publishing Capacitor apps on Codemagic for years, and Ionic's own continuity page lists us as an alternative for Appflow native builds. Capacitor teams could also already get OTA updates from our CodePush service through the community cap-codepush plugin. Patch replaces that arrangement with a first-party SDK that we design, test, and support ourselves. For a Capacitor team, that means native builds and live updates from one vendor.

What you get with Patch

A server you can run yourself, an SDK in the app, a CLI to publish the web build you already produce, and a dashboard for what happened after that.

Web-layer fixes reach devices that already include the SDK. The check runs on launch, and you can also run it when the app returns to the foreground.
Downloads are a diff of what changed, with a fallback to the full bundle if the diff fails.
A bad release rolls itself back if the app never reports the new bundle as healthy.
You choose when an update takes effect. Mandatory updates can follow a different rule.
Releases can be signed, and the server can reject unsigned ones.
Staging and Production stay separate. You can send a release to a percentage of devices, then promote the one that worked without rebuilding it.
The dashboard shows adoption, failures, and download size for each release.

Your native version number is the compatibility boundary

There's one rule every team should understand before shipping their first Capacitor OTA release, because it's much cheaper to learn it now than in production.

Your web bundle calls into native code: Capacitor plugins, your own native classes, native configuration. A bundle built for one native build can break on another. If your new web code calls Camera.getPhoto() and the installed binary shipped before you added @capacitor/camera, it will fail.

The Capacitor CLI doesn't try to detect this by fingerprinting your native project. Every release instead targets one exact native app version (CFBundleShortVersionString on iOS, versionName on Android) and is only delivered to that version. Ranges and wildcards aren't accepted. In day-to-day terms:

Bump the native version every time anything native changes: a plugin added, removed, or upgraded, native code edited, native configuration changed.
If one web bundle should go to several binary versions, release it once per version.
Never ship two different native builds under the same version number. If they differ in ways your web code cares about, no OTA tool can tell them apart.

If your team already versions carefully, you'll hardly notice this. If it doesn't, OTA will push you into the habit, and you'll be better off for it. The binary version filter added to the Patch dashboard's deployment and Metrics pages in this release makes it easy to see how each version is doing.

Put together, every change goes down one of two paths:

If the change touches…	Then…
Only the web layer	Build your web assets, publish them with `cmpatch-capacitor release create` against the current binary version, test on Staging, then promote to Production with a staged rollout.
Plugins, native code, or native config	Bump the native version, then build, sign, and publish through Codemagic. Once the new binary is through review and in users' hands, future OTA releases target the new version.

What OTA buys you, and what it doesn't

OTA is easy to oversell, so it's worth being specific.

The obvious win is speed. A web-layer fix stops taking days of review and update lag and starts reaching users within minutes of publishing, as soon as their devices check in. For a consumer app, that can be the difference between a wave of one-star reviews and nobody noticing. For a B2B or internal app, it's the difference between an escalation and a ticket closed the same afternoon.

You also end up supporting fewer versions. With store-only updates, every version a user hasn't bothered to update is still out there, still generating bug reports. With OTA, devices on the same binary converge on the same web bundle, so "can't reproduce" happens a lot less.

And your two release cycles can run at their own pace. The native release train can stay as deliberate as your compliance process requires, monthly or quarterly, while the web layer ships whenever your team is ready. Staging, staged rollouts, and promotion give you a controlled route from merge to full rollout.

What OTA can't do is ship native code, and the app stores are explicit about where that line is.

Apple's Developer Program License Agreement, section 3.3.1(B) forbids apps from downloading executable code but allows interpreted code, which is what the JavaScript in a Capacitor WebView is. There are conditions. The downloaded code can't change the app's primary purpose by adding features that don't match how the app was described and advertised. It can't get around signing, sandboxing, or other OS security features. And it can't turn the app into a store for other apps.

Google Play's Device and Network Abuse policy starts from a stricter position. Apps may not update themselves outside Google Play or download executable code such as dex, JAR, or .so files from anywhere else. The policy then makes an exception for code that runs in an interpreter or virtual machine with only indirect access to Android APIs, and gives "JavaScript in a webview or browser" as its example. That code still can't be used to break any other Play policy.

So both stores end up in the same place. Bug fixes, copy changes, UI tweaks, and incremental improvements to the app people already installed are fine. Using OTA to turn the app into something other than what was reviewed is not, and it puts your developer account at risk. Signed releases help with the security side of Apple's conditions, and keeping your native versions disciplined keeps native changes inside reviewed binaries, where they belong.

How to self-host live updates for Capacito

The server, release worker, and dashboard run on your infrastructure as a single Docker Compose deployment: Caddy for TLS, the Patch server, PostgreSQL, and S3-compatible object storage, with Cloudflare or CloudFront in front if you want a CDN. Your bundles, metrics, and release history stay on your network. The Capacitor SDK talks to the standard Patch server without any changes, so you set up the server once with the self-hosting guide, and cmpatch-capacitor handles everything Capacitor-specific from there.

The SDKs and CLIs are licensed under Apache 2.0. The server uses the Codemagic Server License, which is free for up to 1,000,000 monthly active devices and converts to Apache 2.0 two years after each release. The only thing you can't do is resell Patch as a competing OTA service.

To try it before provisioning anything, run the local evaluation stack. It runs the real server, database, storage, and dashboard on your machine in Docker, and the Capacitor CLI can point straight at it:

{{< highlight bash "style=paraiso-dark">}}
git clone https://github.com/codemagic-ci-cd/codemagic-patch.git
cd codemagic-patch
./scripts/local-eval/up.sh

cmpatch-capacitor config set --server-url http://localhost:3000
cmpatch-capacitor login
{{< /highlight >}}

The local server has a prefilled one-click login, so there's no account to create.

Self-hosting makes the most sense for teams with strict data residency rules, regulated or air-gapped environments, or a preference for owning their infrastructure.

Getting started

The Patch documentation covers setup step by step, so this is an overview of the path from nothing to your first OTA release.

1. Decide where Patch runs. Self-host with the self-hosting guide, or talk to our team about hosted service. For a first look, the local stack above is enough.

2. Install the CLI and create one Patch app per platform. Each app comes with Staging and Production deployments, each with its own deployment key. Don't let iOS and Android share a deployment. A release's delivery path doesn't include the platform, so the two would overwrite each other.

{{< highlight bash "style=paraiso-dark">}}
npm install -g @codemagic/capacitor-patch-cli

cmpatch-capacitor config set --server-url https://YOUR_PATCH_SERVER
cmpatch-capacitor login # opens the browser

cmpatch-capacitor app create --name MyApp-iOS
cmpatch-capacitor app create --name MyApp-Android
cmpatch-capacitor deployment list --app MyApp-iOS # deployment IDs and keys
cmpatch-capacitor deployment list --app MyApp-Android
{{< /highlight >}}

3. Add the SDK to your Capacitor project. It supports the two most recent Capacitor major versions (currently 7 and 8) and Android minSdkVersion 24 or higher.

{{< highlight bash "style=paraiso-dark">}}
npm install @codemagic/capacitor-patch
npx cap sync
{{< /highlight >}}

Configuration goes in capacitor.config.ts, with one block per platform. The API URL and download base URL come from your Patch server: the self-host installer prints both, and we give them to you for hosted Patch.

{{< highlight typescript "style=paraiso-dark">}}
// capacitor.config.ts (excerpt)
plugins: {
CodemagicPatch: {
ios: {
deploymentKey: 'YOUR_IOS_DEPLOYMENT_KEY',
apiUrl: 'https://YOUR_PATCH_API_URL',
downloadBaseUrl: 'https://YOUR_PATCH_DOWNLOAD_BASE_URL',
},
android: {
deploymentKey: 'YOUR_ANDROID_DEPLOYMENT_KEY',
apiUrl: 'https://YOUR_PATCH_API_URL',
downloadBaseUrl: 'https://YOUR_PATCH_DOWNLOAD_BASE_URL',
},
},
},
{{< /highlight >}}

Then call start() once the app has rendered its first screen:

{{< highlight typescript "style=paraiso-dark">}}
import { CheckFrequency, start } from '@codemagic/capacitor-patch';

// Checks on launch and on every return to the foreground.
// Calling it after the first render is what marks the bundle as healthy.
start({ checkFrequency: CheckFrequency.ON_APP_RESUME });
{{< /highlight >}}

Where you call it matters. start() is what tells the SDK the running bundle is healthy, so call it after your UI is actually up, not early in bootstrap. That way an update that crashes during startup still gets rolled back. Two more tips: every config value can also be set as a native resource (Info.plist or strings.xml) if you inject per-environment values in CI, and npx codemagic-patch-check-config is worth adding to your native build workflow to catch a shared deployment key before it ships. The check reads JSON only, so if your config is capacitor.config.ts, run it after npx cap sync and point it at the synced copy: npx codemagic-patch-check-config android/app/src/main/assets/capacitor.config.json. The Patch docs cover native setup for Capacitor, checking for updates, install modes, and the step-by-step APIs, and the SDK reference lists everything the SDK exports. Pick Capacitor in the switcher at the top of the docs menu to see the Capacitor version of each page.

4. Publish a release to Staging from the CLI. Build the web assets the way you already do, then publish that folder once per platform. --target-binary-version has to be the native version you will ship in the next step (CFBundleShortVersionString on iOS, versionName on Android). www below is the webDir from capacitor.config.ts.

{{< highlight bash "style=paraiso-dark">}}
npm run build

cmpatch-capacitor release create --bundle-path www \
--app MyApp-iOS --deployment Staging \
--target-binary-version 1.4.0

cmpatch-capacitor release create --bundle-path www \
--app MyApp-Android --deployment Staging \
--target-binary-version 1.4.0
{{< /highlight >}}

Each command publishes one platform. Install a build that includes the SDK and uses that same native version if you want to try the Staging release on a device before it goes to the stores.

5. Ship the native release, then publish Production from CI. The SDK has to be in the installed app before a device can receive an update, so this first binary is a normal store release. Build, sign, and publish it through Codemagic as usual. CI/CD for Ionic apps walks through connecting the repo and a first workflow, and the Ionic Capacitor build guide covers code signing, versioning, and publishing for both platforms.

After that, Production releases belong in CI. Create a token with cmpatch-capacitor token create, store it with your server URL and the deployment IDs from deployment list, and publish from the pipeline. The first release guide covers that workflow, including promotion and staged rollouts.

Coming from Appflow Live Updates

Most Appflow concepts carry over directly. Appflow channels become Patch deployments, and you get Staging and Production from the start. A few things work differently, and it's better to know about them before you start:

The SDK swap takes one native release. You can't deliver a new OTA SDK through the old one. Plan a native release that replaces the Appflow Live Updates SDK with @codemagic/capacitor-patch, and leave enough time for it to reach your users before December 2027.
There's no runtime channel switching. Appflow's getConfig() and setConfig() let the app change its channel at runtime. The Patch SDK doesn't have an equivalent, because the deployment key is part of the binary's configuration. If your beta testers currently opt into a channel from inside the app, you'll need another approach, such as separate beta builds pointing at a Beta deployment.
Your release history stays behind. There's no import of Appflow channels, builds, or deployment history. Your first Patch release starts the history fresh.
Each platform gets its own key. Appflow used one channel name across platforms. Patch uses a separate app and deployment key for iOS and for Android.
Binary versions must match exactly. If your Appflow setup relied on looser version matching, settle on a clear native versioning scheme before you switch.

None of these should stop you, but the first one decides your timeline. The Appflow migration guide walks through the swap.

If you're already using our CodePush service with cap-codepush, nothing changes for you today. When you're ready, the move to Patch follows the same pattern: one native release with the new SDK, then you publish with cmpatch-capacitor instead of code-push.

When Patch isn't the right fit

We'd rather you choose the right tool than the wrong one from us, so here are the cases where Patch won't help much.

Most of your changes are native. Plugin upgrades, Capacitor version bumps, and native features all need a reviewed binary whichever OTA service you use. For teams like that, a fast and reliable native build-and-publish setup matters more, and Codemagic handles that too.

Your beta program depends on runtime channel switching. The Patch Capacitor SDK doesn't offer it today. Separate beta builds work, but it's a different workflow, so think it through before migrating.

Your native versioning is a mess and you can't fix it. Exact-version targeting will feel strict. We think strict is the safer default, because it makes the compatibility boundary visible instead of guessing at it, but it does ask for some discipline.

You're happy on Appflow right now. You don't have to move tomorrow. You do have to move before the end of 2027, and the native release the swap requires means you should start well before that.

Try Patch today

If Appflow's shutdown is on your roadmap, start before it becomes urgent. Spin up the local evaluation stack this week, and put the SDK in your next native release.

How Much It Costs to Self-Host OTA Updates for 100 Million Users

Codemagic — Mon, 26 Oct 2026 23:00:00 +0000

How much does it actually cost to self-host over-the-air (OTA) updates and what infrastructure pieces are required? Especially for a React Native or Capacitor app with many millions of users.
It’s a useful number to know if you’ve got a growing Expo Updates bill.

This article prices an extreme case of 100 million monthly active users (MAU). As a quick answer, here is the monthly cost of hosting Codemagic Patch on DigitalOcean at a few sizes:

Monthly users	10 thousand	1 million	100 million
DigitalOcean	$12	$63	about $843
Cloudflare	$0	$0	$0
License	$0	$0	$7,250
Total	$12	$63	about $8,093

You can host Patch on any Linux compatible machine, such as an EC2 on AWS or a machine on Fly.io. We’re just using DigitalOcean as an example.

Requirements for hosting Patch

Patch is designed to be easy to run and adaptable to different requirements. The key pieces it needs are:

A server for metrics, the dashboard, and publishing
Object storage for the manifests and the bundles.
Postgres for the metric rows and the release records.
A CDN, optionally, in front of the storage hostname for manifests and bundles.

A small deployment can keep all of this on a single 2 GB machine. How to self-host OTA updates for React Native walks through standing that up. In these cases, the install wizard uses Caddy for HTTPS on the API and storage hostnames, and Silo for object storage. For 100 million users we will split the pieces apart.

Understanding the traffic for Patch

To plan our architecture, let's talk about what requests and posts are made.

Requests

Devices will make a request for whether an update is available. The answer is provided as meta.json and manifest.json, a pair of files created along with each release that will be kept in object storage and served by the CDN. Designing scalable OTA update architecture for React Native explains why that check is a file on the CDN rather than a call to the server.

When an update is available, the bundle will also be fetched from the CDN. So, you won't deal with millions of device requests hitting your server.

Posts

The posts are the phones reporting back. Receiving and installing an update posts Downloaded, then Ready and Applied. The phone also posts Active, to say what it is running, at most once per day.

These are initially stored as an individual row per device, then rolled up into daily totals after eight days.

Load estimates for 100M users

We will need to make some assumptions to decide the required spec.

We'll say 1/4 of the monthly active users open the app on a given day, meaning 25 million update checks and Active posts per day.

Let's also assume one OTA update per week. On our end, releasing an update only means three extra post events per device.

The rates are those assumptions spread across a day.

	10 thousand	1 million	100 million
Opens per day	2,500	250,000	25 million
Active posts, averaged over 24 hours	under 1/s	about 3/s	about 300/s
Active posts, if the day bunches into 8 hours	under 1/s	about 10/s	about 1,000/s

Sizing the infrastructure

Do not size the droplet from the downloads. Size it from Active, then add the ship-day posts.

Server and throughput

A VM with a dedicated CPU is useful for the incoming metrics. The most basic one on DigitalOcean is 2 vCPUs with 8 GiB of RAM, at $63 a month.

A quick load test showed that this machine can post about 750 events per second to a basic managed Postgres. Faster than that, and the database couldn't keep up.

To go beyond 750/s, it's possible to add measures such as saving a batch of posts once a second. That isn't currently included in Patch, but a quick test showed it increasing throughput to 4,000/s on the same setup.

Managed Postgres

Postgres is best on a separate managed database. You will need roughly 4 GiB per 1M MAU. About half of that is Active, and about half is the ship-day posts still inside the eight-day window.

For one million users, the basic managed Postgres is $15 a month. A $48 basic droplet beside it makes the $63 in the table above. At about 10 posts a second, that tier does not need the dedicated CPU.

For 100M users, we start needing one of the bigger offerings. 400GiB should be enough, but we'll double it to 800GiB to be safe.

DigitalOcean has a PostgreSQL Advanced plan at $352 a month for 800 GiB, with 16 GiB of RAM and 4 vCPUs. It includes backups and point-in-time recovery.

Rollup time

On a busy day, rolling 50 million rows into the daily total would take about 25 minutes. Posts that arrive during that time are still stored.

Approaches such as partitioning the table by day could make that a quick task, but aren't yet supported by Patch.

Adding redundancy

To keep publishing and metric posts going when a machine dies, add three pieces:

A standby database node. It is promoted if the primary dies. Without one, the database is down while a replacement is provisioned. A standby does not take inserts itself.
A second 2 vCPU droplet, so metric posts and publishing have a machine to land on. The first droplet already covers the busy hour.
A load balancer in front of those droplets. In front of one droplet it does nothing when that droplet dies.

That covers a dead primary database or a dead droplet.

Data transfer

The phones download on the order of a petabyte a month. A few megabytes, once a week, across 100 million devices is already about that.

Cloudflare serves those files, and CDN bandwidth is included in the plan. The objects live in R2, where egress is free. The droplet only sends metric responses, a few hundred gigabytes, which fits in the transfer included with the machine. That means our data transfer costs come to $0.

What's not needed

Because requests don't hit the server, pieces to deal with that load aren't needed for Patch.

No queue. The post is stored before the server acknowledges it. The phone retries on failure, and event_id keeps that retry from inserting a row that is already there.
No HTTP cache in front of the API. The reads worth caching are the manifest and the bundle, which are already on the CDN. Posts are writes, so there is no response to cache.
No Redis. It is often added for metadata, a cached update check, or metric counters. Metadata and metric rows are in Postgres, and the update check is those manifest files.
No Kubernetes or API gateway. Two droplets and a load balancer cover a dead machine. Downloads stay on the CDN, so a gateway has no phone traffic to spread.
No autoscaling. The droplet count does not follow download traffic, because that traffic never reaches the server.
No multi-region Postgres. One database holds the eight-day window, and update checks do not read it.
No timeseries database. A timeseries database such as Prometheus could give more granular analysis, but is option.

What you pay

At 100 million the month looks like this. Prices are the current droplet list, managed Postgres list, and load balancer price.

Line	What it covers	Monthly
Two API droplets	2 vCPU and 8 GiB each	$126
Load balancer	Sends metric posts and publishing to the live droplet	$12
Managed Postgres	4 vCPUs, 16 GiB, 800 GiB. Backups and point-in-time recovery	$352
Standby node	A second copy of that database in case it dies	$352
Droplet egress	Metric responses, a few hundred gigabytes. That sits inside the transfer included with the droplet	$0
R2	The release artifacts, tens of gigabytes. Egress is $0	about $1
Cloudflare	Cache in front of the storage hostname	$0
Infrastructure		$843
License	100 million at the published bands	$7,250
Total		$8,093 /month

The license is the main item line, which is required above a million users. Pricing is tiered per million users, with details on the pricing page.

Want to try out Patch?

To find out more about Patch and view the docs, visit patch.codemagic.io. It includes a local evaluation stack so you can play with it on your machine.

If you want to use it for over a million users, ask sales@codemagic.io for more information.

Java Heap Space error and how Codemagic helps to remediate it

Codemagic — Thu, 12 Sep 2024 11:15:42 +0000

Overcoming issues related to Java Heap Space while building Android projects can be quite challenging and frustrating. Understanding the concept of heap memory in Java is crucial, as well as being aware of the available solutions.

This article will provide a brief explanation of the reasons behind the occurrence of the Java Heap Space issue and present Codemagic’s recommended solutions for addressing it.

I recently added some gradle tasks to my Android project, which stuffed my project with memory-hungry gradle tasks, e.g. DexGuard and ProGuard, that ended up requiring more heap space memory and the machine fell short of providing it. To put more context into it, while executing tasks, it was either exiting Daemon by shutting it down prematurely or throwing java.lang.OutOfMemoryError :

ERROR:: R8: java.lang.OutOfMemoryError: Java heap space
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':app:minifyReleaseWithR8'.
> com.android.tools.r8.CompilationFailedException: Compilation failed to complete

During the project’s construction, I found it unexpected that running DexGuard demanded a significantly larger amount of memory than what some machines could manage. This was already impacting the release pipelines that had to be tested and deployed to the Google Play Store.

The limitation does not specifically apply only to DexGuard or ProGuard, but any other gradle tasks might restrict build pipelines by requiring more memory. There are some suggestions out there to get the issue resolved:

Consider updating the gradle-wrapper.properties file to the latest version of Gradle and the android/build.gradle file to the latest version of the Android Gradle plugin as this may resolve the issue. However, working with their Java version compatibility can be tricky by keeping in mind that projects do not support the latest versions of Gradle and AGP.
Increasing the -Xmx heap size without confirmation of sufficient available memory from the machine is uncertain. If the assigned heap size exceeds the machine’s capacity, the value will be disregarded.

Codemagic to the rescue

Codemagic as a CI/CD platform did the team a huge favour by speeding up workflow pipelines along with automatically conducting tests, creating builds, and releasing team apps on the Play Store, on top of addressing the Java Heap Space issue. Codemagic’s robust machines have made building, testing, and publishing not just Android but iOS applications incredibly easy. Struggles with not only the Java Heap Space error but also other related issues can be relieved through the powerful machines provided by Codemagic:

macOS with Apple M2, M2 Pro, Max and Ultra chips
Linux with arm64 and x64 architectures
Windows

Conclusion

Contact here if your Android builds are affected by OOM (out of memory) error or similar issues, and you are interested in trying any of these machines with extended specifications.

100% Flakiness-free UI test automation with Kaspresso and Allure TestOps

Codemagic — Wed, 22 Nov 2023 08:17:00 +0000

This article was written by Nihal Agazade and originally posted to the Codemagic blog.

UI testing in mobile app development is a challenging task due to multiple factors such as flaky tests, saving screenshots, printing useful logs and readability of test codes. We will be talking about a new UI testing framework Kaspresso for Android apps and how it is different from other frameworks when it comes down to solving these challenges.

What is Kaspresso and why should it be chosen?

Kaspresso is based on Espresso and Kakao DSL which helps it have a great readability of test codes and comes with many built-in features:

Kakao DSL based test code readability. For our better understanding, let’s quickly check how Kaspresso Kakao DSL wrappers differ from Espresso:

Espresso:

@Test
fun LoginActivity() {
    onView(withId(R.id.login_button))
        .check(ViewAssertions.matches(
               ViewMatchers.withEffectiveVisibility(
                       ViewMatchers.Visibility.VISIBLE)))
    onView(withId(R.id.login_button)).perform(click())
}

Kaspresso:

@Test
fun LoginActivity() {
    MainScreen {
        LoginButton {
            isVisible()
            click()
        }
    }
}

100% flaky test protection, thanks to its built-in protection rules.
Allure Test Ops support

To learn more about what else Kasspresso offers, feel free to check the official documentation.

How to get started with Kaspresso?

First and foremost, mavenCentral() needs to be declared inside the root build.gradle. Make sure that jcenter() is removed from the project along with the dependencies that require jcenter().

Note: Recent native android projects have it defined inside settings.gradle instead:

pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

Open app/build.gradle and integrate Kaspresso into your project by adding the following line:

dependencies {
    androidTestImplementation("com.kaspersky.android-components:kaspresso:1.5.3")
}

By this, we are good to go with Kaspresso unless Allure Testops needs to be integrated which requires additional steps to be followed, and we will be talking about it in the next section.

We briefly talked about what features Kaspresso introduces and what makes Kaspresso different from other frameworks. Let’s go through some of the key features for further clarification.

Painful flaky tests

Test flakiness is something we can hardly avoid considering that our code constantly changes, adding new screens, new functionalities etc. There are multiple reasons that could be the actual cause of flaky tests, such as:

Real devices or emulators
Test code
Production code
General infrastructure
Or even instability with the testing framework you are using

Kaspresso has it reduced to the very minimum with its DSL wrappers and Interceptors. Interceptors are built-in and help achieve many useful things, e.g:

add custom actions to each framework operation like writing a log or taking a screenshot;
overcome flaky operations by re-running failed actions, scrolling the parent layout or closing the android system dialog;

For an example, ScreenshotStepWatcherInterceptor is utilised to take pictures whether tests fail or pass and it is part of TestCase() constructor:

class SimpleLoginActivity : TestCase(
    kaspressoBuilder = Kaspresso.Builder.simple().apply {
        stepWatcherInterceptors.add(ScreenshotStepWatcherInterceptor(screenshots))
    }
)

TestCase() is a class inherited from com.kaspersky.kaspresso.testcases.api.testcase.TestCase which is out of the box ready for use.

Screenshots

Kaspresso has made the process of taking screenshots much easier via its interceptors. It is possible to take snapshots of every screen while tests are executed and save these screenshots under a desired file name through the device.screenshots.take("desired_file_name") method:

   @Before
   @Test
   fun test() {
       run {
           step ("Products dropdown is available") {
           device.screenshots.take("screenshot_file_name")
           ProductsScreen {
               testActivityButton {
                   isVisible()
                   isClickable()
               }
             }
           }
       }
   }

Permissions must be granted for screenshots to be taken by importing androidx.test.rule.GrantPermissionRule, otherwise there will be no READ_EXTERNAL_STORAGE nor WRITE_EXTERNAL_STORAGE in place. So, at the top of the Kotlin Class/File where the kotlin test code is stored, GrantPermissionRuleneeds needs to be imported:

import androidx.test.rule.GrantPermissionRule

and then, within the same file, @Rule must be declared which is inherited from org.junit.Rule:

@get:Rule
    val grantPermissionRule: GrantPermissionRule = GrantPermissionRule.grant(
        android.Manifest.permission.READ_EXTERNAL_STORAGE,
        android.Manifest.permission.WRITE_EXTERNAL_STORAGE
    )

Besides these changes, AndroidManifest.xml needs to be configured for a complete permission cycle:

<manifest>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> 
    <application>
    </application>
</manifest>

Kaspresso device.screenshots.take object is similar to device.uiDevice.takeScreenshotfrom the uiautomator library, however the key difference would be custom file names that can be easily managed through device.screenshots.take, especially when there are lots of snapshots and it can be tricky to find the appropriate ones.

Note: A video mp4 file is saved to sdcard/Documents along with screenshots and you can find an exact file path in the logs which is explained in the following section.

Logging

Custom notes can be added to the logs, and for that purpose testLoggerobject can be used with the i method:

fun test() {
       run {
           testLogger.i("Either hardcoded or dynamic values through env vars $VALUE")
           MainScreen {}

However, there is another challenge at this point and it is about splitting test internals into different steps, so that which tests fail and which ones pass can be observed easier.

What we can do is to wrap our code in try catch block along with adding manual logs to the output. Something like:

@Test
    fun sampleTest() {
        try {
            Log.i("Step 1:")
            MainScreen {
                loginActivityButton {
                    isVisible()
                }
            }
            Log.i("Step 1: Succeeded")
        } catch (e: Throwable) {
            Log.i("Step 1: Failed")
            throw e
        }
     anotherTest(){
      try {
       ...
       Log.i("Step 1:")
     } catch(e: Throwable){
      Log.i("Step 2: Failed")
    }
}

Works! Though with all the try catch blocks, the code will lose its readability and potentially, lead to flakiness.

In the Kaspresso world, Steps can be added in order to simplify code readability and more importantly, by keeping its flaky reduction rules. Steps can be used by declaring the run{} method:

fun test() {
       run {
           step ("Testing user registration auth") { ... }
           step ("Testing user login auth") { ... }
           ...
       }
   }

and then we can observe our crafted logs:

Complete automation with Codemagic CI/CD and uploading results to Allure Testops

We can further automate the process and upload test results to Allure Testops.

Thanks to Codemagic, we can automatically run UI tests, collect logs, and deploy results to Allure Testops on every change or daily.

Allure Testops is a DevOps ready test reporting platform where we can analyse test results through graphical reports and gathering results from servers in real-time while the build job is being executed. In order to achieve it with Codemagic, we will be utilising allurectl which is a command line wrapper of Allure Testops API. Allure Testops functions in two modes:

CI mode
Non-CI mode

allurectl detects automatically which one is in use through finding the required environment variables specified in Codemagic as explained below. So, let’s get the steps together for an easy flow of the process:

Sign up with Allure Testops.
Go to your profile, and create a secret token

As soon as your request for registration is approved by the Allure Testops team, you will receive an active endpoint to your work environment.
Create a project and fetch its ID.

The very vital step not to miss is to enable Allure support in our test code via withForcedAllureSupport. In order to enable it, we need to go through a couple of steps in our code:

Import com.kaspersky.components.alluresupport.withForcedAllureSupport
Add withForcedAllureSupportto TestCase() constructor which will look like:

class YOUR_ACTIVITY_TEST : TestCase(
    kaspressoBuilder = Kaspresso.Builder.withForcedAllureSupport()
)

After this, as soon as our tests are executed, there will be a directory created (sdcard/Documents/allure-results) and they will be pulled out of the device and uploaded to Allure Testops by Codemagic.

If you have not signed up with Codemagic and yet added your repo, you can follow the steps as explained in the Codemagic documentation here.

Go to your repo settings in the UI and you will find the Environment variables tab right next to codemagic.yaml and add your Allure secrets that we went through how to create them above.
Add the following lines in codemagic.yaml:

workflows:
  run-android-ui-test:
    name: Upload test results to Allue Testops
    instance_type: linux
    environment:
      groups:
        - allure_credentials
    scripts:
      - name: Set Android SDK location
        script: |
                        echo "sdk.dir=$ANDROID_SDK_ROOT" > "$CM_BUILD_DIR/local.properties"
      - name: Launch Emulator
        script: |
            cd $ANDROID_HOME/tools
            emulator -avd emulator &
            adb wait-for-device            
      - name: Install Allure CLI
        script: | 
            set -e
       wget https://github.com/allure-framework/allurectl/releases/download/2.2.1/allurectl_linux_amd64 -O ./allurectl
            chmod +x ./allurectl
      - name: Execute tests
        script: |
                        ./gradlew :app:connectedDebugAndroidTest
      - name: Pull test files from the device and upload to Allure Testops
        script: |
            set -e
            adb pull sdcard/Documents/allure-results
            ./allurectl upload allure-results

Note: When installing Allure CLI and building with a Mac machine, the platform must be changed in the command line to allurectl_darwin_amd64 for Mac Pro machines. In order to switch the machine type from Linux to Mac Pro in codemagic.yaml, changing instance_type value to mac_pro suffices.

Note: As the Apple Virtualization Framework does not support nested virtualization, Android emulators are not available with Apple silicon (M1 or M2) machines.

From this point on, Codemagic will start its automation process and print out the build/test logs:

A link to the Allure Testops environment where the test results can be accessed will be printed in the logs:

Worth pointing out that Codemagic has a possibility to schedule builds. It means that your tests will be run at a certain time you set up and you will already have had the test results in hand, and ready for review in Allue Testops. Let’s see how we can schedule a build:

Open your application in Codemagic.
Switch to the Scheduled builds tab and click the Add new schedule button.
Select the Branch and the Workflow to run.
In the Schedule for field, select the days you want to run the build.
Specify the start time (UTC) of the build by selecting a value from the At field. Note that the build may be delayed up to 15 minutes during peak hours.
Click Add schedule to save the schedule.

Checking test results in Allure Testops

Now, we can observe screenshots, videos, and customised test logs in the Allure Testops UI along with a graphical report of the test results.

Here Allure UI indicates how many tests passed, which ones failed:

In the screenshot below, we will find our passing tests along with the test logs, screenshots, and videos:

You will also have a chance to check failing test logs and which steps the issues occurred with:

Summary

We have gone through the steps regarding how Kaspresso manages to overcome the key issues of UI testing environments by allowing us to automate Android UI tests with flakiness protection and providing test results to Allure Testops platform to better control our manual, and automated testing through graphical analysis of test results including screenshots, videos, and all the logs. Codemagic took the code over, added an extra layer of automation, and completed the whole cycle of the automation process.

How to Test Native Features in Flutter Apps with Patrol and Codemagic

Codemagic — Sun, 05 Nov 2023 13:03:36 +0000

This article was written by Kevin Suhajda and originally posted to the Codemagic blog.

"It's no use! I can't run an end-to-end test with Flutter's integration tests", exclaimed one of our customers about 9 months ago. I asked what the problem was and they explained that they were using Google Authentication for logging in and used the google_sign_in package but it wasn't possible to use Flutter's integration tests to interact with the login screens. I still didn't quite understand what the problem was, and then it clicked: this plugin uses native UI components which the integration tests don't work with.

I was quite disappointed that I couldn't offer a solution at the time and had to leave it at that. However, fast forward to today and an awesome new solution has presented itself called "Patrol" by LeanCode. I'm going to tell you all about it, but before we dive in let's just recap why it's important to run tests, what tools you had available until now, and then talk about how to get started with Patrol.

Why test Flutter apps anyway?

One of the main reasons development teams use Continuous Integration (CI) services like Codemagic is to get immediate feedback on the code they are committing to their repo. Tests can be run automatically as part of your pipeline to ensure a level of both quality and stability because bugs or issues can be caught early and rectified straight away. We always encourage customers to implement testing when setting up their workflows, but it's not uncommon to hear "We haven't got time to write tests". Hopefully, you're not in that boat, and use testing as part of your app development cycle to deliver great quality and bug-free apps!

What are the main automated ways to test Flutter apps?

There are four main testing methods that can be automated as part of your CI workflow. Testing is a topic unto itself, so I'll keep it brief, but using a combination of these testing methods will help you improve the quality of your app and catch problems sooner rather than later.

Firstly, there is "Unit testing" which is commonly used for testing your functions and methods in isolation to make sure they work as expected. Unit tests can also be written to make sure your business logic works in different scenarios without any unexpected results.

Next, we have Flutter "Widget tests" which allows you to test your UI components and make sure they render correctly and work as you expect.

Then there is "Integration testing" which is where you test if the units and components of your application work together as expected.

Finally, there is "End-to-End UI testing" where you test the application as if it were being used by a real user. In a CI workflow, this is usually automated using simulators or emulators to test different pathways through your app to make sure there aren't any issues after you make changes to your code.

This is where the customer I was talking about at the beginning was stuck because they couldn't run their End-to-End UI tests because it wasn't possible to log in to the app. At the time they tested a 'dev' version that bypassed the log-in part.

However, that's no longer required now that "Patrol" is available!

Enter, stage left, Patrol!

So first of all, what is Patrol? Well, I think the docs say it best:

Patrol is a new and open-source UI testing framework for Flutter developed by LeanCode. It builds on top of Flutter's existing test tooling to let you do things which were previously impossible. Patrol lets you access native features of the platform that the Flutter app is running on.

The most important part here is that it lets you access the native features of the platform your Flutter app is running on.

This means that you can now do things such as:

Interact with Permission Request dialogs to dismiss or accept requests.
Interact with WebViews.
Minimize and maximize your app.
Interact with authentication flows like Google or Apple authentication.
Interact with other native features such as opening the Notifications tray, pressing the Home button, turning Wi-Fi connectivity on or off, or changing the device to dark mode, etc.

Okay, this sounds great, but what's the catch?

Well, there isn't one! And what's more, it's not only free but also open source!

Moreover, Patrol also introduces 'custom finders' which gives you a more concise syntax for writing your tests. You can read more about them here.

Installing and setting up Patrol

To get started with Patrol you will need to install the CLI, add the Patrol dependency to your pubspec.yaml and set up some configurations in your iOS and Android projects.

LeanCode has created some great documentation here which takes you through the process for each platform which you can find here. Their step-by-step guide will take you through the setup for both iOS and Android.

If you run into any problems, the best place to get help is in the Patrol Community Discord server which you can join here.

If you find any bugs, then you can raise an issue here.

Writing native feature tests with Patrol

Now you are all set up, let's start testing some native features. To try it myself, I set up a simple Flutter app with an elevated button that when clicked opens a native alert dialog.

Clicking "OK" or "Cancel" simply dismisses the dialog.

Again, I would recommend using Patrol's own documentation which you can find here to get your first test file added.

So for my test, I wanted to click on the elevated button that has the text "Click me!". It's a standard Flutter widget so it can be tapped using the following Patrol finder:

await $('Click me!').tap();

The native dialog should then be displayed, so we can now start interacting with a native UI component. So let's add the native finder that will allow us to tap the "OK" button:

await $('Click me!').tap();
await $.native.tap(Selector(text: 'OK'));

That was easy! I also want to test the "Cancel" button, so let's tap on the "Click me!" button again and then tap on the native dialog's "Cancel" button by adding a couple more lines as follows:

await $('Click me!').tap();
await $.native.tap(Selector(text: 'OK'));

await $('Click me!').tap();
await $.native.tap(Selector(text: 'Cancel'));

Your completed test file should look like this:

import 'package:cmpatrol/main.dart';
import 'package:patrol/patrol.dart';

void main() {
  patrolTest(
    'Native tests',
    nativeAutomation: true,
    ($) async {
      await $.pumpWidgetAndSettle(const MyApp());

      await $('Click me!').tap();
      await $.native.tap(Selector(text: 'OK'));

      await $('Click me!').tap();
      await $.native.tap(Selector(text: 'Cancel'));

      await $('Click me!').tap();
      await $.native.tap(Selector(text: 'NO'));
    },
  );
}

You should now be able to run that test on your emulator or a real device using the command to launch the test. My integration test file was called "button_test" so I started the tests from Terminal as follows:

patrol test -t integration_test/button_test.dart

You'll see if your tests pass or fail directly in the Terminal. If the tests fail you will get a link to the full test report. Alternatively, If you are running your tests on Android like I did then this should you can access the report by clicking the index.html in the following directory:

./build/app/reports/androidTest/connected

You can experiment further with other native features such as opening the notifications tray, disabling the wifi, enabling dark mode, minimizing and maximizing the app:

// minimize app
await $.native.pressHome();

await $.native.openNotifications();

await $.native.disableWifi();

await $.native.enableDarkMode();

// maximize app
await $.native.openApp();

⚠️ Note that it is not possible to completely close your app and then re-open it because doing so would end the whole test and, therefore, make it fail.

Consult the Patrol documentation for more examples.

Using Patrol in your Codemagic workflows

To incorporate Patrol into your workflows, you'll first have to install the Patrol CLI on the build machine. This only takes a few seconds and once that's done, you can run your test script. Below is an example of how you would add these steps to the "scripts" section of your codemagic.yaml configuration file. I would recommend running the script to install the Patrol CLI as one of the first script steps and then you can run your Patrol tests either immediately after that or after any other tests you might also want to run beforehand.

Before running your Patrol tests you will need to start the emulator so we'll add a script to launch the emulator and wait for it to be fully booted. Note that the Android emulators are not available on machines using Apple Silicon M1 or M2 machines due to the Apple Virtualization Framework not supporting nested virtualization. Therefore, I would recommend using a linux instance when testing Android apps.

The scripts section of your codemagic.yaml should look something like this:

scripts:
  ...
  - name: Install Patrol CLI
    script: dart pub global activate patrol_cli
  - name: Launch Android emulator
    script: |
      cd $ANDROID_HOME/tools
      emulator -avd emulator &
      adb wait-for-device
  - name: Run tests with Patrol
    script: patrol test -t integration_test/your_test.dart
    ignore_failure: true
  ...

Showing Patrol test results in the Codemagic build logs

The Patrol test results are also available in JUnit XML format, which means they can be displayed in the build logs on the Codemagic build overview screen. You just need to add the test_report property pass in the path to the JUnit XML file that is generated. You can use the ignore_failure property with a boolean to control whether you want the rest of the workflow to continue running or not. If you want to upload your results to a test management system as described in the next section, you should set this to true.

Here's an example of what your script should look like:

scripts:
  ...
  - name: Run tests with Patrol
    script: |
      patrol test -t integration_test/your_test.dart
      test_report: build/app/outputs/androidTest-results/connected/*.xml
      ignore_failure: true
  ...

A failing test might look something like this:

Gathering the Patrol test report as a build artifact

One additional thing you might want to do is gather the test report output as a build artifact so you can view the full report should any errors occur. Doing this will make the report available for download as a zip file on the build overview screen in the "Artifacts" section on the left-hand side. The easiest way to do this is to copy the directory the report files are in to the directory Codemagic uses to export artifacts. There's a built-in environment variable called $CM_EXPORT_DIR that references this directory which you can use in your script.

The script to do this should be like this:

scripts:
  ... 
  - name: Export Patrol test report
    script: | 
      cp  -r build/app/reports/androidTests/connected $CM_EXPORT_DIR/report
  ...

Conclusion

Patrol has finally overcome the problem of running UI and integration tests that involve native features. It's now possible to test native features and interact with authentication flows, native dialogs, and even toggle native features like wifi, cellular, dark mode, and even minimize your app and maximize it. Additionally, it's both free and open source and provides a solution to a real problem that's been around since Flutter was launched. What's more, it's straightforward to add and use it in your Codemagic workflows. If you want to support the great work LeanCode is doing, give Patrol a like on pub.dev here and give the Patrol GitHub repository a star here.

This article is written by Kevin Suhajda, Head of Solutions Engineering at Codemagic. You can find Kevin on X, GitHub, and LinkedIn.

Introducing the official Codemagic integration for Runway

Codemagic — Tue, 31 Jan 2023 13:15:23 +0000

This post is written by Gabriel Savit and originally posted to Codemagic blog.

Codemagic is now officially integrated with Runway, the DevOps platform for mobile. But wait, you might be wondering, isn't Codemagic already that as a CI/CD for mobile? Aren't the two services interchangeable? In fact, it's quite the opposite --- they're powerfully complementary.

By pairing the flexibility and ease that Codemagic brings to your build pipeline with Runway's ability to pull the rest of your toolchain and team into a unified control center, you'll be set up for success as you scale your mobile practice. Let's take a look at how it works.

Codemagic: An easy way to automate building and distribution

Say you have an app and you're tired of manually building, code signing, and releasing it. Naturally, you look for a CI/CD solution and end up building a Codemagic pipeline that effortlessly churns out signed builds of your app across any and all platforms you support -- Android, iOS, macOS, Windows, etc.

Maybe you have different flavors configured, from dev builds to poke at while you work on new features to release candidates that your team can run regression on and prepare for release. You may even be taking advantage of Codemagic features that allow you to not only build and sign your artifacts but even distribute new builds automatically to App Store Connect and Play Console. You can literally release app updates to users with a single click --- CI/CD at its finest!

If you're new to CI/CD, check out this guide on getting started with CI/CD for mobile

Now imagine you're on a team of more than one person. Can you ship updates with a click of a button? You have other engineers around you who might need to finalize their work for the release. You have QA engineers who need to complete testing and sign off on a final RC. OK, that's still possible with Codemagic and some good practices around working with pull requests, but it's already become more complicated.

Add to the mix PMs who need to plan ahead and understand what will be shipping and when. You have customer service and ops folks who need to know about new versions before they start receiving a flood of feedback from users about it. You have security and compliance reviewers who need to apply their rubber stamp. You have managers and other stakeholders who care about what you're up to and need to weigh in. The list goes on. As your team and product grow, the number of parties involved --- and the number of steps from build to release (and post-release) --- increase. And that's where Runway comes in.

Runway: A home to get your entire mobile org on the same page

Runway integrates with your build pipeline (Codemagic, in this case) and the rest of your toolchain to give your entire mobile org a home. By keeping everyone --- and we mean all stakeholders, not only the technical ones --- on the same page and automating all sorts of tasks that exist outside the realm of CI, Runway ensures your releases stay as streamlined as possible, even as your team and product grow. Instead of bouncing between your Codemagic dashboard and 10 other browser tabs and endlessly pinging people back and forth over Slack, everyone can leverage Runway to see exactly where things stand during your release cycles and collaborate on releases together.

For maximum visibility across the team, Runway surfaces build data alongside info on feature work from version control and project management tools, stability and health metrics from crash reporting and product analytics, and even info on the state of your feature flags.

Runway allows you to release hands-free from kickoff to submission to release --- but not without the input and signoffs needed from various team members. Combine scheduled automations for branch cuts, version bumps, rollouts, and much more with a robust and customizable system of checklist items and approval gates to ensure you don't sacrifice quality even as you move to a level of automation you haven't been able to achieve before.

Runway's deep integrations with App Store Connect and Play Console allow for a saner --- and safer --- publishing experience. Instead of constant roundtrips between engineers, PMs, and marketing folks just to get store copy updated, you can give responsible parties scoped access within Runway to update and validate metadata. For cross-platform teams, this is an especially big win --- similar to how keeping your different platforms' build pipelines nicely consolidated in Codemagic reduces overhead, Runway's unified and platform-agnostic treatment of the stores will save your team context switching and make things more approachable for non-technical folks.

Your team's job isn't over once a build lands in the store: Running a successful rollout is a demanding and critical part of the process, and Runway helps with this stage too. With disparate signals of health pulled together from across your stack --- including crash reporting, product analytics, and even user reviews --- your team gets a single source of truth to refer to when making the call to halt or continue a rollout. You can configure granular thresholds that define what "healthy" looks like for your team, then tie those to alerting or even "halt" and "accelerate" automations.

How to integrate Codemagic with Runway

It takes minutes to integrate Codemagic with Runway. After heading to runway.team to sign up for free, you'll be guided through a simple onboarding flow. When you're on the CI/CD integration step, select the Codemagic option and drop your Personal Access Token in there. (To generate a token, in your Codemagic account, navigate to Teams > Personal Account > Integrations.) Runway is SOC 2 Type 2 certified --- your secrets are safe with them! You'll be prompted to select the Codemagic workflows that correspond to your different flavors of builds (where applicable: dev builds, RCs, and release builds), and that's it! You're ready to streamline and democratize releases and rollouts with the combined power of Codemagic and Runway.

Once Runway and Codemagic are integrated, you get to decide how you want them to work together. You can continue triggering builds from Codemagic or take advantage of Runway's scheduled release automations to kick off timed RCs for you. Alternatively, you can trigger builds in Runway manually along with extra context from the rest of your toolchain. Everything to do with building artifacts stays in Codemagic, and you don't have to touch anything in your workflows; Runway will plug and play with your current processes and practices.

However streamlined and powerful your Codemagic pipelines are, you may find the dream of one-click deployment slipping away as your team and product grow and your overall release process gets more complex. By integrating Codemagic in Runway, you can get everyone back on the same page and keep shipping smoothly.

And there's more good news: Codemagic and Runway are both free to start with. So, if you haven't done so already, sign up for Codemagic and head to runway.team to get started for free -- and use both services to create a fully integrated DevOps home for your apps.

Creating WebView Content Blockers with Flutter InAppWebView

Codemagic — Mon, 09 Jan 2023 11:32:10 +0000

Written by Lorenzo Pichilli and originally posted to Codemagic blog

In this article, we are going to learn how to create a custom Content Blocker for our WebView instances using the flutter_inappwebview plugin.

Read this article to get started with Flutter InAppWebView

Content Blockers are usually used for blocking ads, but you can also use them to block any other content. Blocking behaviors include hiding elements, blocking loads, and, on iOS and macOS, stripping cookies from WebView requests.

Keep in mind that, in general, Content Blockers cannot achieve the same level of functionality as specialized extensions such as AdBlock or AdBlock Plus. Content Blockers are a set of rules that never receive any callbacks or notifications back from the WebView when it finds content it needs to block.

Through the contentBlockers property of the InAppWebViewSettings class, we can define a list of ContentBlocker instances that the WebView will use.

The ContentBlocker class

We define content-blocking behavior in the ContentBlocker class. Each one contains an action property and a trigger property. The action tells the WebView what to do when it encounters a match for the trigger. The trigger tells the WebView when to perform the corresponding action.

Here is a basic example:

initialSettings: InAppWebViewSettings(contentBlockers: [
 ContentBlocker(
   trigger: ContentBlockerTrigger(
     urlFilter: ".*",
     resourceType: [
       ContentBlockerTriggerResourceType.IMAGE,
       ContentBlockerTriggerResourceType.STYLE_SHEET
     ]
   ),
   action: ContentBlockerAction(
     type: ContentBlockerActionType.BLOCK
   )
 )
]),

In this example, the ContentBlocker blocks the loading of every image and stylesheet for every URL.

Add triggers to your Content Blocker

A trigger must define the required urlFilter property, which specifies a regular expression as a string to match the URL against. The other properties are optional --- they modify the behavior of the trigger. For example, you can limit the trigger to specific domains or have it not apply when the WebView finds a match for a specific domain.

Here is an example of a Content Blocker with a trigger for image and style sheet resources that the WebView finds on any domain except those specified:

initialSettings: InAppWebViewSettings(contentBlockers: [
 ContentBlocker(
   trigger: ContentBlockerTrigger(
     urlFilter: ".*",
     resourceType: [
       ContentBlockerTriggerResourceType.IMAGE,
       ContentBlockerTriggerResourceType.STYLE_SHEET
     ],
     unlessDomain: ["example.com", "github.com", "pub.dev"]
   ),
   action: ContentBlockerAction(
     type: ContentBlockerActionType.BLOCK
   )
 )
]),

For deeper trigger customization, you can use the other properties of ContentBlockerTrigger:

urlFilterIsCaseSensitive: If the URL matching should be case-sensitive. By default, it is case insensitive.
resourceType: A list of "ContentBlockerTriggerResourceType" representing the resource types (how the browser intends to use the resource) that the rule should match. If it is not specified, the rule matches all resource types.
ifDomain: A list of strings matched to a URL's domain; it limits action to a list of specific domains. Values must be lowercase ASCII or Punycode for non-ASCII characters. Add ` in front to match the domain and subdomains. It can't be used with unlessDomain`.*
unlessDomain: A list of strings matched to a URL's domain; acts on any site except domains in a provided list. Values must be lowercase ASCII or Punycode for non-ASCII. Add ` in front to match the domain and subdomains. It can't be used with ifDomain`.*
loadType: A list of ContentBlockerTriggerLoadType that can include one of two mutually exclusive values. If not specified, the rule matches all load types. ContentBlockerTriggerLoadType.FIRST_PARTY triggers only if the resource has the same scheme, domain, and port as the main page resource. ContentBlockerTriggerLoadType.THIRD_PARTY triggers if the resource isn't from the same domain as the main page resource.
ifTopUrl: A list of strings matched to the entire main document URL; it limits the action to a specific list of URL patterns. Values must be lowercase ASCII or Punycode for non-ASCII characters. It can't be used with unlessTopUrl.
unlessTopUrl: An array of strings matched to the entire main document URL; it acts on any site except URL patterns in the provided list. Values must be lowercase ASCII or Punycode for non-ASCII characters. It can't be used with ifTopUrl.
loadContext: An array of strings that specify loading contexts.
ifFrameUrl: A list of regular expressions to match iframes' URL against.

Check the code documentation for each specific property to find out which platform supports that feature.

Add actions to your Content Blocker

When a trigger matches a resource, the WebView evaluates all the triggers and executes the actions in order.

Group the rules with similar actions together to improve performance. For example, first specify rules that block content loading followed by rules that block cookies.

There are only two valid properties for actions: type and selector. An action type is required.

If the type is ContentBlockerActionType.CSS_DISPLAY_NONE, a selector is required as well; otherwise, the selector is optional.

Here is a simple example:

initialSettings: InAppWebViewSettings(contentBlockers: [
 ContentBlocker(
   trigger: ContentBlockerTrigger(
     urlFilter: "https://flutter.dev/.*",
   ),
   action: ContentBlockerAction(
     type: ContentBlockerActionType.CSS_DISPLAY_NONE,
     selector: '.notification, .media, #developer-story'
   )
 )
]),

Valid types are:

BLOCK: Stops the loading of the resource. If the resource was cached, the cache is ignored.
BLOCK_COOKIES: Strips cookies from the header before sending it to the server. This only blocks cookies that are otherwise acceptable to WebView's privacy policy. Combining BLOCK_COOKIES with IGNORE_PREVIOUS_RULES doesn't override the browser's privacy settings.
CSS_DISPLAY_NONE: Hides elements of the page based on a CSS selector. A selector field contains the selector list. Any matching element has its display property set to none, which hides it.
MAKE_HTTPS: Changes a URL from http to https. URLs with a specified (nondefault) port and links using other protocols are unaffected.
IGNORE_PREVIOUS_RULES: Ignores previously triggered actions.

Check the code documentation for each specific type to find out which platform supports it.

Creating a simple ad blocker

Let's create a simple ad blocker using what we have learned.

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_inappwebview/flutter_inappwebview.dart';

Future main() async {
 WidgetsFlutterBinding.ensureInitialized();
 if (!kIsWeb &&
     kDebugMode &&
     defaultTargetPlatform == TargetPlatform.android) {
   await InAppWebViewController.setWebContentsDebuggingEnabled(kDebugMode);
 }
 runApp(const MaterialApp(home: MyApp()));
}

class MyApp extends StatefulWidget {
 const MyApp({Key? key}) : super(key: key);

 @override
 State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
 final GlobalKey webViewKey = GlobalKey();

 // list of ad URL filters to be used to block ads from loading
 final adUrlFilters = [
   ".*.doubleclick.net/.*",
   ".*.ads.pubmatic.com/.*",
   ".*.googlesyndication.com/.*",
   ".*.google-analytics.com/.*",
   ".*.adservice.google.*/.*",
   ".*.adbrite.com/.*",
   ".*.exponential.com/.*",
   ".*.quantserve.com/.*",
   ".*.scorecardresearch.com/.*",
   ".*.zedo.com/.*",
   ".*.adsafeprotected.com/.*",
   ".*.teads.tv/.*",
   ".*.outbrain.com/.*"
 ];

 final List<ContentBlocker> contentBlockers = [];
 var contentBlockerEnabled = true;

 InAppWebViewController? webViewController;

 @override
 void initState() {
   super.initState();

   // for each ad URL filter, add a Content Blocker to block its loading
   for (final adUrlFilter in adUrlFilters) {
     contentBlockers.add(ContentBlocker(
         trigger: ContentBlockerTrigger(
           urlFilter: adUrlFilter,
         ),
         action: ContentBlockerAction(
           type: ContentBlockerActionType.BLOCK,
         )));
   }

   // apply the "display: none" style to some HTML elements
   contentBlockers.add(ContentBlocker(
       trigger: ContentBlockerTrigger(
         urlFilter: ".*",
       ),
       action: ContentBlockerAction(
           type: ContentBlockerActionType.CSS_DISPLAY_NONE,
           selector: ".banner, .banners, .ads, .ad, .advert")));
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
       appBar: AppBar(
         title: const Text("Ads Content Blocker"),
         actions: [
           TextButton(
             onPressed: () async {
               contentBlockerEnabled = !contentBlockerEnabled;
               if (contentBlockerEnabled) {
                 await webViewController?.setSettings(
                     settings: InAppWebViewSettings(
                         contentBlockers: contentBlockers));
               } else {
                 await webViewController?.setSettings(
                     settings: InAppWebViewSettings(contentBlockers: []));
               }
               webViewController?.reload();

               setState(() {});
             },
             style: TextButton.styleFrom(foregroundColor: Colors.white),
             child: Text(contentBlockerEnabled ? 'Disable' : 'Enable'),
           )
         ],
       ),
       body: SafeArea(
           child: Column(children: <Widget>[
         Expanded(
           child: Stack(
             children: [
               InAppWebView(
                 key: webViewKey,
                 initialUrlRequest:
                     URLRequest(url: WebUri('https://www.tomshardware.com/')),
                 initialSettings:
                     InAppWebViewSettings(contentBlockers: contentBlockers),
                 onWebViewCreated: (controller) {
                   webViewController = controller;
                 },
               ),
             ],
           ),
         ),
       ])));
 }
}

Using these rules will prevent a bunch of ads from appearing, such as Google Ads.

Click the Disable/Enable button to disable or enable the ad blocker feature.

Conclusion

Content Blockers allow us to write performant rules for blocking content in the WebView while respecting the user's privacy.

Full project code is available on GitHub.

That's all for today!

Are you using this plugin? Submit your app through the Submit Application page and follow the instructions.

Check the Showcase page to see who's already using it!

This project follows the all-contributors specification (contributors). I want to thank all the people who are supporting the project in any way. Thanks a lot to all of you! 💙

Migrating a Flutter app to Material 3

Codemagic — Fri, 16 Dec 2022 08:33:53 +0000

This article is written by Taha Tesser and originally posted to Codemagic blog.

At Google I/O 2021, Google announced the next evolution of Material Design, Material You, along with Android 12. The Material Design system's biggest overhaul yet brought redesigned components, new colors, a wide range of shapes, simplified typography, new elevation, better accessibility, and many other tweaks. With this update, Flutter apps can have a consistent design across multiple platforms. Material Design 3 (the technical name for Material You) is sometimes referred to as Material 3 or simply M3 for the sake of brevity, similarly to how Material 2 is referred to as M2.

In this article, we will discuss everything that you, as a Flutter developer, should know about migrating your Flutter app to Material 3.

How to enable Material 3 in Flutter

Since the announcement of Material 3, Flutter has received a bunch of updates to support it, including support for new typography, shapes, elevation, updated widgets, and new M3 widgets. Most of the M3 components are available in Flutter. You can track the few remaining widgets that are yet to receive Material 3 support and the progress of the Material 3 implementations in Flutter for them in the Bring Material 3 to Flutter issue.

Currently, Material 3 changes are only available when opting in, so you'll need to use the useMaterial3 flag on ThemeData to enable Material 3 support. (This might change in the future, so be sure to check out the Flutter website for updated documentation. We'll also update this article soon after the change takes place.)

To use Material 3 in Flutter instead of Material 2, specify the following:

theme: ThemeData(
  useMaterial3: true,
),

What's new in Material Design 3 for Flutter?

Material 3 updates brought revamped typography, an improved ColorScheme (including the ability to generate a full ColorScheme from a given seed color), updated elevation, a beautiful Android 12 overscroll stretch effect, and a new ink ripple. A bunch of Material widgets, such as AppBar, FloatingActionButton (FAB), ElevatedButton, OutlinedButton, IconButton, and Card, have been updated to support Material 3 design. There are also new Material 3 widgets, such as NavigationBar, NavigationDrawer, andSegmentedButton, some new M3-style buttons, such as FilledButton and FilledButton.tonal, and a whole lot more.

If you simply migrate the Flutter starter app to Material 3, you'll already notice some changes: The AppBar has no elevation or background color, and the FAB has a rounded rectangular shape instead of the more familiar circular shape.

For a complete overview of M3 in Flutter, check out the official Material 3 Demo.

In the following sections, I'll explain some of the key changes and tweaks you might want to make in your app to support Material 3.

The key changes in Material 3 are:

Dynamic color
Typography
Shapes
Elevation

Let's go through each of them in detail.

Dynamic color

Let's start with Dynamic color, which enables you to apply consistent colors across your app. It contains some key colors and neutral colors related to separate tonal palettes. Colors from these tonal palettes are applied across the UI. Use the Material Theme Builder web app or the Figma plugin to visualize the dynamic color for your app and create a custom color scheme.

Flutter uses a low-level material_color_utilities package that contains algorithms to create a Material Design 3 color system. You can create color schemes for your apps using dynamic_color based on a platform's implementation of dynamic color.

The easiest way to create an M3 ColorScheme is by providing a seedColor color in the app's theme.

For instance, add colorSchemeSeed: Colors.green to the starter app. Notice that the FAB is now using a lighter green color instead of the light purple from the default color scheme.

Adding colorSchemeSeed when primarySwatch is present will throw assertion : 'package:flutter/src/material/theme_data.dart': Failed assertion: line 477 pos 12: 'colorSchemeSeed == null || primarySwatch == null': is not true.

To fix this, remove primarySwatch: Colors.blue, from the starter app's theme.

    ///...
    primarySwatch: Colors.blue,
  useMaterial3: true,
  colorSchemeSeed: Colors.green,
),

Here, I've created an example that shows all the colors from the M3 ColorScheme. On the left, we have the default ColorScheme, which is available when setting the useMaterial flag to true. And on the right, we're using the custom ColorScheme, generated using the colorSchemeSeed parameter, which takes a seed color or key color to generate a full Material 3 ColorScheme.

Default M3 `ColorScheme`	Custom M3 `ColorScheme`

You can take this to the next level using both flex_seed_scheme, which allows you to create a more flexible version of Flutter's ColorScheme.fromSeed, and flex_color_scheme, which ensures UI components get themed completely by the color schemes and custom colors you provide.

Typography

Material 3 simplified the typography naming by splitting the typescales into five key groups:

Display
Headline
Title
Body
Label

The role of each key group is more descriptive, and it's much easier to use different sizes in a particular typography group, e.g., BodyLarge, BodyMedium, and BodySmall instead of bodyText1, bodyText2, and caption. This helps when implementing typography for devices with different screen sizes.

The scaling of the typography has become consistent across the groups. Here is a comparison between the M3 and M2 typescales:

Elevation

In Material 2, each elevated component gets a shadow. The higher the elevation, the bigger the shadow. Going even further, Material 3 introduces a new surfaceTintColor color property. When applied to elevated components, the surface of the elevated components gets this color, and its intensity depends on the elevation value.

Source: https://m3.material.io/styles/elevation/overview

The surfaceTintColor property is added to all the elevated widgets in Flutter, along with the elevation and shadow properties.

Try out this Material elevation demo: Turn off shadows by tapping on the icon button in the top right and switch between M2 and M3. Notice that elevated surfaces take on the surfaceTintColor color, which makes them visible even when no shadow is provided.

When comparing the M2 AppBar with the M3 AppBar in the starter app, you'll notice that the AppBar doesn't have a default elevation value, surfaceTintColor color, or shadow color.

M2 `AppBar`	M3 `AppBar`

Providing a custom elevation value shows the default surfaceTintColor color in effect and applies the theme's shadow color to the AppBar so that the AppBar casts a shadow as well.

Note: This AppBar.elevation property is different from the new AppBar.scrolledUnderElevation property, which is only in effect when the content is scrolled underneath the AppBar. Learn more about this further below.

  appBar: AppBar(
    title: Text(widget.title),
    elevation: 4,
  ),

  appBar: AppBar(
    title: Text(widget.title),
    elevation: 4,
    shadowColor: Theme.of(context).shadowColor,
  ),

Shapes

Material 3 offers a wider range of shapes, including squared, rounded, and rounded rectangular shapes. The FAB, which was previously circled, now has a rounded rectangular shape, and material buttons went from rounded rectangular to pill shaped. Widgets like Card, Dialog, and BottomSheet are also more rounded in M3.

Migrating from Material 2 to Material 3

Here, I'll walk you through the process of migrating a Material 2 demo app to Material 3.

This demo app contains some Material 2 Flutter widgets. Some of them will be updated when enabling M3, and some of the M2 widgets can be replaced with new M3-style widgets. For example, ElevatedButton can be replaced with the new FilledButton to preserve the visual design, and BottomNavigationBar can be replaced with the new M3-style NavigationBar widget. The demo app also contains some customization needed in an M2 app for some widgets to stack well. For instance, InputDecorationTheme applies a custom fillColor so that the TextField is visible when placed in the AppBar in an M2 app.

  theme: ThemeData(
    colorScheme: const ColorScheme.light().copyWith(
      primary: Colors.green[700],
      secondary: Colors.green[700],
    ),
    inputDecorationTheme: InputDecorationTheme(
      filled: true,
      fillColor: Theme.of(context).colorScheme.onPrimary,
      hintStyle: TextStyle(
        color: Colors.green[700],
      ),
    ),
    floatingActionButtonTheme: const FloatingActionButtonThemeData(
      foregroundColor: Colors.white,
    ),
  ),

One of the best things about Material 3 is that widgets use consistent colors, and the overall theming experience has also been improved. For example, in the demo, we used a custom InputDecorationTheme to make the TextField visible in the dark green AppBar. But when migrating to M3, we can remove this, and the TextField will be visible without any customization.

In the demo, remove the existing colorScheme property, inputDecorationTheme, and floatingActionButtonTheme. Then add the following lines:

    theme: ThemeData(
    useMaterial3: true,
    colorSchemeSeed: Colors.green[700]
  ),

We now have a new beautiful ColorScheme that's applied to all the components in the demo app. Each UI component is using specific tonal palette colors. TextField uses an appropriate fillColor, and cards have the default greenish surfaceTintColor.

IconButton now supports the ButtonStyle property, which you can use to customize the IconButton to get an M3 visual and a new selected state. Let's update the IconButton from the AppBar in the demo app to an M3 filled-style icon button.

Check out https://api.flutter.dev/flutter/material/IconButton-class.html and https://m3.material.io/components/icon-buttons/overview to learn more.

Here's my favorite part: When you scroll through the content, the AppBar's default scrollUnderElevation kicks in. Notice that the surfaceTintColor intensified when we're scrolling, and as a result, the AppBar changes color. This is because the AppBar is elevated based on the scrollUnderElevation value when the content is scrolled underneath. List views send scroll notifications to the AppBar that they're being scrolled beneath.

You can implement AppBar.notificationPredicate and listen to scroll notifications from a nested list view for more complex layouts.

The Material 3 AppBar is elevated when content is scrolled underneath the AppBar. You can adjust this elevation using the new scrolledUnderElevation property.

Check out the official scrolledUnderElevation code sample I've added in the AppBar docs.

Execute flutter create --sample=material.AppBar.2 mysample to create a local project with this code sample.

The migration process for our demo app isn't complete yet. It still uses the M2-style BottomNavigationBar, so let's replace it with the new M3-style NavigationBar widget. It's taller and easier to interact with, and it isn't elevated.

M2-style `BottomNavigationBar`	M3-style `NavigationBar`

Check out the documentation for the NavigationBar class for more details.

Tapping on the FAB on the home screen opens a dialog with a rounded rectangular shape. Since the dialog is elevated by default, we can see that the default surfaceTintColor has been applied and the content padding has been slightly modified, as it has an optional icon property.

Check out the documentation for the showDialog function for more details.

Now, navigate to the details page by tapping on one of the list items. This page contains a SliverAppBar with expandedHeight and flexibleSpace to make the app bar title large and the SliverAppBar collapsable. This can be replaced with the new SliverAppBar.large, which supports large titles and is also collapsable. When doing so, we can remove expandedHeight and flexibleSpace.

    SliverAppBar.large(
    title: const Text('Lorem Ipsum'),
  ),

For the new M3 AppBar variants, which support medium and large titles, use the new SliverAppBar.medium and SliverAppBar.large.

Check out the documentation for the SilverAppBar.medium constructor and SilverAppBar.large constructor for more details.

Here are the screenshots of the final M3 demo.

The source code for all the demos is available on GitHub.

Conclusion

Material 3 makes it possible to create beautiful, personalized, and accessible designs. When combining Material 3 with Flutter, you can create a consistent and unified UI experience across mobile, web, and desktop platforms. It makes it much easier to create complex algorithmic color schemes and scale typography for devices with varying screen sizes. Furthermore, accessibility has been improved, and visual feedback is clearer.

The Flutter team has been working hard on adding full support for Material 3 to Flutter. As demonstrated above, you can already migrate your existing Material 2 app to Material 3. If you use some widgets that are yet to receive Material 3 support, you can track their progress in the Material 3 issue.

10 reasons to choose Codemagic CI/CD in 2022–2023

Codemagic — Mon, 21 Nov 2022 08:33:46 +0000

Codemagic is a CI/CD (continuous integration and continuous delivery) tool that is best suited for mobile developers. It can help you speed up your release cycle, get actionable feedback faster, and forget about the pain of manually submitting your apps to stores.

Codemagic is evolving fast: This year, we added M1 Mac mini build machines and changed our pricing so that everyone can afford to use the friendliest mobile DevOps tool on the market.

Why using a CI/CD tool is especially important for mobile app development

Mobile application development has come a long way over the last decade, and users have developed high expectations for the look, feel, and functionality of the apps they use. They expect apps to work smoothly, be available across multiple platforms, look nice, and be intuitive.

All of that requires a fast software development life cycle so that you can quickly test concepts, fix issues, and iterate in order to improve the quality of your app and release new features. Building such a release cycle is impossible without adhering to DevOps best practices, which include automating a lot of tasks and improving collaboration between team members by building a continuous integration and continuous delivery pipeline for your app.

For continuous integration, you'll need a version control system such as GitLab, GitHub, or Bitbucket (Codemagic supports all of these version control systems, by the way) for your source code. You will also require a tool that will grab the source code from your repository, run automated tests, and build it into an actual working app.

For continuous delivery, you'll usually use the same tool to automatically publish your app to the app stores, such as Google Play and Apple App Store. This means that just committing your code with a change to a repository or approving a pull request is enough to trigger a pipeline that will automatically build, test, and deploy your app with that change and enable users to access it immediately.

Tools that carry out the above processes are called continuous integration and continuous delivery services, or CI/CD for short.

There are many CI/CD tools available in the market, from universal solutions such as Jenkins or GitHub Actions to hosted mobile-first cloud services such as Codemagic, Bitrise, or Appcircle. How do you know which CI/CD service is best for building mobile apps?

Download our ebook "Continuous Integration and Delivery for Mobile Apps"

Below, you'll find ten reasons why you should consider using Codemagic in 2022 (and 2023) for your mobile app development.

1. Never overspend

Codemagic has a unique billing model that helps you save money by adapting to your needs.

Firstly, you get 500 free build minutes per month. If you need more, you only pay for the build minutes you have used at the end of the month.

And if your usage exceeds 50 build-machine hours per month, you won't have to pay more than $299 a month --- Codemagic fixes the costs for you while providing unlimited build minutes. This is done automatically, so there's no need to worry about optimizing the spend --- we'll optimize it for you.

Finally, if you're sure you will be building extensively every month, you can choose the annual plan with the same unlimited usage but at a 20% discount so that you pay $2,870 per year of unlimited use.

Learn more about Codemagic's pricing

2. Build with Apple silicon machines

This winter, Codemagic introduced Apple M1 build machines, which recently replaced the old Intel Mac minis as our default VMs (even though you can still use Intel machines if you need to). That means that you can build with M1s even on a free plan. Once you exceed the limit and need to pay for build minutes, Codemagic still offers M1 Mac minis at a fraction of the price of what other mobile CI/CD services offer.

Read how Codemagic managed to lower its pricing while improving its infrastructure

3. Enjoy good performance

There are many benefits of using Apple silicon build machines in continuous integration/continuous delivery pipelines. The improvements in build speed that they provide are just amazing. Building with other Codemagic machines is also quite fast, primarily because they have all the necessary tools, such as Flutter SDK, Android Studio, Xcode, Unity Editor, and many more preinstalled.

You can find the build machine specs and information about preinstalled software via the links below:

Learn more about how Mac M1 build machines increase the build speed of Flutter apps

4. Forget about maintaining infrastructure

Perhaps even more importantly, you don't need to worry about maintaining infrastructure and updating dependencies. We always keep all the software up to date so that you don't need to worry about it --- you can just use it, and we'll take care of the maintenance. You don't need to update your environment. We've got you covered, from the latest Xcode versions (actually, we have several versions to choose from) to the latest Flutter versions.

And with Codemagic, there's no such thing as "our build server is broken" anymore --- there are always build machines in the pool ready to build your apps.

5. Embrace flexibility with the visual Workflow Editor or YAML Infrastructure as Code

Codemagic offers two different approaches to building CI/CD pipelines, and you can choose the one that suits you best. With our visual Workflow Editor, you can follow a very intuitive (yet well-documented) process to build a CI/CD pipeline with just a few clicks.

Alternatively, you can utilize the power IaC (Infrastructure as Code) with codemagic.yaml. This method gives you infinite options for customizing your pipeline and enables you to set up new pipelines within a few minutes by simply copying and pasting the contents of your codemagic.yaml file from the previous pipeline.

Choose whichever approach you like best. What's even better is that you can start with the simple Workflow Editor and then export your configuration as a codemagic.yaml file to continue tweaking it.

Learn how to get started with the Workflow Editor and codemagic.yaml

6. Build white-label apps at scale

Have you built a successful app for one service and want to sell it to another service with minor tweaks? This is called white labeling, and Codemagic supports it at no additional cost. No matter which white-labeling approach you choose or whether you're using Flutter, React Native, or another framework, Codemagic can help you build all flavors of your white-label app with a single commit and distribute them all to the stores using their respective accounts.

Codemagic speeds up release cycles for your white-label applications, helping you make sure your clients are happy with your app.

Learn more about white labeling apps with Codemagic

7. Build for all platforms

One of the core benefits of frameworks such as Flutter, React Native, and Unity is their support for many platforms, and Codemagic allows you to enjoy this support at its fullest.

Codemagic has Linux, Windows, and Mac build machines. (The latter even come with two different architectures --- x86/x64 and ARM64.) We allow you to build apps for the following platforms:

Android
iOS
Windows
Linux
Mac
Web
Standalone Oculus VR headsets

Codemagic can not only build your app for all these platforms but also help you automate deployment to the respective stores.

8. Enjoy tight integrations with App Store and Google Play

Codemagic is tightly integrated with both App Store Connect and the Google Play Store. This means that setting up automated deployment is easier with Codemagic. It can help you with steps such as code signing, automatic app versioning, distributing apps to TestFlight or Google Play Beta, and more.

Also, did you know that publishing to the App Store with Codemagic doesn't consume your build minutes? Well, now you do.

Learn more about Codemagic's App Store Connect integration

9. Use integrations with various test automation tools

Codemagic has quite an extensive list of integrations that are documented and ready for you to try out. Among those integrations, we'd like to specifically highlight tools that allow you to automate testing, including Katalon (one of the most powerful engines for no-code test automation), Kobiton (for testing on real devices), Sofy (for low-code test automation), and Firebase Test Lab (for cloud-based testing for Android and iOS apps on various devices).

And there are many more integrations that can help you improve testing, code coverage, and more.

Get acquainted with Codemagic's integrations

10. Get help from our very responsive support

With some SaaS companies, it can be difficult and time-consuming to reach support, and they often don't really solve your issue. Codemagic is different: You can contact our support using the in-app chat (for paying customers) or on GitHub Discussions (for everybody). We strive to provide help within 24 hours, and it usually takes just a few hours.

We also offer free onboarding assistance, and our DevOps engineers are here for you to get the most out of Codemagic and build better pipelines.

Conclusion

Choosing the right CI/CD for mobile app development might seem like a complicated task, but it essentially boils down to choosing the solution with the best parameters, such as:

Ease of use
Cost
Features and integrations
Build speed

Codemagic excels at all of the above. It is easy to set up and use, is much more affordable than its competitors, is feature-rich, and has a lot of useful integrations. And finally, Codemagic's virtual machines are really, really fast.

How to build a Chrome extension with Flutter Web

Codemagic — Tue, 01 Nov 2022 14:01:18 +0000

This article is written by Hrishikesh Pathak and originally posted to Codemagic blog.

What is a Google Chrome extension?

Google Chrome is the most popular web browser in the world. Chrome extensions are small programs that extend Chrome's functionality. Google Chrome has a standardized API through which extensions can perform various tasks in the browser.

In our daily lives, we use browser extensions for various tasks, like ad and tracker blocking, grammar correction, and translation. These extensions are made using JavaScript and use the Chrome extension API to interact with the browser. Since Flutter Web projects are compiled in JavaScript, we can build a Chrome extension with Flutter with some small tweaks.

In this tutorial, we are going to learn how to make a Chrome extension using Flutter Web. We will explore different use cases, tweaks, and build commands to get the best result. To get the most out of this guide, make sure to follow it to the end.

The final result of the tutorial will be a Flutter application that runs as a Chrome extension. It will look like this.

To create a Chrome extension with Flutter, we'll need to go through the following steps:

Configure the manifest.json file for Flutter Web
Deal with Content Security Policy to make our Chrome extension actually work in the browser environment
Configure Flutter Web
Add optional background scripts to our Flutter Chrome extension
Build our Flutter Web project
Build a Codemagic pipeline to build and deploy our Chrome extension to Chrome Web Store

Add a new manifest.json file

If you look in the web/ folder in a default Flutter project, you will see a manifest.json file. This file includes all the application configuration and aims to provide Progressive Web App (PWA) capabilities to our Flutter web application.

To learn more about building PWAs with Flutter, take a look at this blog post.

Google Chrome also requires a manifest.json file to register an extension. Therefore, to make our extension work, delete the contents inside the manifest.json file, and substitute them with the following code.

{
  "name": "Chromextension",
  "description": "A Flutter chrome extension",
  "version": "0.0.0.1",
  "manifest_version": 3,
  "content_security_policy": {
    "extension_pages": "script-src 'self' ; object-src 'self'"
  },
  "action": {
    "default_popup": "index.html",
    "default_icon": {
      "16": "icons/chromextension16.png",
      "32": "icons/chromextension32.png",
      "48": "icons/chromextension48.png",
      "128": "icons/chromextension128.png"
    }
  },
  "icons": {
    "16": "icons/chromextension16.png",
    "32": "icons/chromextension32.png",
    "48": "icons/chromextension48.png",
    "128": "icons/chromextension128.png"
  }
}

Here, you can change the name and description of the extension. Chrome extensions require icons in four different sizes. Use an image-resizing tool to make four versions of your extension icon with dimensions of 128x128, 48x48, 32x32, and 16x16 pixels. Then place the icons in the adjacent icons/ directory.

In the action field in the manifest.json file, set index.html as the default pop-up page. This way, when you click on the extension icon in the browser's top bar, the index.html page will pop up.

An explanation of Content Security Policy

Content Security Policy (CSP) is a security layer in the browser that protects users from cross-site scripting and data injection attacks. Normally, browsers trust the content coming from a server. Cross-site scripting misuses this trust and runs malicious code in the browser.

Using CSP, developers can specify a trusted domain in the HTTP header. A CSP-enabled browser will only execute scripts coming from that specific domain and ignore inline scripts and event-handling HTML attributes.

Take a look at the CSP in our manifest.json file. Here, we define script-src and object-src as self. Therefore, the browser won't execute inline scripts and scripts from another origin. In developer mode, you get a CSP error.

We will rectify this error in the next section. If you want to learn more about CSP on the web, you can read this CSP guide from MDN Web Docs.

Configure Flutter Web

To rectify the CSP error, remove all the script tags from the index.html file in the web/ directory. Then link the main.dart.js file inside the <body> tag. The main.dart.js is generated at build time and contains all the transpiled Dart and Flutter code.

Now, remove all the unnecessary meta tags from the index.html file, and add an explicit width and height to the <html> element. After all these changes, the final version of index.html looks like this.

<!DOCTYPE html>
<html style="height: 600px; width: 300px">
  <head>
    <meta charset="UTF-8" />
    <title>chromextension</title>
  </head>
  <body>
    <script src="main.dart.js" type="application/javascript"></script>
  </body>
</html>

Add a custom background script

Background scripts are event-based programs that react to certain events within the browser. These scripts are optional for Chrome extensions. If you're developing some feature in your extension that requires the execution of background code, then having custom background scripts comes in handy.

To add a background script to a Flutter Chrome extension, add a new file background.js inside the web/ directory.

Then, register the background script in your manifest.json file.

{
  "name": "Chromextension",
  "description": "A flutter chrome extension",
  "version": "0.0.0.1",
  "manifest_version": 3,
  "content_security_policy": {
    "extension_pages": "script-src 'self' ; object-src 'self'"
  },
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["contextMenus", "clipboardWrite", "clipboardRead"],
  "action": {
    "default_icon": {
      "16": "/images/scholarr16.png",
      "32": "/images/scholarr32.png",
      "48": "/images/scholarr48.png",
      "128": "/images/scholarr128.png"
    }
  },
  "icons": {
    "16": "/images/scholarr16.png",
    "32": "/images/scholarr32.png",
    "48": "/images/scholarr48.png",
    "128": "/images/scholarr128.png"
  }
}

The background script needs explicit permission to run in the browser. This is controlled with the permissions field in the manifest.json file.

Now, populate the background script with the logic to run upon a browser event. To learn more, check out the Chrome developer documentation.

Build a Flutter Web project

Flutter Web projects can be built with two types of renderers. The first, HTML renderer, uses a combination of HTML elements, CSS, Canvas elements, and SVG elements. The second, CanvasKit renderer, uses Skia as the rendering engine and draws pixel-perfect widgets. CanvasKit renderer adds about 2 MB to the download size of your application.

If we don't specify the renderer when we build our Flutter Web project using the flutter build web command, Flutter will use an HTML-rendered web app in mobile browsers and a CanvasKit-rendered web application in desktop browsers.

However, Chrome extensions don't support CanvasKit-rendered applications. Therefore, add the --web-renderer html flag at build time to generate only an HTML-rendered application.

Another issue with Flutter Web is the dynamically generated code in the build output. This behavior gives us CSP errors in the browser. To disable dynamically generated code, use the --csp flag with the Flutter build command.

Therefore, to make an optimized Chrome extension using Flutter, the build command should look like this.

flutter build web --web-renderer html --csp

Integrate a Codemagic CI/CD pipeline

Codemagic is a CI/CD platform that facilitates the building and deployment of Flutter applications. We can use it to build and deploy our Flutter app for any platform, including the Flutter Web Chrome extension that we've just made. Create a Codemagic account today to get 500 build minutes for free.

Create a Codemagic account

Go to your Codemagic project dashboard and add a new application. Select your repository provider from the pop-up list. My code is hosted on GitHub, so I am selecting GitHub here.

Now, find your project repository in the dropdown menu, and select "Flutter App (via Workflow Editor)" as the project type.

For the build platform option, select web builds.

In the build argument, add the --web-renderer and --csp flags.

Finally, save your changes and start your Codemagic build.

Now you can download the generated artifacts and publish to Chrome Web Store. Let's do that!

Publish the Chrome extension to Chrome Web Store

After you've built your Chrome extension, it's possible to automatically publish in Chrome Web Store using a Codemagic post-publish script. Before following the steps in this section, make sure to sign up for a Chrome Developer Account.

It's also important to note that you should publish the extension manually the first time. But afterward, you can automate the deployment of your Chrome extension with Codemagic CI/CD.

So, let's start by getting the credentials we'll need to publish the extension for the first time.

Acquire the required credentials

Go to the Google Cloud Console and create a new project. In the search bar, search for "Chrome Web Store API". Click on the first result and enable the API.

Then click on the OAuthConsentScreen and select the user type "External". Fill out all the application details in the respective fields, click "Save", and continue to the next step. You can skip the "Scopes" tab and continue. Then add your email as a test user and click "Save and continue".

To get the access key, go to "Credentials" and select the "Create credentials" option. From the dropdown list, select "OAuth client ID".

For the application type, select "Desktop App", fill out the name, and click "Create". Now, a pop-up containing your client ID and client secret should appear. You can download the JSON file and save it in a secure place.

To work with the Chrome Web Store API, you'll need to have an access token. To get the access token, paste this URL https://accounts.google.com/o/oauth2/auth?response_type=code&scope=https://www.googleapis.com/auth/chromewebstore&client_id=$CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob in your browser, and replace $client_ID with our app's client ID.

When your browser resolves the URL, a Google OAuth page appears. Sign in with the email you have set as the test user inside the OAuthConsentScreen.

After you have been successfully authorized, you will get an authorization code. We'll use this code to request an access token.

To generate the access token, you have to make a request with your client ID, client secret, and the authorization code we've found in the previous step. I am using curl for this purpose.

curl "https://accounts.google.com/o/oauth2/token" -d\
"client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&code=$CODE&grant_type=authorization_code&redirect_uri=urn:ietf:wg:oauth:2.0:oob"

Replace $CLIENT_ID, $CLIENT_SECRET, and $CODE with their respective values. The response to this request should look like this.

{
  "access_token" : "ya29.a0Aa4xrXO...",
  "expires_in" : 3599,
  "refresh_token" : "1//0gZyg...",
  "scope": "https://www.googleapis.com/auth/chromewebstore",
  "token_type" : "Bearer",
}

Now you can use this access token to interact with the Chrome Web Store Publish API.

Publish the Chrome extension using the Chrome Web Store API

Before publishing, make sure to enable two-step authentication in your Google account.

Then go to your Chrome Web Store dashboard and create a new item. Fill out the store listing and privacy practices page.

After properly setting things up, we are ready to publish our extension to Chrome Web Store. I am using curl to make the request to the Chrome Web Store API.

 curl\
-H "Authorization: Bearer $TOKEN"\
-H "x-goog-api-version: 2"\
-X POST\
-T $FILE_NAME\
-v\
https://www.googleapis.com/upload/chromewebstore/v1.1/items

Here, fill in $TOKEN and $FILE_NAME with the access token and the ZIP file with the extension, respectively.

How to automate publishing a Chrome extension with a Codemagic post-publish script

After finishing building our Flutter project with Codemagic, click on the gear icon at the end to reveal the post-publish script section.

To access the generated artifacts from the build stage, add this script inside the post-publish script section.

ARTIFACT_TYPE=".zip"
ARTIFACT_URL=$(echo $CM_ARTIFACT_LINKS | jq -r '.[] | select(.name | endswith("'"$ARTIFACT_TYPE"'")) | .url')

Here, the ARTIFACT_URL contains the URL to the generated ZIP file in the build stage.

Now we can use this URL in our curl script to directly upload to Chrome Web Store.

curl\
-H "Authorization: Bearer $TOKEN"\
-H "x-goog-api-version: 2"\
-X POST\
--url $ARTIFACT_URL
-v\
https://www.googleapis.com/upload/chromewebstore/v1.1/items

Here, we replace the -T flag from the previous curl script with the --url flag to directly upload the generated artifact. Now, whenever you build your extension, it automatically uploads the project to Chrome Web Store.

You can use this official guide to explore more use cases of the Chrome Web Store API.

Conclusion

This is a beginner's guide to making a Google Chrome extension using Flutter Web. If you have followed all the steps, by now, you've learned how to configure the different files of your Flutter Web app so that it can be a Chrome extension, build the app, publish it to Chrome Web Store, and automate the process with Codemagic CI/CD.

You can find the sample project for making a Chrome extension with Flutter on GitHub.

Codemagic is a CI/CD tool for Flutter and other mobile developers.

Dr. Riverpod: How I learned to stop worrying and love state management

Codemagic — Tue, 01 Nov 2022 13:50:46 +0000

This post is written by Alessio Salvadorini and originally posted Codemagic blog.

Overview

State management is a very controversial topic in the Flutterverse, with many holding strong opinions on it.

In the last few weeks, my Twitter feed has been overwhelmed with threads about state management, covering the entire spectrum of opinions, from GetX/BLoC/Riverpod fanatics on one side to a few rare enlightened ones on the other side who recommend not using any state management at all.

While I personally enjoyed almost all of them, the impact on the Flutter community has been quite severe.

When I asked my readers about writing this article in a typical TDD (Twitter-Driven Development, ©® @mkobuolys) approach, about a third voted no, and half of them were so fed up with state management that they recommended that I shoot myself, metaphorically speaking.

So, keep all this in mind while I walk you through this article about state management to show you how to choose the best state management solution for Flutter at the end of 2022 (and perhaps in 2023 as well). It's worth noting that this advice is based entirely on my own opinion, and you're always welcome to disagree. However, we first need to understand how and why we ended up in this situation, so bear with me for a few minutes longer.

The state of Flutter state management: How did we get here?

If you haven't done so yet, I strongly recommend you watch these two videos: the first shows Filip Hracek and Matt Sullivan on the Google I/O stage in May 2018 introducing BLoC (the pattern) to all of us; the second shows the same Filip and Matt on the very same stage but in May 2019, exactly one year later, introducing pragmatic state management.

However, in between those two videos, I think something important yet fleeting happened. A big misunderstanding was born, and it impacted our community more than I initially realized.

To understand the context at the time when the first video was released, we need to remember that the community was already asking Google, and the Flutter team in particular, for a recommended approach for state management. Also, Flutter wasn't as relevant as it is nowadays. This meant that very few videos at Google I/O were about Flutter, so one about state management felt even more relevant --- or at least, the community perceived it to be.

Shortly after the first video was released, a talented developer who needs no introduction, Felix Angelov, started to develop BLoC (the package).

It quickly became the de facto standard for state management, one of the most used packages by individual developers and big companies, and the subject of mandatory questions at job interviews. Basically, it was essential for anyone who wanted to become a Flutter developer to understand it.

This happened around the time when I was starting to look into Flutter. I quickly reached a point when the more I was coding in Android, the more I wanted to code in Flutter, and the more I was coding in Flutter, the more I wanted to code in Flutter. So, by the time I tried to wrap my head around BLoC (the pattern) and BLoC (the library), the second video was released, introducing what immediately felt like a much simpler approach to state management.

But, as the demand for a state management solution had already been met (or at least the community thought so), and everyone was already using BLoC (the package), I think the second video went almost unnoticed.

It does, however, contain this little gem starting at around 19:20, where Filip and Matt mention that even though Google also open sourced a similar package based on scope model, they would instead recommend Provider, a library created by a young and talented French developer, Remi Rousselet.

And Provider wasn't the only alternative to BLoC (the package) because many other options were also flourishing: Redux (which was already familiar to developers coming from JavaScript), get_it, MobX, the controversial GetX, and many, many more.

You can find a non-exhaustive list in the official Flutter docs.

Given all that, it's quite easy to understand how, by the end of 2022, we're still in a messy and unclear situation.

It's frustratingly difficult for beginners and new developers approaching Flutter to make a choice unless they have lots of time to spend learning about the topic.

The Flutter team has been mainly silent about this topic, and I don't blame them, as they can't (and, IMHO, shouldn't) suggest one state management technique that would be suitable for all kinds of apps, nor can they add one directly into the SDK.

The only way to resolve this situation is to end at the beginning.

Isn't this where we came in?

Believe me or not: Not all states need a state management technique. A state can be classified into one of two distinct types: ephemeral or application state.

You can think of the ephemeral state as a state that is self-contained into a widget, which doesn't need to be shared or accessed from anywhere else.

An example of an ephemeral state is the index of the actual page in a page viewer. For an ephemeral state, you don't need any state management technique, and setState() and StatefulWidget work perfectly fine for handling this case.

Think of the application state as a state that is shared between the different views of your app or that needs to be restored between two separate user sessions.

In this case, you need to move the state away from your view and into a state holder class. Examples of an application state are the settings or the login.

For an application state, you do need a state management technique.

Since you are going to pick only one, you want to choose carefully. And to choose carefully, you need to be able to compare your options. And to be able to compare, we need to agree on the metrics of the comparison.

Introducing metrics: Measuring how good a state management solution is

The only way we can choose which one is the "best" state management solution is to agree on how we define "best."

There are many different types of apps, and more will come in the future that we can't even imagine now. Therefore, it's practically impossible to suggest one state management technique to rule them all.

So far, I have found only two sources that have helped me compare state management techniques.

The first source is by my mate Mike Rydstrom, who created an exhaustive picture comparing the top 30 state management packages:

As you can see, this picture ranks the packages by package likes. It also includes extra information, like if a given package is null safe (NS), the percentage of test coverage (CodeCov), the percentage of API docs' completeness (API docs), a summary (Points), the package's popularity, GitHub stars, the ratio of likes to stars, and the ratio of open to closed issues.

That's a lot of info to crunch for one single picture.

It's a good start, with Provider, BLoC (the package), get_it, and Riverpod placing in the top rankings (2, 3, 4, and 5, respectively). This is all fine until you look at the highest-ranked package, get (formally known as GetX), which, for me, is an anti-pattern and a no-go.

The second source is a bachelor's thesis titled "State management approaches in Flutter" by Dmitrii Slepnev, published in December 2020.

In this thesis, Slepnev categorizes some of the most common state management techniques. He chooses six criteria, some of which are still subject to opinion, but they are well defined and easy to understand: complexity, amount of boilerplate code, code generation, time travel support, scalability, and testability.

An intuitive summary is provided in Table 11 of the study.

As you can see, this table makes comparing state management techniques easy, and it may help you to choose one based on such metrics. Likewise, after you choose your state management technique, this table could help you profile it.

Now that we have defined at least some metrics based on these two sources, let's see how to apply them.

And the winner is...

Just like many of you at this point, I was initially confused and overwhelmed by all the possibilities and alternatives we have when it comes to state management in Flutter.

This is definitely a healthy sign, as it clearly indicates that Flutter is developing, but it could also lead to a negative downward spiral.

So, I looked into and tried some of the different options. I strongly recommend you try them out too and not take anyone's opinion for granted, not even mine.

Try to implement and re-implement a sample app with different state management techniques, compare them, and see which one feels better to you and for what reasons. If possible, try to make the metrics explicit.

There is also a non-official code sample app that compares some of the alternatives.

For me, simplicity was the key, as simplicity is one of the most important values in my life.

After I tried some of them, I decided which one was the best for me: Provider/Riverpod. This choice was supported by Table 11 in Slepnev's study. Since I prefer simplicity, I want the complexity to be as low as possible. Additionally, I want minimal boilerplate code, I don't want any code generation, time travel is irrelevant to me, and scalability and testability must be decently good.

You can find a tutorial that will help you get started with Riverpod here

This decision is also confirmed by Mike's picture, as I want a well-maintained package.

Last but not least, this choice is supported by the official Flutter docs: Simple state management is the only officially documented state management technique.

What is simple state management?

Simple state management, aka pragmatic state management, is based on Provider+ChangeNotifier. It's well documented, and there's a code sample.

In case you don't know, Riverpod is a second take on Provider made by the same author, Remi Rousselet. You can think of Riverpod as a "Provider 2.0," a better version of Provider. If you're still using Provider, you should migrate to Riverpod, as it's very straightforward.

So, you can easily implement simple state management nowadays with Riverpod and ChangeNotifier.

Note: ChangeNotifier, ValueNotifier (from SDK), and StateNotifier (from Remi) are all interchangeable. Since they all accomplish the same thing, you can use the one you prefer as long as you know what you're doing and why.

Simple state management is very simple. It is built on three pillars:

The state holder class encapsulates the application state. It's responsible for changing the state and notifying about state changes; this is done with the ChangeNotifier class.
The UI needs to have access to your state holder class (the ChangeNotifier); this is done through Riverpod with its provider classes (ChangeNotifierProvider, ValueNotifierProvider, StateNotifierProvider, etc.).
The UI needs to consume the state changes; this is done through Riverpod with its consumer classes (Consumer, ConsumerWidget, ConsumerStatefulWidget).

Build your Flutter apps faster with Apple M1 VMs. Learn more!

Conclusion

This article is an extension of part of my talk for Flutter Vikings 2022.

In this article, I gave you some reasons why state management is a complex topic for Flutter and some metrics that can help you decide between the many options available. I recommend that you choose the safest bet (Riverpod) and the metric used (simplicity).

Now that you've chosen your state management technique, though, keep in mind that it's not enough to create a scalable and robust app in a production environment. You'll need a whole architecture.

Luckily, Riverpod is much more than a tool for state management; it's a reactive caching and data-binding framework, and we can build the whole app architecture around Riverpod. Curious to know how?

I kept this article codeless on purpose, as I'll follow up with a deep dive into architecture. So if you're interested, keep an eye on this blog. I'll keep you posted!

To be continued...

Codemagic is a CI/CD tool for Flutter and other mobile developers.

Flutter widgets cheat sheet

Codemagic — Tue, 01 Nov 2022 13:43:05 +0000

This post is written by Godwin Alexander Ekainu and originally posted to Codemagic blog.

Flutter is an open-source tool designed to build fast and beautiful applications across multiple platforms. The Flutter SDK has been widely adopted for developing mobile applications, and many developers are learning Flutter every day. It is important to create content that can help them do this, and that's the aim of this blog post! So, we've prepared a simple cheat sheet of different Flutter widgets (and in Flutter, everything is a widget!), which you can use to build your Flutter apps.

We've grouped the widgets into several categories:

Interaction widgets. These help make your Flutter app interactive.
Input widgets. These widgets are used to handle user input.
Alignment and layout widgets. You use these widgets everywhere to position other widgets on the screen relative to one another and organize them into structures.
Scrollable widgets. These widgets come in handy when you need to create scrollable lists and galleries.
Structure widgets. These are the foundational widgets for your app.
Paint widgets. These widgets allow you to customize the design of your app.
Button widgets. These are, as you might have guessed, for creating buttons.
Basic navigation. To navigate between screens, you'll need navigation. We'll provide a basic example of navigation in this article.

If you don't understand the concept of widgets, you can refer to our Flutter From Scratch video on this topic.

How do you use this Flutter widgets cheat sheet? Just copy-paste the code for the widgets you want to use in your app, and modify it to incorporate the logic you need. Let's get started!

1. Interaction widgets

Interaction widgets make your application dynamic and provide a good user experience, so it's essential to understand how to use them.

GestureDetector

GestureDetector is a widget that responds to events or gestures that correspond to its non-callbacks.

onTap
onTapUp
onTapDown
onLongPress
onDoubleTap
onHorizontalDragStart
onVerticalDragDown
onPanDown
onScaleStart

You can use this gesture detector to create custom buttons or clickable text or pictures.

To add a gesture detector, use the code below:

    GestureDetector(

      onTap: () {
        const snackBar = SnackBar(content: Text('Tap'));

        ScaffoldMessenger.of(context).showSnackBar(snackBar);
      },
      // The custom button
      child: Container(
        padding: const EdgeInsets.all(12.0),
        decoration: BoxDecoration(
          color: Colors.lightBlue,
          borderRadius: BorderRadius.circular(8.0),
        ),
        child: const Text('My Button'),
      ),
    )

AlertDialog

The AlertDialog widget creates a window to display crucial information with options that allow the user to make decisions.

To add an alert dialog to your app, you can use the following code:

     Future<void> _showMyDialog() async {
      return showDialog<void>(
        context: context,
        barrierDismissible: false, // user must tap button!
        builder: (BuildContext context) {
          return AlertDialog(
            title: const Text('Cheat Sheet'),
            content: SingleChildScrollView(
              child: ListBody(
                children: const <Widget>[
                  Text('This is a demo alert dialog.'),
                  Text('Would you like to approve of this message?'),
                ],
              ),
            ),
            actions: <Widget>[
              TextButton(
                child: const Text('Approve'),
                onPressed: () {
                  Navigator.of(context).pop();
                },
              ),
            ],
          );
        },
      );
    }

SnackBar

The SnackBar widget is used to briefly tell a user that an action has taken place. For example, you can delete an item that triggers a snackbar, which tells the user that an item has just been deleted.

To add a snackbar to your application, use the code below:

    Center(
            child: ElevatedButton(
              onPressed: () {
              final snackBar =  SnackBar(
                content: const Text('Yay! A SnackBar!'),
                action: SnackBarAction(
                  label: 'Undo',
                  onPressed: () {
                   Text('data');
                  },
                ),
              );
                  ScaffoldMessenger.of(context).showSnackBar(snackBar);
              },
              child: const Text('Show snackbar'),
            ),
          ),

Dismissable

You can use a Dismissable widget to remove or dismiss items from a list. You can swipe left or right to remove any item.

Use the code below to implement this feature:

    List<String> items = <String>[
        'banana',
        'strawberry',
        'apple'
        'orange'
        'cat'
        'bobcat'
      ];
    ListView.builder(
              itemCount: items.length,
              padding: const EdgeInsets.symmetric(vertical: 16),
              itemBuilder: (BuildContext context, index) {
                return Dismissible(
                  background: Container(
                    color: Colors.green,
                  ),
                  key: Key(items[index]),
                  onDismissed: (DismissDirection direction) {
                    setState(() {
                      items.removeAt(index);
                    });
                  },
                  child: ListTile(
                    title: Text(
                      'Item ${items[index]}',
                    ),
                  ),
                );
              },
            ),

InteractiveViewer

If you have a big picture that doesn't fit on the screen, you can use the InteractiveViewer widget to enable it to fit on the screen by allowing the user to zoom in and out of the picture.

    InteractiveViewer(
            boundaryMargin: const EdgeInsets.all(20.0),
            child: Container(
              decoration: const BoxDecoration(
                gradient: LinearGradient(
                  begin: Alignment.topCenter,
                  end: Alignment.bottomCenter,
                  colors: <Color>[Colors.blue, Colors.yellow],
                  stops: <double>[0.0, 1.0],
                ),
              ),
            ),
          ),

2. Input widgets

Input widgets are a very important part of modern-day Flutter applications. For example, they are used to create an account, log in, or even perform a simple search.

Flutter forms

You can create a login and signup form using these widgets.

Try creating a form using the Forms widget and TextFormFields widget:

      class MyApp extends StatelessWidget {
      const MyApp({Key? key}) : super(key: key);
      @override
      Widget build(BuildContext context) {
        const appTitle = 'Flutter Form Demo';
        return MaterialApp(
          title: appTitle,
          home: Scaffold(
            appBar: AppBar(
              title: const Text(appTitle),
            ),
            body: const MyCustomForm(),
          ),
        );
      }
    }
    // Create a Form widget
    class MyCustomForm extends StatefulWidget {
      const MyCustomForm({Key? key}) : super(key: key);
      @override
      MyCustomFormState createState() {
        return MyCustomFormState();
      }
    }
    class MyCustomFormState extends State<MyCustomForm> {
      final formKey = GlobalKey<FormState>();
      @override
      Widget build(BuildContext context) {
        // Build a Form widget using the formKey created above
        return Form(
          key: formKey,
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: <Widget>[
              TextFormField(
                decoration: const InputDecoration(
                  icon:  Icon(Icons.person),
                  hintText: 'Enter your name',
                  labelText: 'Name',
                ),
              ),
              TextFormField(
                decoration: const InputDecoration(
                  icon: Icon(Icons.calendar_today),
                  hintText: 'Enter your date of birth',
                  labelText: 'Dob',
                ),
              ),
              const ElevatedButton(
                child:  Text('Submit'),
                onPressed: null,
              ),
            ],
          ),
        );
      }
    }

Autocomplete

This widget can come in handy in search boxes.

To add autocomplete to your Flutter application, you can use the following code snippet. The options to be displayed are determined by the optionsBuilder and rendered by the optionsViewBuilder.

    // have a list of words or names from a remote source or package
    const List<String> _kOptions = <String>[
        'aardvark',
        'bobcat',
        'chameleon',
      ];
    // use the Autocomplete widget to make selections
    Autocomplete<String>(
          optionsBuilder: (TextEditingValue textEditingValue) {
            if (textEditingValue.text == '') {
              return const Iterable<String>.empty();
            }
            return _kOptions.where((String option) {
              return option.contains(textEditingValue.text.toLowerCase());
            });
          },
          onSelected: (String selection) {
            debugPrint('You just selected $selection');
          },
        );

TextField

TextField is one of the most fundamental and commonly used widgets for keyboard input.

    TextField(
      obscureText: true,
      decoration: InputDecoration(
        border: OutlineInputBorder(),
        labelText: 'Password',
      ),
    )

3. Alignment and layout widgets cheat sheet

These widgets are very important for building UIs in Flutter.

Center

This widget centers a child within itself.

    Center( child: Text('Center me'))

Expanded

The Expanded widget expands the child of a Row or Column to fill any available space.

For example, you can use it to build a UI that fills the screen with just three containers or pictures. Theoretically, we can just specify their heights, but remember that there are different screen sizes for different devices, including tablets such as iPad devices. The expanded widget can help you create a more responsive design that can easily fit all screen sizes.

    Row(
              children: <Widget>[
                Expanded(
                  flex: 2,
                  child: Container(
                    color: Colors.amber,
                    height: 100,
                  ),
                ),
                Container(
                  color: Colors.blue,
                  height: 100,
                  width: 50,
                ),
                Expanded(
                  child: Container(
                    color: Colors.amber,
                    height: 100,
                  ),
                ),
              ],
            ),

Align

The Align widget aligns its child within itself. This widget is very flexible and can take the size of its child.

The child can be placed at different points within its parent widget using the alignment property, as shown below:

    Container(
        height: 120.0,
        width: 120.0,
        color: Colors.blue[50],
        child: const Align(
          alignment: Alignment.topRight,
          child: FlutterLogo(
            size: 60,
          ),
        ),
      ),

Row

The Row widget takes a list of widgets and arranges them horizontally. You will likely use this widget a lot when making layouts in your code.

    Row(
            children: [
              ElevatedButton(
                child: const Text('Widget 1'),
                onPressed: () => Navigator.pushNamed(context, '/second'),
              ),
               ElevatedButton(
                child: const Text('Widget 2'),
                onPressed: () => Navigator.pushNamed(context, '/third'),
              ),
               ElevatedButton(
                child: const Text('Widget 3'),
                onPressed: () => Navigator.pushNamed(context, '/fourth'),
              ),
            ],
          ),

Column

The Column widget allows you to arrange a list of widgets vertically, similar to how the Row widget aligns them horizontally.

    Column(
      children: const <Widget>[
        Text('Deliver features faster'),
        Text('Craft beautiful UIs'),
        Expanded(
          child: FittedBox(
            fit: BoxFit.contain,
            child: FlutterLogo(),
          ),
        ),
      ],
    )

SizedBox

Use SizedBox to give a specific size to its child widget or provide some white space between widgets.

    const SizedBox(
      width: 200.0,
      height: 300.0,
      child: Card(child: Text('Size me!')),
    )

BaseLine

Use the BaseLine widget to position the child widget according to the starting point of the parent widget.

    Center(
          child: Container(
                  width: 100,
                  height: 100,
                  color: Colors.green,
                  child: Baseline(
                    baseline: 50,
                    baselineType: TextBaseline.ideographic,
                    child: Container(
                      width: 50,
                      height: 50,
                      color: Colors.purple,
                    ),
                  ),
                ),
        );

LimitedBox

Use this widget to assign a default size to a list of widgets that are unconstrained.

    LimitedBox(
             maxHeight: 150,
             maxWidth: 150,
             child: Container(
             color: Colors.red,
            )
           )

Padding

Use the Padding widget to provide space around its child. The padding widget adds space around its child using the abstract EdgeInsetsGeometry class.

The padding property of the padding widget accepts the EdgeInsets object, which allows you to add different types of padding, including padding only in certain places using EdgeInsets.only or from different angles using EdgeInsets.fromLTRB.

    const Card(
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Text('Hello World!'),
      ),
    )

4. Scrollable widgets

ListView Builder

ListView Builder is the most used scrollable widget. It displays its children in the scroll direction one after the other. For example, if you have a long list that is dynamically created, you can use Listview.builder to display it.

Use the following code to get started:

    final List<String> entries = <String>['A', 'B', 'C'];
    ListView.builder(
      padding: const EdgeInsets.all(8),
      itemCount: entries.length,
      itemBuilder: (BuildContext context, int index) {
        return Container(
          height: 50,
          color: Colors.amber[colorCodes[index]],
          child: Center(child: Text('Entry ${entries[index]}')),
        );
      }

SingleChildScrollView

The SingleChildScrollView widget will come in handy if you have a list of items that you initially didn't intend for the user to scroll through, but the requirements change upon implementation. In this case, you can quickly wrap the parent widget with a SingleChildScrollView to make it scrollable.

    SingleChildScrollView(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            mainAxisAlignment: MainAxisAlignment.spaceAround,
            children: <Widget>[
              Container(
                color:  Colors.red,
                height: 300.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
              Container(
                color: Colors.blue,
                height: 250.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
              Container(
                color: Colors.green,
                height: 250.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
              Container(
                color: Colors.purple,
                height: 250.0,
                alignment: Alignment.center,
                child: const Text('Fixed Height Content'),
              ),
            ],
          ),
        );

5. Structure widgets

These are the widgets that compose your app. In this Flutter widget cheat sheet, we will only be highlighting two of them: Scaffold and Loader.

Scaffold

Use Scaffold widgets for all your application layers.

    Scaffold(
          appBar: AppBar(),
          body: Row(
            children: [
              ElevatedButton(
                child: const Text('Widget 1'),
                onPressed: () => Navigator.pushNamed(context, '/second'),
              ),
          ),

Adding Loader

Create Loaders for your app when making an API request.

    class SomeWidget extends StatefulWidget {
      @override
      _SomeWidgetState createState() => _SomeWidgetState();
    }
    class _SomeWidgetState extends State<SomeWidget> {
      late Future future;
      @override
      void initState() {
        future = Future.delayed(const Duration(seconds: 8));
        super.initState();
      }
      @override
      Widget build(BuildContext context) {
        return FutureBuilder(
          future: future,
          builder: (context, snapshot) {
            return snapshot.connectionState == ConnectionState.done
                ? const Text('Loaded')
                : const CircularProgressIndicator();
          },
        );
      }
    }

6. Paint widgets

Painting effects can give a finished look to your app's design.

InkWell

With the InkWell widget, you can create ink splash effects on images or custom buttons when you click on them.

    class _SomeWidgetState extends State<SomeWidget> {
      @override
      Widget build(BuildContext context) {
        Image img = Image.network(
            'https://images.unsplash.com/photo-1592194996308-7b43878e84a6?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=687&q=80');
        return Material(
          child: Ink.image(
            fit: BoxFit.fill,
            width: 300,
            height: 300,
            image: img.image,
            child: InkWell(
              onTap: () {
                print('image');
              },
              child: const Align(
                child: Padding(
                  padding: EdgeInsets.all(10.0),
                  child: Text(
                    'PUFFIN',
                    style: TextStyle(
                      fontWeight: FontWeight.w900,
                      color: Colors.white,
                    ),
                  ),
                ),
              ),
            ),
          ),
        );
      }
    }

DecoratedBox

DecoratedBox, together with BoxDecoration, helps you add more styling to your container widget.

    Container(
          decoration: const BoxDecoration(
            borderRadius: BorderRadius.all(
              Radius.circular(12),
            ),
            gradient:RadialGradient(
          center: Alignment(-0.5, -0.6),
          radius: 0.15,
          colors: <Color>[
            Color(0xFFEEEEEE),
            Color(0xFF111133),
          ],
          stops: <double>[0.9, 1.0],
        )));

ClipRect

Use ClipRect to clip the child within different shapes.

    class DecorateContainer extends StatelessWidget {
       const DecorateContainer(Key? key, this.image) : super(key: key);
     final Image image;
      @override
      Widget build(BuildContext context) {
        return ClipRect(
      child: Container(
        child: Align(
          alignment: Alignment.center,
            widthFactor: 0.4,
            heightFactor: 1.0,
            child: image
        ),
      ),
    );
      }
    }

ClipPath

With the ClipPath widget, you can give any shape to the child widget. This means you can use it to draw any shape of your choice or according to your UI requirements with less code.

     // body of your app
    ClipPath(
            child: Container(
              width: MediaQuery.of(context).size.width,
              height: 250,
              color: Colors.red,
            ),
            clipper: CustomClipPath(),
          ),

    // custom class
     class CustomClipPath extends CustomClipper<Path> {
      var radius=5.0;
      @override
      Path getClip(Size size) {
        Path path = Path();
        path.lineTo(size.width / 2, size.height);
        path.lineTo(size.width, 0.0);
        return path;
      }
      @override
      bool shouldReclip(CustomClipper<Path> oldClipper) => false;
    }

7. Buttons

There are many types of buttons in Flutter, so we'll only suggest the most useful ones in this cheat sheet.

TextButton

This is a Material button with text that has no borders.

     TextButton(
                      style: TextButton.styleFrom(
                        padding: const EdgeInsets.all(16.0),
                        primary: Colors.white,
                        textStyle: const TextStyle(fontSize: 20),
                      ),
                      onPressed: () {},
                      child: const Text('Gradient'),
                    ),

ElevatedButton

ElevatedButton is a Material button that elevates when pressed. Avoid using elevated buttons on widgets that are already elevated, like dialogs.

    ElevatedButton(
                style: ElevatedButton.styleFrom(),
                onPressed: () {},
                child: const Text('Enabled'),
              ),

FloatingActionButton

Use FloatingActionButton to create a primary action on the screen.

    Scaffold(
          appBar: AppBar(
            title: const Text('Floating Action Button'),
          ),
          body: const Center(child: Text('Press the button below!')),
          floatingActionButton: FloatingActionButton(
            onPressed: () {
              // on pressed
            },
            backgroundColor: Colors.green,
            child: const Icon(Icons.navigation),
          ),
        );

8. Basic navigation

Named routing can be used for small to medium-sized projects. Alternatively, you can use the Navigator API, which provides various routing functions.

Flutter provides named routing to enable users to navigate your application:

    void main() {
      runApp(MaterialApp(
        initialRoute: '/',
        routes: {
          '/' : ((context) => const FirstScreen()),
          '/second':(context) => const SecondScreen()
        },
        home: const MyApp()));
    }
    class MyApp extends StatelessWidget {
      const MyApp({Key? key}) : super(key: key);
      @override
      Widget build(BuildContext context) {
        return Scaffold(
            appBar: AppBar(
              title: const Text('Navigation'),
            ),
            body:const FirstScreen()

        );
      }
    }

    class FirstScreen extends StatelessWidget {
      const FirstScreen({Key? key}) : super(key: key);
      @override
      Widget build(BuildContext context) {
        return Center(
          child: ElevatedButton(
            child: const Text('Go to SecondScreen'),
            onPressed: () => Navigator.pushNamed(context, '/second'),
          ),
        );
      }
    }
    // can add this in a new file
    class SecondScreen extends StatelessWidget {
      const SecondScreen({Key? key}) : super(key: key);

      @override
      Widget build(BuildContext context) {
        return ElevatedButton(
          child:const Text('Go back!'),
          onPressed: () => Navigator.pop(context),
        );
      }
    }

To learn more about Flutter Navigator 2.0, read this article.

Conclusion

We have created this list of Flutter widgets as a quick reference for you while you build your Flutter app. We hope you have learned something new about these widgets that can help you improve the functionality of your Flutter application.

We have an ebook that covers a list of libraries commonly used by Flutter developers, including networking, state management, and more. You can also watch our Flutter From Scratch tutorial, which goes into detail about how to use these libraries and widgets.

Codemagic is a CI/CD tool for Flutter and other mobile developers.