Even if you are familiar with development, building your first mobile app can be intimidating. We know that, we’ve been there before 🙂
The goal of this page is to guide you through the process of building a simple test app with WP-AppKit from configuration in WordPress to installing the app on your phone. Thereby we hope to give you a better insight on how to build a mobile app and how WP-AppKit works.
Obviously, it’s not the WordPress 5 minutes install 😉 But you will see that we are commited to ease the process as much as possible.
We’ll see how to:
- get your phone ready for tests
- install WP-AppKit and an app’s theme
- create and compile (with PhoneGap Build) a simple test app
- install the test app on your phone
By the way, WP-AppKit is open source. It is FREE and will remain free (released under the GPL v3).
As with any other WordPress plugin, this step is a simple one.
You first need to download the latest release from our github repository. Then, extract the zip file you get into your wp-content/plugins/ folder: you should now have a wp-appkit-master folder created here.
The last thing to do is to activate WP-AppKit from your WordPress backoffice (inside “Plugins” menu).
Thanks to the activation you’ve just done, you should now see a new “WP-AppKit” menu, with a “Themes” submenu. This allows you to see and manage the list of available themes for your apps.
By default, you should only have our 2 starter themes: Q for iOS and Q for Android. You can easily add new ones and here’s how:
- Download the theme for example from our github repo
- Click on “Add new” from the themes management screen, or click “Upload Themes” inside “WP-AppKit” menu
- Upload the zip you got earlier into the dedicated form
For the moment, we only show you how to prepare an Android phone, we’ll soon explain you how to prepare an iOS one as well, please be patient.
By default with Android phones, you cannot install an app if it comes from an unknown source, which is basically everything except Google Play Store. Of course, if you need to test your app, you don’t need to publish it each time on the app store, so here’s how to allow your app to install:
- On your phone, go to “Settings”
- Find something containing “Security” (it could vary with your Android version)
- Find a switch called “Unknown sources” and check it. It should say “Allow installation of apps from sources other than the Play Store”
You are now ready to get your app!
First of all, let’s talk about risks and good practices.
As you’ll notice, many things you can do within WordPress backoffice will directly have an impact on all already installed apps. Instantly. In a few words: you can completely ruin your users experience in a click. Don’t worry though, the UI will warn you when you change something like that.
That being said, themes are another aspect of “live” changes. This means that when you choose a theme for an app, every change under “php” folder into this theme will be instantly available into all already installed apps.
And this leads us to good practices:
- Create a copy of default themes if you want to use them, this will ensure future upgrades won’t break your apps
- Generally, create copies of your themes to work and test before releasing them live: you should follow a workflow similar to code versioning, branches being themes here
- Create a theme by OS (one for Android, one for iOS): as both will surely have more and more differences, this will ensure you don’t break your apps on one OS because of changes related to the other one
- Directly related to previous point: create one app per OS
Now, we can start building our app. If you already are familiar with WordPress, you should easily find how to proceed to create a new app: click “WP-AppKit / Applications”, then “Add New”.
This screen is quite different from what you’re used to with the other post types, so here is what you need to know:
- Globally, you should fill in the forms in the order they appear on the screen
- You have a visual progression tool in “My Project” box, usually on the right, so that you can see how far you are in the creation process
- Some fields are optional if you only need to test an app and don’t want to publish it yet
- If you’re lost, click “Help me” on top of each metabox to see some explanations about the fields it contains
To be able to have a fully working test app, you’ll have to do following things:
- Choose a title: you can even choose the application title that will be displayed in the app top bar (from “Appearance” metabox)
- Choose a theme: you can see in “Appearance” metabox the list of available themes (see Install a Theme)
- Choose components: from “Components” metabox, you can create different types of component with different options, give them a label. Once created, their content is instantly available from the app. If default components aren’t enough for your needs, see our doc section about custom components.
- Create the app menu: you need to have at least 1 component created, and then from “Appearance” metabox, you can add your components to the menu and reorder them by drag&drop. Adding all your components in the menu is not mandatory, you could have only one over three components into it.
- Choose a platform (iOS / Android): you don’t need it to test, but it can change some fields from the form
At this step, you should see that you’re 2 steps far from the app completion thanks to the visual progression tool. Click “Save” to complete one more!
The other one should be “Setup PhoneGap config” and this is mandatory only if you want to compile the app and install it on a phone. We’ll see how to do that later.
As soon as you save your app project, you can “Preview” it directly in the browser. Make sure you activate touch events emulation if your theme uses them, otherwise you won’t be able to navigate through the app.
Previewing the app allows you to see how it will render on a phone, so that you can make adjustments on the theme, menu, components and so on. Plus, if you activate “Debug mode”, your browser’s console will show you a lot more information, so that you can go through bugs in the theme for example.
You should note that native phone functions (accessible through cordova plugins) are not available through your browser, so you won’t be able to test sharing a post for example.
Of course, content is dynamically retrieved, so feel free to add a new post in WordPress backoffice and see how it magically comes into your app!
Finally, preview also support offline. This means that you can disconnect your computer from the internet and you’ll still be able to navigate through your app!
Now that your app is great in preview, it’s time to see how it is on a real phone!
Since you’ll compile your app through PhoneGap Build, you should first take care of the “PhoneGap Build” metabox from the app edit screen. This tool requires a configuration file (named config.xml), and this metabox allows you to generate it properly. It is divided into 3 fieldsets: Application, Author and PhoneGap.
Here are some explanations:
- The name and description of your app will both appear in PhoneGap Build and app stores
- The ID is a string uniquely identifying your app, usually looking like com.yourcompany.yourapp
- Version is a name for your version (e.g. “1.0.0”) that will appear in app stores
- On Android, VersionCode is a integer representing your app version, so it should increase with each new release
- In “Icons and Splashscreens” field, you can put XML in order to use your own images. Please see our tutorial to know more about it.
- Author data will appear on app stores, so you should put public information about your company here
- PhoneGap Version allows you to choose a specific version of PhoneGap your app should use to compile. Currently, the last version is “cli-6.1.0” and the default version is “cli-5.2.0” (see PhoneGap Build current support table for more details).
- In “Plugins” field, you can put XML in order to add cordova/PhoneGap plugins you want to use
If you want to know more about PhoneGap Build configuration, you can check their documentation.
Update your app, then click “Export”. You’ll get a zip file containing everything PhoneGap Build needs to compile your app: save it somewhere and let’s move on!
This part is probably the most magical one. All you have to do is:
- Login into PhoneGap Build
- Click “New app” and choose “Upload a .zip file”
- Select the file you saved earlier and upload it
PhoneGap Build will then take care of compiling your app for the specified platform, and you will be able to download and install it as soon as it ends compiling.
Regarding Android, you only have to download the apk, in flashing the provided QR-Code for example, and install it on the phone you prepared earlier.
For iOS, it’s a bit more complicated… You need to sign your app with a certificate that allows your phone and this test app to fit together, and you need to subscribe to Apple Developer Program to do that.
For more details about how to compile with PhoneGap Build, you can read our tutorial.
This adventure ends where another one begins: build an app for real and publish it in app stores. We provide a complete documentation to help you build and customize your app. Also, publishing in app stores take time. Be sure to have enough time to learn how to do it. It can be intimidating the first time.
Through support, we regularly have the issues raised. We’ll maintain answers to most common ones in that section.
Once you activated WP-AppKit and want to preview your app, you might encounter a white screen of the death, or an error screen.
As stated in Install the WP-AppKit Plugin, you should activate WordPress permalinks (any other option than “Plain”) in order to preview your app. A complete white screen can show up if you didn’t do that.
Plus, if you didn’t make your preview public by choosing it under “App Simulation Visibility”, you need to be logged in.
This error screen can also show up in case your website runs a cache or security plugin. Indeed, these plugins often block URL parameters or Web Service calls your app may need. Try to deactivate all your other plugins and see if it works, so that you will have a clue about what is causing your issue.