README.md

motion-takeoff

A RubyMotion specific iOS gem for scheduling stuff. You can use motion-takeoff to display messages at certain launch counts and schedule local notifications. Currently, there are two modules in this gem: Messages & Reminders.

The Messages module will allow you to schedule alerts to users at certain launch counts.

The Reminders module is a nice wrapper for UILocalNotification to help you set reminders for the user to come back to your app at specified periods of time. It supports all the options of UILocalNotification and does some fancy interpretation of dates for you if needed.

More modules are planned for the future. This gem is in its infancy. Please help me make it better!

Installation

Add this line to your application's Gemfile:

gem 'motion-takeoff'

And run: bundle

Usage: Messages Module

Open your app delegate and in your applicationDidBecomeActive: method do something like this:

def applicationDidBecomeActive(application)
  messages = Takeoff::Messages.new
  messages.schedule launch:1, title:"Welcome to #{App.name}!", message:"Thanks for checking it out!"
  messages.schedule launch:3, title:"Quick Tip:", message:"This is the 3rd time you've launched this application!"
  messages.schedule launch:500, title:"Quick Tip:", message:"This is the 500th time you've launched this application!"
  messages.takeoff
end

This will display an alert to the user on the 1st, 3rd, and 500th launches of the app.

Asking for confirmation

You can use the Messages module to ask a user to do something. Just pass a Proc object to the :action option. You can send an array of strings using :buttons but it will default to ["Cancel", "OK"]. When the user presses the "OK" button, the Proc will run.

def applicationDidBecomeActive(application)
  messages = Takeoff::Messages.new
  messages.schedule(
    launch: 1,
    title: "Welcome to #{App.name}!", 
    message: "So you want to view the settings?"
    action: Proc.new{ App.delegate.viewController.showSettings }
  )
  messages.takeoff
end

Usage: Reminder Module

The reminders module is a nice wrapper on UILocalNotification and makes it easy to schedule reminders to come back and use your app!

iOS 8 requires that you ask the user for permission to send notifications:

def application(application, didFinishLaunchingWithOptions:launchOptions)
  Takeoff::Reminders.setup
end

You should always reset all local notifications when your app becomes active:

def applicationDidBecomeActive(application)
  Takeoff::Reminders.reset
end

And here's how to set multiple reminders when your app enters the background:

def applicationDidEnterBackground(application)
  Takeoff::Reminders.schedule(
    body: "Fires 20 seconds after the user closes your app.",
    fire_date: 20 #seconds
  )

  Takeoff::Reminders.schedule(
    body: "Fires 10 seconds after the first notification.",
    fire_date: Time.now + 30 #Time object in the future
  )
end

The Takeoff::Reminders.schedule method takes a hash of options that are send to the UILocalNotification. body and fire_date are required and will raise an exception if you try to schedule a notification without those two options. Here's all the default options:

{
    action: nil,
    launch_image: nil,
    badge_number: 0,
    has_action: true,
    repeat: {
        calendar: nil,
        interval: 0
    },
    time_zone: NSTimeZone.defaultTimeZone,
    sound: UILocalNotificationDefaultSoundName,
    user_info: {}
}

You can read about what each of these does in Apple's UILocalNotification Documentation, but I've implemented all of Apple's defaults that you can override if needed.

If you pass a NSCalendarUnit for the repeat option, we'll automatically assume you want to use NSCalendar.currentCalendar as the repeat calendar. Possible values of repeat are as found in the NSCalendarUnit documentation.

Future plans

I'd like it to be able to be a multi-purpose tool for doing things at launch other than just alerting users. Things like asking for ratings in the iTunes store and scheduling other activities likes clearing caches on the 10th load or checking a server every other load, etc.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request