NewsLoopVersion 1.0.0 · offline copyGuides

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:

What readers get ​

An article in the app, with its picture, section and text - 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. The app home screen, as the default layout shows it

What you need ​

Try it first ​

Point the app at your site with NF_API_URL, from the mobile folder:

bash
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:

bash
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:

bash
dart run tool/whitelabel.dart

The script checks your answers and explains anything it cannot use. It then:

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) ​

  1. In the Firebase console, create a project and add an Android app with your android_application_id, and an iOS app with your ios_bundle_id.
  2. Under Project settings → General → Your apps, copy these into firebase in whitelabel.yaml:
    • the Web API key;
    • the project ID;
    • the sender ID;
    • both app IDs. You do not need to download google-services.json or GoogleService-Info.plist.
  3. iPhone only: under Project settings → Cloud Messaging, upload your Apple Push Notifications key (a .p8 file from the Apple Developer site).
  4. 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.

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.

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:

The site then serves /.well-known/assetlinks.json and /.well-known/apple-app-site-association.

Android (Google Play) ​

  1. 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
  2. Create android/key.properties (never share or commit it):
    properties
    storeFile=upload.jks
    storePassword=your-store-password
    keyAlias=upload
    keyPassword=your-key-password
  3. Build the bundle:
    bash
    flutter build appbundle --release --dart-define-from-file=whitelabel.defines.json
  4. Upload build/app/outputs/bundle/release/app-release.aab in 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) ​

  1. On the Apple Developer site, create an App ID with your bundle ID. Turn on:

    • Push Notifications;
    • Associated Domains, if website_host is set;
    • Sign in with Apple.

    Set ios_capabilities: true and run the script again.

  2. Open ios/Runner.xcworkspace in Xcode. Under Runner → Signing & Capabilities, choose your team.

  3. Build:

    bash
    flutter build ipa --release --dart-define-from-file=whitelabel.defines.json
  4. Upload build/ios/ipa/*.ipa with Apple's Transporter app, or from Xcode's Organizer. Test it in TestFlight first.

Build without a Mac ​

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:

App Store, privacy:

Troubleshooting ​

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