▓
▄▓▓▓▌
▓▓▓▓▓▌
▓▓▓▓▓▓▓▌
▄▓▓▓▓▓▓▓▓▓▄▄▄▄
▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄
▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▓▓▓▓▓
▓▓▓█▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▄▀▓▓▓▓▄
▓▀▀ ▐▓▓▓▓██▀▀▀█▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░█▓▓▓▄
▐▓ ▀▀ █▓▓▓▓▓▓▓▓▓▓▓▓▓▌ ▓▓▓▓▄
▓ ▀▓▓▓▓▓▓▓▓▓▓▓▓▄▓▓▓▓▓▓▓▄▄▄▄
▓▌ ▀▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█
▐▌ █▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▀
▐▌ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▀
▐▌ ▄▄▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▀
▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▀
▓ ▓█▀▀ ▀█▓█▀
▐▌ ▐ ▓
▓ ▐▓
▀▄ ▄▀
▀▒▄▄ ▄▄▄▀▀▄▄▄▀▀
▀▀▒▄▄▄▄▄▄▒▀▀▀
█████╗ ███████╗████████╗██████╗ ██████╗
██╔══██╗██╔════╝╚══██╔══╝██╔══██╗██╔═══██╗
███████║███████╗ ██║ ██████╔╝██║ ██║
██╔══██║╚════██║ ██║ ██╔══██╗██║ ██║
██║ ██║███████║ ██║ ██║ ██║╚██████╔╝
╚═╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝
Astro
An SDK that makes it easy to leverage native or web UI for building amazing iOS and Android apps.
Astro Android vs iOS Feature Parity Status Doc
Additional Documents
Table of Contents
Documentation
You can find the Astro documentation at astro.mobify.com or you can view it locally (see Making Changes). We currently publish the documentation for all versions of Astro since v0.5.
The documentation is organized by Astro release in folders. docs/public/
contains one folder for
each release of Astro plus a special dev
folder for changes related to an unreleased version of
Astro. See the release checklist for more information.
Installation
We use Harp to build our docs. To install Harp, run npm install
.
Making Changes
Most of our documentation is written in markdown. Changes to
any tutorials or reference guides should be changed in /docs
.
To preview your changes, run the following:
npm run harp:server
Then browse to http://localhost:9000
.
Publishing
The Astro documentation is hosted on S3 at http://astro.mobify.com.s3-website-us-east-1.amazonaws.com, which is the origin for http://astro.mobify.com.
To deploy an update to the docs, you will need permission to deploy to the astro.mobify.com S3 bucket.
If you have the correct permissions, ensure AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
environment
variables are set, and run the following to deploy the updated docs site:
npm run upload_astro_docs
Installing
Clone the repo: git clone git@github.com:mobify/astro.git
Prerequisites
- We recommend you use nvm to manage node and npm versions.
- node ^4.0.0 LTS
- npm ^2.0.0
- Grunt CLI - Install via
npm install -g grunt-cli
- Java Development Kit (JDK) 8
- XCode 7.3.X
- Android Studio
NPM dependencies
- Install npm dependencies (push libraries) by running:
npm install
Android
- Download and install Android Studio.
- Open
Android Studio
. - Click
Open an existing Android project
, and selectastro/sandbox/android
. Android Studio will open both the Astro Android source code and the Sandbox Android app source code. - Create a Android Virtual Device if you haven't already.
- Follow these instructions to install SDK packages.
- Run the Sandbox app!
iOS
- Download and install Xcode 7.3.X
- Run
open sandbox/ios/Sandbox.xcworkspace
in your Terminal. It will open both the Astro iOS source code and the Sandbox iOS app source code. - Run the Sandbox app!
Note: Xcode 6 is no longer supported as we have upgraded to Swift 2.2!
How to create and ship a change
In order to ship a change to Astro, follow our Contributing guidelines.
Testing
Running Tests
JS
- Install the dependencies needed for testing, run
npm install
. - To run the tests on the command line, run
npm test
. - To run the tests in the browser, run
open js/tests/index.html
.
iOS
- Start the server required for testing by running
npm run fixture-server
- In Xcode, select the "Astro" workspace in the workspace dropdown.
- Go to Product -> Test
Android
- Go to Run -> Edit Configurations
- Click on the "+" on the top left, and select "Android Tests"
- Label it "Astro Tests", choose the module "astro", and click OK.
- Select "Show chooser dialog"
- In the drop down next to the green play button, select "Astro Tests" and click the play button.
- Watch the tests run!
Writing Tests
Android
The testing framework we use is jUnit 3.
The mocking library we use is Mockito.
Test Coverage
Android
Run the following command to generate the test coverage report:
cd android; ./gradlew createDebugCoverageReport
Then, open the report index.html file to have a look at the coverage:
open android/build/outputs/reports/coverage/debug/index.html
iOS
Currently we are not measuring test coverage in iOS :(
JS
Currently we are not measuring test coverage in JS :(
Publishing a new version
Run npm publish
to publish a new version of astro-sdk
.
To do a release of astro-client.js to our CDN on http://assets.mobify.com/astro/astro-client-X.X.X.min.js, run the following command:
grunt upload_astro_client
Structure
android/
- Contains the source code for the Astro Android libraryios/
- Contains the source code for the Astro iOS libraryjs/
- Contains the source code for the Astro JavaScript librarysandbox/
- Contains the source code for the demonstration sandbox (aka Catalogue).
JS
When you're developing an Astro application, there are a few key pieces of JS to know about:
- app.js
- astro-base.js
- astro-client.js
- astro-full.js
- webViewPlugin.js, drawerPlugin.js, and other plugins
app.js
app.js is your main entry point to developing an Astro project. This is where the main business logic of you application lives. The app logic is handled in a persistent WebView that lives throughout the lifecycle of your application. It's also the place where you import/require the different plugins that you need for your application.
A sample app.js
lives inside of sandbox/app/
.
You can learn more about how to build and develop the demo here.
astro-base.js
astro-base.js is the module that allows communication between JavaScript and the native bridge. astro-client.js and astro-full.js extend from this module. In general, as a user of the Astro SDK you should never have to require this module directly.
astro-client.js
astro-client.js is the library which provides the ability for web views to communicate with app.js.
astro-full.js
astro-full.js is the library which provides the ability for app.js to communicate with native Astro components. It's the library that SDK plugin developers should import in order to create a plugin.
Plugins
iOS
TODO
Android
TODO
JS
Most native plugins have a corresponding JavaScript plugin that you will use to instantiate and use different plugins in your app.js file.
All plugins can be found inside of android/src/main/java/com/mobify/astro/plugins
.
You can learn more about how to build and develop Astro plugins
here.