Mobile App for WooCommerce documentation

What you bought: three parts that work together

Which way should I go?

The big picture in 8 steps

1. Check your store is ready (chapter 3).
2. Install the plugin (chapter 4).
3. Design the home screen (chapter 5).
4. Choose colours, login and links (chapters 6 and 7).
5. Create a free Firebase project for notifications (chapter 8).
6. Build the Android app online (chapter 10).
7. Install it on your phone and test it (chapter 11).
8. Publish it to Google Play (chapter 12).

Checklist

Accounts you may need

1. In your WordPress dashboard open Plugins → Add New → Upload Plugin.
2. Choose the file mobile-app-for-woocommerce-plugin.zip and press Install Now, then Activate.
   Use the inner zip files only. Do not upload the big complete-package zip.
3. Two new menu items appear on the left: App Layouts and App Settings. Three sample layouts were created for you.

Check that it works

Open this address in your browser (replace with your own store address):

https://yourstore.com/wp-json/mo-app/v1/homepage

If you see a page of text full of curly brackets, the plugin works. If you see "Active App Layout not configured", that is normal for now: you choose the layout in chapter 6.

1. Go to App Layouts and open Modern Store Homepage (or press Add Post for a new one).
2. Click the blue + button and search for Mobile. You will find three blocks: Mobile: App Banners, Mobile: App Categories, Mobile: App Product Collection.
3. Add the blocks you want and drag them into the order you like.
4. Click a block and use the settings on the right to change it (see the tables below).
5. Press Update (or Publish).

The three blocks

Make it pretty (all three blocks)

• Title and description with their own colours.
• Background: a colour, a gradient or a picture.
• Spacing: padding above and below, rounded corners.

The side panel: App Screen Settings

In the right-hand panel you will find App Screen Settings. It controls the top bar and the search bar of this screen:

What is saved behind the scenes (for the curious)

Each layout is saved as simple block text like this. You never have to type it, it is only here so you know there is no magic:

<!-- wp:wc-mobile/banners {"layoutType":"slider","bannerHeight":170,"showDots":true,"autoplay":true} /-->

<!-- wp:wc-mobile/categories {"title":"Shop by category","displayStyle":"horizontal_scroll"} /-->

<!-- wp:wc-mobile/products {"title":"Fresh picks for you","layoutType":"grid","gridColumns":2,"limit":6} /-->

General Settings

Drawer Menu

Switch the slide-out menu on or off, show or hide My Wallet and Reward Points (they need extra plugins, see chapter 14), and choose its background: a colour, a gradient or a picture address.

Legal & Policies

Paste the web addresses of your Privacy Policy, Terms & Conditions and Return Policy pages. Stores such as Google Play require a privacy policy.

Support & Social

Your support email, WhatsApp number (with country code, for example +971…) and your Facebook, Instagram and X pages.

App Info & Updates

After you publish, paste the Play Store and App Store links. Minimum App Version: if a customer has an older version than this number (for example 1.0.5), the app asks them to update before continuing. Leave it empty until you really need it.

Theme (Flex)

Setting up phone login (OTP)

1. Open the SMS / OTP section further down in the Integrations tab.
2. Choose 2Factor or OTPless as the provider.
3. Paste the key(s) from your provider into the boxes that appear.
4. Tick Enable Phone Login at the top, then Save All Settings.

Part A: create the project and register the Android app

1. Go to console.firebase.google.com and sign in with your Google account.
2. Press Add project, give it your shop's name and finish the wizard (you can turn Google Analytics off).
3. Inside the project press the Android icon to add an Android app.
4. In Android package name type the package name you want for your app, for example com.yourshop.app. Write it down: you will type the same one in the App Builder.
5. Press Register app, then Download google-services.json. Keep this file safe. You can skip the other steps of the wizard.

Part B: copy four values into the plugin

1. In Firebase press the gear icon → Project settings → tab General.
2. Scroll to Your apps. Copy the API key, Project ID, App ID and Messaging Sender ID (the Sender ID is under the Cloud Messaging tab).
3. In WordPress open App Settings → Integrations & APIs → Firebase Configuration and paste each value into its box.

Part C: the key that lets your store send notifications

1. In Firebase project settings open the Service accounts tab.
2. Press Generate new private key. A small file ending in .json downloads.
3. Open that file with a text editor (Notepad, TextEdit), select everything and copy it.
4. Paste it into the big box Firebase Service Account JSON in the plugin and press Save All Settings.

Part D (only for Google login)

1. In Firebase open Authentication → Sign-in method and switch on Google.
2. After your first build, add the app's SHA-1 and SHA-256 fingerprints in Project settings → your Android app. For Google Play builds use the fingerprints that Google Play shows under App integrity.
3. Download google-services.json again and use the new file for the next build.

Automatic order notifications

In Integrations & APIs tick Order Placed and Order Status Updated to send a push notification to the customer's phone whenever an order is placed or changes status (processing, shipped…).

Below, Notification Message Templates let you write your own wording. You can use these placeholders, which are replaced with real details:

Title:  Order #{order_id} update
Message: Your order is now {order_status}. Thank you for shopping with us!

WhatsApp and SMS (optional)

• WhatsApp: sends order receipts and updates through Meta Cloud API, Twilio or UltraMsg. Paste the provider's token and the sender number.
• SMS: sends order updates with 2Factor, MSG91, Twilio or Unifonic. Tick Order Updates via SMS and paste the provider's key.

Send your own announcement

1. Open the Send Notification tab.
2. Type a title and a message (for example "Weekend sale: 20% off fruit").
3. Choose All users, or Selected users and search by name or email.
4. Press send. A green message means Firebase accepted it. A red message tells you what to fix.

What you need on the table first

Create the WooCommerce keys (one time)

1. Open WooCommerce → Settings → Advanced → REST API → Add key.
2. Description: Mobile app. User: your admin account. Permissions: Read/Write.
3. Press Generate API key. Copy the Consumer key and Consumer secret into a safe note. The secret is shown only once.

Fill in the App Builder

1. Open App Settings → App Builder.
2. Under Connect to Cloud Builder type your Site URL and Purchase Code, then press Fetch App Details. A green message says the connection works and the form below opens.
3. Basic App Information: app name, package name, your email, phone and two-letter country code (for example AE, IN, US).
4. Security Keys: paste the Consumer Key and Consumer Secret. Add a Google Maps key only if you want customers to pick their address on a map.
5. Facebook Login Setup: fill only if you use Facebook login.
6. Branding Images: pick the splash colour, then choose the App Icon, Loading Logo, Splash Image and the Firebase Config file (google-services.json). Each file uploads the moment you choose it and shows a green Uploaded Successfully.
7. Choose the Build Output Type: APK to test on your own phone, App Bundle (AAB) for Google Play.
8. Press Save Details, then Start Android Build.

What happens next

Rules to know

• All four files are required: icon, loading logo, splash image and google-services.json.
• The package name must appear inside your google-services.json. On your very first build, if they differ, the builder adopts the package name from the file.
• One purchase code allows the number of apps stated on your licence (normally one app for one store address). If you see "maximum number of apps reached", contact support.
• Some licences are limited to APK builds. The builder then makes an APK even if you chose App Bundle.
• The builder makes Android files. For iPhone see chapter 13.
• Your uploaded pictures and Firebase file are removed from the build server after about three months.

When something goes wrong

1. Open the email on your Android phone and tap Download APK (or download on a computer and send the file to the phone).
2. Open the downloaded file. Android may ask you to allow installing from this source. Allow it for this one time.
3. Open the app. Wait a few seconds: the splash screen shows, then your home screen.
4. Walk through this checklist.

Google Play (Android)

1. Create a Google Play Console developer account.
2. Create a new app and fill in the store listing: short and long description, an icon, screenshots of the app and a feature graphic.
3. Add the link to your privacy policy (required).
4. Fill in the content questionnaires (ads, data safety, target age). Explain that the app uses location to fill in the delivery address, and does not show ads.
5. Build an App Bundle (AAB) in the App Builder, upload it under Production → Create release, and send it for review.
6. Review usually takes from a few hours to a few days. Afterwards paste the store link into App Settings → App Info & Updates.

Apple App Store (iPhone)

An iPhone app needs a Mac with Xcode and an Apple Developer account, so this part is done from the source code with a developer's help (chapter 13). Apple also requires Sign in with Apple if the app offers other social logins, and a privacy policy.

One-time setup

1. Install Flutter 3.41 or newer (this installs Dart too).
2. Run flutter doctor and fix every item it reports (Android SDK and licences, Xcode, CocoaPods).
3. Unzip flutter-app-source.zip, open a terminal in the folder and run:

flutter pub get

Point the app to your store

Open lib/core/constants/app_config.dart and change two lines:

static const String siteUrl = 'https://yourstore.com';   // no slash at the end
static const String appName = 'My Store';

The API path /wp-json/mo-app/v1 is added for you. To test with a store on your own computer use an address the phone can reach: Android emulator http://10.0.2.2:8888/wp, iPhone simulator http://localhost:8888/wp.

Name, ID, icon, splash and version

dart run change_app_package_name:main com.yourbrand.app

dart run flutter_launcher_icons

dart run flutter_native_splash:create

Firebase files

The package has no Firebase files: they belong to your own project (chapter 8).

• Android: put google-services.json into android/app/, then add the Google services plugin. In android/settings.gradle.kts add inside plugins { }:

id("com.google.gms.google-services") version "4.4.2" apply false

and in android/app/build.gradle.kts add inside plugins { }:

id("com.google.gms.google-services")

• iPhone: open ios/Runner.xcworkspace in Xcode, drag GoogleService-Info.plist into the Runner folder and tick Copy items if needed.

Without these files the app still shops normally, but push notifications and Google login are off.

Facebook, Google, Apple, maps

In ios/Runner/Info.plist replace the placeholders:

<string>fbYOURAPPID</string>      <!-- keep the fb prefix -->
<key>FacebookAppID</key><string>YOURAPPID</string>
<key>FacebookClientToken</key><string>CLIENT-TOKEN</string>

For Android follow the flutter_facebook_auth package guide. Switch on Google and Apple in Firebase Authentication; Apple sign-in also needs the Sign in with Apple capability in Xcode. Razorpay needs no key in the app: it is read from your WooCommerce Razorpay settings.

Run and build

flutter run                          # on a phone or emulator
flutter build apk --release          # Android APK
flutter build appbundle --release    # Android AAB for Google Play
flutter build ipa --release          # iPhone (on a Mac)

Sign the Android app for Google Play

Release builds use the debug key until you add your own. Create a key once and keep it safe:

keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

Create android/key.properties:

storePassword=YOUR_PASSWORD
keyPassword=YOUR_PASSWORD
keyAlias=upload
storeFile=/Users/you/upload-keystore.jks

and in android/app/build.gradle.kts load it and use it in signingConfigs / buildTypes.release as described in the Flutter signing guide. For iPhone choose your team in Xcode → Signing & Capabilities.

Base address: https://yourstore.com/wp-json/mo-app/v1. Logged-in calls send the header X-App-Token that the login call returns.

Try it

# The home layout and global settings
curl https://yourstore.com/wp-json/mo-app/v1/homepage

# Products: page 1, 10 items, search for "milk"
curl "https://yourstore.com/wp-json/mo-app/v1/products?page=1&per_page=10&search=milk"

# Log in and keep the token
curl -X POST https://yourstore.com/wp-json/mo-app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"customer@example.com","password":"secret"}'

# Use the token to read the customer's orders
curl https://yourstore.com/wp-json/mo-app/v1/orders -H "X-App-Token: YOUR_TOKEN"

Dart example (inside the app)

final res = await dio.get('/products', queryParameters: {'category': 'fruits', 'per_page': 20});
final products = res.data['products'];

All endpoints

The plugin's includes/api folder has one file per group with the exact parameters.

Update the plugin by uploading the new zip (Replace current with uploaded); your layouts and settings are kept. Update the app by building a new version and uploading it to the stores. To remove the plugin, deactivate and delete it; your app layouts stay in the database until you delete them from App Layouts.

Installation help and bug fixes are included for 6 months, with lifetime updates. Contact us through the marketplace item page where you purchased the package. When you write, include your store address and what you see on the screen.