Helios is an open-source framework that provides essential backend services for iOS apps, from data synchronization and user accounts to push notifications, in-app purchases, and passbook integration. It allows developers to get a client-server app up-and-running in just a few minutes, and seamlessly incorporate functionality as necessary.
Helios is designed for "mobile first" development. Build out great features on the device, and implement the server-side components as necessary. Pour all of your energy into crafting a great user experience, rather than getting mired down with the backend.
One great example of this philosophy in Helios is Core Data Synchronization. This allows you to use your existing Core Data model definition to automatically generate a REST webservice, which can be used to shuttle data between the server and client. No iCloud, no problem.
Helios also comes with a Web UI. Browse and search through all of your database records, push notification registrations, in-app purchases, and passbook passes. You can even send targeted push notifications right from the browser.
Requirements
- Ruby 2.0+ with Bundler installed
- PostgreSQL 9.2+ (Postgres.app is the easiest way to get a Postgres server running on your Mac)
Getting Started on OS X
- Verify Ruby Installation:
$ ruby -v
- Install Helios, Bundler, and at the command prompt:
$ gem install helios
- Create a new Helios application:
$ helios new myapp
- Create a Postgres database at the command prompt:
$ createdb -h localhost myapp
Database credentials are read from the
.env
file generated by Helios, as the variableDATABASE_URL
. By default, this will point to a database with the name of the generated app.
- Change directory to
myapp
$ cd myapp
- Start the web server:
$ helios server
- Go to http://localhost:5000/admin and you’ll see your app's Web UI
Read on for instructions on the following:
- Linking a Core Data model
- Integrating Helios into your mobile client
Usage
Built on the Rack webserver interface, Helios can be easily added into any existing Rails or Sinatra application as middleware. Or, if you're starting with a Helios application, you can build a new Rails or Sinatra application on top of it.
This means that you can develop your application using the tools and frameworks you love, and maintain flexibility with your architecture as your needs evolve.
Sinatra / Rack
Gemfile
gem 'helios'
config.ru
require 'bundler'
Bundler.require
run Helios::Application.new do
service :data, model: 'path/to/DataModel.xcdatamodel'
service :push_notification, apn_certificate: 'path/to/apple_push_notification.pem', apn_environment: 'development'
service :in_app_purchase
service :passbook
end
Rails
To create a Rails app that uses Postgres as its database, pass the -d postgresql
argument to the rails new
command:
$ rails new APP_PATH -d postgresql
If you're adding Helios to an existing Rails project, be sure to specify a PostgreSQL database in config/database.yml
and check that the pg
gem is included in your Gemfile
:
Gemfile
gem 'helios'
gem 'pg'
Helios can be run as Rails middleware by adding this to the configuration block in config/application.rb
config/application.rb
config.middleware.use Helios::Application do
service :data, model: 'path/to/DataModel.xcdatamodel'
service :push_notification, apn_certificate: 'path/to/apple_push_notification.pem', apn_environment: 'development'
service :in_app_purchase
service :passbook
end
Available Services
Each service in Helios can be enabled and configured separately:
data
: Generates a REST webservice from a schema definition. Currently supports Core Data (.xcdatamodel
) files.
Parameters
model
: Path to the data model file
Associated Classes
Each entity in the specified data model will have a Sequel::Model
subclass created for it under the Rack::CoreData::Models
namespace.
GET /:resources |
Get list of all of the specified resources |
POST /:resources |
Create a new instance of the specified resource |
GET /:resources/:id |
Get the specified resource instance |
PUT /:resources/:id |
Update the specified resource instance |
DELETE /:resources/:id |
Delete the specified resource instance |
push_notification
: Adds iOS push notification registration / unregistration endpoints.
Associated Classes
Rack::PushNotification::Device
PUT /push_notification/devices/:token |
Register or update existing device for push notifications |
DELETE /push_notification/devices/:token |
Unregister a device from receiving push notifications |
POST /push_notification/message |
Send out a push notification to some devices |
in_app_purchase
: Adds an endpoint for iOS in-app purchase receipt verification endpoints, as well one for returning product identifiers.
Associated Classes
Rack::InAppPurchase::Receipt
Rack::InAppPurchase::Product
POST /in_app_purchase/receipts/verify |
Decode the associated Base64-encoded receipt-data , recording the receipt data and verifying the information with Apple |
GET /in_app_purchase/products/identifiers |
Get an array of valid product identifiers |
passbook
: Adds endpoints for the web service protocol for communicating with Passbook
Associated Classes
Rack::Passbook::Pass
Rack::Passbook::Registration
GET /passbook/v1/passes/:passTypeIdentifier/:serialNumber |
Get the Latest Version of a Pass |
GET /passbook/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier[?passesUpdatedSince=tag] |
Get the Serial Numbers for Passes Associated with a Device |
POST /passbook/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber |
Register a Device to Receive Push Notifications for a Pass |
DELETE /passbook/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber |
Unregister a Device |
newsstand
: Adds endpoints for Newsstand. Offers complete management of issues, covers, and assets, with plist-based web services and Atom feeds.
Associated Classes
Rack::Newsstand::Issue
GET /newsstand/issues |
Get list of all issues |
GET /newsstand/issues/:name |
Get a specific issue |
POST /newsstand/issues |
Add a new issue |
Command-Line Interface
Helios comes with a CLI to help create and manage your application. After you $ gem install helios
, you'll have the helios
binary available.
$ helios --help
helios
A command-line interface for building mobile infrastructures
Commands:
console Open IRB session with Helios environment
help Display global or [command] help documentation.
link Links a Core Data model
new Creates a new Helios project
server Start running Helios locally
Creating an Application
The first step to using Helios is to create a new application. This can be done with the $ helios new
command, which should be familiar if you've ever used Rails.
$ helios new --help
Usage: helios new path/to/app
The `helios new` command creates a new Helios application with a default
directory structure and configuration at the path you specify.
Options:
--skip-gemfile Don't create a Gemfile
-B, --skip-bundle Don't run bundle install
-G, --skip-git Don't create a git repository
--edge Setup the application with Gemfile pointing to Helios repository
-f, --force Overwrite files that already exist
-p, --pretend Run but do not make any changes
-s, --skip Skip files that already exist
Linking a Core Data Model
In order to keep your data model and REST webservices in sync, you can link it to your helios application:
$ helios link path/to/DataModel.xcdatamodel
This creates a hard link between the data model file in your Xcode and Helios projects—any changes made to either file will affect both. The next time you start the server, Helios will automatically migrate the database to create tables and insert columns to accomodate any new entities or attributes.
If you are using OS X, do not attempt to delete your Helios application directory using
rm -r
if you have linked a Core Data model. Doing so will result in the removal of the Xcode data model itself. Instead use the finder to move the Helios application directory to trash.
Starting the Application Locally
To run Helios in development mode on localhost
, run the server
command:
$ helios server
Testing Push Notifications
Once you have registered a device and set up your certificate, try this:
$ curl -X POST -d 'payload={"aps": {"alert":"Blastoff!"}}' http://localhost:5000/push_notification/message
Setting Up Storage for Newsstand
In order to set up storage for Newsstand, you will need an account with one of the following cloud storage providers:
In your application directory, edit the config.ru
with your credentials for the cloud storage provider of your choice. Here is an example configuration using AWS.
require 'bundler'
Bundler.require
app = Helios::Application.new {
service :data, model: Dir['*.xcdatamodel*'].first if Dir['*.xcdatamodel*'].any?
service :push_notification
service :in_app_purchase
service :passbook
service :newsstand, {
storage: {
provider: 'AWS',
aws_access_key_id: 'YOUR_ACCESS_KEY_ID',
aws_secret_access_key: 'YOUR_SECRET_ACCESS_KEY'
}
}
}
run app
For other configuration options, see fog.io.
Running the Helios Console
You can start an IRB session with the runtime environment of the Helios application with the console
command:
$ helios console
This command activates the services as configured by your Helios application, including any generated Core Data models. The rack
module is automatically included on launch, allowing you to access everything more directly:
> Data::Artist.all #=> [...]
> InAppPurchase::Receipt.all #=> [...]
> Newsstand::Issue.all #=> [...]
> Passbook::Passes.all #=> [...]
> PushNotification::Device.all #=> [...]
Deploying to Heroku
Heroku is the easiest way to get your app up and running. For full instructions on how to get started, check out "Getting Started with Ruby on Heroku".
Once you've installed the Heroku Toolbelt, and have a Heroku account, enter the following commands from the project directory:
$ heroku create
$ git add .
$ git push heroku master
Integrating with an iOS Application
Core Data Synchronization
With AFIncrementalStore, you can integrate your Helios app directly into the Core Data stack. Whether it’s a fetch or save changes request, or fulfilling an attribute or relation fault, AFIncrementalStore handles all of the networking needed to read and write to and from the server.
See "Building an iOS App with AFIncrementalStore and the Core Data Buildpack" on the Heroku Dev Center for a comprehensive guide on how to use AFIncrementalStore with the Core Data buildpack. An article for Helios is forthcoming, but aside from deployment, the instructions are essentially unchanged.
Push Notification Registration
With Orbiter you can integrate Push Notifications into your app easily.
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
NSURL *serverURL = [NSURL URLWithString:@"http://raging-notification-3556.herokuapp.com/"];
Orbiter *orbiter = [[Orbiter alloc] initWithBaseURL:serverURL credential:nil];
[orbiter registerDeviceToken:deviceToken withAlias:nil success:^(id responseObject) {
NSLog(@"Registration Success: %@", responseObject);
} failure:^(NSError *error) {
NSLog(@"Registration Error: %@", error);
}];
}
Converting Your Push Notification Certificate
These instructions come from the APN on Rails project.
Once you have the certificate from Apple for your application, export your key and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:
- Click the disclosure arrow next to your certificate in Keychain Access and select the certificate and the key.
- Right click and choose
Export 2 items…
. - Choose the p12 format from the drop down and name it
cert.p12
.
Now covert the p12 file to a pem file:
$ openssl pkcs12 -in cert.p12 -out apple_push_notification.pem -nodes -clcerts
License
Helios is released under the MIT License.