When an Electric Book project has so many images that its app size is over 100MB, Google Play requires that they are stored in a separate expansion file. To manage that expansion file, you need to maintain the Google Play version of the app in this repo, separately from the main project repo.
First, make sure you have Android Studio and Java SDK 8 (at the moment, SDK 9 does not work). Guidance here.
Install Cordova 6.5 globally, or if you're on Windows and use the script mentioned below, the script uses that version locally from node_modules
.
Note: In this guidance, we'll use
com.example.myapp
to refer to your app ID. You'll use your own, as stored in your main content project's_data/meta.yml
files as itsapp-id
.
If you are building a translation, search this repo for all instances of com.example.myapp.expansion
or com.example.myapp.fr.expansion
(where com.example.myapp
is your project's app ID, and .fr
is the language tag of the app you're working on) and make sure that the language tag (fr
in this example) matches the language you're working on.
-
To update the content, build app-ready HTML over in your main content project, then copy the contents of
_site/app/www
there to this project'swww
directory. When building the HTML there:- if you're outputting a translation, when asked by the output script for extra config files, use
_configs/_config.app.fr.yml
(e.g.fr
for French) - remember to activate the expansion file behaviour there in
_data/settings.yml
by settinggoogle-play-expansion-file-enabled: true
.
- if you're outputting a translation, when asked by the output script for extra config files, use
-
In
config.xml
, we recommend updating the version number in thewidget
element to match the version of the main content repo as specified in its_data/meta.yml
. This keeps the content version aligned with the app version. The app version must increment with each release added to Google Play. -
Run the
run-windows.bat
batch file. This will move the images toexpansion-main
and zip them up with no compression. (This script isn't available for Mac or Linux yet.)If xAPKReader plugin has been successfully added, the script will try to build a local testing version of the app.
If you don't want to use the
run-windows.bat
batch file or you're on Mac or Linux, you can run these commands manually:- First install the required Node modules:
npm install
- Then remove, re-add, and prepare the android platform files with these three commands:
cordova platform remove android
cordova platform add [email protected]
cordova prepare android
-
Open
platforms/android/project.properties
and find the linecordova.system.library.1=com.google.android.gms:play-services-base:+
. Add16.
before the plus sign, like this:cordova.system.library.1=com.google.android.gms:play-services-base:16.+
This avoids a known bug with google
play-services-base
. If you are using therun-windows.bat
script and you are getting build errors, you may need to run these commands manually instead of using the script to build the app, so that you can make this edit before the next step. -
Build the app:
cordova build android
- If your emulator is set up, you can run this to launch the app in an emulator:
cordova emulate android
-
To create a signed release:
- Copy
build-example.json
tobuild.json
and fill in the path to your keystore and its passwords and key alias. Do not commitbuild.json
or the keystore to version control. - In the project root run
cordova build android --release
.
- Copy
If you need to generate a keystore, the easiest way to do this is with Android Studio. Open the project (the repo) in Android Studio, then go to 'Build > Generate signed APK...'. Fill in the prompts, and your .jks
keystore will appear where you've defined there that it should.
If you're working on an existing app, it's likely that a keystore already exists for this project, and you should use that one. Its password and the password for the key it contains should be stored somewhere safely for you to find.
Note: The first time you set up a new app, you'll go to 'App signing' on Google Play for your certificate. Google Play will say that you will get a certificate once you've uploaded an APK. You worry, because you wonder whether Google will accept an unsigned APK. So you upload an insigned APK and Google Play says that it can't use that because it's unsigned. You are rightly confused by this. Then go back to 'App signing' and, voila, magically there is now a certificate ready for you to use to sign your APK.
For each application, the Google Play service automatically generates a 2048-bit RSA public/private key pair that is used for licensing and in-app billing. The key pair is uniquely associated with the application. Although associated with the application, the key pair is not the same as the key that you use to sign your applications (or derived from it). ... To add licensing to an application, you must obtain your application's public key for licensing and copy it into your application. โ Google Developer guidelines
Some useful resources:
-
Install the
android-debug.apk
* as an app normally. (I.e. download it to your phone over a network or email, and open the APK file on the device to install it.) Don't open the app yet.* Note that signed apps (
android-release.apk
) can't be tested locally, presumably because once signed the app is only allowed to use expansion files downloaded securely from Google Play. -
Rename
expansion-main.zip
tomain.1.com.example.myapp.obb
. -
Copy
main.1.com.example.myapp.obb
to your device, into this folder:Android/obb/com.example.myapp
. You may need to create the folder inAndroid/obb
. Do not save it to the SD card, which has a similar path.So the expansion is now on your device (not the SD card) at
Android/OBB/com.example.myapp/main.1.com.example.myapp.obb
.If you are creating a translation-specific app, you need to add the language tag to the folder name and expansion file name, as with
.fr
in this example:Android/obb/com.example.myapp.fr
main.1.com.example.myapp.fr.obb
This is because for translation apps (i.e. where built with a
site-language
set in the config) we set a different APK ID: the parent ID, but with the language tag appended like this. -
Your app Should Just Work.
Testers should be members of a Google Group. Once added the the group, get the testing URL for them to visit to opt in from Google Play. It should look like https://play.google.com/apps/testing/com.example.myapp
.
The first time you add an APK to Google Play that needs an expansion file, the upload dialog gives you no way to add the expansion file. This is probably because Google Play treats expansion files firstly as a way to update existing apps.
To upload the expansion file, go to 'Artifact library' and click the plus sign to the right of the APK. Choose 'Add update'. That will ask if you want to add an expansion file. Select that and choose the expansion file to upload.
(This odd behaviour may have been fixed by now.)
The xAPKReader plugin has already been added here. In the event it needs to be done again, follow the guidelines here. When adding, use the full add command including the public API key and expansio authority like this:
cordova plugin add https://github.com/agamemnus/cordova-plugin-xapkreader.git#cordova-6.5.0 --variable XAPK_PUBLIC_KEY="MIIBIjANBgkqh[...]AQAB" --variable XAPK_EXPANSION_AUTHORITY="com.example.myapp.expansion"