New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add publishing & signing docs; generate Android App Bundle #342
Add publishing & signing docs; generate Android App Bundle #342
Conversation
filename:
The |
I'll try to migrate this to use Google's hosted signing thing, which means our key would become an "uploading" key in their terminology. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure if the Play Store has had a major update since you wrote this, but the workflow I saw didn't match what you wrote here (definitely enough to get me going, but plenty of discrepancies.)
docs/how-to/code-signing/android.rst
Outdated
|
||
Run this command:: | ||
|
||
$ keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some guidance on appropriate naming schemes for "my release key" and "my-alias" would be helpful. Are these keystores/keys app specific? project specific? Organization specific?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now, I believe.
docs/how-to/publishing/android.rst
Outdated
|
||
:: | ||
|
||
$ zipalign -p 4 -f filename.apk |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Need to describe where these tools are located on the path.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This overwrites the exsitng file; would it be safer to give instructions that result in an "app-release-aligned.apk"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FWIW, the reason I wrote it this way is that zipalign is a very safe operation IMHO, so adding another file creates more confusion than it's worth.
Having said that, the zipalign process is no longer needed with the Android App Bundle approach, so whatever. :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now, I believe.
docs/how-to/publishing/android.rst
Outdated
Adding the app requires a few steps. You need to have a Google Account and | ||
create a listing for your app. You will need to choose your app's signing | ||
configuration in the store. Finally, you will create a new release of the app, | ||
at which point you will upload the APK files that comprise your app. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Worth mentioning the registration fee (A$25; don't know what is in US monies)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now, I believe.
docs/how-to/publishing/android.rst
Outdated
|
||
Once you've done that, click **Create Application**. Choose a language and | ||
write a brief app title, up to 50 characters. This should probably be the | ||
same as your app's Formal Name in the BeeWare ecosystem. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was really confused by this difference. The reason is that I already had one Google Play Store Android app in my Google Play Store console, whereas you didn't. Presumably our users will be more like you than like me in this regard. I'll be fixing that now :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now, I believe.
docs/how-to/publishing/android.rst
Outdated
your app's ``pyproject.toml`` file. Look for a line starting with ``icon = ``. | ||
The Google Play Store will require a variety of other information, including at least | ||
one screenshot of your app and your assessment of likelihood that children will want | ||
to use the app. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Icon needs to be 512x512, which isn't a size required during setup.
Minium 2 screenshots are required; they must be at least 320px, no more than 3480px, and can't have an aspect ratio > 2:1.
Feature graphic (1024x500px) is also required.
Other details like a promo graphic, tv banner, promo vidio, and daydream 360 degree stereoscopic image can be provided, but aren't required.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now, I believe.
docs/how-to/publishing/android.rst
Outdated
|
||
Click **App Signing** in the left navigation. The Google Play Store offers an app signing | ||
feature where they maintain the signing key for your app. For simplicity, you will | ||
click **Opt Out** to opt out of that feature. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This appears out of order; I couldn't manage keys until uploading an APK.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now, I believe.
docs/how-to/publishing/android.rst
Outdated
app's signing key. | ||
|
||
You can enable this feature later if you are willing to give Google the private | ||
key corresponding to this app. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From going through the release process, it's pretty clear that Google wants you to use google-managed keysigning. I'd argue it's better for these instructions to reflect that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1; fixed now, I believe.
docs/how-to/publishing/android.rst
Outdated
|
||
This will prompt a variety of questions from the Google Play Store about the content | ||
of your app, including the absence/presence of advertising, its appropriateness for | ||
different age groups, and any embedded commercial aspects. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I also had to save a draft, then visit the "Content Rating", "App Content" and "Pricing and Distribution" tabs to fill out all sorts of details. There's a series of grayed out arrows; until they're all green, you can't publish. There wasn't a "just answer the questions" workflow.
It also raised a warning about being a non-optimized bundle. Short term, we need to flag this isn't a problem; long term, we should modify the publish command to produce multiple APKs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now. (Also, the Android App Bundle saves us from the non-optimized bundle problem! Yay.)
docs/how-to/publishing/android.rst
Outdated
same as your app's Formal Name in the BeeWare ecosystem. | ||
|
||
This will take you to **Store Listing** section of your app. You will need to | ||
answer a variety of questions. Take your time to answer them well. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Your app metadata may be helpful here."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed now
Hi @freakboy3742 -- good feedback. I'll plan to take a fresh look and submit revisions tomorrow daytime my time, perhaps sooner. |
…and-publishing-docs-android
c1d76c7
to
861d230
Compare
Hi @freakboy3742 -- I've tested this pretty well and am happy for another review pass and/or merge if you like. Note that the switch to Android App Bundle format results in a change in the code and docs. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A couple of initial review comments; more to come later.
docs/how-to/publishing/android.rst
Outdated
|
||
.. code-block:: bash | ||
|
||
$ ~/.briefcase/tools/java/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks android/*/app/build/outputs/bundle/release/app-release.aab upload-key -storepass android |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To confirm - the '*' here is trying to capturie "all .aab files in the android folder" without explicitly naming the app, right? The possible problem here is that a briefcase project can contain multiple apps.
Also - does this sign-in-place, or produce a new aab file somewhere?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To confirm - the '*' here is trying to capturie "all .aab files in the android folder" without explicitly naming the app, right? The possible problem here is that a briefcase project can contain multiple apps.
True -- I'm trying to capture "all .aab files in the android folder". And true -- this is a bad fit given the possibility of a briefcase project containing multiple apps. I hadn't considered that.
I'll fix that in a follow-up push in a sec.
Also - does this sign-in-place, or produce a new aab file somewhere?
In-place.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We use a password of **android**. This is the `default password for common | ||
Android keystores <https://developers.google.com/android/guides/client-auth>`__. | ||
You can change the password if you like. It is more important to limit who | ||
has access to the keystore file than to change the password. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any reference on “use the default password" as best practice? The general philosophy makes sense, but if we're going to recommend using a default password, I want to be sure we're giving good advice.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unfortunately, no -- this page here talks about creating and confirming a secure password for your keystore -- https://developer.android.com/studio/publish/app-signing -- followed by a different password for the key.
This is IMHO near-total insanity.
A Java keystore does nearly nothing, and the Java keystore password is approximately useless. See https://gist.github.com/zach-klippenstein/4631307 for demo code that shows how to change the password on a keystore without knowing the old password.
In our case, I'm using the PKCS #12 format for keystores, which may or may not have that specific problem, but it adds no value to the key password if the keystore only contains one key, which is how we suggest doing it.
As for the key's password... this is a classic ambiguity in current crypto recommendations. I'll spare you my standard rant for now, but I'm also happy to offer it to you if useful. My suggestion would be that the password adds no value if you're not sharing the key, and if you are sharing the key, do you really think the password you picked is solid enough to protect the key? If so, then you surely need to put it somewhere safe, because you surely can't remember it... in which case you have now opened a massive can of worms. Oops, I gave you 50% of the standard rant anyway.
Codecov Report
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good. I'm wary of making crypto-based recommendations, but your comments make sense to me, so I guess we can commit to that.
I've made a few tweaks for editorial voice, but otherwise this looks good to go!
In checking the details, I did notice that there's a new version of the Play Store Console in Beta... so I guess we're going to need to review this a few months :-(
Fixes #438.
I'd love your feedback on this. I know there's more changes I need to make, but I wanted to get a draft out ASAP.
Some questions for you:
Is it organized in the way you'd expect?
Did I miss any TODOs? :)
Where do we ask the user to store their Android app signing keys? We could use
~/.briefcase/keys/
by default in these instructions. I get the impression there is no true consistent default keystore path in Android; the official docs use an arbitrary-seeming path: https://developer.android.com/studio/publish/app-signing#generate-key . Whatever path we decide on, I'm going to have to make sure these docs use it consistently, so I left it a TODO until we chat.I'll proofread it at least once before resubmitting to you.