The mobile app ​
The Flutter app in Main_File/newsloop-app draws the layout you design in the app builder, with your site's articles. You build it once with your name, icon and store IDs. After that, layout changes you publish reach installed apps on their next launch, without a store update.
This guide covers:
- trying the app;
- branding it;
- notifications and sign-in;
- building for Google Play and the App Store, with or without a Mac;
- what the stores ask about privacy.
What readers get ​
- Your layout: screens, menu, colours, fonts and every app builder component, in light and dark mode and in every language you publish, including right-to-left.
- Articles with pictures and captions, pull quotes, galleries, "Listen to this article", video, live blogs that update every 30 seconds, tags, likes, comments and sharing. Members-only stories show the opening and a membership offer; free articles per month are counted as on the website.
- Search, sections, tags and writers' pages; "See all" on any list.
- Saved articles that sync across the reader's devices once they sign in.
- Accounts: email with two-step codes, Google, and Apple on iPhone. Readers can turn the newsletter on or off and delete their account.
- Settings: theme, text size, notifications, language, your privacy policy, rate the app.
- Breaking news notifications by topic and language.
- No ads and no tracking prompt: the app contains no ads SDK. Ads are a website feature.
- Offline reading of what was opened before, with an offline notice.
- Links to your website open in the app.
- A maintenance screen and a "please update" screen, both switched on from the app builder's settings.
What you need ​
- The app's source: copy the
Main_File/newsloop-appfolder from your download to a folder calledmobile. This guide calls it themobilefolder, and runs every command from it. - Flutter 3.44 or newer (flutter.dev). Run
flutter doctoruntil it has no errors for the platforms you build. - Android: Android Studio with the Android SDK, and a Google Play developer account.
- iPhone: a Mac with Xcode and an Apple Developer account. Without a Mac, see Build without a Mac. The app runs on iOS 15 and newer, which Firebase needs.
- Your site running on https with at least one published article.
Try it first ​
Point the app at your site with NF_API_URL, from the mobile folder:
flutter pub get
flutter run --dart-define=NF_API_URL=https://news.example.com/api/v1
Without NF_API_URL, development builds use a site on your own computer at port 8000. The Android emulator reaches it at 10.0.2.2, which the app knows. Development builds may use plain http for that local site; store builds only use https.
A real phone cannot use either address: 127.0.0.1 on the phone is the phone itself. Over USB, forward the phone's port 8000 to your computer, then point the app at 127.0.0.1:
adb reverse tcp:8000 tcp:8000
flutter run --dart-define=NF_API_URL=http://127.0.0.1:8000/api/v1
The forwarding stops when the phone is unplugged.
If the app cannot reach the site, it says "Can't reach the news site right now." at the top of the screen, with a Try again button. Development builds also show the address they tried.
Until you publish a layout in the app builder, the app uses the NewsLoop template built into it.
Brand it ​
All branding lives in one file, mobile/whitelabel.yaml. Fill it in, then run from the mobile folder:
dart run tool/whitelabel.dart
The script checks your answers and explains anything it cannot use. It then:
- writes the Android and iPhone settings (
android/nf.properties,ios/Flutter/Brand.xcconfig); - writes the build settings in
whitelabel.defines.json; - makes the icons and splash screen;
- copies your published layout into the app, so the first launch looks right even without a connection.
Run it again whenever you change the file.
| Setting | What it is |
|---|---|
app_name |
The name under the icon, up to 30 characters. |
api_url |
Your site's API, such as https://news.example.com/api/v1. |
android_application_id, ios_bundle_id |
Store IDs in reverse domain form, such as com.harbourherald.news. They cannot change after the first release. |
website_host |
Your site's host name, such as news.example.com, so links to it open the app. Leave empty to turn this off. |
ios_capabilities |
true once your App ID has Associated Domains, Sign in with Apple and Push Notifications (see iPhone). |
icon, splash_color, splash_image |
Leave empty to use the ones set on your site under App → Mobile app. If you give your own, the icon is a 1024×1024 PNG without transparency. |
firebase |
For notifications; see below. Leave empty to build without them. |
google |
For Google sign-in; see below. |
fetch_layout |
Copy the published layout into the app (default true). |
Colours, fonts, the logo style, screens and the menu are not set here: they come from the app builder.
Notifications (Firebase) ​
- In the Firebase console, create a project and add an Android app with your
android_application_id, and an iOS app with yourios_bundle_id. - Under Project settings → General → Your apps, copy these into
firebaseinwhitelabel.yaml:- the Web API key;
- the project ID;
- the sender ID;
- both app IDs.
You do not need to download
google-services.jsonorGoogleService-Info.plist.
- iPhone only: under Project settings → Cloud Messaging, upload your Apple Push Notifications key (a
.p8file from the Apple Developer site). - On your site, set up sending under Readers → Push notifications (see Newsletter, push and statistics).
The app asks for permission from the notifications invitation in your layout, or from Settings. It subscribes to the topics chosen in the app builder's settings (Breaking news and All by default), in the reader's language.
The App Store privacy manifest ​
Apple asks every app to describe the data it collects, in a privacy manifest and in App Store Connect.
- The app's own manifest is
ios/Runner/PrivacyInfo.xcprivacy. It declares what NewsLoop's own code collects: the reader's name and email (for their account), the notification token, comments they write, and anonymous reading counts. It also says the app reads saved settings (UserDefaults, reasonCA92.1). It setsNSPrivacyTrackingtofalse, because the app doesn't track anyone. Leave it like that. - The Firebase SDKs bring their own manifests, which declare what they collect. You don't copy them into the app's manifest: Xcode adds them by itself.
- Before you submit, archive the app in Xcode (Product → Archive), then right-click the archive in the Organizer and choose Generate Privacy Report. It lists everything the app and its SDKs declare. Use it to answer App Store Connect's privacy questions (App Privacy).
- If you add your own code or SDKs that collect data, add them to
PrivacyInfo.xcprivacytoo. - The app does not track. It has no ads SDK and shows no tracking prompt, so you answer that the app does not track.
Sign in with Google and Apple ​
Both are switched on for the site in App → Mobile app (see Setting up the app). On iPhone, the Google button only shows when Sign in with Apple is on too, because Apple's App Store rules require Apple sign-in in any app that offers Google's. The app shows each button only when the site accepts it.
- Google: in Google Cloud, create OAuth clients for Android (package name and SHA-1), iOS (bundle ID) and Web.
- On the site, paste all three client IDs, one per line.
- In
whitelabel.yaml, put the Web client ID asgoogle.server_client_idand the iOS client ID asgoogle.ios_client_id.
- Apple: shown on iPhone only, where Apple requires it next to Google sign-in. Turn on Sign in with Apple for your App ID. Paste the bundle ID on the site, and set
ios_capabilities: true. Until then, the app hides the Apple button (and so, on iPhone, the Google one too), because Apple refuses sign-in from an App ID without the capability.
Links to your site ​
When website_host is set, links to that site open in the app. The app asks your site what each link is, such as an article, a section or a tag. Pages the app cannot show open in the browser.
The phone checks that the site and the app belong together. On your site, open App → Mobile app and fill in:
- Android: the package name, and the SHA-256 fingerprint of the key that signs the app. For Play App Signing, find it in Play Console under Setup → App signing.
- iPhone: the Apple App ID (Team ID and bundle ID, such as
ABCDE12345.com.harbourherald.news). Setios_capabilities: truetoo.
The site then serves /.well-known/assetlinks.json and /.well-known/apple-app-site-association.
Android (Google Play) ​
- Create an upload key once, and keep it safe: you cannot replace it easily.bash
keytool -genkey -v -keystore android/upload.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload - Create
android/key.properties(never share or commit it):propertiesstoreFile=upload.jks storePassword=your-store-password keyAlias=upload keyPassword=your-key-password - Build the bundle:bash
flutter build appbundle --release --dart-define-from-file=whitelabel.defines.json - Upload
build/app/outputs/bundle/release/app-release.aabin Play Console, first to internal testing.
Raise version: in pubspec.yaml for every upload, for example 1.0.1+2. The number after + must always go up.
iPhone (App Store) ​
-
On the Apple Developer site, create an App ID with your bundle ID. Turn on:
- Push Notifications;
- Associated Domains, if
website_hostis set; - Sign in with Apple.
Set
ios_capabilities: trueand run the script again. -
Open
ios/Runner.xcworkspacein Xcode. Under Runner → Signing & Capabilities, choose your team. -
Build:
bashflutter build ipa --release --dart-define-from-file=whitelabel.defines.json -
Upload
build/ios/ipa/*.ipawith Apple's Transporter app, or from Xcode's Organizer. Test it in TestFlight first.
Build without a Mac ​
- Codemagic builds both apps in the cloud and signs the iPhone app for you. Add your repository, connect an App Store Connect API key, upload your Android upload key, and follow the steps at the top of
mobile/codemagic.yaml. Every iPhone build goes to TestFlight. - GitHub Actions builds the Android bundle. Copy
mobile/ci/github-actions.ymlto.github/workflows/and add the four secrets listed at its top.
Both run the white-label script, the tests and the build.
Changing the app later ​
| Change | What to do |
|---|---|
| Screens, menu, colours, fonts, components, topics, maintenance, "please update" | Publish in the app builder. Apps pick it up on their next launch. |
| Name, icon, splash, store IDs, Firebase, Google client IDs | Edit whitelabel.yaml, run the script, raise the version, build and upload. |
To make old versions update, set the minimum versions in the app builder, under App settings → Required update. Readers with an older version then see a screen with a link to the store (the store addresses are on App → Mobile app).
What the stores ask ​
Both stores require a way to delete the account inside the app. It is in Profile → Delete account; the site deletes the account and its saved articles.
Google Play, Data safety form:
- Collected:
- Name and email address, for account management. Optional, and only for readers who sign in.
- App interactions: article views, counted without the reader's identity.
- Device or other IDs: the notification token, so the site can send notifications.
- Shared: none.
- Data is encrypted in transit.
- Readers can ask for their data to be deleted: yes, in the app and on the website.
- Target API level: Flutter 3.44 targets Android's current level. Play requires you to keep up, so build with a recent Flutter.
App Store, privacy:
ios/Runner/PrivacyInfo.xcprivacydeclares what the app itself collects: name, email, the notification token, comments and anonymous reading counts. The Firebase SDKs bring their own (see The App Store privacy manifest).- The app does not track. Answer "No" to tracking in App Store Connect's privacy questions.
Troubleshooting ​
- The app shows the built-in layout, not mine. Publish it in the app builder, then close and reopen the app. The app checks for a new layout at launch and when it comes back to the screen.
- "Can't reach the news site right now." on a real phone during development. A phone cannot reach
127.0.0.1on your computer by itself. Connect it with a USB cable and runadb reverse tcp:8000 tcp:8000(Android), as in Try it first, or put the site online with https. - Android build fails with "Could not close incremental caches". This happens on Windows when the project and the Flutter package cache are on different drives.
android/gradle.propertiesalready turns Kotlin's incremental builds off. If you removed that line, addkotlin.incremental=falseback. - No notifications. Check the
firebasevalues and run the script again. On iPhone, also upload the Apple key to Firebase and setios_capabilities: true. - Links open the browser, not the app. Fill in App → Mobile app on the site, and check that
https://your-site/.well-known/assetlinks.json(Android) orapple-app-site-association(iPhone) shows your app. Android checks again when the app is installed. - Pictures are missing in a web build. A web build needs your site to send CORS headers for
/uploads. Phones do not.
For developers ​
mobile/
lib/
app/ the app, the router and where links go
components/ one widget per app builder component, and the registry
core/ the API client and models, the layout, storage, theme, providers
features/ the account and saved articles
screens/ screens: layout screens, article, lists, search, sign-in, settings
services/ notifications, links to the site
ui/ article cards and shared pieces
l10n/ the app's own text, in six languages
test/ unit and widget tests, with a fake site in test/support
integration_test/ a run on a phone against a real site
tool/whitelabel.dart
-
flutter analyze,dart format lib test toolandflutter testmust pass; CI also builds an Android APK. -
The widget tests boot the whole app against a fake site. They draw every component in light, dark and right-to-left, with no network.
-
Integration test, on a phone or emulator:
bashflutter test integration_test --dart-define=NF_API_URL=http://10.0.2.2:8000/api/v1 -
To add a component:
- Add it to the schema and the builder (see App builder).
- Write its widget in
lib/components/. - Register it in
app_components.dart.
The "every component" widget test then draws it too.
-
To add a language to the app's own text: add
lib/l10n/app_<code>.arband runflutter gen-l10n. Article text and layout labels come from the site.