Update: 18-August; Package URI tester added
Hi everyone, as we have just rolled out our latest OS release, I wanted to acknowledge that we have been receiving many app submissions from the group at large, which is fantastic - thank you! With these app submissions we have noticed a few common issues and wanted to issue a few reminders, call-to-actions, and two new utilities to help your app remain compliant with our OS requirements.
New Utility Downloads Links
- amzn-amzn-package-analyzer-1.0.0.tgz.zip (12.9 KB)
- package_uri_tester.py.zip (6.1 KB) - unzip and use
REMINDERS/ACTIONS:
- Building with V0.20.x is mandatory, and as of 6-August the App Store has started blocking vpkg submissions built prior to v0.20.x. We have previously shared that 0.20.x enables apps to utilize additional “system-bundled” React Native JavaScript libraries leading to improved performance and direct bugfixes/enhancements to these libraries without the need to update/resubmit your app. Enforcing apps to be built with 0.20.x ensures your app stays compatible with future OS uplevels.
- When up-leveling to V0.20.x, remember you must also clear out your npm cache to use our recommended minimum versions and follow our semver expression guidance in order to obtain the latest library updates from our npm repo - both for 0.20.x and SDK updates in the future. This ensures that your app takes full advantage of the split bundle architecture mentioned previously. We have seen numerous instances where developers’ (or CI systems’) machines have had the SDK running for several versions (e.g. months) and are using now out-of-date libraries; which means they are not receiving updates with bugfixes (nor taking advantage of the split bundle architecture). Specifically we recommend that for every release new SDK version you run the following commands (as documented on our 0.20.x release notes) to ensure your app is fully up-to-date
commands for npm:
npm start -- --reset-cache // clears metro cache
npm run clean // this assumes that you have a "clean" script in your package.json
npm update // pulls the latest version of your app's dependencies
npm list
For other package managers (yarn/pnpm), please refer to our blog post for their referenced commands.
To help confirm you are on the latest libraries, we have a new npm command line tool (amzn-package-analyzer) you can run to validate. You can download it here: amzn-amzn-package-analyzer-1.0.0.tgz.zip (12.9 KB)
Example Usage:
$ amzn-package-analyzer /path/to/project
================================================================================
🔍 @AMZN PACKAGE ANALYZER
================================================================================
Root directory: /path/to/project
CSV file: recommended-versions.csv
Output file: amzn-packages-report.json
📋 Parsing recommended versions...
Found 8 recommended package versions
🔍 Searching for node_modules directories...
Found 12 node_modules directories
📦 Analyzing @amzn packages...
Found 15 @amzn package instances
Unique packages: 8
================================================================================
📊 ANALYSIS SUMMARY
================================================================================
Total @amzn packages found: 15
Packages with higher version than recommended: 5
Packages with equal version to recommended: 2
Packages with lower version than recommended: 3
Packages with unknown/invalid versions: 0
Packages not in recommendations: 5
⚠️ PACKAGES NEEDING UPDATES:
================================================================================
❌ @amzn/base-ui
Current: 1.9.0 | Recommended: 2.1.0
Location: /path/to/project/node_modules/@amzn/base-ui
✅ PACKAGES WITH HIGHER VERSIONS:
================================================================================
✅ @amzn/cloudscape-components
Current: 3.2.1 | Recommended: 3.0.0
Location: /path/to/project/node_modules/@amzn/cloudscape-components
- Validate Mandatory Manifest Permissions and Modules
Messages are how components on the OS (including your apps and Kepler services) communicate with each other. Application launches, event notifications (e.g. change of locale), and few service integrations like Live TV, Content Launcher, etc. leverage messaging to pass small chunks of data around.
As a measure of access control, a set of module dependencies and privileges need to be declared in the app manifest to be able to send and receive certain messages. We have recently started checking submitted packages and are flagging apps with deficient permissions to be addressed in future submissions. Your Amazon contact will reach out with any required actions.
To assist you in this compliance, we are releasing a utility that will simplify your testing workflow and iterate with you to identify missing manifest entries. This utility installs your app to the attached device, enables permission enforcement, launches the app, and prints log statements related to Manifest Permissions. You will need to run through common test scenarios to help generate the complete logs (we recommend running through your apps entire regression test suite for maximum coverage).
Pre-requisites: vpt (installed as part of Kepler SDK) and Python
When available, you will run the attached script and supply your vpkg path with:
Example usage:
python3 package_uri_tester.py <path-to-your-vpkg>
Extracting package ID from .vpkg file...
Unpacking frenchpress_armeabi-v7a.vpkg...
Reading manifest file...
Found package ID: com.amazon.frenchpress
Enabling security enforcement for package com.amazon.frenchpress...
Starting log monitoring...
Uninstalling existing package...
Pushing package to device: frenchpress_armeabi-v7a.vpkg
Push result: frenchpress_armeabi-v7a.vpkg: 1 file pushed, 0 skipped. 33.3 MB/s (21563215 bytes in 0.618s)
Installing package...
==================================================
🚀 START TESTING YOUR APP NOW 🚀
==================================================
Press Ctrl-C to stop the test
URI 'broadcast://*/com.amazon.usermanagerservice/profile/created' access failed due to missing module '/com.amazon.usermanagerservice@IProfileManager'
URI 'unicast://*/device-messaging/payload' access failed due to missing module '/com.amazon.ace.messaging.service@IDeviceMessaging
When you stop you may choose to iterate, when the script automatically updates the manifest and reinstalls the app.
\^C
Test stopped.
Update manifest with fixes and retry test (Y) or show summary and exit (N)? [Y/N]: y
Unpacking current package for manifest update...
Locating manifest file...
Reading manifest: frenchpress_armeabi-v7a/manifest.toml
Analyzing failures and generating fixes...
Adding 1 fixes to manifest...
Packing updated package...
Package packed successfully
Saving updated manifest for verification...
Start test with updated package (Y) or show summary and exit (N)? [Y/N]: y
This can be iterated multiple times until you have covered all your test cases, upon which you may choose to print a full summary of the changes identified:
^C
Test stopped.
Update manifest with fixes and retry test (Y) or show summary and exit (N)? [Y/N]: n
============================================================
TEST SUMMARY
============================================================
Package ID: com.amazon.frenchpress
Command: python3 package_uri_tester.py frenchpress_armeabi-v7a.vpkg
Total URIs that failed during testing: 1
FIXED URIs (1):
------------------------------
URI: unicast://*/device-messaging/payload
Issue: Missing module '/com.amazon.ace.messaging.service@IDeviceMessaging'
Fix Applied: Added [[wants.module]] id = "/com.amazon.ace.messaging.service@IDeviceMessaging" to manifest
Test summary updated in test_summary.txt
You can then inspect the test_summary.txt for actions to take upon your manifest privileges.
Note that at this time, the python script only works with one Kepler device attached (IE it will fail if you have two Kepler Fire Sticks connected or if you are running the Kepler Virtual Device AND have a Kepler Fire Stick connected. Also, you must have updated to the 14-Aug OS OTA
update in order to use this tool
- For apps using any library/services requiring user-consented privilege (such as the Kepler Identifiers getFriendlyDeviceName), ensure that you have implemented logic for run-time privileges, including obtaining consent from the user (via the Security Manager API) and gracefully handling when the customer declines the privilege. For example, we have seen some cases where a customer had denied consent and introduces the app introduced a bug/crash due to improperly handling the denied permission (payload of response is
SecurityManagerTypes.PrivilegeState.DENY).
The current set of APIs requiring permission includes NET_INFO, ACCESS_ACCESSORY_CONTROL_ACCOUNT, CONNECT_ACCESSORY_CONTROL_ACCOUNT, DISCOVER_ACCESSORY_CONTROL_ACCOUNT, ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, RECORD_AUDIO, DEVICE_FRIENDLY_NAME, BLUETOOTH_ADVERTISE, BLUETOOTH_DISCOVERABLE, READ_EXTERNAL_STORAGE, DISCOVERABLE_ACCESSORY_CONTROL_ACCOUNT, CAMERA, READ_CALENDAR, WRITE_CALENDAR
For more details on implementation, see our code sample.
Thank you for your attention to detail on these items; complying with these will ensure your Kepler app functions properly for launch and beyond.
Thanks,
Eric
amzn-amzn-package-analyzer-1.0.0.tgz.zip (12.9 KB)
FAQ(s)
I have updated to 0.20.x, but my application is not using system bundles, what else can I check?
We previously (before 0.20.x) provided an opt-in/opt-out method for system bundles in two places: 1) In package.json’s “kepler” section, where we provided an optional flag called useSystemJsBundles . Please remove references to that flag in your package.json. 2) In the actual build-kepler command (which may also be defined in your package.json , you could set a flag for --use-system-js-bundles as true or false. If you have defined this, please remove this flag. If both flags are set, the command line “wins”, so if you have set the package.json version and are still running into the issue, double check that your command line is not passing in an incorrect version of --use-system-js-bundles .