DEV Community: George Ikwegbu Chinedu

$$$$$$BACKUP FOR | Shipping a Safe Rollback: Downgrading a Drift (SQLite) Database in Flutter Without Losing User Data

George Ikwegbu Chinedu — Thu, 22 Oct 2026 20:30:26 +0000

You're about to ship a release that bumps your local database schema. Being careful, you also prepare a rollback build, the version currently in production, so that if the new release has problems you can push the old one straight back out.

Then you test the rollback, and it crashes on startup.

This post covers:

Why Drift refuses to "upgrade" to a lower schema version
The fix (and why the obvious fix doesn't work)
A bug that's easy to introduce while making the fix
The git worktree workflow for building both versions side by side
Building three test APKs so QA can test upgrade → rollback → re-upgrade without losing data

All names, branches and paths below are made up for the article.

The setup

Production (v1.4.1) uses database schema 11.
The new release (v1.5.0, branch feature/new-release) moves to schema 12. It adds three nullable columns:
- settings.dark_mode_enabled
- settings.beta_features_enabled
- reports.submitted_at
The rollback build (branch release/1.4.2) is production code (schema 11) with a higher build number, so the stores treat it as an update.

The local database is Drift (version 2.x), and migrations use Drift's generated stepByStep helper:

@override
int get schemaVersion => 11;

@override
MigrationStrategy get migration => MigrationStrategy(
  onCreate: (m) async {
    await m.createAll();
    await seedDefaultSettings();
  },
  onUpgrade: stepByStep(
    from1To2: (m, schema) async { /* ... */ },
    // ...
    from10To11: (m, schema) async { /* ... */ },
  ),
  beforeOpen: (details) async {
    await customStatement('PRAGMA foreign_keys = ON');
    await validateDatabaseSchema(this); // debug-only check
  },
);

The problem

On a device that had run the schema 12 build, installing the schema 11 rollback build crashed on startup with:

StateError: runMigrationSteps was asked to downgrade from versions 12 to 11.
Migration steps can only upgrade. This might happen if users downgrade app versions.

First attempt: handle it in `beforeOpen` (didn't work)

My first idea was to detect the downgrade in beforeOpen, then drop and recreate every table:

beforeOpen: (details) async {
  if (details.versionBefore != null && details.versionBefore! > schemaVersion) {
    final m = createMigrator();
    await customStatement('PRAGMA foreign_keys = OFF');
    for (final table in allTables) {
      await m.drop(table);
    }
    await m.createAll();
    await customStatement('PRAGMA foreign_keys = ON');
  }
  // ...
},

It made no difference. The same error kept appearing, and the code inside the if never ran.

Why: Drift calls `onUpgrade` before `beforeOpen`, including for downgrades

In Drift's source (lib/src/runtime/api/db_base.dart), the open sequence looks roughly like this:

if (details.wasCreated) {
  await _resolvedMigration.onCreate(migrator);
} else if (details.hadUpgrade) {           // versionBefore != versionNow
  await _resolvedMigration.onUpgrade(migrator, details.versionBefore!, details.versionNow);
}

await _resolvedMigration.beforeOpen?.call(details);

Note that hadUpgrade is just versionBefore != versionNow. Drift doesn't distinguish upgrades from downgrades. Both go through onUpgrade, and MigrationStrategy's own docs say so: "Schema version upgrades and downgrades will both be run here."

stepByStep then calls VersionedSchema.runMigrationSteps, which refuses to downgrade:

if (from > to) {
  throw StateError('runMigrationSteps was asked to downgrade from versions $from to $to. ...');
}

So the exception is thrown in onUpgrade, the database fails to open, and beforeOpen never runs.

Why dropping everything was a bad idea anyway

Even if it had worked, dropping every table and recreating it would have:

Lost unsynced data. Anything the user created offline and hadn't uploaded yet would be gone.
Logged users out, if session or settings data lives in the database.
Skipped the default seed data. onCreate seeds default settings, but a bare createAll() doesn't.

A rollback is meant to make things safer for users, and wiping their data on the way back defeats that.

What the schema change actually was

Before choosing a fix, I compared the two schemas. Schema 12 only added nullable columns.

That matters because Drift-generated queries always list columns explicitly:

SELECT "id", "name", ... FROM "settings";
INSERT INTO "reports" ("id", "title", ...) VALUES (...);

An older build that doesn't know about dark_mode_enabled never selects it, and on insert SQLite stores NULL. Extra nullable columns (or columns with a default) are harmless to older code.

So the safest downgrade is to do nothing: keep the data and let Drift record the lower version.

⚠️ This only works when the newer schema is additive. If it renamed or dropped columns, added NOT NULL columns without defaults, or changed table shapes, you'd need a real downgrade migration (for example m.alterTable(TableMigration(...)) to rebuild the table).

The fix

1. Handle the downgrade in `onUpgrade`, before `stepByStep` runs

stepByStep(...) returns an OnUpgrade function, (Migrator m, int from, int to) => Future<void>. Wrap it in your own closure and check the direction first:

onUpgrade: (m, from, to) async {
  // Drift calls onUpgrade for downgrades too (from > to), e.g. when a user
  // on a newer build (schema 12) installs this rollback build (schema 11).
  // stepByStep only supports upgrades and throws on a downgrade, so skip it
  // and keep the existing data. Newer schemas only added nullable columns,
  // which this version ignores. Drift then writes user_version = `to`.
  if (from > to) return;

  // Normal upgrade path. stepByStep returns an OnUpgrade function, so it
  // must be invoked with (m, from, to) and awaited.
  await stepByStep(
    from1To2: (m, schema) async { /* ... */ },
    // ...
    from10To11: (m, schema) async { /* ... */ },
  )(m, from, to);
},

After this runs, Drift sets PRAGMA user_version to 11. The schema 12 columns are still in the file, but nothing reads them.

2. Skip debug schema validation after a downgrade

The next run in debug mode produced a different error:

Schema does not match
reports:
 columns:
  additional:
   Contains the following unexpected entries: submitted_at
settings:
 columns:
  additional:
   Contains the following unexpected entries: dark_mode_enabled, beta_features_enabled

This comes from VerifySelf(db).validateDatabaseSchema() (from drift_dev), which compares the real tables with the current schema. That check is usually wrapped in kDebugMode, so it doesn't affect release builds, but it will get in your way when testing locally. Skip it only when the database was downgraded:

beforeOpen: (details) async {
  await customStatement('PRAGMA foreign_keys = ON');

  // After a downgrade the tables still have the newer schema's columns, so
  // the debug-only schema validation would fail. Skip it in that case;
  // fresh installs and upgrades are still validated in debug builds.
  final isDowngrade =
      details.versionBefore != null &&
      details.versionBefore! > details.versionNow;
  if (!isDowngrade) await validateDatabaseSchema(this);
},

3. Make the newer migration safe to run twice

When a user goes 12 → 11 → 12, from11To12 runs a second time against a database that already has those columns. A plain addColumn would fail with duplicate column name. Guard it:

Future<bool> _columnExists(String table, String column) async {
  final rows = await customSelect('PRAGMA table_info($table)').get();
  return rows.any((r) => r.data['name'] == column);
}

from11To12: (m, schema) async {
  if (!await _columnExists('settings', 'dark_mode_enabled')) {
    await m.addColumn(settingsTable, settingsTable.darkModeEnabled);
  }
  // ...same for the other columns
},

Ideally the migration in the new release is written this way from the start. It costs very little and makes a rollback much safer.

A bug that's easy to introduce while making the fix

My first version of the wrapper looked like this:

onUpgrade: (m, from, to) async {
  if (from > to) return;

  stepByStep(          // ❌ no await, and never called
    from1To2: ...,
    // ...
  );
},

It compiles, and the downgrade test passes because it returns before reaching that line. But stepByStep(...) only builds the migration function. It's never called, so every normal upgrade does nothing. Drift still writes the new user_version, leaving users on older schemas with missing columns.

The correct form is:

await stepByStep(/* ... */)(m, from, to);

Lesson: after touching onUpgrade, always run your migration tests for the upgrade path, not just the scenario you were fixing:

flutter test test/drift/migration_test.dart

Testing locally without the release keystore

Release signing lived in CI, so flutter run --release wasn't possible locally. Two options:

Profile mode. It isn't kDebugMode, so it behaves like release for this test:

  flutter run --profile --flavor production

If Android complains about signing, temporarily point the build type at the debug signing config. Don't commit that change.

Debug mode with the validation guard from step 2.

Checking that the downgrade happened

Log the versions in beforeOpen. Use print, because kDebugMode-guarded logging doesn't appear in profile mode:

print('[DB] versionBefore=${details.versionBefore} versionNow=${details.versionNow}');

You should see:

first launch of the rollback: versionBefore=12 versionNow=11
next launch: versionBefore=11 versionNow=11

Or check the file directly on Android:

adb exec-out run-as com.example.myapp cat app_flutter/app.db > app.db
sqlite3 app.db "PRAGMA user_version;"            # expect 11
sqlite3 app.db "PRAGMA table_info(settings);"    # schema 12 columns still there, unused

(getApplicationDocumentsDirectory() maps to app_flutter/ on Android. If the app is still running, also pull app.db-wal.)

The git workflow: two versions side by side with `git worktree`

To test the round trip you need builds from two branches. Your working branch probably has uncommitted local files (environment config, FVM settings and so on), so switching back and forth is painful. git worktree checks another branch out into a separate folder that uses the same repository.

# from the repo root
git worktree list
git worktree add ../myapp-v12 feature/new-release
cd ../myapp-v12

# confirm it's really the newer schema
grep -n "schemaVersion =>" lib/data/database/database.dart   # expect 12

Untracked local files aren't in git, so copy them across:

cp ../myapp/.fvmrc .
cp ../myapp/lib/core/env.dart lib/core/      # make sure both builds use the same backend environment
fvm install
fvm flutter pub get

One rule: a branch can only be checked out in one worktree at a time. If you get fatal: '<branch>' is already checked out, git worktree list shows where it is.

When you're done:

git worktree remove ../myapp-v12

Building the three QA builds

QA needs to test three transitions on one device without uninstalling, because uninstalling deletes the database and makes the test pointless.

APK	Branch	Schema	Build number	Purpose
A	`feature/new-release`	12	150	The new release
B	`release/1.4.2`	11	151	The rollback
C	`feature/new-release`	12	152	Re-upgrade after the rollback

There are two Android rules to work around:

Same signing key. Android won't install an update signed with a different key (INSTALL_FAILED_UPDATE_INCOMPATIBLE). Build all three on the same machine, so they're all signed with ~/.android/debug.keystore.
versionCode must not go down when the user taps an APK to install it. That's why C exists: the same code as A, with a higher build number, so QA can install it over B. Without C, QA needs adb install -r -d A.apk.

Commands

OUT=~/Desktop/QA-ROLLBACK
FLAVOR=production
APK=build/app/outputs/flutter-apk/app-$FLAVOR-debug.apk
mkdir -p "$OUT"

# B: the rollback (main folder, release/1.4.2)
cd ~/dev/myapp
fvm flutter clean && fvm flutter pub get
fvm flutter build apk --debug --flavor $FLAVOR
cp "$APK" "$OUT/B_rollback_v1.4.2-151_db11_debug.apk"

# A: the new release (worktree, feature/new-release)
cd ~/dev/myapp-v12
fvm flutter pub get
fvm flutter build apk --debug --flavor $FLAVOR
cp "$APK" "$OUT/A_new-release_v1.5.0-150_db12_debug.apk"

# C: re-upgrade (same worktree, higher build number)
fvm flutter build apk --debug --flavor $FLAVOR --build-number 152
cp "$APK" "$OUT/C_reupgrade_v1.5.0-152_db12_debug.apk"

Putting the order, version and schema in the file names makes it hard for QA to install them in the wrong order.

Debug APKs include every CPU architecture and can be 150–250 MB. If your ticket system rejects them, build for physical phones only:

fvm flutter build apk --debug --flavor $FLAVOR --target-platform android-arm64

The QA test plan

Install order: A → B → C. Never uninstall in between. If a store build is already on the device, uninstall it once before A, because it's signed with a different key.

Rollback (A → B). Install A, log in, go offline, create unsynced data, and change a setting. Then install B over it.
- Expected: the app opens, the user is still logged in, and all data is still there.
Use the app after the rollback. On B, create new records in the tables that still have the newer columns, and change a setting. Then go back online.
- Expected: saving works and everything syncs.
Re-upgrade (B → C). Install C over B.
- Expected: no migration error (the guarded from11To12 skips the existing columns), the data is intact, and the new features work.
Regression: production → B. Install the current store build, then B over it.
- Expected: an 11 → 11 no-op with the data intact.
Fresh install of B.
- Expected: onCreate runs and the default settings are seeded.

Shipping it

Commit only the database change. Generated plugin registrants, rebuilt web workers and local config files can stay out of the commit:

git add lib/data/database/database.dart
git status --short     # only this file should be staged
git commit -m "Allow safe DB downgrade from schema 12 to 11 for rollback build"
git push origin release/1.4.2

Watch for branches whose names differ only in case (release/1.4.2 vs Release/1.4.2). Check what your branch tracks before you push:

git rev-parse --abbrev-ref @{u}

When CI builds the store version of the rollback, its build number must be higher than the new release's, or the stores won't offer it as an update.

Takeaways

Drift sends downgrades through onUpgrade. beforeOpen runs afterwards, so it's too late to handle a downgrade there.
stepByStep throws on a downgrade. Wrap it and check from > to first.
If the newer schema is additive, the safest downgrade is a no-op. Keep the data. Only drop or rebuild tables when you really have to.
Make the newer migrations idempotent (_columnExists checks) so 12 → 11 → 12 works.
Skip debug-only schema validation after a downgrade.
stepByStep(...) returns a function. Call it and await it, and run your upgrade tests after changing onUpgrade.
Prepare the rollback before you need it. Test the downgrade path before release day, not during an incident.
git worktree + same-key debug builds + build-number control lets QA test the whole upgrade → rollback → re-upgrade cycle on one device.

If your next release adds anything other than nullable columns, plan the downgrade path before you ship it.

Building a Multi-Tenant Production-Grade Wallet Pass System for Google & Apple: A Complete Architectural & Implementation Guide

George Ikwegbu Chinedu — Thu, 22 Oct 2026 19:47:05 +0000

Introduction

Your customers already carry everything on their phones — and their native digital wallet apps (Apple Wallet on iOS and Google Wallet on Android) are accessed daily. Building a production-grade system that issues real digital passes transforms customer engagement: digital loyalty cards, tickets, and membership cards that users add with a single tap, receive live dynamic updates on their lock screens, and scan at physical locations to redeem rewards or verify admission.

This guide provides an end-to-end, production-tested blueprint for architecting and implementing a dual-platform wallet pass engine. The concepts, cryptographic signing pipelines, API specifications, and database models presented here are deliberately stack-agnostic — applicable whether your backend is built with TypeScript/Node.js, Go, Python, Java, or Rust, and whether your database is PostgreSQL, MySQL, or a document store.

By the end of this guide, you will master:

Google Wallet Architecture: From Google Cloud service account provisioning and Google Pay Console issuer setup to signing JWT passes and handling class inheritance.
Apple Wallet & PassKit Architecture: Managing certificate authorities, .p12 to .pem extraction, WWDR G4 chains, APNs push channels, and strict PassKit validation rules.
Local Development & Mobile Testing via HTTPS Tunneling (ngrok): How to satisfy Apple’s non-negotiable HTTPS requirement and Google’s JWT origin validation when testing on physical smartphones.
Pass Design & Cryptographic QR Redemptions: Structuring fields, image bundles, and tamper-proof, short-lived QR codes.
Multi-Tenant System Design: How a single platform issuer can host hundreds of individual brands with their own custom colors, logos, and points systems without requiring separate Apple or Google developer accounts.
Customer Identity & Junction Data Modeling: Handling customers who belong to multiple businesses simultaneously without data leaks or duplicate pass collisions.

📂 Reference Implementation & Open Source Repository:
A complete, production-ready reference implementation of this architecture — featuring a NestJS backend, PostgreSQL/Prisma persistence, PassKit signing pipeline, and a Vue 3 Tailwind admin dashboard — is available on GitHub:
👉 https://github.com/gikwegbu/add_to_google_apple_wallet

Contributions, issue reports, and pull requests are warmly welcome!

Part 1 — Google Wallet: From Zero to Issuer

Google Wallet passes are powered by the Google Wallet REST API and authenticated using JSON Web Tokens (JWTs) signed with RS256 using an asymmetric Google Service Account key.

┌────────────────────────────────────────────────────────────────────────┐
│                        GOOGLE WALLET ECOSYSTEM                         │
├────────────────────────────────┬───────────────────────────────────────┤
│      GOOGLE CLOUD CONSOLE      │      GOOGLE PAY & WALLET CONSOLE       │
│  - Cloud Project               │  - Issuer Account (Issuer ID)         │
│  - Google Wallet API Enabled   │  - Service Account Authorization      │
│  - Service Account (RSA Key)   │  - Pass Class Definitions             │
└────────────────────────────────┴───────────────────────────────────────┘

1.1 Create a Google Cloud Project

Every Google Wallet integration lives under a Google Cloud Project:

Navigate to the Google Cloud Console.
Create a new project (e.g., wallet-pass-platform). Choose a name reflecting your platform rather than a single client brand.
Ensure billing is enabled for the project.

1.2 Enable the Google Wallet API

In your Cloud Project, open APIs & Services → Library.
Search for Google Wallet API.
Click Enable. This activates the endpoints under walletobjects.googleapis.com.

1.3 Provision a Dedicated Service Account

Your backend server authenticates with Google using an automated Service Account identity:

Open IAM & Admin → Service Accounts.
Click Create Service Account, naming it descriptively (e.g., wallet-issuer-sa).
Click into the newly created service account and navigate to the Keys tab.
Select Add Key → Create new key → JSON.
Download the JSON credential file and store it securely on your server (e.g., core/service-account.json). Never commit this file or its private key to version control.

The downloaded file contains:

client_email: The service account email (e.g., wallet-issuer-sa@project-id.iam.gserviceaccount.com).
private_key: The RSA 2048-bit private key (PEM format with \n characters).

1.4 Register in the Google Pay & Wallet Console

Having the Cloud Project API enabled is not enough. You must register as an authorized pass issuer:

Go to the Google Pay & Wallet Console.
Complete the business registration profile (Legal Business Name, Website, Point of Contact).
Once approved, note your Issuer ID (a numeric string such as 3388000000023066256). This permanent identifier namespaces every class and object you ever produce.

1.5 Authorize the Service Account in the Wallet Console

The Cloud Console and the Pay & Wallet Console are independent security domains. You must bridge them:

In the Google Pay & Wallet Console, navigate to the Users tab.
Click Invite a user (or Add User).
Paste the full client_email from your service account JSON file.
Set the permission level to Developer or Admin.
Save.

⚠️ Common Trap: If you omit this step, any API call or pass creation will fail with 401 Unauthorized: Request had invalid authentication credentials or 403 Forbidden: Not an issuer, even if the Service Account is Project Owner in Google Cloud.

1.6 Pass Classes vs. Pass Objects

Google Wallet separates templates from individual user passes:

Pass Class (Template): Defines the global layout, program name, brand logos, primary colors, review status, and callback URLs. Created once per brand/program.
Pass Object (Instance): Represents a single user's pass. References the classId and holds specific values (User's Name, Current Points Balance, Unique Barcode, Account ID).

Google supports several class types:

genericClass / genericObject: Best for flexible reward cards, club memberships, vouchers, and event tickets. Highly customizable.
loyaltyClass / loyaltyObject: Specifically tailored for retail points programs with structured tier labels.
eventTicketClass / eventTicketObject: Tailored for seated venue events with seat/gate numbers.

Class IDs follow the format: <Issuer_ID>.<custom_class_suffix> (e.g., 3388000000023066256.summer_rewards_class).

1.7 Generating the Save Link: The "Skinny" JWT Flow

You do not need to make an upfront REST API call to pre-create every object before a user saves it. Google provides an atomic, high-performance issuance pattern known as the Skinny JWT:

 ┌─────────────────┐       GET /google/pass/:id       ┌─────────────────┐
 │   User Browser  │ ───────────────────────────────> │  Your Backend   │
 │                 │ <─────────────────────────────── │  Signs JWT      │
 └─────────────────┘       302 Redirect to Save URL   └─────────────────┘
          │
          ▼
 ┌─────────────────┐
 │ Google Pay Save │ ──> Pass added to Google Wallet app instantly!
 └─────────────────┘

JWT Structure

The backend constructs an RS256-signed JWT containing the pass object and returns a 302 redirect:

// JWT Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// JWT Claims Payload
{
  "iss": "wallet-issuer-sa@project-id.iam.gserviceaccount.com",
  "aud": "google",
  "typ": "savetowallet",
  "iat": 1729600000,
  "origins": [
    "http://localhost:3000",
    "https://your-domain.ngrok-free.dev"
  ],
  "payload": {
    "genericObjects": [
      {
        "id": "3388000000023066256.user-uuid-1234",
        "classId": "3388000000023066256.summer_rewards_class",
        "state": "ACTIVE",
        "cardTitle": {
          "defaultValue": { "language": "en-US", "value": "Reisty Rewards" }
        },
        "header": {
          "defaultValue": { "language": "en-US", "value": "George Ikwegbu" }
        },
        "textModulesData": [
          {
            "id": "points",
            "header": "POINTS",
            "body": "120"
          }
        ],
        "barcode": {
          "type": "QR_CODE",
          "value": "<signed_qr_payload>",
          "alternateText": "Scan at terminal"
        }
      }
    ]
  }
}

⚠️ Critical Requirement: The origins claim is required by Google. It must match the domain or IP from which the user initiates the Save flow. For local and mobile testing, include your HTTPS tunnel domain (see Part 4).

The user is redirected to:
https://pay.google.com/gp/v/save/<signed_jwt>

When clicked on Android or desktop Chrome, Google verifies the cryptographic signature against your Service Account public key, provisions the object on their servers, and adds it to the user's Google Wallet immediately.

Part 2 — Apple Wallet: Developer Setup, PassKit & Certificates

Apple Wallet passes (.pkpass) are signed ZIP archives verified by iOS using Public Key Cryptography Standards (PKCS#7). iOS strictly validates the signature against Apple's Worldwide Developer Relations (WWDR) Certificate Authority.

                      APPLE PASSKIT SIGNING PIPELINE

  pass.json + icon.png + logo.png
               │
               ▼
  Generate manifest.json (SHA-1 checksum of every asset)
               │
               ▼
  Sign manifest.json using Pass Certificate + Private Key + WWDR G4
  (Generates detached PKCS#7 signature)
               │
               ▼
  Compress into ZIP archive named <user_name>_pass.pkpass

2.1 Apple Developer Setup

Enroll in the Apple Developer Program (annual $99 membership).
Locate your Team ID under Account → Membership Details (a 10-character alphanumeric string like A1B2C3D4E5).

2.2 Register a Pass Type Identifier

Go to Certificates, Identifiers & Profiles → Identifiers.
Click +, select Pass Type IDs, and click Continue.
Provide a Description (e.g. Platform Loyalty Passes) and an Identifier formatted as pass.<organization>.<product> (e.g. pass.com.yourcompany.wallet).
Register the identifier.

2.3 Create & Export Signing Certificates

Passes must be signed by a certificate issued specifically for your Pass Type ID.

In Keychain Access on macOS, select Certificate Assistant → Request a Certificate from a Certificate Authority.
- Enter your email, select Saved to disk, and leave CA Email blank. This creates a CertificateSigningRequest.certSigningRequest (CSR).
In the Apple Developer portal under Identifiers → Pass Type IDs, select your ID and click Create Certificate.
Upload your CSR. Download the resulting pass.cer.
Double-click pass.cer to install it into Keychain Access. > 💡 Keychain Tip: Ensure the certificate is installed in the login keychain, NOT the System keychain; otherwise, macOS will grey out the .p12 export option.
In Keychain Access, right-click the Pass Type ID certificate and choose Export "Pass Type ID: ...".
Export as .p12 format (e.g. pass.p12). Enter an export password — this is your APPLE_CERT_PASSPHRASE.

2.4 Convert to Server-Ready PEM Files

Convert the .p12 file and Apple’s root authority certificate into unencrypted PEM files for your backend:

# 1. Extract the public pass certificate
openssl pkcs12 -in pass.p12 -clcerts -nokeys -out passcertificate.pem

# 2. Extract the unencrypted private key
openssl pkcs12 -in pass.p12 -nocerts -nodes -out passkey.pem

# 3. Download Apple Worldwide Developer Relations (WWDR) G4 Certificate
curl -O https://www.apple.com/certificateauthority/AppleWWDRCAG4.cer

# 4. Convert WWDR from DER to PEM
openssl x509 -inform DER -in AppleWWDRCAG4.cer -out wwdr.pem

Store passcertificate.pem, passkey.pem, and wwdr.pem in core/apple/certs/. Add this folder to .gitignore.

2.5 The .pkpass Package Anatomy & Mandatory Assets

A .pkpass bundle is a standard ZIP file with an exact file hierarchy:

George_Ikwegbu_pass.pkpass
├── pass.json          ← Data structure, text fields, colors, serial number
├── icon.png           ← MANDATORY: 29x29px (shown in iOS notifications & pass list)
├── icon@2x.png        ← MANDATORY: 58x58px
├── icon@3x.png        ← MANDATORY: 87x87px
├── logo.png           ← MANDATORY: 160x50px (pass header face)
├── logo@2x.png        ← MANDATORY: 320x100px
├── manifest.json      ← SHA-1 checksum map of every file above
└── signature          ← Detached PKCS#7 signature of manifest.json

⚠️ Strict Asset Rules:

Apple PassKit will fail with SyntaxError: Missing required image icon.png if icon.png is absent from the bundle template.

Never include manifest.json or signature inside manifest.json.

2.6 Apple PassKit Validation Rules & Gotchas

When building with libraries such as @walletpass/pass-js (Node), passkit-generator (Python), or passbook (Ruby), you must satisfy two critical Apple requirements:

authenticationToken Length Requirement: Apple PassKit mandates that if a pass defines a webServiceURL, the authenticationToken must be at least 16 characters long.

   // ❌ FAILS: Throws TypeError: authenticationToken must be 16 characters or longer
   pass.authenticationToken = 'auth-' + Math.random().toString(36).substring(7);

  // ✅ CORRECT: Increase it
   pass.authenticationToken = 'auth-' + Math.random().toString(36).substring(2) + Math.random().toString(36).substring(2);

   // ✅ CORRECT: Cryptographically random 32-character hex token
   pass.authenticationToken = crypto.randomBytes(16).toString('hex');

Apple Web Service Protocol Requires HTTPS: Apple devices strictly refuse to register passes or fetch background updates if webServiceURL uses plain http://. It must be HTTPS with a valid TLS certificate.

Part 3 — Testing Live Passes Locally via HTTPS Tunneling (ngrok)

Developing wallet passes locally presents a challenge:

Apple Wallet on iOS requires a public HTTPS webServiceURL to register passes and receive background push updates.
Google Wallet JWT tokens enforce an origins check and require publicly resolvable image URLs.
Testing on physical iPhones and Android devices requires your computer’s local dev server to be reachable from mobile devices.

This is resolved using an HTTPS tunnel such as ngrok.

 ┌─────────────────┐       HTTPS Requests       ┌──────────────┐      Port 3000      ┌──────────────┐
 │ Physical Phone  │ ─────────────────────────> │ ngrok Tunnel │ ──────────────────> │ Local Server │
 │ (iOS / Android) │ <───────────────────────── │ Public HTTPS │ <────────────────── │ (Nest / Exp) │
 └─────────────────┘                            └──────────────┘                     └──────────────┘

3.1 Starting the Tunnel

Launch an HTTPS tunnel targeting your local backend server port (e.g. port 3000):

# Standard dynamic tunnel
ngrok http 3000

# Or using a persistent static domain (recommended)
ngrok http --url=https://your-domain.ngrok-free.dev 3000

ngrok will output a secure HTTPS endpoint:
https://your-domain.ngrok-free.dev -> http://localhost:3000

3.2 Configuring the Backend

Update your server configuration (e.g. core/.env):

PORT=3000
API_BASE_URL=https://your-domain.ngrok-free.dev

In your pass generation logic:

Google Wallet: Add process.env.API_BASE_URL to the JWT origins array:

   origins: [this.configService.get('API_BASE_URL'), 'http://localhost:3000']

Apple Wallet: PassKit sets the registration URL dynamically:

   const webServiceURL = `${this.configService.get('API_BASE_URL')}/api/apple`;
   if (webServiceURL.startsWith('https://')) {
       pass.webServiceURL = webServiceURL;
       pass.authenticationToken = crypto.randomBytes(16).toString('hex');
   }

Now, clicking pass generation links on physical devices or in your web dashboard allows iOS and Android to connect directly to your local workstation.

Part 4 — Interactive Pass Endpoints & Frontend UX

A clean user experience offers dedicated chips for both mobile ecosystems:

┌────────────────────────────────────────────────────────────────────────┐
│ USER                POINTS     PASSES                        ACTIONS   │
├────────────────────────────────────────────────────────────────────────┤
│ James Groka         ° 80       [ ● GOOGLE ]   [ ● APPLE ]    [⎘] [🗑] [⋮] │
└────────────────────────────────────────────────────────────────────────┘

4.1 Server Pass Endpoints

Google Pass Redirect Endpoint

GET /google/pass/:userId

Looks up the user and active pass configuration in the database.
Generates the signed Google JWT.
Responds with 302 Found redirecting directly to https://pay.google.com/gp/v/save/<jwt>.
Clicking this link with target="_blank" on desktop or mobile opens the native Google Wallet save dialogue.

Apple Pass Download Endpoint

GET /apple/pass/:userId

Looks up the user and active pass template.
Injects the user’s name, points, barcode, and unique serial number into pass.json.
Signs and compresses the .pkpass bundle in memory.
Sanitizes the user's name for the download filename (e.g. George_Ikwegbu_pass.pkpass).
Returns binary data with standard PassKit headers:

   HTTP/1.1 200 OK
   Content-Type: application/vnd.apple.pkpass
   Content-Disposition: attachment; filename="George_Ikwegbu_pass.pkpass"
   Cache-Control: no-store, no-cache, must-revalidate, max-age=0

4.2 Frontend Chip Design & Interaction

In your frontend dashboard (Vue, React, or standard HTML), implement two distinct pills matching platform conventions:

Google Chip: Light grey/white pill (#F8FAFB), subtle border (border-slate-200), rounded rectangle (rounded-lg), uppercase bold label, and a blue indicator dot (#1A73E8).

  <a 
    :href="`${apiBaseUrl}/google/pass/${user.id}`" 
    target="_blank" 
    rel="noopener noreferrer"
    class="inline-flex items-center px-3 py-1.5 bg-[#F8FAFB] hover:bg-slate-100 border border-slate-200 rounded-lg text-[11px] font-bold text-slate-700 tracking-wider"
  >
    <span class="w-2 h-2 rounded-full bg-[#1A73E8] mr-2"></span>
    GOOGLE
  </a>

Apple Chip: Identical pill container with a dark slate/black indicator dot (#0F172B).

  <a 
    :href="`${apiBaseUrl}/apple/pass/${user.id}`" 
    :download="`${user.fullname.replace(/\s+/g, '_')}_pass.pkpass`"
    class="inline-flex items-center px-3 py-1.5 bg-[#F8FAFB] hover:bg-slate-100 border border-slate-200 rounded-lg text-[11px] font-bold text-slate-700 tracking-wider"
  >
    <span class="w-2 h-2 rounded-full bg-[#0F172B] mr-2"></span>
    APPLE
  </a>

When clicked:

The Google chip opens a new tab that immediately redirects into Google Wallet's cloud save prompt.
The Apple chip triggers a browser download of the .pkpass bundle on desktop, or launches the Apple Wallet installation sheet on iOS Safari.

Part 5 — Designing Passes & Tamper-Proof QR Codes

5.1 Barcodes & Cryptographic Redemptions

A common security vulnerability in loyalty passes is encoding raw customer IDs in the QR code (e.g. {"userId": "123"}). A user can screenshot their QR code or copy another customer’s ID and redeem unauthorized points.

Secure Tokenized QR Architecture:

Server Signs a Short-Lived JWT for the QR:

   {
     "sub": "user-uuid-123",
     "tenantId": "tenant-uuid-456",
     "iat": 1729600000,
     "exp": 1729603600
   }

Scanner Validates Authenticity: When the merchant scans the QR code at the terminal:
- Validates the cryptographic signature against the platform secret.
- Verifies exp has not lapsed.
- Atomically decrements points in the database.
- Triggers background pass balance updates to both Apple and Google.

5.2 Dynamic Pass Updates

When a customer’s balance updates:

Google Wallet: Execute a PATCH request to https://walletobjects.googleapis.com/walletobjects/v1/genericObject/<objectId> updating the text modules. Google pushes an automated lock-screen update.
Apple Wallet:
1. Update the database record.
2. Send an APNs background push notification containing an empty JSON body {} to all registered device tokens for that pass serial number.
3. iOS wakes up silently, calls your server's GET /v1/passes/:passTypeIdentifier/:serialNumber, and replaces the .pkpass bundle on device.

Part 6 — Multi-Tenant Architecture: One Platform, Hundreds of Brands

In a multi-tenant platform (SaaS for restaurants, fitness studios, or ticketing agencies), each business wants its own logo, colors, and rewards structure.

You do not need separate Apple Developer accounts or Google Cloud projects for each tenant. A single platform issuer can host hundreds of branded passes.

Your Platform (Issuer)
│   Google Issuer ID: 3388000000023066256
│   Apple Pass Type ID: pass.com.yourplatform.wallet
│
├── Tenant A: Restaurant Rosso
│     Google Class: 3388000000023066256.rosso_loyalty
│     Apple Template: templates/rosso/pass.json + red branding
│     Customers receive Rosso-branded passes
│
└── Tenant B: Café Verde
      Google Class: 3388000000023066256.verde_loyalty
      Apple Template: templates/verde/pass.json + green branding
      Customers receive Verde-branded passes

6.1 Tenant Class ID Convention

Adopt deterministic namespacing tied to your internal database UUIDs:

Google Class ID:    <Issuer_ID>.<tenant_uuid>_loyalty
Apple Template:     storage/tenants/<tenant_uuid>/pass.json
Apple Icons/Logos:  storage/tenants/<tenant_uuid>/logo.png

When a business updates its logo or primary color in your admin portal:

Google: Call PATCH /walletobjects/v1/genericClass/<classId> with the new asset URLs. Google propagates the change to all existing customer passes automatically.
Apple: Update the tenant's asset directory and trigger APNs push notifications to update devices.

Part 7 — One Customer, Many Tenants: The Junction Model

Customers frequently visit multiple businesses on the same platform. A user might hold a loyalty pass for Restaurant Rosso and another for Café Verde.

7.1 Relational Data Model

Decouple the global user profile from their tenant-specific membership using a Junction Record:

User Account: george@example.com (Global ID: user-101)
│
├── Tenant Membership (Rosso)
│     points: 80
│     googleObjectId: 3388000000023066256.rosso_user_101
│     appleSerialNumber: rosso_user_101
│
└── Tenant Membership (Verde)
      points: 30
      googleObjectId: 3388000000023066256.verde_user_101
      appleSerialNumber: verde_user_101

-- Relational Schema Representation
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    fullname VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE tenant_memberships (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    tenant_id UUID REFERENCES tenants(id) ON DELETE CASCADE,
    points INTEGER DEFAULT 0,
    google_pass_id VARCHAR(255),
    apple_pass_id VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, tenant_id)
);

7.2 Idempotent Pass Issuance

To prevent duplicate passes when a user clicks "Add to Wallet" multiple times, employ an upsert pattern:

POST /passes/issue
Body: { userId, tenantId, platform }

1. Upsert tenant_memberships WHERE user_id = userId AND tenant_id = tenantId.
2. If membership already possesses a valid pass ID:
   -> Return existing Google Save URL or stream existing Apple .pkpass.
3. If new membership:
   -> Mint unique pass IDs: `${tenant_id}_${user_id}`
   -> Persist pass ID in membership record.
   -> Return generated Save URL / .pkpass.

Conclusion & Production Checklist

Building a unified wallet pass system bridges digital interaction with real-world physical verification. By structuring your backend around standards-compliant JWTs for Google Wallet, strictly validated PassKit packages for Apple Wallet, and an HTTPS tunnel for live testing, you create a robust, production-ready foundation.

Production Pre-Flight Checklist

[ ] Google Service Account: Authorized as Developer/Admin in the Google Pay & Wallet Console.
[ ] JWT Origins: Configured with your live production HTTPS domain.
[ ] Apple Certificates: Extracted into passcertificate.pem, passkey.pem, and wwdr.pem.
[ ] PassKit Asset Validation: Template contains icon.png (29x29) and logo.png (160x50) in all pixel densities.
[ ] PassKit Token: authenticationToken is verified to be $\ge 16$ characters.
[ ] Security & .gitignore: All .pem, .p12, service account JSON files, and environment files (.env, .env.*) are untracked and excluded from version control, leaving only .env.example and pass.json.example.
[ ] Local Testing: Verified live pass installation on physical iOS and Android devices using ngrok HTTPS tunneling.

Open Source Repository & Community Contributions

The complete codebase backing this guide — including the backend pass generation controllers, Apple PassKit signing pipeline, and the Vue 3 Tailwind admin dashboard — is open-source on GitHub:

👉 https://github.com/gikwegbu/add_to_google_apple_wallet

We Welcome Contributions!

This project is open-source and actively evolving. If you would like to contribute:

Fork the repository on GitHub.
Submit Pull Requests for new features, bug fixes, automated pass push notifications, or documentation improvements.
Open Issues to report bugs or suggest enhancements.
If this project helped you or your team, consider giving it a ⭐ on GitHub!

Shipping a Safe Rollback: Downgrading a Drift (SQLite) Database in Flutter Without Losing User Data

George Ikwegbu Chinedu — Tue, 20 Oct 2026 20:09:26 +0000

Then you test the rollback, and it crashes on startup.

This post covers:

Why Drift refuses to "upgrade" to a lower schema version
The fix (and why the obvious fix doesn't work)
The rollback-window data problem: structural compatibility vs. data-semantic compatibility
A bug that's easy to introduce while making the fix
Testing rollback compatibility automatically in CI
The git worktree workflow for building both versions side by side
Building three test APKs so QA can test upgrade → rollback → re-upgrade without losing data

All names, branches and paths below are made up for the article.

The setup

Production (v1.4.1) uses database schema 11.
The new release (v1.5.0, branch feature/new-release) moves to schema 12. It adds three nullable columns:
- settings.dark_mode_enabled
- settings.beta_features_enabled
- reports.submitted_at
The rollback build (branch release/1.4.2) is production code (schema 11) with a higher build number, so the stores treat it as an update.

The local database is Drift (version 2.x), and migrations use Drift's generated stepByStep helper:

@override
int get schemaVersion => 11;

@override
MigrationStrategy get migration => MigrationStrategy(
  onCreate: (m) async {
    await m.createAll();
    await seedDefaultSettings();
  },
  onUpgrade: stepByStep(
    from1To2: (m, schema) async { /* ... */ },
    // ...
    from10To11: (m, schema) async { /* ... */ },
  ),
  beforeOpen: (details) async {
    await customStatement('PRAGMA foreign_keys = ON');
    await validateDatabaseSchema(this); // debug-only check
  },
);

The problem

On a device that had run the schema 12 build, installing the schema 11 rollback build crashed on startup with:

StateError: runMigrationSteps was asked to downgrade from versions 12 to 11.
Migration steps can only upgrade. This might happen if users downgrade app versions.

First attempt: handle it in `beforeOpen` (didn't work)

My first idea was to detect the downgrade in beforeOpen, then drop and recreate every table:

beforeOpen: (details) async {
  if (details.versionBefore != null && details.versionBefore! > schemaVersion) {
    final m = createMigrator();
    await customStatement('PRAGMA foreign_keys = OFF');
    for (final table in allTables) {
      await m.drop(table);
    }
    await m.createAll();
    await customStatement('PRAGMA foreign_keys = ON');
  }
  // ...
},

It made no difference. The same error kept appearing, and the code inside the if never ran.

Why: Drift calls `onUpgrade` before `beforeOpen`, including for downgrades

In Drift's source (lib/src/runtime/api/db_base.dart), the open sequence looks roughly like this:

if (details.wasCreated) {
  await _resolvedMigration.onCreate(migrator);
} else if (details.hadUpgrade) {           // versionBefore != versionNow
  await _resolvedMigration.onUpgrade(migrator, details.versionBefore!, details.versionNow);
}

await _resolvedMigration.beforeOpen?.call(details);

stepByStep then calls VersionedSchema.runMigrationSteps, which refuses to downgrade:

if (from > to) {
  throw StateError('runMigrationSteps was asked to downgrade from versions $from to $to. ...');
}

So the exception is thrown in onUpgrade, the database fails to open, and beforeOpen never runs.

Why dropping everything was a bad idea anyway

Even if it had worked, dropping every table and recreating it would have:

Lost unsynced data. Anything the user created offline and hadn't uploaded yet would be gone.
Logged users out, if session or settings data lives in the database.
Skipped the default seed data. onCreate seeds default settings, but a bare createAll() doesn't.

A rollback is meant to make things safer for users, and wiping their data on the way back defeats that.

What the schema change actually was

Before choosing a fix, I compared the two schemas. Schema 12 only added nullable columns.

That matters because Drift-generated queries always list columns explicitly:

SELECT "id", "name", ... FROM "settings";
INSERT INTO "reports" ("id", "title", ...) VALUES (...);

An older build that doesn't know about dark_mode_enabled never selects it, and on insert SQLite stores NULL.

However, it is critical to distinguish between two kinds of compatibility:

Structural (schema) compatibility: Can the older application physically open the SQLite file, run its queries, and write rows without SQLite errors?
Data-semantic compatibility: When the newer application returns, will it correctly interpret data that was created or modified while the older application was running?

Extra nullable columns (or columns with defaults) are structurally compatible with older code, provided the older application can safely ignore them. However, the newer application still needs to account for data written while those columns were unavailable.

So for the immediate rollback step, the safest schema downgrade is a structural no-op: keep the data intact and let Drift record the lower version number in SQLite's PRAGMA user_version.

⚠️ This only works when the newer schema is strictly additive. If it renamed or dropped columns, added NOT NULL columns without defaults, or changed table shapes, you'd need a real downgrade migration (for example m.alterTable(TableMigration(...)) to rebuild the table).

The fix

1. Handle the downgrade in `onUpgrade`, before `stepByStep` runs

stepByStep(...) returns an OnUpgrade function, (Migrator m, int from, int to) => Future<void>. Wrap it in your own closure and check the direction first:

onUpgrade: (m, from, to) async {
  // Drift calls onUpgrade for downgrades too (from > to), e.g. when a user
  // on a newer build (schema 12) installs this rollback build (schema 11).
  // stepByStep only supports upgrades and throws on a downgrade, so skip it
  // and keep the existing data. Newer schemas only added nullable columns,
  // which this version ignores. Drift then writes user_version = `to`.
  if (from > to) return;

  // Normal upgrade path. stepByStep returns an OnUpgrade function, so it
  // must be invoked with (m, from, to) and awaited.
  await stepByStep(
    from1To2: (m, schema) async { /* ... */ },
    // ...
    from10To11: (m, schema) async { /* ... */ },
  )(m, from, to);
},

After this runs, Drift sets PRAGMA user_version to 11. The schema 12 columns are still in the file, but nothing reads them.

2. Skip debug schema validation after a downgrade

The next run in debug mode produced a different error:

Schema does not match
reports:
 columns:
  additional:
   Contains the following unexpected entries: submitted_at
settings:
 columns:
  additional:
   Contains the following unexpected entries: dark_mode_enabled, beta_features_enabled

beforeOpen: (details) async {
  await customStatement('PRAGMA foreign_keys = ON');

  // After a downgrade the tables still have the newer schema's columns, so
  // the debug-only schema validation would fail. Skip it in that case;
  // fresh installs and upgrades are still validated in debug builds.
  final isDowngrade =
      details.versionBefore != null &&
      details.versionBefore! > details.versionNow;
  if (!isDowngrade) await validateDatabaseSchema(this);
},

3. Make the newer migration safe to run twice

When a user goes 12 → 11 → 12, from11To12 runs a second time against a database that already has those columns. A plain addColumn would fail with duplicate column name. Guard it:

Future<bool> _columnExists(String table, String column) async {
  final rows = await customSelect('PRAGMA table_info($table)').get();
  return rows.any((r) => r.data['name'] == column);
}

from11To12: (m, schema) async {
  if (!await _columnExists('settings', 'dark_mode_enabled')) {
    await m.addColumn(settingsTable, settingsTable.darkModeEnabled);
  }
  // ...same for the other columns
},

Ideally the migration in the new release is written this way from the start. It costs very little and makes a rollback much safer.

The rollback-window data problem: structural vs. semantic compatibility

Making the database structurally downgradeable prevents the crash on startup, but it exposes a deeper challenge: the semantic data gap.

Consider the complete round-trip lifecycle of a rollback:

v12 (new release)
  │
  ▼  Rollback triggered
v11 (rollback build active)
  │
  ▼  User creates, edits, or submits data
v11 writes rows (v12-only columns are stored as NULL)
  │
  ▼  Fixed v12 re-shipped
v12 (re-upgrade)

Any record created or modified while the user is on the v11 rollback build has no awareness of schema 12's columns.

Take reports.submitted_at as a concrete example.

In v11, the reports table exists, but v11 queries have no reference to submitted_at. If a user submits a report while running v11, the row is inserted or updated without touching submitted_at. In SQLite, that column remains NULL:

report_id | title          | submitted_at
----------|----------------|-------------
123       | Q3 Audit       | NULL

When the user eventually re-upgrades to v12, what does submitted_at == NULL mean?

In normal v12 code, developers often assume:

if (report.submittedAt == null) {
  // "This report has not been submitted yet"
  showDraftStatus();
  showSubmitButton();
}

That assumption is dangerous. In a post-rollback world, submitted_at = NULL does not necessarily mean "not submitted." It may mean:

This record was created or modified while the application was running an older schema during the rollback window.

Blindly treating NULL as a definitive business state can trigger serious defects: a report the customer successfully submitted under v11 suddenly reappears as a draft, or a background sync process submits the report to your server a second time.

Two ways to solve the NULL/unknown problem

Depending on your domain and data model, there are two approaches to address this:

Approach A — Backfill during the re-upgrade migration

If the existing v11 data contains enough surrounding information to reconstruct or infer the correct state, from11To12 can backfill the column when the user returns to v12:

from11To12: (m, schema) async {
  if (!await _columnExists('reports', 'submitted_at')) {
    await m.addColumn(reportsTable, reportsTable.submittedAt);
  }

  // Backfill from existing v11 state where possible.
  // The exact conditions depend entirely on your application's data model
  // (for example, checking an existing status column or an audit log).
  await customStatement('''
    UPDATE reports
    SET submitted_at = ...
    WHERE submitted_at IS NULL
      AND ...;
  ''');
},

If your schema already has an existing status column or sync timestamp from schema 11, you can use that to backfill a sensible value. The exact SQL depends on your specific data model, but the key is placing it inside the idempotent from11To12 migration step.

Approach B — Treat NULL as "unknown" in application logic

If v11 simply does not capture enough data to reconstruct the missing value, the v12 application logic should treat NULL as unknown, rather than assuming "no":

if (report.submittedAt == null) {
  // Unknown: this record may have passed through an older schema
  // during a rollback window. Reconcile with the server or inspect
  // secondary state before allowing re-submission.
  await reconcileReportStatusWithServer(report);
} else {
  showSubmittedConfirmation(report.submittedAt!);
}

Treating NULL as an ambiguous state prompts your app to check secondary signals — querying your sync server, inspecting local event logs, or running a reconciliation check — before taking a destructive or user-visible action.

Neither approach is universal; the right choice depends on your business domain. What matters is that your v12 code does not mistake a missing column value for a definitive business state.

A bug that's easy to introduce while making the fix

My first version of the wrapper looked like this:

onUpgrade: (m, from, to) async {
  if (from > to) return;

  stepByStep(          // ❌ no await, and never called
    from1To2: ...,
    // ...
  );
},

The correct form is:

await stepByStep(/* ... */)(m, from, to);

Lesson: after touching onUpgrade, always run your migration tests for the upgrade path, not just the scenario you were fixing:

flutter test test/drift/migration_test.dart

Testing locally without the release keystore

Release signing lived in CI, so flutter run --release wasn't possible locally. Two options:

Profile mode. It isn't kDebugMode, so it behaves like release for this test:

  flutter run --profile --flavor production

If Android complains about signing, temporarily point the build type at the debug signing config. Don't commit that change.

Debug mode with the validation guard from step 2.

Checking that the downgrade happened

Log the versions in beforeOpen. Use print, because kDebugMode-guarded logging doesn't appear in profile mode:

print('[DB] versionBefore=${details.versionBefore} versionNow=${details.versionNow}');

You should see:

first launch of the rollback: versionBefore=12 versionNow=11
next launch: versionBefore=11 versionNow=11

Or check the file directly on Android:

adb exec-out run-as com.example.myapp cat app_flutter/app.db > app.db
sqlite3 app.db "PRAGMA user_version;"            # expect 11
sqlite3 app.db "PRAGMA table_info(settings);"    # schema 12 columns still there, unused

(getApplicationDocumentsDirectory() maps to app_flutter/ on Android. If the app is still running, also pull app.db-wal.)

The git workflow: two versions side by side with `git worktree`

# from the repo root
git worktree list
git worktree add ../myapp-v12 feature/new-release
cd ../myapp-v12

# confirm it's really the newer schema
grep -n "schemaVersion =>" lib/data/database/database.dart   # expect 12

Untracked local files aren't in git, so copy them across:

cp ../myapp/.fvmrc .
cp ../myapp/lib/core/env.dart lib/core/      # make sure both builds use the same backend environment
fvm install
fvm flutter pub get

One rule: a branch can only be checked out in one worktree at a time. If you get fatal: '<branch>' is already checked out, git worktree list shows where it is.

When you're done:

git worktree remove ../myapp-v12

Building the three QA builds

QA needs to test three transitions on one device without uninstalling, because uninstalling deletes the database and makes the test pointless.

APK	Branch	Schema	Build number	Purpose
A	`feature/new-release`	12	150	The new release
B	`release/1.4.2`	11	151	The rollback
C	`feature/new-release`	12	152	Re-upgrade after the rollback

There are two Android rules to work around:

Same signing key. Android won't install an update signed with a different key (INSTALL_FAILED_UPDATE_INCOMPATIBLE). Build all three on the same machine, so they're all signed with ~/.android/debug.keystore.
versionCode must not go down when the user taps an APK to install it. That's why C exists: the same code as A, with a higher build number, so QA can install it over B. Without C, QA needs adb install -r -d A.apk.

Commands

OUT=~/Desktop/QA-ROLLBACK
FLAVOR=production
APK=build/app/outputs/flutter-apk/app-$FLAVOR-debug.apk
mkdir -p "$OUT"

# B: the rollback (main folder, release/1.4.2)
cd ~/dev/myapp
fvm flutter clean && fvm flutter pub get
fvm flutter build apk --debug --flavor $FLAVOR
cp "$APK" "$OUT/B_rollback_v1.4.2-151_db11_debug.apk"

# A: the new release (worktree, feature/new-release)
cd ~/dev/myapp-v12
fvm flutter pub get
fvm flutter build apk --debug --flavor $FLAVOR
cp "$APK" "$OUT/A_new-release_v1.5.0-150_db12_debug.apk"

# C: re-upgrade (same worktree, higher build number)
fvm flutter build apk --debug --flavor $FLAVOR --build-number 152
cp "$APK" "$OUT/C_reupgrade_v1.5.0-152_db12_debug.apk"

Putting the order, version and schema in the file names makes it hard for QA to install them in the wrong order.

Debug APKs include every CPU architecture and can be 150–250 MB. If your ticket system rejects them, build for physical phones only:

fvm flutter build apk --debug --flavor $FLAVOR --target-platform android-arm64

The QA test plan

Install order: A → B → C. Never uninstall in between. If a store build is already on the device, uninstall it once before A, because it's signed with a different key.

A successful database migration only proves that the database engine could open the file without throwing a SQLite error. It does not prove that data written during the rollback window still has the correct business meaning. QA must test both structural and data-semantic transitions:

Install v12 (Build A). Log in, go offline, create unsynced data (e.g. drafts or reports), and change settings (dark_mode_enabled).
Rollback to v11 (A → B). Install B directly over A without uninstalling.
- Expected: The app opens cleanly, the user is still logged in, and all existing data remains accessible.
Use the app during the rollback window. On B, create and modify records in the tables that contain v12 columns (for example, submit a new report on B where submitted_at is not referenced by code). Change a setting. Then go back online.
- Expected: Saving works and records sync. SQLite writes NULL for the unused v12 columns.
Re-upgrade to v12 (B → C). Install C directly over B without uninstalling.
- Expected:
  - No migration error occurs (the guarded from11To12 skips existing columns instead of failing with "duplicate column name").
  - Existing data created under A remains intact.
  - Critically, verify the records created or modified under B: Verify that v12-only fields on those records are interpreted correctly. Verify that NULL values are not blindly treated as a definitive business state (e.g. submitted reports should not be reverted to drafts or re-submitted).
  - Verify that records are not duplicated, corrupted, or shown in an inconsistent state.
Regression: production → B. Install the current store build (schema 11), then B over it.
- Expected: An 11 → 11 no-op with all data intact.
Fresh install of B.
- Expected: onCreate runs and default settings are seeded.

Put rollback compatibility in CI

Manual QA on physical devices is indispensable, but the "additive-only" constraint should not rely solely on a manual QA checklist. A developer working on a future schema could easily introduce a breaking change:

ALTER TABLE reports ADD COLUMN reviewer_notes TEXT NOT NULL; -- ❌ Breaks downgrade!

or rename an existing column, silently making future rollbacks impossible.

Catch this before release by automating rollback compatibility in CI using drift_dev's schema snapshots and SchemaVerifier.

Drift allows dumping schema snapshots to JSON files via drift_dev make-migrations. In your test suite, you can write an automated integration test that simulates the complete round-trip:

v11 database
    ↓
open/use with v12
    ↓
v12 database
    ↓
open/use with v11 (rollback)
    ↓
upgrade again to v12

Using SchemaVerifier, you can verify that the database class for v11 can cleanly open a database initialized with schema 12, and that re-opening it with v12 succeeds without errors:

// test/drift/rollback_test.dart
import 'package:drift_dev/api/migrations.dart';
import 'package:test/test.dart';

void main() {
  test('schema 12 database can safely be opened by schema 11 and re-upgraded', () async {
    final verifier = SchemaVerifier(GeneratedHelper());

    // 1. Start with schema 11, upgrade to 12
    final connection = await verifier.startAt(11);
    final dbV12 = MyDatabase(connection);
    await dbV12.customStatement('PRAGMA user_version = 12');
    await dbV12.close();

    // 2. Open the v12 database using the v11 rollback database class
    // This exercises the `if (from > to) return;` guard in onUpgrade.
    final rollbackConnection = await verifier.newConnection();
    final dbV11Rollback = MyRollbackDatabase(rollbackConnection);
    expect(() => dbV11Rollback.select(dbV11Rollback.reports).get(), returnsNormally);
    await dbV11Rollback.close();

    // 3. Re-upgrade back to v12
    // This exercises the idempotent from11To12 migration step.
    final reUpgradeConnection = await verifier.newConnection();
    final dbV12Reopened = MyDatabase(reUpgradeConnection);
    expect(() => dbV12Reopened.select(dbV12Reopened.reports).get(), returnsNormally);
    await dbV12Reopened.close();
  });
}

Run this in your pipeline:

flutter test test/drift/rollback_test.dart

This automated check validates the schema contract: if an incompatible schema change (such as a NOT NULL column without a default) is introduced, the test fails immediately in CI before the release is ever cut.

Remember: CI validates the migration contract; device testing validates the real release build. CI verifies that SQLite will accept the schema; the three-APK device test verifies that package management, background tasks, and application-level business state behave properly in production.

Shipping it

Commit only the database change. Generated plugin registrants, rebuilt web workers and local config files can stay out of the commit:

git add lib/data/database/database.dart
git status --short     # only this file should be staged
git commit -m "Allow safe DB downgrade from schema 12 to 11 for rollback build"
git push origin release/1.4.2

Watch for branches whose names differ only in case (release/1.4.2 vs Release/1.4.2). Check what your branch tracks before you push:

git rev-parse --abbrev-ref @{u}

When CI builds the store version of the rollback, its build number must be higher than the new release's, or the stores won't offer it as an update.

Takeaways

Drift sends downgrades through onUpgrade. beforeOpen runs afterwards, so it's too late to handle a downgrade there.
stepByStep throws on a downgrade. Wrap it and check from > to first.
Schema compatibility is not data-semantic compatibility. An older build opening a newer SQLite database without error does not mean the newer app will understand data written during the rollback window.
Data written during the rollback window must be planned for. New nullable columns will contain NULL. Either backfill them in your re-upgrade migration or treat NULL as an explicit "unknown" state in application logic.
If the newer schema is additive, the safest downgrade is a no-op. Keep the data. Only drop or rebuild tables when an incompatible schema change makes it unavoidable.
Make newer migrations idempotent (_columnExists checks) so the 12 → 11 → 12 cycle does not crash with "duplicate column name".
Skip debug-only schema validation after a downgrade so local development and QA aren't blocked by the extra columns.
stepByStep(...) returns a function. Call it and await it, and always run your upgrade tests after editing onUpgrade.
Enforce rollback compatibility in CI. Use Drift schema snapshots and SchemaVerifier to catch non-additive or breaking schema changes before release.
git worktree + same-key debug builds + build-number control lets QA test the entire upgrade → rollback → re-upgrade cycle on one device without uninstalling.
Rollback safety is a multi-layered discipline. It requires coordinating schema structure, migration idempotency, semantic business logic, and automated CI tests before release day.

If your next release adds anything other than nullable columns, plan the downgrade path before you ship it.

Shorebird: Deploy Flutter Updates Without App Store Review (Step-by-Step Guide)

George Ikwegbu Chinedu — Wed, 23 Sep 2026 00:05:58 +0000

What is Shorebird?
Why You Need It
Prerequisites
Installation
Setup & Configuration
Creating Your First Release
Deploying Patches
CI/CD Integration
Best Practices
Troubleshooting

What is Shorebird?

Shorebird is a code push solution for Flutter that lets you update your app's Dart code without going through the Apple App Store or Google Play Store review process.

Think of it as hotfix superpowers for production apps. Bug in production? Deploy a patch in minutes instead of waiting days for app store approval.

Key Capabilities:

✅ Push Dart code updates instantly
✅ Bypass app store review cycles
✅ Automated rollback on crashes
✅ Staged rollouts (release to 5%, then 50%, then 100%)
✅ Detailed analytics on patch adoption
✅ Works with Flutter's native capabilities

Why You Need It

Scenario: It's Friday evening. Your production app has a critical bug affecting checkout. Users are losing money.

Without Shorebird:

Submit fix to Apple App Store
Wait 24-48 hours for review
Users suffer the entire time
Potential revenue loss

With Shorebird:

Deploy fix in 5 minutes
Users get the patch immediately
Crisis averted

Real-World Benefits:

Reduce Time-to-Market: Deploy hotfixes without waiting for store approval
Better User Experience: Critical bugs fixed instantly
Cost Savings: Fewer production incidents = fewer support tickets
Faster Iteration: Deploy A/B tests and feature toggles in real-time
CI/CD Integration: Automate patch deployment through your pipeline

Prerequisites

Before starting, ensure you have:

Flutter Project: An existing Flutter app (or create one)

   flutter create my_app
   cd my_app

Shorebird Account: Sign up at shorebird.dev
Flutter SDK: Version 3.0 or higher

   flutter --version

Git: For version control

   git --version

Platform Requirements:
- iOS: Xcode 14+
- Android: Android SDK 21+

Installation

Step 1: Install Shorebird CLI

# On macOS/Linux
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/shorebird/main/scripts/install.sh | bash

# On Windows (PowerShell)
iwr https://raw.githubusercontent.com/shorebirdtech/shorebird/main/scripts/install.ps1 -UseBasicParsing | iex

Step 2: Verify Installation

shorebird --version

Expected output:

Shorebird 0.x.x

Step 3: Initialize Shorebird in Your Project

cd your_flutter_project
shorebird init

This creates:

.shorebird/config.yaml - Shorebird configuration
Updates pubspec.yaml with dependencies

Setup & Configuration

Step 1: Authenticate with Shorebird

shorebird login

This opens a browser window for authentication. Sign in with your Shorebird account.

Step 2: Review `shorebird.yaml`

Located in your project root:

app_id: "your-app-id-here"
flavors:
  - name: production
    app_id: "prod-app-id"

Step 3: Update Your App Version

In pubspec.yaml:

version: 1.0.0+1  # version+build_number

Important: Increment the build number for each Shorebird release.

Step 4: Configure Your App

In lib/main.dart, ensure your app can handle code updates:

import 'package:shorebird_code_push/shorebird_code_push.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Optional: Check for updates on app start
  final codePush = ShorebirdsCodePush();
  await codePush.checkForUpdates();

  runApp(const MyApp());
}

Creating Your First Release

Step 1: Build for Release

Before creating a Shorebird release, build your app for both platforms.

For Android:

shorebird build apk --release

For iOS:

shorebird build ipa --release

Step 2: Review Build Output

Successful output looks like:

✓ Built APK: build/app/outputs/flutter-app-release.apk
✓ Built IPA: build/ios/ipa/MyApp.ipa

Step 3: Submit to App Stores

Google Play Store:

fastlane supply --apk build/app/outputs/flutter-app-release.apk

Or upload manually via Google Play Console.

Apple App Store:

fastlane pilot upload --ipa build/ios/ipa/MyApp.ipa

Or use Xcode/Transporter.

Step 4: Create a Release in Shorebird

Once your app is live on stores:

shorebird release

This captures the current code state as your baseline release.

Deploying Patches

Scenario: You have a bug fix ready

Step 1: Make Your Code Changes

Fix the bug in your Dart code:

// Before
class LoginScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // BUG: Email validation broken
    return TextField(
      onChanged: (value) => emailValidation(value),
    );
  }
}

// After
class LoginScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // FIXED: Proper email validation
    return TextField(
      onChanged: (value) => _validateEmail(value),
    );
  }

  void _validateEmail(String email) {
    final regex = RegExp(r'^[^@]+@[^@]+\.[^@]+');
    return regex.hasMatch(email);
  }
}

Step 2: Bump the Build Number

In pubspec.yaml:

# Before
version: 1.0.0+1

# After
version: 1.0.0+2

Step 3: Create a Patch

shorebird patch

Shorebird will:

Build the patched code
Compare it to the release baseline
Create a minimal delta package
Upload it to Shorebird servers

Step 4: Monitor Patch Status

shorebird patch status

Output shows:

Patch creation status
Percentage of devices updated
Any errors or rollbacks

Step 5: Staged Rollout (Optional)

Deploy to a small percentage first:

shorebird patch --staged-rollout 0.05
# Deploys to 5% of users

Monitor for 24 hours, then increase:

shorebird patch --staged-rollout 0.5
# Deploys to 50% of users

Finally, roll out to everyone:

shorebird patch --staged-rollout 1.0
# 100% rollout

CI/CD Integration

GitHub Actions Example

Create .github/workflows/shorebird-patch.yml:

name: Shorebird Patch Deployment

on:
  workflow_dispatch:
    inputs:
      staged_rollout:
        description: 'Staged rollout percentage (0.0-1.0)'
        required: false
        default: '1.0'

jobs:
  patch:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.x'

      - name: Install Shorebird
        run: |
          curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/shorebird/main/scripts/install.sh | bash

      - name: Authenticate Shorebird
        run: shorebird login --token ${{ secrets.SHOREBIRD_TOKEN }}

      - name: Create Patch
        run: shorebird patch --staged-rollout ${{ github.event.inputs.staged_rollout || '1.0' }}

      - name: Notify Slack
        uses: slackapi/slack-github-action@v1
        with:
          webhook-url: ${{ secrets.SLACK_WEBHOOK }}
          payload: |
            {
              "text": "✅ Shorebird patch deployed successfully!",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "Shorebird Patch Deployed\nRollout: ${{ github.event.inputs.staged_rollout || '100%' }}\nRef: ${{ github.ref }}"
                  }
                }
              ]
            }

GitLab CI Example

Create .gitlab-ci.yml:

patch:shorebird:
  stage: deploy
  image: google/flutter:latest

  script:
    - curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/shorebird/main/scripts/install.sh | bash
    - shorebird login --token $SHOREBIRD_TOKEN
    - shorebird patch --staged-rollout 0.5

  only:
    - main

  when: manual

Best Practices

1. Test Before Patching

Always test your code locally and in staging:

flutter test
flutter analyze
flutter run --release

2. Use Semantic Versioning

# Major.Minor.Patch+BuildNumber
version: 1.2.3+45

3. Document Your Patches

Create a CHANGELOG:

## [1.2.3] - 2024-06-07

### Fixed
- Fixed email validation bug in login screen
- Corrected typo in onboarding flow
- Resolved memory leak in metrics tracker

### Changed
- Improved error messages for better UX

4. Staged Rollouts for Critical Patches

Never roll out 100% immediately:

# Day 1: 5%
shorebird patch --staged-rollout 0.05

# Day 2: 25%
shorebird patch --staged-rollout 0.25

# Day 3: 100%
shorebird patch --staged-rollout 1.0

5. Monitor Metrics

Check adoption and error rates:

shorebird patch status --verbose

6. Have a Rollback Plan

If a patch causes issues:

shorebird patch rollback

Troubleshooting

Issue: "App ID not found"

Solution:

shorebird init  # Re-initialize
shorebird login  # Re-authenticate

Issue: "Patch failed: No changes detected"

Cause: No Dart code changes since last release.

Solution:

# Ensure build number is incremented
version: 1.0.0+2  # Changed from +1

Issue: "Users not receiving patch"

Cause: App not checking for updates.

Solution: Add to main.dart:

final codePush = ShorebirdsCodePush();
await codePush.checkForUpdates();

Issue: "Staged rollout stuck at X%"

Solution:

shorebird patch status --verbose
shorebird patch resume  # Resume rollout

Issue: "Build fails on iOS"

Solution:

cd ios
pod repo update
pod install
cd ..
flutter clean
shorebird build ipa --release

Summary

Shorebird transforms how you deploy Flutter apps:

Feature	Without Shorebird	With Shorebird
Hotfix Time	24-48 hours	5 minutes
User Experience	Bugs persist	Instant fixes
A/B Testing	Requires app update	Real-time
Rollback	Requires new submission	Instant
Cost	High (support tickets)	Low (automated)

Next Steps

Visit: https://shorebird.dev/
Read: Shorebird documentation
Try: Create your first patch
Integrate: Add to your CI/CD pipeline
Deploy: Ship faster, update smarter

Resources

📖 Official Docs: https://docs.shorebird.dev/
🐛 GitHub Issues: https://github.com/shorebirdtech/shorebird
💬 Discord Community: https://discord.gg/shorebird
📺 Video Guide: https://www.youtube.com/watch?v=EIiBDoVHlNc&t=10s

Happy patching! 🚀

📲 Why Your iOS Push Notifications Just Died: APNs Certificates vs. Keys

George Ikwegbu Chinedu — Mon, 04 May 2026 16:16:08 +0000

Cover image source: RDNE Stock project by RDNE

If you've been building Flutter apps for a while, you know the sinking feeling of a QA report saying: "Push notifications stopped working on iOS." You check the code, and nothing has changed. You check Android, and it works perfectly.

Then you log into Firebase and see it: The dreaded red box. Your APNs certificates have expired.

In this article, we'll dive into the fundamental difference between APNs Certificates and Auth Keys, and why as a seasoned developer, you should almost always choose the latter.

The Contenders: .p12 vs. .p8

For years, developers relied on APNs Certificates (.p12 files). While they work, they come with a high maintenance cost. Recently, Apple introduced APNs Authentication Keys (.p8 files), which have quickly become the industry standard.

1. APNs Certificates (.p12)

Expiration: They expire every 12 months. If you forget to renew them, your production notifications stop instantly.
Scope: Each certificate is tied to a single App ID. If you have 5 apps, you manage 5 certificates.
Environment: You often need separate certificates for Development (Sandbox) and Production.

2. APNs Authentication Keys (.p8) — Recommended

Expiration: They never expire. Set it once, and forget it forever.
Scope: One key works for all your apps under a single Apple Developer account.
Environment: The same key handles both Sandbox and Production environments seamlessly.

Step-by-Step: How to Get Your APNs Credentials

Option A: The Modern Way (APNs Auth Key)

This is the "Pro" move to ensure your notifications never die again.

Apple Developer Portal: Log in and head to Certificates, Identifiers & Profiles.
Create Key: Click Keys on the left sidebar, then hit the (+) button.
Configure: Give it a name (e.g., "Firebase_Global_Key") and check the box for Apple Push Notifications service (APNs).
Register & Download: Click Continue, then Register. Download the .p8 file.
- Warning: You can only download this file **ONCE. Store it securely!
Firebase Setup: Go to Project Settings > Cloud Messaging. Under your iOS app, upload the .p8 file. You’ll need your Key ID (found on the download page) and your Team ID (found in your Apple account membership details).

Option B: The Old Way (APNs Certificate)

Use this only if your specific infrastructure requires it.

Apple Developer Portal: Go to Certificates and click (+).
Select Type: Choose Apple Push Notification service SSL (Sandbox & Production).
Choose App ID: Select the specific Bundle ID for your app.
CSR Request: You’ll need to upload a Certificate Signing Request (CSR) generated from your Mac's Keychain Access app.
Download & Export: Once generated, download the .cer file. Double-click to add it to your Keychain, then right-click and Export it as a .p12 file.
Firebase Setup: Upload this .p12 file to Firebase under Cloud Messaging.

The Expert Verdict

Stop using .p12 certificates. The overhead of annual renewals and multi-app management is a productivity killer. Switch to a .p8 Auth Key today to safeguard your app's communication and keep your QA team happy.

Happy Fluttering! 🚀

Implementing App and Universal Links in Flutter

George Ikwegbu Chinedu — Mon, 08 Apr 2024 15:06:04 +0000

It's no news that, come August 25, 2025, Firebase will no longer support dynamic links for Flutter applications. To that effect, we will need to handle the app link (for Android) and the universal link (for iOS) ourselves. And in this article, we will be doing so with the help of onGenerateRoute.

Table of Content

🎉 Introduction
✨ AppLink Overview
⚙️ Updating AndroidManifest.xml
🍦 Creating SHA256
💪 Creating & Hosting assetlinks.json file
🧪 Testing and Confirming assetlinks.json
🚀 Deploy app to PlayStore internal testing
✅ Confirm the link is auto verified in the device hardware app settings
🌐 Universal Link Overview
👮🏾‍♀️ Adding capability
📡 Creating & Hosting AASA file
🔌 Confirming Our AASA file
⚒️ Testing Via cmd xcrun
⛓️ OnGenerateRoute Setup and Routing to a dynamic page with data

🎉 Introduction

Deep or dynamic linking is a great feature that Flutter offers in its application to enable a continuance in data consumption from a website to a mobile application.

For instance, say you have an e-commerce website with products to be sold or an online campaign website where users need to vote or be voted for. A user could share a link to that product/profile with another user, who then clicks on the link to be led to the website to continue their business. In a situation where you have both a website and a mobile app and you want the users to still continue their business through the mobile interface, that is where a deep or dynamic link comes in.

NB: In situations where the shared user does not have the app installed, they'd be redirected to their respective device's stores (Play or Apple Store) to download and continue with the application.

PS: In this article, we will be handling the applink and universal link for Android and iOS, respectively.

✨ AppLink Overview

We will be following the official Android Guidelines.

⚙️ Updating AndroidManifest.xml

Navigate to your AndroidManifest.xml file and add the below intent inside your <android> block.

<meta-data android:name="flutter_deeplinking_enabled" android:value="true" /> 
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:scheme="http" />
    <data android:host="gikwegbu.com" />
    <data android:host="www.gikwegbu.com" />
</intent-filter>

NB: You need `flutter_deeplinking_enabled` for it to work; that way, the route can be passed from the Android routing system into our Flutter application.

NB: Please update the `gikwegbu` host with your personal domain name.

🍦 Creating SHA256

We will need to create an SHA256 for our application. To do that, open your root project in the terminal and run the below code:

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

Then copy the SHA256 value that comes up.

💪 Creating & Hosting AssetLink.json file

You can either use the Statement List Generator and Tester link to Generate your statement and in future, Test your statement. Or simply update the below json file with your own details;

NB: This code MUST be saved in the assetLinks.json file.

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.gikwegbu.app",
      "sha256_cert_fingerprints":
      ["PASTE YOUR OWN SHA256 HERE"]
    }
  }]

NB: Update the package_name with your app's own.

Congratulations if you've gotten to this place so far; you're a genius. But before we host our json file, we need to do something first. I assume you already have a PlayStore account and an APP created for your currently built application. If you don't, please pause and do so.

There is every tendency that your app already exists in the store, and you just want to include this feature, which is perfect. All I need you to do is get the SHA256 google Auto-created for you application in the integrity section of the console and update the sha256_cert_fingerprints in your AssetLink.json. Remember, it's an array of SHA256 values, so just a comma and the new SHA256 value from PlayStore console.

    [{
      "relation": 
      ["delegate_permission/common.handle_all_urls"],
       "target": {
      "namespace": "android_app",
      "package_name": "com.gikwegbu.app",
      "sha256_cert_fingerprints":
      ["PASTE YOUR OWN SHA256 HERE", "PASTE GOOGLE PLAY CONSOLE SHA256 HERE TOO"]
    }
  }]

Hosting your AssetLink.json file;

For this, you will have to reach out to the person managing the website, as we need to upload our file to a specific directory.

http://gikwegbu.com/.well-known/assetlinks.json

NB: It is very important that you place assetlinks.json inside the .well-known/ directory.

NB: The domain must match what you provided in your AndroidManifest.xml android:host data as well.

NB: Once it has been hosted, make sure it's accessible by visiting http://gikwegbu.com/.well-known/assetlinks.json. If it's accessible, you'll see the json data displayed.

🧪 Testing and Confirming AssetLink.json file

To test if your assetlink.json will be OK, provide the required details in the Statement List Generator and Tester, then click on Test Statement to confirm.

This will crawl your website, to confirm the assetlink.json file is present, and the SHA256 keys are also valid.

As a bonus, try inputing the SHA256 you got from the Google Play Console, to confirm it works too.

🚀 Deploy app to PlayStore internal testing

Based on my earlier assumption that you just created the app on your Google Console, we would be deploying to internal testing, just so we could test out our deep links before releasing them to the actual store.

NB: This article won't cover how to build and upload your appbundle to the store.

PS: If you have already released your app, no problem, just continue with the next step.

On your Google Play Console, go to the Deep Links on Side Navigation, If everything we've done so far has worked out well, you should get a pretty dashboard like below.

Getting Started

Successful Upload

NB: If there's still an issue, please reach out to me, and I'll be glad to help out.

NB: Once you have uploaded the appbundle to your internal testing, wait for a while (say an hour; honestly, I don't know how long it takes for Google to verify your assetlink and web domains) before installing it.

NB: When you have installed it on your device, go to your flutter app's details, select Set as default, > Supported web addresses and see if the host you provided in the AndroidManifest.xml is/are present there.

Your flutter app settings

Set as default

Approved Hosts

✅ Confirm the link is auto verified in the device hardware app settings

Because in our AndroidManifest.xml, we set the <intent-filter android:autoVerify="true">, therefore, you shouldn't see the toggle/switch button beside your host.

Approved Hosts

Whoop Whoooop!!!! We just finished Applink on our Android.

PS: Stick around to the end of the article to learn how the routing works with the onGenerateRoute configs in Flutter.

🌐 Universal Link Overview

For our iOS application, we will be using a Universal link, which is an exclusive type of deep link to Apple devices that uses either the http or the https schemes.

👮🏾‍♀️ Adding capability

In the next few steps, we will be working closely with XCode via the following steps:

Open your project in XCode,
In your Project Navigator, click on the Runner.
Click the Runner in the TARGETS section.
Select Signing & Capabilities.
Click on the + Capability,
When the Modal pops up, search for Associated Domains and add it.

After adding the Associated Domains, update the current web credential Domains with;

applinks:gikwegbu.com // first input
applinks:www.gikwegbu.com // second input

NB: I like adding more options so my app will be recognized when users try to access it with or without the www.

NB: While the above is the easiest and UI approach of adding the Runner.entitlements to your app, you could just create. a Runner.entitlements file within your ios/Runner/ directory, ad add the below code manually:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:gikwegbu.com</string>
        <string>applinks:www.gikwegbu.com</string>
    </array>
</dict>
</plist>

NB: gikwegbu.com should be your own domain.

From our Step 3 above, whilst still on the Runner in the TARGET section:

Click on the info tab.
Open the URL Types dropdown and complete the form with below data:

identifier : your app's bundle Identifier,
URL Schemes: https.

NB: You can get you bundle Identifier from your Signing & Capabilities tab in XCode.

NB: For the iOS routing system to successfully parse the dynamic url back into our Flutter application, we need to add the below data into our info.plist file;

<key>FlutterDeepLinkingEnabled</key>
<true/>

📡 Creating & Hosting AASA file

Open your project root in the terminal and run the below code:

$ touch apple-app-site-association

Then copy and paste the below code, with your own data;

{   
  "applinks": {       
    "apps": [],

    "details": [{           
        "appID": "[TEAM_ID].[APP_BUNDLE_ID]",           
        "paths": ["[PATH_FOR_REDIRECTION]"]
    }]
  }
}

NB: To get your Team_ID, just open your apple dev account, you'd see the ID by the top right, underneath your name of your screen,

"paths": [
       "/your_path", // Users will be be redirected if they visit <https://gikwegbu.com/your_path>
       "/your_path/*", // Users will be redirected if they visit  <https://gikwegbu.com/your_path/[shduewjakssd]>
       "*", // will be redirected to any link <https://gikwegbu.com/[wild card links]>
       "NOT /your_path", // Users will be be redirected  to any link other than <https://gikwegbu.com/your_path>
       "NOT /your_path/*", // Users be redirected to any link other than <https://gikwegbu.com/your_path/[wild card]>

]

Once you're done with the above, host the AASA file on your domain, within the .well-known/ directory, just like you did with your Android assetlinks.json file.

🔌 Confirming Our AASA file

To confirm if the AASA file was properly hosted, once you visit the http://gikwegbu.com/.well-known/apple-app-site-association, the file will automatically be downloaded onto your machine.

NB: gikwegbu will be your own domain.

⚒️ Testing Via cmd xcrun

First make sure your XCode is running your Flutter app, Open your terminal and run the below code:

$ xcrun simctl openurl booted https://gikwegbu.com/guest/dsewe

NB: Since we haven't worked on the Routing system in our Flutter app, the above command should simply launch your app.

⛓️ OnGenerateRoute Setup and Routing to a dynamic page with data

For an efficient and cleaner codebase, I like to keep all my routes in a separate file.

Within your MaterialApp, in your main.dart file, you can add your onGenerateRoute data and point it to the external routes file.

Image of the main.dart file

Here, we will create a class called Routes;

class Routes {
  static Route<dynamic> generateRoute(RouteSettings settings) {
    debugPrint('${settings.name} Is the current route' );

    if (settings.name!.contains('guest')) {
      final page = PreInviteInfoScreen(
        code: settings.name!.split('/').last,
      );
      return MaterialPageRoute(builder: (_) => page);
    }

    final args = settings.arguments;  // For screens that requires arguements to be passed
    switch (settings.name) {
      case HomeView.routeName:
        const page = HomeView();
        return MaterialPageRoute(builder: (_) => page);
      default:
        const page = HomeView();
        return MaterialPageRoute(builder: (_) => page);
    }
  }
}

NB: For more context, say the link our users clicks on is https://www.gikwegbu.com/guest/Uhdys, the if statement, will check if that route has the guest keyword, then extract to get the code as it a URL PATH.

This way, when a user clicks on the link above, only the Uhdys is now being passed as the argument for the next screen immediately the app launches.

THE END

So with the above sets of instructions and examples, you should be able to get the Applink and Universal link ready for your FLutter application. CONGRATULATIONS AND GOOD LUCK.

Custom Flutter GroupListView Widget

George Ikwegbu Chinedu — Mon, 05 Feb 2024 09:08:50 +0000

Table of Content

🎉 Introduction
✨ Items JSON
⚙️ Modeling our Data
🍦 Implementation
💪 Full Code
💙 Summary

🎉 Introduction

You may need to arrange items in an orderly manner at some point. These objects might be anything, employing a specific property in their object, from a list of books to questions.

NB: Check out my previous article, in which I explain how to create a form in Flutter dynamically. I used this article to group the questions according to their order.

✨ Items JSON

I would be constructing a basic JSON data set as our source data in order to keep things simple. Although this will be relatively little data, you can reuse the function in your larger dataset after you understand how it operates.

// Continent and Country Json data
const itemsJsonData = 

[
  {
    "id": 0,
    "continent": "Africa",
    "country": "Nigeria", 
    "order": 1
  },
  {
    "id": 1,
    "continent": "Asia",
    "country": "Cambodia", 
    "order": 10
  },
  {
    "id": 2,
    "continent": "NorthAmerica",
    "country": "Canada", 
    "order": 2
  },
  {
    "id": 3,
    "continent": "NorthAmerica", 
    "order": 2
  },
  {
    "id": 4,
    "continent": "SouthAmerica",
    "country": "Brazil", 
    "order": 3
  },
  {
    "id": 5,
    "continent": "Europe",
    "country": "Austria", 
    "order": 12
  },
  {
    "id": 6,
    "continent": "Africa",
    "country": "Burundi",
    "order": 1
  },
  {
    "id": 7,
    "continent": "Asia",
    "country": "Azerbaijan",
    "order": 10
  },
  {
    "id": 8,
    "continent": "NorthAmerica",
    "country": "Belize",
    "order": 2
  },
  {
    "id": 9,
    "continent": "NorthAmerica",
    "country": "Antigua and Barbuda",
    "order": 2
  },
  {
    "id": 10,
    "continent": "SouthAmerica",
    "country": "Argentina",
    "order": 3
  },
  {
    "id": 11,
    "continent": "Europe",
    "country": "Andorra",
    "order": 12
  },

];

NB: Pay close attention to the continent and country 
dataset and it's ordering and how it is an `int`..

NB: Request the server sends the `order` as an `int` 
value. Else, you might have to map over the keys and turn 
them to `int`

⚙️ Modeling our Data

For simplicity sake, we would be creating a model, which will enable us interact with the data efficiently.

class ContCountryModel {
  final int? id;
  final String? continent;
  final String? country;
  final int? order;

 ContCountryModel({
    this.id, 
    this.continent, 
    this.country, 
    this.order,
   });

   factory ContCountryModel.fromJson(Map<String, dynamic> json) => ContCountryModel(
        id: json["id"],
        continent: json["continent"],
        country: json["country"],
        order: json["order"],
    );

    Map<String, dynamic> toJson() => {
        "id": id,
        "continent": continent,
        "country": country,
        "order": order,
    };

  List<ContCountryModel> fromList(List<dynamic> items) {
    if(items.isEmpty) {
      return [];
    } else {
      return items.map((e) => ContCountryModel.fromJson(e)).toList();
    }
  }
}

🍦 Implementation

NB: We won't be covering the network calls; as I assume, you already have the data list in your system and just want to create the grouped list

// We will be needing the `groupBy` found in the `collection` package to first group our items.

import 'package:collection/collection.dart';



// Placed within the State of your stateful widget
List<ContCountryModel> _itemList = [];

Map groupItemsByOrder(List<ContCountryModel> items) {
 return groupBy(items, (item) => item.order);
}
// When the above function runs, it'll arrange all the items by their `order`. But since the `order` is a `String` datatype, it won't be mathematically correct, e.g; `10` will come before `2`.


// Placed within state builder:

Map groupedItems = groupItemsByOrder(_itemList);

// NB: You can either load the `_itemList` in the `initState` or use any `state management` system of your choice to get the data.


// Here we will be using a `ListView.builder` within a `ListView.builder` to get our `Continents` and the `Countries` within it in a grouped fashion


ListView.builder(
  itemCount: groupedItems.length,
  itemBuilder: (BuildContext context, int index) {

    var sortedKeys = groupedItems.keys.toList()..sort();
   // Since the groupedItems is a Map,we can use the .keys, 
      to get all the keys, then turn it into a list before 
      sorting it

    int order = sortedKeys.elementAt(index);
    // Recall that groupedItems returns a Map of data grouped 
       by 'order', hence using the above listView index,

    // we fetch the key that matches the index, which inturn 
       becomes the active 'order' in the current loop.

    List<ContCountryModel> itemsInCategory =
groupedItems[order]!;

     // With the help of the retrieved `order` , we now get 
        the items in the category data, with which we would 
        use to create the second ListView

     // Return a widget representing the category and its 
        items

     return Column(
              children: [
                 Padding(
                   padding: const EdgeInsets.only(top: 20),
                   child: Text(
                         "${itemsInCategory.first.continent}:"),
                   ),
                 ListView.builder(
                   shrinkWrap: true,
                   physics: const ClampingScrollPhysics(),
                   itemCount: itemsInCategory.length,
                   itemBuilder: (BuildContext context, int 
                       index) {
                       ContCountryModel each = 
                      itemsInCategory[index];
                          int _originalListIndex = _itemList
                              .indexWhere((q) => q.id == each.id);
                          // Return a widget representing the item
                          return Padding(
                            padding: const EdgeInsets.symmetric(
                              vertical: 10.0,
                            ),
                            child: Text("${each.country}"),
      );
     },
    ),
   ],
  );
 },
),

💪 Full Code

Here is the full code implementation:



import 'package:flutter/material.dart';
import 'package:collection/collection.dart';


void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'GrouupedList Demo',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'Flutter Grouped List'),
    );
  }
}



class MyHomePage extends StatefulWidget {
  final String title;

  const MyHomePage({
    super.key,
    required this.title,
  }) : super();

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {

// Placed within the State of your stateful widget
  List<ContCountryModel> _itemList = [];

  Map groupItemsByOrder(List<ContCountryModel> items) {
   return groupBy(items, (item) => item.order);
  }
  // When the above function runs, it'll arrange all the items by their `order`. But since the `order` is a `String` datatype, it won't be mathematically correct, e.g; `10` will come before `2`.

   @override
   void initState()  {
    _itemList = ContCountryModel().fromList(itemsJsonData);
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    Map groupedItems = groupItemsByOrder(_itemList);

    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
      ),
      body: Container(
        height: double.infinity,
        width: double.infinity,
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Expanded(
              child: ListView.builder(
                itemCount: groupedItems.length,
                itemBuilder: (BuildContext context, int index) {

                  var sortedKeys = groupedItems.keys.toList()..sort();
                  // Since the groupedItems is a Map,we can use the .keys, to get all the keys, then turn it into a list before sorting it

                  int order = sortedKeys.elementAt(index);
                  // Recall that groupedItems returns a Map of data grouped by 'order', hence using the above listView index,
                  // we fetch the key that matches the index, which inturn becomes the active 'order' in the current loop.

                  List<ContCountryModel> itemsInCategory =
                      groupedItems[order]!;
                  // With the help of the retrieved `order` , we now get the items in the category data, with which we would use to create the second ListView

                  // Return a widget representing the category and its items
                  return Column(
                    children: [
                      Padding(
                        padding: const EdgeInsets.only(top: 20),
                        child: Text(
                              "${itemsInCategory.first.continent}:"
                            ),
                      ),
                      ListView.builder(
                        shrinkWrap: true,
                        physics: const ClampingScrollPhysics(),
                        itemCount: itemsInCategory.length,
                        itemBuilder:
                            (BuildContext context, int index) {
                          ContCountryModel each = itemsInCategory[index];
                          int _originalListIndex = _itemList
                              .indexWhere((q) => q.id == each.id);
                          // Return a widget representing the item
                          return Padding(
                            padding: const EdgeInsets.symmetric(
                              vertical: 10.0,
                            ),
                            child: Text("${each.country}"),
                          );
                        },
                      ),
                    ],
                  );
                },
              ), // ListView Ends here
            )

          ],
        ),
      )
      // Body ends here
    );
  }
}


class ContCountryModel {
  final int? id;
  final String? continent;
  final String? country;
  final int? order;

 ContCountryModel({
    this.id, 
    this.continent, 
    this.country, 
    this.order,
   });

   factory ContCountryModel.fromJson(Map<String, dynamic> json) => ContCountryModel(
        id: json["id"],
        continent: json["continent"],
        country: json["country"],
        order: json["order"],
    );

    Map<String, dynamic> toJson() => {
        "id": id,
        "continent": continent,
        "country": country,
        "order": order,
    };

  List<ContCountryModel> fromList(List<dynamic> items) {
    if(items.isEmpty) {
      return [];
    } else {
      return items.map((e) => ContCountryModel.fromJson(e)).toList();
    }
  }
}

// Continent and Country Json data
const itemsJsonData = 

[
  {
    "id": 0,
    "continent": "Africa",
    "country": "Nigeria", 
    "order": 1
  },
  {
    "id": 1,
    "continent": "Asia",
    "country": "Cambodia", 
    "order": 10
  },
  {
    "id": 2,
    "continent": "NorthAmerica",
    "country": "Canada", 
    "order": 2
  },
  {
    "id": 3,
    "continent": "NorthAmerica", 
    "order": 2
  },
  {
    "id": 4,
    "continent": "SouthAmerica",
    "country": "Brazil", 
    "order": 3
  },
  {
    "id": 5,
    "continent": "Europe",
    "country": "Austria", 
    "order": 12
  },
  {
    "id": 6,
    "continent": "Africa",
    "country": "Burundi",
    "order": 1
  },
  {
    "id": 7,
    "continent": "Asia",
    "country": "Azerbaijan",
    "order": 10
  },
  {
    "id": 8,
    "continent": "NorthAmerica",
    "country": "Belize",
    "order": 2
  },
  {
    "id": 9,
    "continent": "NorthAmerica",
    "country": "Antigua and Barbuda",
    "order": 2
  },
  {
    "id": 10,
    "continent": "SouthAmerica",
    "country": "Argentina",
    "order": 3
  },
  {
    "id": 11,
    "continent": "Europe",
    "country": "Andorra",
    "order": 12
  },

];

💙 Summary

In this article, we were able to

create a model class for our item that also houses a .fromList method that enables you to easily get a list of items from a dynamic list and the .fromJson also to easily map our json data onto our model.
Provide a dummy list for the item, and lastly,
Implement a ListView within a ListView, which would represent the sorted items while having it's continent as a Header placed above each section of the list..

NB: Once you understand how the above was achieved, you can create multiple UI using the same approach.

Flutter Apple Auth Implementation

George Ikwegbu Chinedu — Tue, 16 Jan 2024 09:14:25 +0000

NB: This article is not for a total beginner, as you need a basic understanding of how Flutter works and API consumption to fully comprehend this article.

Table of Content

✨ Introduction
💪 Flutter Auth Packages
🍏 Apple accepted Data Flow
😬 Edge Cases

✨ Introduction

Apple Sign-In is a feature that enables users of your application to either sign up or sign in to your application using their iCloud account across all of your platforms while utilizing two-factor authentication. In this article, we will be looking at how to use the Flutter package to complete this feature on a mobile phone.

Sign in with Apple flow: From Apple

For full information about this sign in with Apple, please make reference to this site: Authenticating users with Sign in with Apple

💪 Flutter Auth Packages

To follow up with this article, we will be using the sign_in_with_apple package. To avoid repetitions, you can follow the instructions on this package page.

In summary, select Sign In with Apple Capability.
NB: You can achieve this by simply:

Going to your XCode,
Select Signing & Capabilities tab,
Click on the Capability beneath, a modal pops up.
Either scroll down or just search for sign, you should see the option,
Select to enable it.

🍏 Apple accepted Data Flow

Once a user has authenticated and either accepted to show or hide their email, they should be either registered or logged into your application (depending on what feature you're using it for) and not redirected to complete anything else, as that will make the review team flag your app during testing.

Best advice: make your signup endpoint either flexible or have a different endpoint for social OAuths. That way, you get to prompt the user to update their profiles once they're already logged into the system.

SignInWithAppleButton(
  onPressed: () async {
    final credential = await SignInWithApple.getAppleIDCredential(
      scopes: [
        AppleIDAuthorizationScopes.email,
        AppleIDAuthorizationScopes.fullName,
      ],
    );

    print(credential);

    // Now send the credential (especially `credential.authorizationCode`) to your server to create a session
    // after they have been validated with Apple (see `Integration` section for more information on how to do this)
  },
);

Images from Sign_in_with_apple

😬 Edge Cases

Apple's authentication is so security tight, that you as the developer will only get the user's email just once, and which is the initial time they used the apple service to sign into your application. If the log out of your application and tried to log back in, there's a tendency of it not working, as you might be expecting their email to continue.

To circumvent that, I'd suggest that you first check if the email is returned from the above code, if yes then continue with your normal implementation, else, send the identityToken, which is a value returned from the apple api call to your server. Then your server gets to decode that jwt_token, gets the email address and checks if user exist in the system.

PS: You can actually decode the jwt_tpken from you flutter side first and still re-use your supposed api.

This might be a security flaw, what do you think?

flutter iOS app is stuck on launchScreen when installed on real device 🚀🚀🚀🚀

George Ikwegbu Chinedu — Tue, 05 Dec 2023 20:09:22 +0000

NB: This is going to be a really short article 🥹🥹.

While working on my application with my team, we noticed our app was stuck on the splash screen, though this wasn't happening across all devices, as some ios devices went past the splash screen while some were simply stuck.

This even made apple to reject our submission on the basis of Performance - App Completeness.

To keep this short, make sure that all your functions in your main.dart is working well. In my own case, the culprit was my setupNotification() where I handled my pushNotification.

This required me to get the firebase token and also subscribe the device to a topic.

Well, this was where my headache started. I had gone forward to subscribe the device to a topic, which was causing the problem. The painful part was that I didn't get log on my IDE. Luckily for me I was able to see the exception from my firebase crashlytics.

Apparently, I needed to request for the APNSToken for iOS before I can subscribe to the topic.

final FirebaseMessaging _firebaseMessaging = FirebaseMessaging.instance;

  if (Platform.isIOS) {
      String? apnsToken = await _firebaseMessaging.getAPNSToken();
      if (apnsToken != null) {
        try {
          await _firebaseMessaging.subscribeToTopic('notificationChannel');
        } on FirebaseException catch (e) {
          debugPrint("George here is the error: $e");
        }
      } else {
        await Future<void>.delayed(const Duration(seconds: 3));
        apnsToken = await _firebaseMessaging.getAPNSToken();
        if (apnsToken != null) {
          try {
            await _firebaseMessaging.subscribeToTopic('notificationChannel');
          } on FirebaseException catch (e) {
            debugPrint("George here is the error: $e");
          }
        }
      }
    } else {
      try {
        await _firebaseMessaging.subscribeToTopic('notificationChannel');
      } on FirebaseException catch (e) {
        debugPrint("George here is the error: $e");
      }
    }

This way, the error was corrected.

NB: Just trace the functions you have running in your main that might be throwing an error.

Thanks...

Integrating Zendesk with Flutter

George Ikwegbu Chinedu — Mon, 22 Aug 2022 20:02:04 +0000

Image Credit: Pexels by Cottonbro

Table of Content

🕹 Introduction
🎥 Tips
🧰 Zendesk Flutter Package
🧰 implementation
🎙 Setting up Channel Message
📲 Codebase

🕹 Introduction

Zendesk is an American company headquartered in San Francisco, California. It provides software-as-a-service (Saas) products related to customer support, sales, and other customer communications.

This Saas, provides a ticketing platform for users, and companies at large. In this article, you'll learn how to integrate zendesk into your flutter application with ease, setup and configure your zendesk dashboard for the utmost experience.

NB: This article covers both the android and iOS Flutter platform

🎥 Tips

Before we continue, there are somethings I'd love to get out of the way,

You should be familiar with Flutter and how to add Packages.
Already created a zendesk admin account or have access to it. If you don't (probably as the developer), do well to reach out to the person managing the zendesk platform, share this article or explain the information you'll be needing from them.

🧰 Zendesk Flutter Package

There are lots of zendesk packages on the pub.dev platform, but I found one to be very detailed and worked well for me. Click on zendesk_messaging, copy the current version and add to your pubspec.yaml file.

🎥 Implementation

Once you have added the package to your pubspec.yaml, run the below code in the terminal of your project's root.

flutter pub get

In other not to repeat the implementations, do follow through with what you see on the zendesk_messaging package screen. I'd only walk you through where to get the necessary information.

🎙 Setting up Channel Message

On your zendesk admin dashboard, with side navigation bar, go to the Channel -> Messaging and Social, select the message tab.

Incase no messaging channel has been added yet, you'd have to click on the 'Add Channel' dropdown button, to select your options, which in our case will be the 'Android and iOS'

Upon selection of either the Android or iOS channel, you'll be walked through on the settings, there you'll find your "channel key", please copy this out and store in your code.

NB: It's platform specific, meaning both the Android and iOS have different channel keys.

From the Above Image, you'd notice six (6) tabs;

1. The Basic, which is essentially where you see the name 
   of the channel you're currently working on.

2. The Style, here you set the color of the zendesk on 
   either platform you're working on, you could provide 
   your app's color, so it'll still match your beautiful 
   UI.

3. The Response, you get to configure how to respond to 
   messages, add bot privileges etc...

4. The Notification, well it's like adding Firebase Cloud 
   Messaging, for push notifications in your mobile app.

5. The Authentication, here, you'll be redirected to go 
   setup your "jwt", a short form of "Javascript Web 
   Token", which plays a vital role, in recognising  and 
   retaining users once they are chatting with you (The 
   help center)

📲 Codebase

Like I said previously, if you (as a developer), don't have access to the zendesk dashboard, you can request for the above information from the person managing the dashboard.

Initialising Zendesk in your applicaition.

// paste the android and ios channel keys you earlier copied out here.

// These keys, should be placed in a .env file, and added to the .gitignore file, so you don't check it into any version control system.

final String androidChannelKey = '';
final String iosChannelKey = '';

  @override
  void initState() {
    super.initState();
    ZendeskMessaging.initialize(
      androidChannelKey: androidChannelKey,
      iosChannelKey: iosChannelKey,
    );
  }

Showing the Zendesk

ZendeskMessaging.show();

NB: The above method could be added to any GestureDetector of your choice, say onTap, of a button, to pop up the zendesk platform.

Authenticating Users

This is optional, but necessary if you want to keep track of the user chat across platforms, meaning, if user closes and opens the application again, the chat history will be there.

PS: The Zendesk must be initialised before you authenticate.

// Remember the 'jwt' from the Authentication tab on your zendesk dashboard, replace the "YOUR_JWT" with your actual 'jwt'

final ZendeskLoginResponse result = await ZendeskMessaging.loginUser(jwt: "YOUR_JWT");
await ZendeskMessaging.logoutUser();

Flutter Paystack All Options Implementation

George Ikwegbu Chinedu — Thu, 21 Jul 2022 08:51:00 +0000

Table of Content

🕹 Introduction
📡 Required Paystack Details and Endpoints
🖲 Installing WebView Package
🛢 Making API calls in Flutter
📲 Displaying Paystack pop-up in webView
💾 Listening For Navigation url
💙 Important Notes for Release APK

🕹 Introduction

As at the time of writing this article, paystack integration for android and mobile SDK, only supports card payments and bank (with just Zenith as the option).

In this article, you will learn how to include other payment options in your flutter application.

PS: I'm assuming you are familiar with flutter and 
paystack with all the necessary keys and how to get them 
from your paystack dashboard.

Before we continue, please take a quick look at this article from Paystack, that's where I got ideas from 😋. If you want, you could use that article, or continue reading.

📡 Required Paystack Details and Endpoints

You will need your paystack secret_key (use the test key for testing and live key for prod) as your Bearer token in your Authorization header while making a POST request to the paystack initialize api.

Check the below images for better understanding.

Setting your authorization header with secret_key

POST body details

email: This is the payers email.

amount: This is the amount to be paid, please multiply by 
        100, to remove the kobo value

reference: This should be randomly generated as it should 
           be a unique value for each payment.

callback_url: This is the most important part. If you 
              already have a callback url, setup from your 
              paystack dashboard, you don't need this 
              parameter. If you still go ahead to include 
              it, it'll override that of the dashboard. 
              This callback_url is what we will be 
              listening for from our webview.

cancel_action: This will be used to listen for when the 
               user wants to cancel payment, we then pop 
               the webview screen.

Response from paystack API

authorization_url: This is the most important data we will 
                   be needing for our webview, so hold on 
                   to it 😎.

🖲 Installing WebView Package

To install this package, please visit this link, read through the setup and install it.

🛢 Making API calls in Flutter

This approach depends on which architecture you're using to build your application, at the end, it's all the same response you will receive. In this article, i'll be keeping it really simple 🥹.

var headers = {
  'Authorization': 'Bearer sk_test_039***************',
  'Content-Type': 'application/json',
};
var request = http.Request('POST', Uri.parse('https://api.paystack.co/transaction/initialize'));
request.body = json.encode({
  "email": "g.ikwegbu@gmail.com",
  "amount": "10000",
  "reference": "randomDetails",
  "callback_url": "https://github.com/gikwegbu",
  "metadata": {"cancel_action": "https://www.google.com/"}
});
request.headers.addAll(headers);

http.StreamedResponse response = await request.send();

if (response.statusCode == 200) {
  print(await response.stream.bytesToString());
}
else {
  print(response.reasonPhrase);
}

PS: I personally love using the flutter dio package

Retrieve the authorization_url from the response and store 
it in a global variable.

📲 Displaying Paystack pop-up in webView

Ok, let's be on the same page here 🙃. We are building an application that allows users make payment for an item via paystack.

🏳️ The Data Flow:

when the user clicks on the PAY button, the paystack pops-up, user selects whichever option that's suitable, and proceed. Once the payment is successful, we will be redirected to a callback_url. Once this happens, we will have to be listening for that callback_url, which when detected, allows us to close the webview widget, and then continue with sending our reference code to our server to complete checking out of the PAID item.

🏳️ Implementation:

To make the process seamless, i'd be using a popup dialog, set it to fullscreen to overlay our current page, add the webview widget.

Below is a code snippet that will help you understand more:


// This is called when the PAY button is clicked.
_showPaystack() async {
    var _ref = 'ChargedFromMyApp_${DateTime.now().millisecondsSinceEpoch}';
    Map data = {
      // Removing the kobo by multiplying with 100
      "amount": double.parse('${_amount * 100}').toInt(),
      "email": _user.email,
      "reference": _ref,
      "callback_url": "https://github.com/gikwegbu",
      "metadata": {"cancel_action": "https://www.google.com/"}
    };
    // This awaits the [authorization_url](#authUrl). NB: I'm using the MVVM architecture in my live code, but it's still the same process of retrieving the authURL.
    var authUrl = await _profileCtrl.paystackWebViewChargeCard(data);

    // only pull-up the dialog box when we get the authURL
    if (authUrl != null) {
      return showGeneralDialog(
          context: context,
          barrierDismissible: true,
          barrierLabel:
              MaterialLocalizations.of(context).modalBarrierDismissLabel,
          barrierColor: Colors.black45,
          transitionDuration: const Duration(milliseconds: 200),
          pageBuilder: (BuildContext buildContext, Animation animation,
              Animation secondaryAnimation) {
            return Center(
                child: Container(
              width: MediaQuery.of(context).size.width - 10,
              // height: MediaQuery.of(context).size.height - 80,
              height: MediaQuery.of(context).size.height - 0,
              padding: const EdgeInsets.only(top: 40),
              color: Colors.white,
              child: WebView(
                initialUrl: authUrl.toString(),
                javascriptMode: JavascriptMode.unrestricted,
                userAgent: 'Flutter;Webview',
                navigationDelegate: (navigation) {
                  //Listen for callback URL
                  if (navigation.url == "https://standard.paystack.co/close") {
                    Navigator.of(context).pop(); //close webview

                    // _txnRef is my glabally created variable to handle my reference
                    _txnRef = _ref;
                    _submit();
                  }
                  if (navigation.url ==
                      "github.com/gikwegbu?trxref=$_ref&reference=$_ref") {
                    Navigator.of(context).pop();
                    _txnRef = _ref;
                    _submit();
                  }
                  if (navigation.url == "https://www.google.com/") {
                    Navigator.of(context).pop();
                  }
                  return NavigationDecision.navigate;
                },
              ),
            ));
          });
    }
  }

The _submit(), is a function that sends the reference to 
my backend to complete the purchase transaction on the 
selected item.

💾 Listening For Navigation url

From the above code snippet, you'd have noticed the navigationDelegate section, this is where you'll handle listening for the callback_url and also, in the case the user is making payments with a Card, and the 3Ds Authentication will have to redirect you to the 'https://standard.paystack.co/close'. Other than that, we will listen for our custom callback_url, and then pop our screen.

💙 Important Note For Release apk

The application will actually work while in debug mode, but will through an error or not work at all in released build, as you'd only be seeing a gray overlay.

Steps Taken to Resolve this.

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

in your android/app/src/main/AndroidManifest.xml.

if (Platform.isAndroid) WebView.platform = AndroidWebView();

Inside of your initState(){} function of your file. This means you'd have to be using a "Stateful" widget.

This is the most important. Run

flutter run --release

This would help you build your app as in 'release mode', but you can still be seeing your debugs in your console. Now watch closely if you see an error like I/flutter (18782): Another exception was thrown: Instance of 'DiagnosticsProperty<void>', if so, then please look for where Expanded widget was used in your implementation and remove it.

Finally

We have successfully integrated our paystack payment system with multiply option into our flutter application. To experience the multiple option, please change from your test secret key to your live secret key, only then will you see the

Unhandled exception: ProcessException: No such file or directory, Command PhaseScriptExecution failed with a nonzero exit code

George Ikwegbu Chinedu — Fri, 10 Jun 2022 11:28:00 +0000

Photo by eberhard grossgasteiger

As at the time of writing this article, I had already told my parents to prepare a farmland for me, as tech is not my calling again 😂😂😂😂.

This is going to be a different pattern of writing my 
articles.

So if you come across this article as being a solution to a similar problem as the title, well, leave a thumbs up.

So I cloned a flutter project to work on, started off with installing my flutter SDK and the xcode version that the project was created with.

First ran for the android, which worked without issues, but when it got to the iOS, everything went south in split second.

I reached out to the Engineer handling the project initially, we went through installations and codes again, found nothing, I was advised to downgrade my xcode and try again... Long story short, I currently have xcode 13.4, 13.3, 13.3.1, 13.2.1 in my mac 😂.

An image of my error message:

Well, none of the solutions found on stackoverflow and github issues worked for me. Which included the following:

Open the terminal On the root directory of your project, run:

   $ flutter clean
   $ flutter pub get

   // cd into your ios directory
   $ cd ios
   $ pod deintegrate
   $ pod install

   // cd out of your ios directory
   $ cd ..

   // try running the project on your ios simulator
   $ flutter run
   // Be sure your ios simulator is active

Having done all of the above, and even did flutter doctor, just to confirm if I had issues with my installations and setup, nothing worked for me.

The most confusing thing was that, a dummy flutter project I created worked just fine, same as a flutter project I had created with my windows some months back and cloned into my mac, all worked out just fine for both Android and iOS.

I found a regex code

grep -riL "<path to your flutter sdk>" "<path to your project>"

this searches through your project for instances of the flutter sdk in that project. I saw logs for the dummy project and that of the flutter project created with my window, but for this current project, it was showing 'No such directory found'.

Well, my last resort was to open an issue on github, which I reluctantly did, as I saw thousands of opened issues, didn't even expect anyone to look at mine...

Well let's say someone did, and instantly noticed the problem.

Solution

The URL of the cloned project, had a space after the name, 
and git used same pattern to create the directory on my 
machine and this caused the whole problem.

Below is a link to the issue I opened and closed 💁🏽.

Link to Github Issue

Hope it helps.

DEV Community: George Ikwegbu Chinedu

$$$$$$BACKUP FOR | Shipping a Safe Rollback: Downgrading a Drift (SQLite) Database in Flutter Without Losing User Data

The setup

The problem

First attempt: handle it in beforeOpen (didn't work)

Why: Drift calls onUpgrade before beforeOpen, including for downgrades

Why dropping everything was a bad idea anyway

What the schema change actually was

The fix

1. Handle the downgrade in onUpgrade, before stepByStep runs

2. Skip debug schema validation after a downgrade

3. Make the newer migration safe to run twice

A bug that's easy to introduce while making the fix

Testing locally without the release keystore

Checking that the downgrade happened

The git workflow: two versions side by side with git worktree

Building the three QA builds

Commands

The QA test plan

Shipping it

Takeaways

Building a Multi-Tenant Production-Grade Wallet Pass System for Google & Apple: A Complete Architectural & Implementation Guide

Introduction

Part 1 — Google Wallet: From Zero to Issuer

1.1 Create a Google Cloud Project

1.2 Enable the Google Wallet API

1.3 Provision a Dedicated Service Account

1.4 Register in the Google Pay & Wallet Console

1.5 Authorize the Service Account in the Wallet Console

1.6 Pass Classes vs. Pass Objects

1.7 Generating the Save Link: The "Skinny" JWT Flow

JWT Structure

Part 2 — Apple Wallet: Developer Setup, PassKit & Certificates

2.1 Apple Developer Setup

2.2 Register a Pass Type Identifier

2.3 Create & Export Signing Certificates

2.4 Convert to Server-Ready PEM Files

2.5 The .pkpass Package Anatomy & Mandatory Assets

2.6 Apple PassKit Validation Rules & Gotchas

Part 3 — Testing Live Passes Locally via HTTPS Tunneling (ngrok)

3.1 Starting the Tunnel

3.2 Configuring the Backend

Part 4 — Interactive Pass Endpoints & Frontend UX

4.1 Server Pass Endpoints

Google Pass Redirect Endpoint

Apple Pass Download Endpoint

4.2 Frontend Chip Design & Interaction

Part 5 — Designing Passes & Tamper-Proof QR Codes

5.1 Barcodes & Cryptographic Redemptions

Secure Tokenized QR Architecture:

5.2 Dynamic Pass Updates

Part 6 — Multi-Tenant Architecture: One Platform, Hundreds of Brands

6.1 Tenant Class ID Convention

Part 7 — One Customer, Many Tenants: The Junction Model

7.1 Relational Data Model

7.2 Idempotent Pass Issuance

Conclusion & Production Checklist

Production Pre-Flight Checklist

Open Source Repository & Community Contributions

We Welcome Contributions!

Shipping a Safe Rollback: Downgrading a Drift (SQLite) Database in Flutter Without Losing User Data

The setup

The problem

First attempt: handle it in beforeOpen (didn't work)

Why: Drift calls onUpgrade before beforeOpen, including for downgrades

Why dropping everything was a bad idea anyway

What the schema change actually was

The fix

1. Handle the downgrade in onUpgrade, before stepByStep runs

2. Skip debug schema validation after a downgrade

3. Make the newer migration safe to run twice

The rollback-window data problem: structural vs. semantic compatibility

Two ways to solve the NULL/unknown problem

Approach A — Backfill during the re-upgrade migration

Approach B — Treat NULL as "unknown" in application logic

A bug that's easy to introduce while making the fix

Testing locally without the release keystore

Checking that the downgrade happened

The git workflow: two versions side by side with git worktree

Building the three QA builds

First attempt: handle it in `beforeOpen` (didn't work)

Why: Drift calls `onUpgrade` before `beforeOpen`, including for downgrades

1. Handle the downgrade in `onUpgrade`, before `stepByStep` runs

The git workflow: two versions side by side with `git worktree`

First attempt: handle it in `beforeOpen` (didn't work)

Why: Drift calls `onUpgrade` before `beforeOpen`, including for downgrades

1. Handle the downgrade in `onUpgrade`, before `stepByStep` runs

The git workflow: two versions side by side with `git worktree`

Step 2: Review `shorebird.yaml`